DataDirect XQuery™

View PDF

This quick start provides basic information for getting started with DataDirect XQuery immediately after installation. Specifically, this quick start includes the following topics:

1. Setting the CLASSPATH
2. Configuring Connections
3. Developing a Java Application that Executes a Query

In addition, this quick start describes the DataDirect XQuery command-line utility that is available for quickly running and testing XQueries through a console window. See “Using the Command-Line Utility” for details.

For complete information about the many DataDirect XQuery features, we recommend that you read the DataDirect XQuery User's Guide and Reference.

For information about product requirements, refer to the DataDirect XQuery Installation Guide.

1. Setting the CLASSPATH

Only one DataDirect XQuery jar file, ddxq.jar, must be defined in your CLASSPATH. The CLASSPATH is the search string your Java Virtual Machine (JVM) uses to locate DataDirect XQuery on your computer. If ddxq.jar is not defined on your CLASSPATH, you receive a ClassNotFoundException exception when trying to use DataDirect XQuery.

Set your CLASSPATH to include:

install_dir/lib/ddxq.jar

where install_dir is the path to your DataDirect XQuery installation directory.

2. Configuring Connections

DataDirect XQuery provides multiple ways to configure connections to XML data sources and relational data sources. This quick start demonstrates the method of using XQJ to create a DDXQDataSource instance in your Java application explicitly. See the DataDirect XQuery User’s Guide and Reference for information about other methods of configuring connections.

XML Data Source Connections

If your Java application contains queries that access an XML file, you can directly access the file as shown in the following XQJ code, where the location and name of the XML file is specified as a parameter of fn:doc(), an XQuery function.

DDXQDataSource ds = new DDXQDataSource();
XQConnection conn = ds.getConnection();
conn.createExpression().executeQuery("doc('path_and_filename')");

Relational Data Source Connections

How you configure connection information for relational databases using XQJ depends on whether you are accessing a single database or multiple databases. This quick start demonstrates configuring connection information for accessing a single database. For information about accessing multiple databases, see the DataDirect XQuery User’s Guide and Reference.

To configure a single relational data source connection, use the DDXQDataSource class as shown in the following XQJ code, which specifies a connection URL for the relational data source you want to access and specifies the user ID and password required to access the relational data source.

See "Sample Connection URLs" for samples connection URL for each supported database.

DDXQDataSource ds = new DDXQDataSource();
ds.setJdbcUrl
("jdbc:xquery:dbtype://server_name:port;property=value[;...]");
XQConnection conn = ds.getConnection("myuserid","mypswd");

dbtype

server_name

port

property=value

You, also, can specify a user ID and password in the connection URL, for example:

DDXQDataSource ds = new DDXQDataSource();
ds.setJdbcUrl("jdbc:xquery:oracle://server1:1521;user=myuserID;
password=mypswd");

DB2 Required Connection Properties

DISPLAY DDF

WRKRDBDIRE

Sample Connection URLs

The following URLs are examples of the minimum information that must be specified in a connection URL.

DB2 UDB for Linux/UNIX/Windows:

jdbc:xquery:db2://server_name:50000;databaseName=your_database

DB2 UDB for z/OS and iSeries:

jdbc:xquery:db2://server_name:446;locationName=db2_location

Microsoft SQL Server:

jdbc:xquery:sqlserver://server_name:1433

Oracle:

jdbc:xquery:oracle://server_name:1521

Sybase:

jdbc:xquery:sybase://server_name:5000

Developing a Java Application that Executes a Query

Using DataDirect XQuery, a Java application uses XQJ to execute a query. The Java package name of the XQJ classes is:

com.ddtek.xquery3

The Java class name of the DataDirect XQuery implementation of the XQJ standard interface, XQDataSource, is:

com.ddtek.xquery3.xqj.DDXQDataSource

The following sample Java code illustrates the basic steps that an application would perform to execute an XQuery expression using DataDirect XQuery. This example accesses a Microsoft SQL Server data source. To simplify the code, this example contains no error handling.

// import the XQJ classes
import com.ddtek.xquery3.*;
import com.ddtek.xquery3.xqj.DDXQDataSource;

// establish a connection to a relational data source
// specify the URL and the user ID and password
DDXQDataSource ds = new DDXQDataSource();
ds.setJdbcUrl("jdbc:xquery:sqlserver://server1:1433;
databaseName=stocks");
XQConnection conn = ds.getConnection("myuserid", "mypswd");
// create an expression object that is used to execute a query
XQExpression xqExpression = conn.createExpression();

// the query
String es = "for $h in collection('holdings')/holdings " +
			"where $h/stockticker='AMZN' " +
			"return $h";

// execute the query
XQResultSequence result = xqExpression.executeQuery(es);
result.writeSequence(System.out, null);

// free all resources
result.close();
xqExpression.close();
conn.close();

NOTE: XQJ examples are shipped with the product and are located in the /examples subdirectory in the DataDirect XQuery installation directory.

Using the Command-Line Utility

The DataDirect XQuery command-line utility allows you to quickly run and test XQueries through a console window.

To invoke this utility, enter the following command at a prompt from the lib subdirectory of your DataDirect XQuery installation directory (for example, ddxq30/lib):

java -jar ddxq.jar

Alternatively, you can specify the path to the lib directory in the command line, for example:

java -jar ddxq30/lib/ddxq.jar

NOTE: If your XQuery needs to locate classes other than the DataDirect XQuery classes, for example, if you are specifying a custom URI resolver, you must either:

• Set your CLASSPATH to include the path to the jar files or directories for these classes and invoke the utility using the following command:
  

  java com.ddtek.xquery.Query

• Add the class path to the command line:
  

  java -cp c:\myClasses com.ddtek.xquery.Query

  See Examples

The following table lists the options available for the utility.

-cr classname

-e [xhtml|xml]

-jdbc jdbcurl

-mr classname

-noext

-o filename

-option property=value

-p

-r classname

-s file|URI

-t

-?

param=value

#param=value

java -jar ddxq.jar q.xq "#i=2"

+param=value

!option=value

Example 1: Executes a Simple XQuery

This example executes the simple query {2+5}.

java -jar ddxq.jar {2+5}

Example 2: Retrieves Values from an Initial Context Item

This example retrieves all values for UserId from the initial context item users.xml.

java -jar ddxq.jar -s ..\..\examples\xml\users.xml
{//users/UserId}

Example 3: Retrieves Values and Writes Them to a File

This example retrieves all values for UserId and writes the results to a file named out.xml.

java -jar ddxq.jar -o out.xml
{doc('..\..\examples\xml\users.xml')/users/UserId}

Example 4: Executes an XQuery in a File

This example executes the XQuery contained in the file myXQuery.xq using the initial context item input.xml.

java -jar ddxq.jar -s input.xml myXQuery.xq

Example 5: Binds a Query Document Parameter

This example executes the XQuery contained in the file myXQuery.xq binding the query document parameter inputDoc to the input.xml document.

java -jar ddxq.jar myXQuery.xq +inputDoc=input.xml

Example 6: Binds a Query String Parameter and Sets an Option

This example executes the XQuery contained in the file myXQuery.xq binding the query string parameter param1 to the character string Jonathan and setting the serialization option indent to yes so that results are indented.

java -jar ddxq.jar myXQuery.xq param1=Jonathan !indent=yes

Example 7: Accesses a Relational Data Source

This example executes the XQuery contained in the file myXQuery2.xq that accesses a relational data source.

java -jar ddxq.jar -jdbc
jdbc:xquery:sqlserver://localhost:1433;databaseName=pubs;
user=sa myXQuery2.xq

Example 8: Specifies a Document URI

This example retrieves all values for UserId, specifies a document URI, and writes the results to a file named out.xml.

java -cp c:\myClasses com.ddtek.xquery.Query
-r myURIResolver -o out.xml {doc('users.xml')/users/UserId}

NOTES:

• For information about getting started with the examples shipped with DataDirect XQuery, see the examplesreadme.txt file in the /examples subdirectory in the DataDirect XQuery installation directory.
• For information about using the DataDirect XML Converters, refer to: http://www.xmlconverters.com/
• For information about using Stylus Studio, refer to: http://www.stylusstudio.com/xquery/
  datadirect_xquery.html
• For information about getting started with XML Editor for Eclipse (DataDirect XQuery Edition), refer to: http://www.xquery.com/xml_tools