public interface SgwtEEManualSetup

Manual Setup & Deployment of Smart GWT Pro/EE

Isomorphic recommends starting most new projects from one of the provided templates, and in any case using some form of dependency management as covered in documentation for the standard setup. For those unable or unwilling to do so, however, this overview serves as a how-to for adding Smart GWT to your project manually.

Creating a new project from scratch

If you are starting a new project from scratch, we recommend starting with one of the sample projects included with SmartGWT EE under the "samples" directory. Use the project that most closely matches your integration strategy and follow the instructions in the "readme" file within the sample directory. If you have a choice, most projects will benefit from the use of SQLDataSources, illustrated in the BuiltInDS sample.

Adding SmartGWT EE to an existing project

Important: If you have created a project using the GWT Plugin for Eclipse, a Maven archetype, or similar tool, first get rid of unused resources typically included in such "starter projects":

• from your [i]moduleName[/i].gwt.xml file, remove imports of any GWT themes, leaving only the import of com.google.gwt.user.User. Proper imports to add for SmartGWT Pro/EE are shown below.
• get rid of any sample servlets or GWT-RPC services (delete both web.xml entries and server-side source)

Now add SmartGWT EE: all of these steps are required. Do not skip steps or omit resources you think you may not need. Get a working project first, then think about trimming resources, as needed, once you understand the system.

In the steps below, copying from eg "war/WEB-INF/..." means copying from the "war" subdirectory of whichever sample project is closest to your desired integration strategy.

1. Unless you're using Maven to manage dependencies, you'll need to add all jars from the SmartGWT Pro/EE distribution (under smartgwtee-version/lib) to your CLASSPATH. You can copy the '.classpath' file from the appropriate sample project for a working set of includes (it's in the same directory as the war/ folder). There are both client- and server-side jars, both kinds go in the classpath. For server-side .jars, dependencies are documented here.
2. update your modulename.gwt.xml file with these imports:

        <inherits name="com.smartgwtee.SmartGwtEE"/>
        <inherits name="com.smartgwtee.tools.Tools"/>
        

   NOTE: if you were previously using SmartGWT LGPL, remove the <inherit> of 'com.smartgwt.SmartGWT' and ensure the <inherit> of 'com.smartgwt.tools.SmartGwtTools' appears before the imports above. Also ensure that all SmartGWT-related inherits appear *before* your <entry-point> declaration.
3. if you are using Optional Modules such as AI, Analytics or RealtimeMessaging, see LoadingOptionalModules for additional inherits
4. Copy log4j.isc.config.xml across to the "src" dir of your project (it's placed in the "src" dir as a means of getting it into the CLASSPATH). This file is either in the "src/" dir of a given sample project or in war/WEB-INF/classes. This enables default log4 categories for server-side logs appropriate for development. See ServerLogging for information on server-side logging and how to configure it.
5. Copy server.properties across to the "src" dir of your project. This file is either in the "src/" dir of a given sample project or in war/WEB-INF/classes. This contains miscellaneous server settings - see the file itself for documentation.
   • server.properties contains server-side paths that contain the GWT module name. Replace the module name from the sample project (eg "builtinds") with the module name of your actual GWT project
   • if you're using SQLDataSource, enter your JDBC settings (start with a server.properties from a project that uses a database to see the required format for settings)
6. If you plan to use JPA, copy src/META-INF/persistence.xml into your src/META-INF directory. This file will be copied into war/WEB-INF/classes/META-INF directory during build process. Make sure you specify your entity classes in persistence.xml. If you change persistence unit name you have to update "jpa.persistenceUnitName" property in server.properties file. More information on JPA configuration can be found in JpaIntegration.
7. merge web.xml, starting with the web.xml from the sample project that is closest to your target application (under war/WEB-INF in the sample project). The list of servlets and what they do is documented here. See the server-side JavaDoc for further details on servlet APIs and override points.
8. (SmartGWT Power or Enterprise only) If using the BatchUpload functionality, copy war/ds/batchUpload.ds.xml from the Showcase sample project to the shared.datasources directory you configured in server.properties.

Extra Step Required for GWT 2.8+

If you're using GWT 2.8 or later, attempting to run SuperDevMode in Eclipse may lead to an exception being reported such as:

      org.apache.xerces.parsers.XIncludeAwareParserConfiguration cannot be cast to
          org.apache.xerces.xni.parser.XMLParserConfiguration

This is due to xerces classes being included in GWT 2.8+, in addition to being in the JRE. To solve, add the following extra VM arguments to either your launch configuration or JRE in Eclipse:

      -Djavax.xml.parsers.SAXParserFactory=com.sun.org.apache.xerces.internal.jaxp.SAXParserFactoryImpl
      -Djavax.xml.parsers.DocumentBuilderFactory=com.sun.org.apache.xerces.internal.jaxp.DocumentBuilderFactoryImpl
  

Troubleshooting

Problem	Possible Causes	Solution
ClassNotFound or other Java Exceptions in the server log.	Missing JAR files	Verify every .jar from the smartgwtee-version/lib directory has been added to your CLASSPATH. Although you might later be able to remove some .jars, for initial installation testing, copy every .jar
Client-side error about attempting to use "iscServer" request without server installed	Wrong imports in moduleName.gwt.xml	See correct imports above, note remove com.smartgwt.SmartGWT import and be sure imports are in the correct order
Client-side error about "$debox is not defined"	Wrong order of imports in moduleName.gwt.xml	Make sure all SmartGWT-related imports appear before <entry-point> in your .gwt.xml file
Missing images or failure to load page	Didn't set isomorphicDir in .html bootstrap file	See step above for setting isomorphicDir
Server error: "adminConsole" app not found when launching tools such as Reify	Bad filesystem paths configured in server.properties	Correct paths in server.properties. NOTE the samples include the GWT module name in some settings, search and replace this value with your GWT module name
Server error: Can't find DataSource with ID yourDataSourceID	Bad filesystem paths in server.properties or bad DataSource .ds.xml file	Correct paths in server.properties - search for "project.datasources". Also check that the DataSource ID you are using matches the "ID" attribute in the .ds.xml file (NOTE: ID attribute is uppercase "ID" not "id") and that the file is named dataSourceId.ds.xml. DataSource IDs are case sensitive, including the file name. For more in-depth troubleshooting steps, see +link{http://forums.smartclient.com/showthread.php?t=8159#aDSLoad,this FAQ answer}.
Server unable to load builtinTypes.xml as it starts up, possibly hitting a NullPointerException	Modules have been added to your GWT project (.gwt.xml) but you haven't run another GWT compile	GWT compile your project again

For further troubleshooting steps, see the SmartGWT FAQ and, if still stuck, try posting in the Forums. NOTE: gather all the information indicated in the FAQ before posting.

NOTE: It is possible to create a server-only SmartGWT EE project that will run standalone (ie, not inside a servlet container or application server). Please see Standalone DataSource Usage for details.