Logging XQJ Calls with DataDirect Spy™ for XQJ

DataDirect Spy passes XQJ calls issued by an application to DataDirect XQuery and logs detailed information about those calls, which you can use for troubleshooting.

DataDirect Spy logging for connections is not enabled by default. You can enable DataDirect Spy logging and configure it for your needs by setting one or multiple options (attributes) for DataDirect Spy. For example, you may want to direct logging to a local file on your machine.

When DataDirect Spy logging is enabled for a connection, you can turn logging on and off at runtime using the setEnableLogging() method in the com.ddtek.xquery.xqj.ExtLogControl interface. See Generating a DataDirect Spy™ Log for information about using a DataDirect Spy log for troubleshooting.

Enabling DataDirect Spy™ Logging

To enable DataDirect Spy logging, set one or multiple DataDirect Spy attributes using any of the following methods:

Setting DataDirect Spy Attributes Explicitly in a Java Application

To set DataDirect Spy attributes explicitly in your application, use XQJ to construct a DDXQDataSource instance in your Java application and specify the SpyAttributes property of the DDXQDataSource class. The format for the value of the SpyAttributes property is: 

spy_attribute=value[;spy_attribute=value]...

where spy_attribute=value is a DataDirect Spy attribute and a valid value for that attribute. See DataDirect Spy Attributes for a list of supported attributes.

Example on Windows

The following example enables DataDirect Spy logging and configures DataDirect Spy to log all XQJ activity to a log file, including the content of SAX streams passed through XQJ to the spy.log file located in the C:\temp directory
(log=(file)C:\\\\temp\\\\spy.log;logSAX=yes). 

DDXQDataSource ds = new DDXQDataSource(); 
ds.setJdbcUrl("jdbc:xquery:sqlserver://server1:1433;databaseName=stocks"); 
ds.setSpyAttributes("log=(file)C:\\\\temp\\\\spy.log;logSAX=yes"); 
Context ctx = new InitialContext(); 
ctx.bind("holdings_ds", ds); 
XQConnection conn = ds.getConnection("myuserid", "mypswd");

NOTE: If coding a path on Windows to the log file in a Java string, the backslash character (\) must be preceded by the Java escape character, a backslash, as shown in this example.

Example on UNIX/Linux

The following example enables DataDirect Spy logging and configures DataDirect Spy to log all XQJ activity to a log file located in the /tmp directory
(log=(file)/tmp/spy.log;logTimestamp=yes). The spy.log file includes a timestamp on each line in the log. 

DDXQDataSource ds = new DDXQDataSource(); 
ds.setJdbcUrl("jdbc:xquery:oracle://server1:1521;SID=ORCL"); 
ds.setSpyAttributes("log=(file)/tmp/spy.log;logTimestamp=yes"); 
Context ctx = new InitialContext(); 
ctx.bind("holdings_ds", ds); 
XQConnection conn = ds.getConnection("myuserid", "mypswd");

Setting DataDirect Spy Attributes in JNDI

To set DataDirect Spy attributes in JNDI, configure a data source object that specifies the SpyAttributes property of the DDXQDataSource class and use XQJ to load the DDXQDataSource object. The format for the value of the SpyAttributes property is: 

(spy_attribute=value[;spy_attribute=value]...)

where spy_attribute=value is a DataDirect Spy attribute and a valid value for that attribute. See DataDirect Spy Attributes for a list of supported attributes.

Example on Windows

The following example enables DataDirect Spy logging and configures DataDirect Spy to log all XQJ activity to a log file located in the C:\temp directory
(log=(file)C:\\\\temp\\\\spy.log;logTimestamp=yes). The spy.log file includes a timestamp on each line in the log. 

XQDataSource ds = new DDXQDataSource(); 
ds.setJdbcUrl("jdbc:xquery:oracle://server1:1521;SID=ORCL"); 
ds.setSpyAttributes("log=(file)C:\\\\temp\\\\spy.log;logSAX=yes"); 
Context ctx = new InitialContext(); 
ctx.bind("holdings_ds", ds); 
XQConnection conn = ds.getConnection("myuserid","mypswd");

NOTE: If coding a path on Windows to the log file in a Java string, the backslash character (\) must be preceded by the Java escape character, a backslash, as shown in this example.

Example on UNIX/Linux

The following example enables DataDirect Spy logging and configures DataDirect Spy to log all XQJ activity to a log file located in the /tmp directory
(log=(file)/tmp/spy.log;logTimestamp=yes). The spy.log file includes a timestamp on each line in the log. 

XQDataSource ds = new DDXQDataSource(); 
ds.setJdbcUrl("jdbc:xquery:oracle://server1:1521;SID=ORCL"); 
ds.setSpyAttributes("log=(file)/tmp/spy.log;logTimestamp=yes"); 
Context ctx = new InitialContext(); 
ctx.bind("holdings_ds", ds); 
XQConnection conn = ds.getConnection("myuserid", "mypswd");

DataDirect Spy Attributes

Table J-1 describes the attributes you can set for DataDirect Spy.

Table J-1. DataDirect Spy Attributes 
Attribute
Description
enable={yes | no}
Enables and disables DataDirect Spy logging. The default is yes (if any DataDirect Spy attributes are set as described in Enabling DataDirect Spy™ Logging, DataDirect Spy logging is enabled). Once enabled, you can turn DataDirect Spy logging on and off at runtime using the setEnableLogging() method in the com.ddtek.xquery.xqj.ExtLogControl interface. See Turning On and Off DataDirect Spy™ Logging for more information.
linelimit=numberofchars
Sets the maximum number of characters that DataDirect Spy will log on any one line. The default is 0 (no maximum limit).
log=System.out
Directs logging to the Java output standard, System.out.
log=(file)filename
Redirects logging to the file specified by filename.
logDOM={yes | no}
Specifies whether DataDirect Spy logs the content of DOM trees passed through XQJ. The default is no (DOM tree content is not logged). To log the content of DOM trees, set the value of this attribute to yes.
logSAX={yes | no}
Specifies whether DataDirect Spy logs the content of SAX event streams passed through XQJ. The default is no (SAX event stream content is not logged). To log the content of SAX events, set the value of this attribute to yes.
logStAX={yes | no}
Specifies whether DataDirect Spy logs the content of StAX event streams passed through XQJ (StAX event stream content is not logged). To log the content of StAX events, set the value of this attribute to yes.
logTName={yes | no}
Specifies whether DataDirect Spy logs the name of the current thread. The default is no (name of the current thread is not logged). To log the name of the current thread, set the value of this attribute to yes.
logTimestamp={yes | no}
Specifies whether a timestamp is logged on each line of the DataDirect Spy log. The default is no. To log the timestamp on each line of the log, set the value of this attribute to yes.

Generating a DataDirect Spy™ Log

This section provides an example of a typical DataDirect Spy log and instructions for turning on and off DataDirect Spy logging at runtime.

DataDirect Spy™ Log Example

The following example shows a DataDirect Spy log. The numbers in superscript are note indicators that correspond to the notes following the example. They provide explanations for the referenced text to help you understand the content of your own DataDirect Spy logs.

NOTE: The following example does not show logging of XML results that occur when the logDOM, logSAX, or logStAX attributes are set to yes. 

spy>> XQConnection(0).createExpression() 
spy>> OK (XQExpression(0))1 
spy>> XQExpression(0).executeQuery(String query) 
spy>> query : 123,'hello world!' 
spy>> OK (XQResultSequence(0)) 2 
spy>> XQResultSequence(0).next() 
spy>> OK (true) 3 
spy>> XQResultSequence(0).getObject() 
spy>> OK (123) 4 
spy>> XQResultSequence(0).next() 
spy>> OK (true) 3 
spy>> XQResultSequence(0).getObject() 
spy>> OK (hello world!) 4 
spy>> XQResultSequence(0).next() 
spy>> OK (false) 5 
spy>> XQExpression(0).close() 
spy>> OK 6 
spy>> XQConnection(0).close() 
spy>> OK 7
  1. An XQExpression is created. Further in the DataDirect Spy output, this XQExpression is identified by XQExpression(0).
  2. The query 123,'hello world!' is executed. An XQResultSequence is returned.
  3. The application moved to the next item in the result sequence. True is returned, indicating that there is another item in the result sequence.
  4. The item’s data is retrieved into the application.
  5. The application moved to the next item in the result sequence. False is returned, indicating that the end of the sequence has been reached.
  6. The application closes the XQExpression.
  7. The application closes the XQConnection.

Turning On and Off DataDirect Spy™ Logging

Once DataDirect Spy logging is enabled for a connection, you can turn on and off the logging at runtime using the setEnableLogging() method in the com.ddtek.xquery.xqj.ExtLogControl interface. When logging is enabled, all Connection objects returned to an application provide an implementation of the ExtLogControl interface.

For example, the following code turns off logging using setEnableLogging(false): 

import com.ddtek.xquery.xqj.ExtLogControl 
DDXQDataSource ds = new DDXQDataSource(); 
ds.setJdbcUrl("jdbc:xquery:sqlserver://server1:1433;databaseName=stocks; 
ds.setSpyAttributes("log=(file)/tmp/spy.log"); 
XQConnection conn = ds.getConnection("myuserid","mypswd"); 
  
((ExtLogControl) conn).setEnableLogging(false); 
...

The setEnableLogging() method only turns on and off logging if DataDirect Spy logging has already been enabled for a connection; it does not set or change DataDirect Spy attributes. See Enabling DataDirect Spy™ Logging for information about enabling and customizing DataDirect Spy logging.

ExtLogControl Class

ExtLogControl Class
Methods

Description
void setEnableLogging(boolean)
If DataDirect Spy was enabled when the connection was created, you can turn on or off DataDirect Spy logging at runtime using this method. If true, logging is turned on. If false, logging is turned off. If DataDirect Spy logging was not enabled when the connection was created, calling this method has no effect.
boolean getEnableLogging()
Indicates whether DataDirect Spy logging was enabled when the connection was created and whether logging is turned on. If the returned value is true, logging is turned on. If the returned value is false, logging is turned off.