Package com.smartgwt.client.docs

Interface DevModeTroubleshooting

public interface DevModeTroubleshooting

Troubleshooting GWT Development Mode

This topic provides details on configuring and running Development Mode and troubleshooting any problems. For an overview, including historical context, see Debugging: Development Modes in GWT. Note that GWT 2.12.x is the minimum supported GWT version as of SmartGWT 14.1.

Development Mode in GWT 2.12.0+

To use Development Mode in Eclipse with SmartGWT 14.1+, you?ll need to install GWT Eclipse Plugin (GEP). This provides access to the Code Server run configuration, but since the Jetty bundled with GWT isn?t compatible with Jakarta/Servlet 5.0, you?ll also need to install the Jetty Eclipse Plugin and set up an external Jetty 11. (Note that the JEP may not work with Jetty 12+.)

It's assumed that you already have installed the GWT SDK and Java 17+. For more guidance beyond this overview and the links above, see Using GWT with Eclipse.

Eclipse Setup

If you want to import into Eclipse the pre-built projects included with SmartGWT, such as the Built-in-DS app, and use the pre-built run configurations, some Eclipse setup is needed first:

  • Open the Classpath Variables view:
    • Windows: Window -> Preferences -> Java -> Build Path -> Classpath Variables
    • >MacOS X: Eclipse -> Preferences -> Java -> Build Path -> Classpath Variables
  • Set the Eclipse Classpath variable SGWTEE_HOME to point to the root directory of your Smart GWT EE installation.
  • Set the Eclipse Classpath variable GWT_HOME to point to the root directory of your GWT SDK 2.12.x installation.
    (This variable is used by the classpath in the pre-built launch configuration for the Jetty Plugin.)

Now you can use Eclipse?s File -> Import, General -> Existing Projects into Workspace feature to import the pre-built projects and associated run configurations. Or you can create your own GWT project and set up the GWT Development Mode and Jetty run configurations as discussed below.

Note that even if you use the pre-built Jetty Plugin run configuration from one of our projects, you?ll still need to set up the external Jetty 11 configuration as detailed below, and then configure its location into the Jetty Plugin run configuration via the "Use Jetty at path" Jetty Plugin run configuration setup step.

Setting up the Run Configurations

Separate run configurations are needed GWT Development Mode and for the Jetty Plugin, since we can?t use GWT?s built-in Jetty server with Jakarta/Servlet 5.0.

First create the Development Mode run configuration:

  • Right click on your project -> Run As -> Run Configurations...
  • Double click "GWT Development Mode (DevMode)" to create a new configuration underneath it
  • Set the title (very top) to something you'll remember
  • Set the "Main class" to com.google.gwt.dev.DevMode
  • Click into the Server Tab and uncheck "Run built-in server" as we can?t use it for Jakarta/Servlet 5.0
  • In the "Arguments" Tab, add entries for (at a minimum) the source path and the module (package, plus name of your .gwt.xml file) - for example: -src src/ com.smartgwt.sample.BuiltInDS
In your external Jetty 11 installation, we need to make some modifications for the Jetty Eclipse Plugin:
  • Remove the two mortbay JARs from the lib/apache-jsp directory in the Jetty 11 installation
  • Create a new lib/apache-jstl directory in the installation, and populate it with the following two JARs:
    • jakarta.servlet.jsp.jstl-3.0.1.jar
    • jakarta.servlet.jsp.jstl-api-3.0.2.jar
    downloaded from the Maven Repository

Then create the Jetty Plugin run configuration:
  • Right click on your project -> Run As -> Run Configurations...
  • Double click "Jetty Webapp" to create a new configuration underneath it
  • In the Options Tab, click "Use Jetty at path" and then type or browse to your external Jetty 11 installation
  • In the same tab, click on "Enable JNDI support" under Jetty Features
  • In the Classpath Tab, make sure that GWT JARs gwt-servlet-jakarta.jar, gwt-servlet-deps.jar, and gwt-user.jar are included, but don?t include the entire GWT SDK (due to conflicts).
If you?re having trouble setting up the Jetty Plugin and its run configuration, you can always use an external installation of Jetty 11+ instead of running it inside Eclipse.

Running the Code Server

At this stage you should be able to start the Code Server:

  • Right click on your project -> Run As -> Run Configurations...
  • Start the GWT Development Mode run configuration that was imported with your pre-built project or that you created following the instructions above
Observe the logging in the console as the Code Server starts. When it?s ready it will report a URL there. Don?t visit it yet.

Deploying your Web Application

You should now launch the Jetty Plugin Run Configuration:

  • Right click on your project -> Run As -> Run Configurations...
  • Start the Jetty Webapp run configuration that was imported with your pre-built project or that you created following the instructions above
When Jetty has completed launching, go back to the Code Server output logging in the console tab of Eclipse, and visit that URL in your browser. Drag the "Dev Mode On" and "Dev Mode Off" buttons up to your browser bookmarks toolbar. These bookmarks allow you to easily switch to Development Mode (recompiling your Web Application) or switch back to Production Mode.

Entering Development Mode

