The Visual Debug of Web Projects
From WebRatio WebML Wiki
|
|
Contents |
Introduction
From the WebRatio 6.1 it's possible to debug the Web application directly in the Web Model, adding breakpoints on the Web Model elements and verifying step-by-step the execution of every single element through WebRatio itself. In order to visual debug a Web application, it' neccesary to use a properly configured Web server, to create a debug configuration in WebRatio and add at least one breakpoint to the Web Model. When the debug configuration is executed, WebRatio connects to the Web server and, when the breakpoint is met, the visual debug stop the execution at the breakpoint, enabling the step-by-step execution and the parameters inspection.
Instrumenting a Web Server for Debug
Even though the Tomcat installed in bundle with WebRatio is already configured for visual debug, any Web server which publishes one or more Web applications developed using WebRatio can be easily instrumented in order to provide support for debugging. This is done by ensuring that the following Java system property is added to the JVM command line used to start the Web server:
com.webratio.rtx.debug=true
For instance the Tomcat web server can be instrumented adding the following line at the beginning of the catalina.* scripts:
set CATALINA_OPTS=%CATALINA_OPTS% -Dcom.webratio.rtx.debug=true (for catalina.bat) CATALINA_OPTS="$CATALINA_OPTS -Dcom.webratio.rtx.debug=true" (for catalina.sh)
It's important to notice that for performance and security reasons Web servers used in production must not be instrumented for visual debug.
Creating a debug configuration
A debug configuration is simply an element that allows WebRatio to connect to a Web server for Web application debugging. To create a debug configuration, you simply need to:
- click on Run -> Debug configurations...
- in the opened dialog select Web Application in the left hand list of launch configuration types, and press the New button in the toolbar.
This will create a new debug configuration for a Web application.
The control panel on the right hand side allows you to control specific aspects of the debug:
- In the "Project" field select the Web project to debug.
- If the "Use Custom Connection Properties" checkbox is selected, it is possible to specify the following properties:
- In the "Host" field type the IP address or domain name of the host where Web application is running. If the program is running on the same machine as the WebRatio IDE, type localhost.
- In the "Port" field type the port where the Web server is accepting HTTP connections. Generally this port is specified in the configuration file of the Web server (e.g. $TOMCAT_HOME$/conf/server.xml).
- In the "Application" Name field type the context path under which the Web application is deployed. If empty, the context path is extracted from the Output Path property of the selected Web project.
- In the "Debug Port" field type a specific port number to be used for sending and receiving debug information. If empty, a random port will be used. Note that abovementioned HTTP port and the debug port are not the same: the former is used to estabilish the very first connection whereas the latter is used throughout all the debug session.
- If the "Use Custom Connection Properties" checkbox is not selected, the following properties are used:
- Host=localhost
- Port=8080
- Application Name: extracted from the output path specified in the Web model
- Debug port: randomly selected among the available dynamic ports
Defining Breakpoints in Web Model
A breakpoint suspends the execution of a Web application at the location where the breakpoint is set.
Breakpoints can be enabled and disabled via the context menu in the Breakpoints View, or via the context menu of specific elements (pages, units, jobs and operation modules) in the Web Project editor.
An enabled breakpoint causes a thread to suspend whenever the breakpoint is encountered. Enabled breakpoints are drawn with a blue circle. A disabled breakpoint will not cause threads to suspend. Disabled breakpoints are drawn with a white circle. Breakpoints are displayed in the left boundary of model elements and in the Breakpoints view.
Adding Breakpoints
Breakpoints are set on specific model elements of a Web application: pages, units, jobs and operation modules.
To add a breakpoint, simply right-click on the model element where you want to add the breakpoint, expand the Breakpoints sub-menu and select one of the available breakpoint types. A new breakpoint marker appears on the left boundary of the element where you added the breakpoint.
While the breakpoint is enabled, thread execution suspends when the breakpoint is met and the element where the breakpoint was set is highlighted in the Web model editor in the Debug Perspective.
Disabling breakpoints
Breakpoints can be enabled and disabled as needed. When a breakpoint is enabled, thread execution suspends before the step is executed. When a breakpoint is disabled, thread execution is not suspended by the presence of the breakpoint.
To disable a breakpoint in the Breakpoints View:
- Open the breakpoint's context menu and select Disable, or deselect the breakpoint's checkbox.
- The breakpoint image will change to a white circle and its checkbox will be empty.
To enable the breakpoint in the Breakpoints View:
- Open the breakpoint's context menu and select Enable, or select the breakpoint's checkbox.
- The breakpoint image will change back to a blue circle, and its checkbox will be checked.
Removing Breakpoints
Breakpoints can be easily removed when are no longer needed:
- In the editor area, open the Web model where you want to remove the breakpoint.
- Move to the site view, service view or module view of interest.
- Right-click on the model element where you want to remove the breakpoint, expand the Breakpoints sub-menu and select one of the checked breakpoint types. The breakpoint is removed from the element. You can also double-click directly on the breakpoint icon to remove it.
Breakpoints can also be removed in the Breakpoints View. Select the breakpoint(s) to be removed and from the context menu select Remove. All breakpoints can be removed from the workbench using the Remove All action in the context menu of the Breakpoints View.
If you find yourself frequently adding and removing a breakpoint in the same place, consider disabling the breakpoint when you don't need it (using the Breakpoints View) and enabling it when needed again.
Breakpoints View
The Breakpoints View lists all the breakpoints currently set in the workspace.
In the Breakpoints View it's possible to double-click on a breakpoint to display its location in the editor (if applicable) or enable or disable breakpoints, delete them, add new ones, group them by working set, or set hit counts.
Debugging a Web application
Once the Web server, the debug configuration and the breakpoints in the Web Model are correctly configured, it's possible to debug the Web application. During the execution of the Web Application, when a breakpoint is encountered, the thread (the execution of the Web application) will suspend it's execution and enables the debug. In WebRatio, the Debug Perspective is shown, allowing to control the execution step-by-step. When a thread is suspended, the step controls can be used to move through the execution of the application step-by-step. If a breakpoint is encountered while performing a step operation, the execution will suspend at the breakpoint and the step operation is ended. The step controls are:
- Step Over
- Select a stack frame in the Debug View. The current step of execution in that stack frame is highlighted in the editor in the Debug Perspective.
- Click the Step Over button in the view toolbar, or press the F6 key. The currently-selected step is executed and suspends on the next executable step.
- Step Into
- Select a stack frame in the Debug View. The current step of execution in the selected frame is highlighted in the editor in the Debug Perspective.
- Click the Step Into button in the view toolbar, or press the F5 key. The next expression on the currently-selected step to be executed is invoked, and execution suspends at the next inner executable step.
- Step Return
- Select a stack frame in the Debug View. The current step of execution in the selected frame is highlighted in the editor in the Debug Perspective.
- Click the Step Return button in the view toolbar, or press the F7 key. Execution resumes until the next external step is reached.
During the step-by-step execution it's possible to check the execution of every single element. In the Variables View are displayed all the following Information:
- Remote Request:containing all the information of the Request
- Page Form: when debugging a page, its form is displayed in this section
- Execution Context:the data concerning the unit executed
- Session Context:the data contained in the Session
- Unit Inputs: when a Unit is going to be executed, its input is displayed in this section
- Unit Results: after the execution of a Unit, its output is displayed in this section
In this section is possible to change the values of the Units in order to modify the result of the execution in real time.
Examples
Debugging a page execution
In order to debug the execution of a page, along with the single Units within, simply right-click on the page and select Breackpoints -> Begin of Execution (choose End of Execution if it's necessary to check only the result of the execution, just before the display of the page) and then launch the Debug Configuration.
When the Page is accessed then the navigation will stop activating the debug in WebRatio (if not opened, a message will ask to switch to the Debug Perspective).
Now we can proceed step-by-step in the execution of the Page and every single Unit.
It's also possible to check the input and output parameter of every single element, with the possibility to change the values, veryfing the result.
Debugging a Unit execution
By right clicking on a single Unit and selecting Breakpoints -> Begin of Execution (choose End of Execution to check only the results of its execution) it's possible to debug its execution.
The debug is activated when the breakpoint is met, switching to the debug perspective, allowing us to inspect the parameter of the Unit execution.
Debugging a Job
Breakpoints are placeable even on Jobs. This cause the debug configuration to start when the Job is activated.
