Table of contents
- How it works (under the hood)
- How to use it
- Limitations and future improvements
How it works (Under the hood)
Accordingly, remote debugging support for Jaggery is enabled by embedding the Rhino debug support of JSDT feature into the Jaggery server. From the several bundles provided by JSDT debug support for Rhino, we have used two bundles namely, org.eclipse.wst.jsdt.debug.rhino.debugger and org.eclipse.wst.jsdt.debug.transport in the Jaggery server. Eclipse UI is used as the UI for Jaggery debugging as well. org.eclipse.wst.jsdt.debug.rhino.debugger makes use of the Rhino to evaluate and debug the scripts via Eclipse and org.eclipse.wst.jsdt.debug.transport handles the communication between the client-end; the Eclipse UI and the server-end, which is the Jaggery server.
So what about the Jaggery Scope and Context? As mentioned above, embedding the Rhino debug support allows us to attach the debugger instance to our own Scope and Context. Therefore, the debugger embedded in the Jaggery server uses Scope and Context that's specific to Jaggery in order to evaluate the scripts.
Now that the Jaggery debugging support is available, let's see how we can make use of it. The following section consists of a guide on how to use the debugger, including some tips and tricks to make it more effective.
How to use it
Both the client and server side need to be configured before you can start the debugger and run the Jaggery scripts.
- Navigate to the plug-ins directory of your Eclipse installation and locate following jars.
Note: Make sure that you have the exact same versions of these jars as different Eclipse distributions have different versions. Currently, we provide support only to the above-mentioned versions.
- Extract jaggery-0.9.0-SNAPSHOT_ALPHA2.zip to a directory you prefer. Let's call it JAGGERY_HOME.
- Copy the above-mentioned jars into JAGGERY_HOME/carbon/repository/components/dropins directory.
- Deploy the Jaggey app that you want to debug in the Jaggery server.
- In Eclipse go to File > New > Other.
- In the next dialog box select 'Create project from existing resource' and browse to the Jaggery app deployed in the Jaggery server. It is preferable to name the Eclipse project as same as the existing Jaggery app. Then click on Finish.
This will automatically create a copy of the project in Eclipse workspace.
- In Eclipse, go to Windows > Preferences.
- Open General > Content Types in Preferences dialog box.
Note: You will notice error markings in the scripts of the new Jaggery project. In order to avoid that, simply comment out the <% and %> characters in the scripts. Moreover, note that scripts containing HTML content cannot be debugged using this debugger. The reasons are explained in the "Limitations and Future Improvements" section below.
At this point, you would have got the background set for debugging. The next step is to configure the debugger in the Eclipse IDE.
Configuring the Eclipse IDE
- Mozilla Rhino - Attaching Connector should be selected as the connector.
- Fill in the hostname and the port number of the host where the debugger is running.
- Switch to the Source tab, remove the Default project and add the project that you want to debug.
- Set breakpoints as required.
- Change settings to Suspend For All Script Loads (optional).
Starting the debugger
- Navigate to JAGGERY_HOME/bin.
- Run sh ./server.sh -DjsDebug=<port> command to start the server in debug mode.
- Point the browser url to https://localhost:9763/apps/<project_name>/<file_name>.jag. Then the page will remain without loading until the debugger client is connected.
- Go to the Eclipse IDE and launch the newly created debug configuration.
You will be able to see the server starting up in the terminal and the Eclipse IDE will pop to the front as the server will start the execution of the script set to be debugged. From here onward, you can follow the same process as in Java Remote debugging.
You will be able to use the 'Variables' tab and the 'Expressions' tab in the Debug view to evaluate expressions, as shown in the figure below.
Limitations and future improvements
Different distributions of the Eclipse IDE as well as different versions use different versions of org.eclipse.wst.jsdt.debug.rhino.debugger and org.eclipse.wst.jsdt.debug.transport jars. Currently, we are only supporting the versions on the Eclipse Java EE IDE for Web Developers: Juno Release. We are hoping to overcome this limitation as well.
Jaggery, which facilitates a developer-friendly way of writing web applications, is still in its early stages. Therefore, we are in the process of expanding it with new features and of course providing the tooling support. Enabling the debugger support in Jaggery is the beginning of tooling support and there is much room for improvement. The good news is that the Jaggery team is working towards providing editor support for Jaggery in the Eclipse IDE. With proper editor support in Eclipse, we would be able to extend the capabilities of this debugger to overcome the above-mentioned limitations.
Sameera Jayaratna, Trainee Software Engineer, WSO2 Inc