Introduction

Jaggery makes life easy for a web app developer by providing a simple programming model [1]. It simply does everything in JavaScript. However, many developers using Jaggery have been faced with difficulties due to the lack of support of a proper editor and a debugger for Jaggery. Now, we have solved these issues to some extent by providing a basic debugger for Jaggery via Eclipse IDE, with an editor on the way. Moreover, complete editor support in IntelliJ IDEA for Jaggery is now available. The ability to control the execution of your web application and find bugs is a feature you would always like to have. The debugger we have provided will ease some pain of having to use 'print()' statements everywhere to evaluate some expression in your app. Currently, Jaggery provides you this feature through the Eclipse IDE. It means that the Jaggery server allows you to remotely debug the Jaggery scripts via the Eclipse IDE. This feature is implemented with the Rhino JavaScript Debugger support in Eclipse IDE. Currently, this feature is compatible with the Eclipse Java EE IDE for Web Developers: Juno Release.

Applies to

Table of contents

• Background
• How it works (under the hood)
• How to use it
• Limitations and future improvements

Background

Jaggery makes use of Mozilla Rhino[2] to get the scripts compiled and then converts JavaScript (.jag) files into compiled Java classes. Therefore, the main focus of this debugger implementation was to make use of any existing Rhino JavaScript debugging capabilities.

Rhino has a JavaScript debugger[3], which is a GUI that allows debugging of interpreted JavaScript scripts that run in Rhino. This debugger itself is a Java program. The Rhino JavaScript Debugger can debug scripts running in multiple threads and allows to set and clear breakpoints, control execution, view variables, and evaluate JavaScript code in the current scope of an executing script. But this debugger can only debug pure JavaScript content run in Rhino as it uses default JavaScript Scope and Context. Therefore, it cannot be directly used to debug Jaggery, which has its own syntax and Context.

Then there is the JSDT (JavaScript Development Tools) feature in the Eclipse IDE[4], which provides the support for the Rhino JavaScript Interpreter. This feature facilitates local and remote debugging of JavaScript using Rhino. One of the usages of the Rhino debug support in JSDT is that it can easily be embedded into an existing server[5]. Support is actually given to both the client and server side, thus we can setup Rhino debugging in our own server, and we can connect to a server that's already running the Rhino debugger. Embedding the Rhino Debugger allows to remotely control the loading and execution of scripts from the Eclipse IDE.

The server-side requires a bit of configuration and some custom coding to get the debugger working as required. This custom coding enables the creating of a new RhinoDebugger instance and attaching it to a Rhino JavaScript Context as required. Therefore, embedding the Rhino Debugger in the Jaggery server facilitates the implementation of the Jaggery Debugger.

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.

Server side

1. Navigate to the plug-ins directory of your Eclipse installation and locate following jars.
   • org.eclipse.wst.jsdt.debug.transport-1.0.100.v201109150330.jar
   • org.eclipse.wst.jsdt.debug.rhino.debugger-1.0.300.v201109150503.jar

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.

2. Extract jaggery-0.9.0-SNAPSHOT_ALPHA2.zip to a directory you prefer. Let's call it JAGGERY_HOME.
3. Copy the above-mentioned jars into JAGGERY_HOME/carbon/repository/components/dropins directory.

Client side

1. Deploy the Jaggey app that you want to debug in the Jaggery server.
2. If you do not have the Jaggery app as an Eclipse project, you can create a new JavaScript Project from an existing source using your Jaggery app, or else skip to Step 3.
   
   1. In Eclipse go to File > New > Other.
   2. In the dialog box select JavaScript project and click Next.
   3. 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.

3. If you already have the Jaggery app as an Eclipse JavaScript project, import that project into your current Eclipse workspace. Save a copy of the project in the workspace (select 'Copy projects into workspace' option when you are importing).
4. Set the JavaScript editor as the default editor for .jag files.
   
   1. In Eclipse, go to Windows > Preferences.
   2. Open General > Content Types in Preferences dialog box.
   3. Under Content types select Text > JavaScript Source File. It will contain only .js under File associations. Add a new File association as .jag.

    

   

    

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

1. Create a new Remote JavaScript launch configuration. In order to do so
   
   1. Open Debug Configurations dialog and double-click Remote JavaScript launch configuration to create a new one and fill required fields.
   2. Mozilla Rhino - Attaching Connector should be selected as the connector.
   3. Fill in the hostname and the port number of the host where the debugger is running.

    

   

    

    

   4. Switch to the Source tab, remove the Default project and add the project that you want to debug.

    

    

   

    

2. Set breakpoints as required.
3. Change settings to Suspend For All Script Loads (optional).

Starting the debugger

1. Navigate to JAGGERY_HOME/bin.
2. Run sh ./server.sh -DjsDebug=<port> command to start the server in debug mode.
3. 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.
4. 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

As mentioned earlier, currently there is no editor support for Jaggery in the Eclipse IDE. Therefore, we are using the default JavaScript editor in Eclipse for now. As you would expect, this JavaScript editor only supports default JavaScript syntax. But Jaggery has <% and %> characters, which the editor cannot properly identify. Therefore, in the scripts that are in the workspace copy of the app, the above-mentioned characters need to be commented out. Otherwise, you will not be able set any breakpoints on the scripts. However, you need not make any changes in the scripts deployed in the Jaggery server.

As same as JavaScript, Jaggery also can be embedded in HTML content. But as we are using the JavaScript editor, we cannot use this debugger to debug Jaggery content embedded in HTML. We are hoping to enable it once we complete the Jaggery editor for the Eclipse IDE.

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.

Conclusion

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.

Resources

[1] https://jaggeryjs.org/index.jag

[2] https://wiki.eclipse.org/JSDT/Debug/Rhino

[3] https://wiki.eclipse.org/JSDT/Debug/Rhino/Embedding_Rhino_Debugger

[4] https://jaggeryjs.org/howto.jag

Author

Sameera Jayaratna, Trainee Software Engineer, WSO2 Inc