Visit the Production Mode URL of the running Web Application. The bookmarks created earlier can now be used to enter Development Mode:

  • hit the "Dev Mode On" bookmark link
  • on the pop-up, select the button to "Compile"
If you make code changes, you can update Development Mode using the "Dev Mode On" bookmark.

Script Tags in Development Mode

The official GWT Development Mode linker (the default linker since GWT 2.7.0) does not support including modules which load javascript files. SmartGWT restores support for script tags by modifying some of the generated files with a post link step. However, going forward it is recommended to migrate away from script tags in modules since we cannot control future changes to GWT that may introduce additional incompatibilities.

To avoid script tags if you're inheriting the standard module com.smartgwtee.SmartGwtEE, you'll need to switch that to com.smartgwtee.SmartGwtEENoScript, and add the following lines to your bootstrap HTML file (under the "war" directory): 


     <script src="[app]/sc/modules/ISC_Core.js">          </script>
     <script src="[app]/sc/modules/ISC_Foundation.js">    </script>
     <script src="[app]/sc/modules/ISC_Containers.js">    </script>
     <script src="[app]/sc/modules/ISC_Grids.js">         </script>
     <script src="[app]/sc/modules/ISC_Forms.js">         </script>
     <script src="[app]/sc/modules/ISC_RichTextEditor.js"></script>
     <script src="[app]/sc/modules/ISC_Calendar.js">      </script>
     <script src="[app]/sc/modules/ISC_DataBinding.js">   </script>
 
     <script src="[app]/sc/skins/[skinname]/load_skin.js"></script>
In the above lines:
  • Replace "[app]" with the directory containing the "sc" lib - determined by the "rename-to" attribute in your .gwt.xml file -- for example "builtinds" or "dsdmi".
  • Replace "[skinname]" with the name of the skin you want to use -- for example "Enterprise" or "Graphite".

Understanding the Relevant Behavior of SDM

SmartGWT's custom linker generates a file named loadScriptTagFiles.js in the same directory as the GWT-generated file <moduleName>.nocache.js to force-load the script tags rejected by the SuperDevMode linker. SmartGWT attempts to load loadScriptTagFiles.js directly in the root HTML page (see the BuiltInDS sample project), and also injects a hook directly into <moduleName>.nocache.js to load it. If it's not loaded, or doesn't contain the required script files (typically Smart GWT Framework JS files), the GWT page won't load, errors will appear in the console, and the browser will show a blank page. Thus, it's important to understand when such problems may occur.

If you build your GWT project (GWT 2.7.0+, non-SDM) using a command-line tool such as Ant, or run SDM in Eclipse using the CodeServer approach from above (for GWT Plugin version 2.6.x), then the root HTML page should pick up the correct loadScriptTagFiles.js. However, if you're running GWT SuperDevMode as a Web Application using the latest GWT Plugin, the <script> tag in our root HTML page that normally loads <moduleName>.nocache.js really just triggers the delayed generation and loading of that file, and neither it nor loadScriptTagFiles.js is ever actually written to your war directory as configured in Eclipse.

More broadly stated, when SDM is run as a Web Application, all of the GWT linker output, including SmartGWT's custom linker output, is only available through the CodeServer URL (e.g. something like http://localhost:9876/<moduleName>/...), and that content is generated after the page has been loaded - so after the body of the root SmartGWT HTML page as already been run. This is part of GWT's SuperDevMode architecture, so there's no way to avoid the delayed execution.

Troubleshooting Script Tag Loading in SDM

How do you make sure the needed Smart GWT Framework script files are loaded when running SDM as a Web Application - that loadScriptTagFiles.js is valid? The easiest way is probably just to run the GWT Plugin in Legacy Dev Mode once before running SDM (and again if you change your script tags). That mode can be toggled in the GWT Plugin tab of the Run or Debug Configuration in Eclipse.

Using Script Tags in IntelliJ IDEA

You may run into problems using script tags with the IntelliJ IDEA GWT Plugin that aren't fixed by following the advice above (for Eclipse). The problem is that in IntelliJ, the loadScriptTagFiles.js file generated during GWT compilation is never persisted to the file system, even in "Legacy Dev Mode", which differs from the behavior in Eclipse.

To ensure that script tags are loaded properly, follow these steps:

  • Start "Legacy Dev Mode" just as we suggest for Eclipse
  • Create a directory for your module under the "war" directory in your project, either via an OS command shell, or via right-clicking on the "war" directory and selecting New >> Directory. The directory name must match the module name defined at the top of your GWT module file. For our BuiltInDS sample project, the name is "builtinds".
  • Open the module directory you just created in a browser (Firefox tested). You don't need the Classic GWT Plugin. For the BuiltInDS sample project, it will be at URL: "http://127.0.0.1:8888/builtinds/". You should see the file loadScriptTagFiles.js. Right click to "save link as" a file inside the module directory in the actual file system.
  • Now if you stop the server, and switch to SuperDevMode, that file should be present after the compile, and the required Framework files should get loaded.

Browser Source Map Support

Most current browsers should support source maps, required for source debugging, as discussed in Debugging: Dev Mode and Super Dev Mode. If they're not working, make sure that they're enabled in the settings of your browser's developer tools. For example, to enable them in Chrome, make sure the "Enable JavaScript Source Maps" checkbox is ticked in the Developer Tools preferences. When the page is loaded and you've hit the "Dev Mode On" bookmark, you should be able to browse the Java source in the debugger (under the "sources tab"), and set breakpoints in Java code.

Troubleshooting

Problem Possible Causes Solution
Missing GWT classes or JARs are reported when project is compiled. GWT Eclipse Plugin with GWT SDK is not installed or project was built with version different from what's configured in Eclipse and needs to be rebuilt. Install plugin (ticking checkbox for GWT SDK) from here and/or rebuild project.
Errors are reported by GWT about the "linker not supporting script tags" when your project is oompiled. The SmartGWT Linker has been enhanced to work around this issue, so you should no longer be affected by it when migrating from earlier GWT versions. Report any remaining issues at http://forums.smartclient.com.
Nothing happens when you visit the "Dev Mode On" bookmark. The GWT Code Server is not running or the bookmark is not valid. Start the Code Server or create new bookmarks from the URL displayed in the Eclipse console when the Code Server launches.
When you launch your Web Application from Eclipse as directed above, you see an error in the browser indicating the GWT Plugin is missing (and perhaps that it's not available). You've forgotten to remove the gwt.codesvr argument from the URL as we instructed above and the browser is not able to find the GWT Dev Mode Plugin. Remove the gwt.codesvr argument from the URL, or don't use the Eclipse GWT "Web Application" Run Configuration template (intended originally for Dev Mode) to launch your Web Application. You may deploy your Web Application manually outside of Eclipse.
Skins aren't loaded when the application loads, resulting in missing icons and missized controls and fonts. Failed file requests are logged by the browser, but no errors are reported by GWT in Eclipse. You've failed to set global variable isomorphicDir in the application's root HTML page, so the Framework is unable to locate the skin files. Add a <script> declaration in the root HTML page defining isomorphicDir to be "[MODULE_NAME]/sc", where the actual name of your project is substituted for the variable, as it appears in the <module> declaration in your project (gwt.xml) file.


For example, see the file 

helloworld-2.0/war/HelloWorld.html

in the "Hello World" sample for SGWT LGPL, or the file 

built-in-ds/war/BuiltInDS.html

in the "Built-in DS" sample for SGWT EE.
When the SDM Server is launched in Eclipse, the SGWT Application fails to load, resource or configuration files are reported missing, or browser errors are hit because the core Smart GWT JavaScript Framework files haven't been loaded properly. Missing symbols may be reported, such as "isc is not defined". JavaScript Framework or linker-created files are missing from the war directory, or your GWT project uses script tags, but you're not using or have not merged your app's main page from the BuiltInDS Sample Project HTML. The linkers used by GWT for SDM don't support script tags, but SGWT generates code to load them for you automatically. However, this requires that your app's HTML load the file loadScriptTagFiles.js as in the BuiltInDS Sample Project. Make sure to run the GWT Plugin in Legacy Dev Mode at least once, to install the Framework resources and generate loadScriptTagFiles.js. Then, if not already present, merge the line loading loadScriptTagFiles.js into your application's main HTML page from the BuiltInDS Sample Project. (If you hit the latter issue, please add your opinion to the GWT Issue report to help get it resolved.)
You're not able to connect to the SDM Code Server from a remote machine, even though you've launched it with -bindAddress 0.0.0.0 to enable all IP addresses to connect. You're hitting a known issue with SDM in GWT that affects any situation where the fully qualified server name is not available via DNS lookup on the client, even if you access the server by IP address. Ensure DNS lookup is available for the server on the client, or add a binding to your hosts files.
When SuperDevMode is run, Java exceptions are thrown and the server fails to start (e.g. ExecutionException, ClassNotFoundException, IllegalStateException, ...). JARs in the WEB‑INF/lib directory of the filesystem are interfering with those added by the SDM server.Remove the contents of WEB‑INF/lib at the filesystem level, using an OS shell or file explorer. SDM will auomatically populate the served content of that directory using the project classpath when it's run.
An exception involving org.objectweb.asm.ClassVisitor near the top frame is thrown in Eclipse, and the project won't run. You have a version conflict involving the asm JAR. GWT itself as well as other JARs may depend on a specific version of the asm JAR. In Eclipse, the classpath is distinct from JARs copied into your WEB-INF/lib directory, so the problem might also be that the version of asm in your classpath is right, but it should be removed from WEB-INF/lib. Fix your classpath in Eclipse to pick up the proper asm JAR version, based on your GWT version, and other JAR dependencies, such as Hibernate and Spring. If possible, Remove the asm JAR from your WEB-INF/lib directory. To verify your project JAR dependencies you can manually check Maven, or to have Maven automatically manage your dependencies, see MavenSupport. To run our BuiltInDS sample project with GWT 2.12.x, ensure asm-8.x is in your classpath but not WEB-INF/lib.

A useful discussion of some other problems and solutions related to GWT Development Mode can be found here.

See Also: