Debugging the Capsule

One of the most powerful features of AppComposer is that it allows you to run and test a project while you build it. If this were an application or an applet, you could use the Toybox feature to test what the project does. AppComposer also has features that let you test that your servlet does what you expect it to, and diagnose the problem if it does not.

This exercise uses the JSP MathProcess.zac capsule to look at AppComposer's debugging functions. If you have not built this capsule, you can use the MathProcess.zac capsule included in your AppComposer/examples/Math directory.

To turn on debugging:

1. Open the AppComposer/examples/Math/Math.zap project.
2. Double-click MathProcess.zac in the project pane to open the capsule in the workspace.
3. Click on the bug icon in the toolbar to enable debugging.
   A new window, the Debug Console, appears after a few moments.
   

The debug console provides you with clickable debugging options and displays debugging output of interest as you play, or step through, the capsule.

To set watch variables:

1. With debugging enabled, select nextValue in the capsule outline.
2. Click the Set Watch Variable button in the toolbar.
   An entry for nextValue appears in the debug console.
   

Setting a watch variable allows you to see the value of a variable as it may change throughout the execution of the program. This is particularly valuable to track the results of a certain behavior in the capsule. For instance, if you expect it to send a certain value to a variable, you can see the results at every step of the program.

As you click the step button, you can watch what effect each step of the program may have on the value in the variable. This makes it easy to track down when a particular step may not give you the results you expect.

To step through code:

1. Open Internet Explorer to http://localhost/.
2. Click the button.
   The parameters screen appears.
   
   Your servlet can process information from several parameters, and several working together will give you very different results than others. You should start out using simple values so that inaccurate or unexpected results become more obvious.
3. To see all of the parameters that the HTML page passes to the servlet, open the mathmain.html file in a text or HTML editor. If you open it in a browser, view the page's source. Look for the tags that begin with INPUT.
   
   From this, you can see that the page contains six possible parameters and the Submit button. The parameters include:

• initialValue
• endValue
• steps
• square
• reciprocal
• sine

4. Enter each of these parameter names into a field on the left of the parameters page. Enter the values shown below into the corresponding field on the right:
   
   Notice all of the different values for sine, reciprocal and square. Because the behaviors in the capsule only check that those parameters have some value, and not what the value is, any value at all should cause the capsule to perform that operation.
5. Press the Post button to send the parameter names and values to the capsule.
6. Hide the browser or move it to the side and look at the outline pane in AppComposer.

A red arrow has appeared to the left of the on output action group, indicating that execution has stopped just before executing the on output behavior (or on POST behavior if you are using the capsule included in AppComposer).

The watched variables in the Debug Console have not yet changed, because the value of nextValue has not been set yet. However, the single step and play buttons are enabled in the debug console toolbar. In addition, a new entry has appeared in the debug console named ACTIVATINGEVENT. This entry contains the content of the request that invoked the servlet capsule. Click the wedge next to ACTIVATINGEVENT and then open up its child entries to see in detail what it contains. Note the list of parameters and their values.

Click the single step button once to step to the setContent action, again to go to initialize nextValue, and one last time to get out of initialize nextValue. In the debug console, nextValue should now have a value of 2.0.

You could continue single-stepping through the capsule, but with the loops it contains, this would take a very long time. Instead, press the play button to see the results of the servlet in the browser. Your results should match the following:

Look in the DebugServer tab of the console pane to find any error messages from execution on the debug web server.

To add a breakpoint:

1. Make sure that debugging is turned on and that you can see the debug console.
2. In addition to nextValue, set currentValue as a watch variable.
3. Select the behavior in the outline where you want to add a breakpoint. For this example, choose increment current step.
4. In your browser, go back to the parameters page and press Post.
   The debug console window activates its controls.
5. Press the Play button in the debug console. AppComposer runs until it hits your breakpoint, and then stops. See how the values of your variables have changed.
6. Because you set the breakpoint inside of a loop, you can check these values for each loop iteration. Press Play again.
   The loop repeats once, stopping a second time at your breakpoint.

To remove a breakpoint:

1. Select the behavior in the outline whose breakpoint you want to remove.
2. Click from the tool bar or choose Clear Breakpoint from the Capsule menu.
   AppComposer removes the selected breakpoint.

You can also remove all of the breakpoints from your capsule at once. To do so, select Clear all Breakpoints from the Capsule menu.

Those are the basics of using the AppComposer debugger. Experiment with different values and setting watch on different variables to see what happens. You can introduce a deliberate error, such as writing "two" for initialValue instead of 2. Try leaving some of the parameter values blank.

Congratulations! You have finished parts one and two of the Introductory Tutorial. AppComposer has a large feature set and introduces a new framework for building applications, so we have provided many more tutorials, reference guides, examples, and concepts overviews to help you use it to its full extent. Clicking the Next Section button below takes you back to the main tutorials page, where you can branch to lessons on using EJBs and connecting to databases with AppComposer. At any time, you can access the documentation set from AppComposer's Help menu.