The Vaadin Wiki is temporarily in read only mode due to large recent spam attacks.
Debugging Vaadin applications
Debugging your Vaadin application #
It is everyday for all programmers. The nice piece of code is complete, deployed and ready to go. The only problem is it does not work and nobody understands why. Time to fire up the debugger and see what is really going on.
Server side and client side code #
Debugging Vaadin is closely related to debugging any java application. There are a few differences though, depending on if you are debugging server side or client side code.
Although both the server and the client side is written in java the approach to debugging them slightly differs.
Things to keep in mind #
Vaadin is a server side framework so applications are run on the server side and the state is also stored on the server side. The browser only acts as a presentation layer, showing what the server tells it to show and sends events when the user interacts with the application. This means that none of your code is necessarily run on the server even if you refresh your browser. Refreshing the browser will just cause the server to resend the state of the application so it can be presented.
If you want to initialize a new application you can add the
?restartApplicationparameter to the url. This will force the server to forget the (possibly) existing application and initialize a fresh one. This ensure for instance that a new Application instance is created and the init() method is executed.
Vaadin applications are by default Serializable (unless you add an instance of a class that does not implement Serializable). This means that even if you restart the application server, it will store the application state before shutting down and restore it when starting up. So if you restart the server you will still use the old application instance when you refresh the browser and continue where you left off.
The Vaadin debug window #
The Vaadin debug window is a built in feature that can be useful for viewing communication between server and client, analyzing the layouts in the application, viewing error messages and more. To show the debug window you need to ensure two things
- The application is not running in production mode. (The context parameter "productionMode" is not set to true in web.xml).
- You have added "?debug" to the application url. (Remember that if you use both debug and restartApplication you should separate them with "&", not "?" e.g., ?debug&restartApplication).
Debug console #
The debug window that will popup automatically contains a console where some informational messages are printed and client side errors if they occur. The console will also show the data going to the server and the response from the server. The console will also show any messages you write to it in a widget using the ApplicationConnection.getConsole().log() method. After every response from the server the browser will render the changes to the screen and then output a summary row: "Processing time was 837ms". This is the time it took for the browser to render the changes that were sent by the server.
After the first request (e.g., after a browser refresh) the console will also show you information about the version of the vaadin jar you are using (Vaadin application servlet version: 6.2.2) and the Vaadin version that was used to compile the widget set (Widget set is built on version: 6.2.2). If these two do not match you have a problem that you should solve before moving any further. Either recompile your custom widgetset using the same Vaadin version you are using or make sure you don't have any widgetset files extracted from an old jar file laying around. The debug window will also show you a warning if the theme you are using belongs to a different version of Vaadin. Again, if this happens, remove any old theme files or replace them with the same version you are using.
Functions in the debug window #
The debug window contains four buttons: "Clear console", "Restart app", "Force layout", "Analyze layouts".
"Clear console" does exactly what it says: clears the debug console. Usually quite a lot of messages are printed to the console so you might want to clear it to be able to find the information you are looking for.
"Restart app" is a helper for you to restart the application. It will add the "restartApplication" flag to the URL and refresh the page.
"Force layout" causes the Vaadin application to recalulate the sizes of layouts and components. This can be useful if you are editing CSS using a tool like Firebug and want to add borders or similar to a component. Adding borders will cause the component to appear clipped and this can be fixed by pushing "force layout".
"Analyze layouts" is a really useful tool when the application does not look like you expected. It will analyze the component hierarchy in the application and print out any invalid layouts it finds. Invalid in most cases mean that there is a component with relative width/height inside another component that does not define width/height. An undefined dimension in Vaadin typically means that the child determines the dimension and a child being 100% wide/high means that the parent determines the dimension. As a result the inner component typically gets rendered as 0px wide/high (i.e., invisible).
Debugging the server side #
The debug window will mostly help you find layouting issues in your server side code. For other problems you need a real java debugger, like Eclipse or any other debugger you might prefer. Using the debugger the server side code is very straight forward to debug. It is simply a matter of starting your deployment server in debug mode. If you are running a local server from Eclipse this is accomplished through the server view -> debug or by selecting your project and choosing "Debug..." => "Debug on Server". For stand alone or non local servers, see below.
Now that you have your server running in debug mode you can set breakpoints in your code. Restart your application (remember that refresh does not restart the application), click a button or do whatever you want and watch the execution stop and the debugger to pop up. If you are stuck with a problem that you suspect could be a problem in Vaadin, remember that nothing prevents you from stepping into Vaadin code to see if you spot the problem. The source for Vaadin is included in the jar in your project.
If you are having problems with an exception occuring (typically a NullPointerException) remember that you can also set exception breakpoints. These will be triggered whenever an exception of that type occurs. This makes it easier to find the actual line the exception occurs on, instead of trying to step through the code until the exception occurs. Do note that by using an exception breakpoint you might get a lot of extra hits as some code relies on exceptions being thrown and caught and the debugger will break for all these. This can sometimes be avoided by specifying that you only want the break to occur for "uncaught" exceptions.
Stand alone or non local server #
If you are not running the server from an IDE or not even locally the above methods of starting the server in debug mode will not work. In this case you can typically enable remote debugging in the server startup script so you can debug the code remotely (using e.g. the Eclipse debugger). Remote debugging can be enabled in the JVM by a few JVM parameters that you set when starting the server (or any java program for that matter):
-Xdebug -Xnoagent -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=8000
This will tell the JVM to start listening for a debug connection using the Java Debug Wire Protocol (jdwp). It will start listening for incoming debug connections on port 8000 (address=8000) automatically. All you need to do now is to fire up Eclipse (or your favorite debugger) and create a remote debug connection. For a remote debug connection you need to know the ip or hostname of the machine running the program (localhost if running on the same machine) and the port that is listening for the debug connection, 8000 in the example. The debugger will then connect to the JVM running in debug mode and will break at your breakpoints. Note however that you need, as always, make sure your local source is in sync with the classes running on the server. Otherwise you will not be debugging what you think you are debugging.
Client side #
Stack traces in the debug window #
When the widgetset is compiled using "Pretty" or "Detailed" you will see the same error and a similar stack trace but now with the real method names so it will be a lot easier to see where the error is really coming from.
Debugging using GWT Development Mode #
The easiest way to debug the client side (for Java developers at least) is to use the GWT Development Mode. This enables you to run the application in your standard browser (IE/Firefox/Chrome/Safari) and be able to debug the client side Java code just like you would debug the server side code (setting breakpoints, inspecting variables, stepping through code etc.).
Starting GWT Development mode:
- If using Eclipse: Open project properties -> Vaadin and select "Create development mode launch". This will create a launch configuration for the GWT Development mode for the selected project. You can find the launch configuration in "Run -> Debug configurations.." with the name "GWT development mode for <project name>".
- If you want to run GWT Development mode manually you can run
"com.google.gwt.dev.DevMode -noserver -war war/VAADIN/widgetsets com.example.myproject.widgetset.MyProjectWidgetset". Be sure that gwt-user.jar, gwt-dev.jar and the SOURCE folder where your client side java code is located is on the classpath.
GWT Development mode will start a Development mode window that might tell you "No startup URLs provided". This is perfectly ok. To avoid it you can add a -startupUrl parameter to your launch configuration.
When GWT Development mode is up and running, open the normal application URL in your browser but add a "gwt.codesvr=127.0.0.1:9997" parameter at the end of the URL, for instance "http://demo.vaadin.com/sampler/?gwt.codesvr=127.0.0.1:9997". The application will now be opened and the client side code loaded through the GWT Development mode server. Opening the application might take a while as GWT Development mode first recompiles the widgetset.
You are now free to set breakpoints and debug like you otherwise would. When hitting a breakpoint the browser will freeze until you continue running. Setting a NullPointerException breakpoint typically helps to find problems that appear as "this.n is null" in the debug window.
Note: GWT Development Mode is available in Vaadin 6.3.0/GWT2.0 newer. For Vaadin 6.2 see the article about OOPHM to set up the debug mode.