com.smartgwt.client.docs

Interface SuperDevModeTroubleshooting

public interface SuperDevModeTroubleshooting

Troubleshooting Super Dev Mode

This topic provides details on configuring and running Super Dev Mode, and troubleshooting any problems. For an overview see Debugging: Dev Mode and Super Dev Mode.

Super Dev Mode in GWT 2.7.0+

The recommended way of running Super Dev Mode in GWT 2.7.0+ is by installing the GWT (Super) Dev Mode Plugin and launching the Super Dev Mode Server using a Web Application Run Configuration. For more guidance beyond the overview in the previous link, 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" />

and if you're running GWT SDK 2.5 or older, you must also add:

<set-configuration-property name="devModeRedirectEnabled" value="true" />

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.

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 Classic 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 Classic 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.

Browser Source Map Support

As discussed in Debugging: Dev Mode and Super Dev Mode, not all browsers and debuggers at this time support the Source Maps feature that's required to set breakpoints for Super Dev Mode. 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 can 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.
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 Classic 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.

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