Eclipse Debugging¶

Because many classes in the Mulgara project are generated from config files, these need to be made available to Eclipse. There are several ways this could be handled, but because these files are not changed often and the build process is hella complicated, I created a fairly straightforward approach. Once you do a check out (either through Ecilpse or CLI), do a "build.sh clean ideSupport" (or build.bat if you are on Windows) to generate an ideSupport.jar in the dist directory. This contains almost all of the generated files needed to run an instance of Mulgara in a debugger. Note that this will be very helpful in NetBeans/IDEA as well, but I haven't generated projects for those.

Once you run the ideSupport target, do a refresh in Eclipse. You should only have a single error after this in a Descriptor test because a SOAP binding isn't being generated. I don't want to spend any more time on this now, but I'll fix it later if no one else does.

If you are down to only the three errors related to this Descriptor issue, you should be able run/debug Mulgara through org.mulgara.server.!EmbeddedMulgaraServer (which is in src/jar/server/java).

Debugging the Client or Server¶

Mulgara execution involves a client that parses a query and sends this to a server, and a server with accepts a parsed query, executes it, and returns the result to the client.

Debugging is usually required on a server, though there are instances when debugging on the client is required. In each case, it is necessary to run one side of the system from a command prompt, while running the other side from Eclipse.

To run either end from the command prompt, the full distribution must be built:

  $ build.sh dist

Of course, on Windows systems, use build.bat instead of the shell script build.sh.

To debug the client:

• Copy dist/mulgara-x.y.z.jar to a working directory.
• In that directory, start the server with the command: java -jar mulgara-x.y.z.jar
• Create and run a debug target in Eclipse:
  • Select Open Debug Dialog... (available in the "debug" dropdown on the tool bar, or else from the Run menu).
  • Select Java Application in the list on the left of the dialog, and press the New Launch Configuration button in the top left, to create a new debugging target.
  • Give an appropriate name to the target, and set the Main class: field to: org.mulgara.itql.!TqlSession (the last version of Mulgara used org.mulgara.itql.!ItqlSession here)
  • Press the Apply button to save. The target may be run by pressing Debug in this dialog, or by selecting it from the debugging button in the tool bar.
• Make sure you have set any appropriate break points in the client classes before running!
• If you need to restart the server in a clean state, press Ctrl-C on the server terminal, and after it has quit remove the server files with: rm -rf server1 _{(shell command)}. The server can be restarted as described above.

Debugging the server is similar:

• Copy dist/itql-x.y.z.jar to a working directory.
• In that directory, start the client with the command: java -jar itql-x.y.z.jar
• Create and run a debug target in Eclipse:
  • Select Open Debug Dialog... (available in the "debug" dropdown on the tool bar, or else from the Run menu).
  • Select Java Application in the list on the left of the dialog, and press the New Launch Configuration button in the top left, to create a new debugging target.
  • Give an appropriate name to the target, and set the Main class: field to: org.mulgara.server.!EmbeddedMulgaraServer
  • Press the Apply button to save. The target may be run by pressing Debug in this dialog, or by selecting it from the debugging button in the tool bar.
• Make sure you have set any appropriate break points in the client classes before running. Once the appropriate command is issued in the client program, the server should break.

Debugging Scripts¶

The JXUnit scripts are a set of integration tests where TQL commands are sent to the server and the responses compared to a set of pre-determined outputs. The scripts are all encoded into XML files called test.jxu and are found in subdirectories of the jxdata/iTQL directory. The expected outputs for each test script are stored in text files in the same directory as the script.

When the scripted tests are run, an Ant target called jxtest-data copies the entire contents of jxdata into a new directory called jxtest, setting any variable components of the scripts as it does so (eg. the tag server is replaced with the current IP address, and baseuri is replaced with the URL of the base directory for the project). A server is then started, and the tests can be run.

Run these tests in Eclipse is similar to debugging a client:

• From the command line, run build.sh jxtest-data. This will need to be re-run if the clean target is ever called, or the server changes name (such as when a notebook moves networks).
• Select Open Debug Dialog... from the Run menu.
• Select JUnit in the list on the left, and press the New Launch Configuration button.
• Set the following for the test:
  • Give an appropriate name.
  • Ensure the Run a single test option is selected, and not Run all tests in the selected project, package, or source folder.
  • Ensure the Project name is the project containing Mulgara.
  • Set the Test class field to: net.sourceforge.jxunit.JXTestCase.
  • Select the Arguments tab, and set the Working directory to Other.
  • Press the Workspace button to set the directory, and navigate to the subdirectory of jxtest/iTQL that is relevant to the required test.
• Press Apply to save the configuration.
• Run a server from a terminal (see the section on debugging a client, above).
• Back in Eclipse, set some breakpoints in the client code, and select the debugging target that was just created.