Edit online

Debugging with MarkLogic

Oxygen XML Developer Eclipse plugin includes support for debugging XQuery transformations that are executed against a MarkLogic database.

To use a debugging session against the MarkLogic engine, follow these steps:

Configure a MarkLogic data source and a MarkLogic connection.
Make sure that the debugging support is enabled in the MarkLogic server that Oxygen XML Developer Eclipse plugin accesses. On the server side, debugging must be activated in the XDBC server and in the Task Server section of the server control console (the switch debug allow). If the debugging is not activated, the MarkLogic server reports a DBG-TASKDEBUGALLOW error.
Note: An XDBC application server must be running to connect to the MarkLogic server and this XDBC server will be used to process XQuery expressions against the server. You can change the XDBC application server that Oxygen XML Developer Eclipse plugin uses to process XQuery expressions by selecting the Use it to execute queries action from the contextual menu in the Data Source Explorer view.
Open the XQuery file and start the debugging process.
- If you want to debug an XQuery file stored on the MarkLogic server, it is recommended to use the Data Source Explorer view and open the file from the application server that is involved in the debugging process. This improves the resolving of any imported modules.
- The MarkLogic XQuery debugger integrates seamlessly into the XQuery Debugger perspective. If you have a MarkLogic validation scenario configured for the XQuery file, you can choose to debug the scenario directly.
- Otherwise, switch to the XQuery Debugger perspective, open the XQuery file in the editor, and select the MarkLogic connection in the XQuery engine selector from the debug control toolbar.
  
  For general information about how a debugging session is started and controlled, see the Working with the Debugger section.
  Note: Before starting a debugging session, it is recommended that you link the MarkLogic connection with an Eclipse project. To do this, go to the Data Source Explorer view and select Link to project in the contextual menu of the MarkLogic connection. The major benefit of linking a debugging session with a project is that you can add breakpoints in the XQuery modules stored on the server. You are also able to access these modules from the Eclipse Project Explorer view and run debugging sessions from them.

In a MarkLogic debugging session, you can use step actions and breakpoints to help identify problems. When you add a breakpoint on a line where the debugger never stops, Oxygen XML Developer Eclipse plugin displays a warning message. These warnings are displayed for breakpoints you add either in the main XQuery (which you can open locally or from the server) or for breakpoints you add in any XQuery that is opened from the connection that participates in the debugging session. For more information, see Using Breakpoints for Debugging Queries that Import Modules with MarkLogic.

Remote Debugging with MarkLogic

Oxygen XML Developer Eclipse plugin allows you to debug remote applications that use XQuery (for example, web applications that trigger XQuery executions). Oxygen XML Developer Eclipse plugin connects to a MarkLogic server, shows you the running XQuery scripts and allows you to debug them. You can even pause the scripts so that you can start the debugging queries in the exact context of the application. You can also switch a server to debug mode to intercept all XQuery scripts.

Oxygen XML Developer Eclipse plugin also supports collaborative debugging. This feature allows multiple users to participate in the same debugging session. You can start a debugging session and at a certain point, another user can continue it.

Important: When using the remote debugging feature, the HTTP and the XDBC servers involved in the debugging session must have the same module configuration.

Resources

For more information about the XQuery debugger for MarkLogic, watch our video demonstration: