Package com.smartgwt.client.docs

Interface SuperDevModeTroubleshooting

public interface SuperDevModeTroubleshooting

Troubleshooting GWT Development Mode (formerly Super Dev Mode)

This topic provides details on configuring and running Development Mode and troubleshooting any problems. For an overview, including a discussion of the difference between the new Development Mode (formerly known as Super Dev Mode) and Legacy Development Mode, see Debugging: Development Modes in GWT. Note that GWT 2.6.x is the minimum supported GWT version as of SmartGWT 6.1.

Development Mode in GWT 2.7.0+

The recommended way of running (Super) Dev Mode in GWT 2.7.0+ is by installing the GWT Eclipse Plugin and launching the Super Dev Mode Server using a GWT Development Mode (DevMode) Run Configuration (if using GWT Plugin v3) or a Web Application Run Configuration (if using GWT Plugin v2). In the remainder of this troubleshooting overview, we'll use Web Application as a generic term to refer to your Run Configuration, no matter which GWT Plugin version you have.

For more guidance beyond the overview in the links above, see Using GWT with Eclipse. Note that this approach can also be used with GWT 2.6.x if you have installed GWT Plugin 2.7.0 or newer - or you can use the approach below.

Super Dev Mode in GWT 2.6.x and Earlier

For GWT releases before GWT 2.7.0, you must run the Code Server directly. It can be launched in Eclipse (with or without a web server), or you can launch it from the command line. Unless a web server is launched in Eclipse with the Code Server, you'll need to deploy the SGWT Web Application separately from the Code Server.

At this point, it's assumed that you have installed the GWT Eclipse Plugin, and that you already have an Eclipse Project containing your Java code with a valid classpath picking up the SGWT JARs and the GWT SDK Library (perhaps the same project you use for Dev Mode).

Creating a Run Configuration for the Code Server

You must first create a new Run Configuration for the GWT Code Server. To do this:

  • Right Click / Run As... / Run Configurations
  • Select "Java Application", and hit the "New" button
  • Set the title (very top) to something you'll remember
  • Set the "Main class" to com.google.gwt.dev.codeserver.CodeServer
  • If using GWT 2.6.1 or earlier, then in the "Classpath" tab, add gwt-codeserver.jar using the "Add External Jar" button
  • 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

For the required JAR above, you can either download a version of the GWT SDK and extract the needed JAR, or locate it in your Eclipse installation (from the GWT Plugin). Additional arguments beyond those mentioned in the last step above are supported in the "Arguments" Tab, such as specifying a port, bind address, etc. Your Run Configuration should now be complete.

Configuring your GWT Project

A few additions to your GWT Project must be made if you're using a GWT SDK version older than 2.7. (They are included as comments in the "Built in DS" sample GWT Project, BuiltInDS.gwt.xml.) If you're running GWT SDK 2.6 or older, you must add:

<add-linker name="xsiframe" />

Running the Code Server

At this stage you should be able to start the code server:

  • Right Click / Run As... / Run Configurations
  • Select the new configuration you added

You should see a bunch of logging in the console tab of Eclipse, followed by a URL. Visit that URL in your browser, and drag the "Dev Mode On" and "Dev Mode Off" buttons up to your browser bookmarks toolbar. These bookmarks allow you to easily switch to Super Dev Mode (recompiling your Web Application) or switch back to Production Mode.

Deploying your Web Application

You should now launch the "Web Application" Run Configuration that it was suggested you use - the simplest way is to Right Click on the Project / Run As / Web Application. Visit the URL generated by Eclipse, without the gwt.codesvr parameter. You may see a warning about needing a recompile - you can either ignore this or run a full compile once to get rid of it. (If you've deployed your Web Application manually outside of Eclipse, this section can be skipped.)

Entering Super Dev Mode

Visit the Production Mode URL of the running Web Application. The bookmarks created earlier can now be used to enter Super Dev 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 Super Dev Mode using the "Dev Mode On" bookmark.

Super Dev Mode in Java 9+

Starting with Java 9, it has been reported that the built-in Jetty server used by the GWT Plugin v3 no longer works, even with the latest GWT SDK 2.8.2, throwing either a ClassNotFoundException or NoClassDefFoundError, and potentially reporting, "Found resouce but unrecognized URL format." Java 8 is still receiving updates, but may not be an option due to Oracle's new licensing requirements.

Until the GWT Plugin v3 is updated, one solution is to use Tomcat Web Server as a replacement for Jetty. You can read how to set up the GWT CodeServer to work with Tomcat here. You can also add a comment to the GWT Jetty bug report to let them know you're affected.

Script Tags in Super Dev Mode

The official GWT Super Dev Mode linker (the default linker in 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. This won't work if you're running SuperDevMode in GWT 2.6.1, since the non-SDM linker for that release accepts script tags and thus Legacy Dev Mode doesn't generate loadScriptTagFiles.js. In this case you should either run SDM using the older CodeServer approach, or you can navigate to the generated loadScriptTagFiles.js file (after you've attempted to run SDM at least once) using the URL http://localhost:9876/<moduleName>/loadScriptTagFiles.js, and "save as" the page into your Eclipse war directory.

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.
Error reported: "Could not find or load main class com.google.gwt.dev.codeserver.CodeServer". In GWT 2.6.1 and earlier, adding the GWT SDK library to your project's build path doesn't automatically add the gwt-codeserver.jar (included in the GWT SDK zip) to the build path. Add gwt-codeserver.jar as a separate JAR to the project build path.
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.
No GWT projects are found/available for recompiling when the modal dialog opens from clicking "Dev Mode On" bookmark, and you're running GWT 2.6 or earlier. Needed lines of the GWT Project file (gwt.xml) are missing or commented. Read section "Configuring your GWT Project" above and uncomment the appropriate gwt.xml lines based on your GWT version, or copy them from BuiltInDS.gwt.xml
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.)
Alternatively, you may run the Code Server Java app directly (even in GWT 2.7.0) rather than using the GWT SDM Server. See the instructions above provided for GWT 2.6.x and ealier.
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.9.0, 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 Super Dev Mode can be found here.

See Also: