Quick Start: DataDirect XQuery®
© Copyright 2009 Progress Software Corporation and/or its subsidiaries or affiliates. All rights reserved.
This quick start provides basic information for getting started with DataDirect XQuery immediately after installation. It covers the following topics:
Getting Started with DataDirect XQuery
This section shows you how to get up and running with DataDirect XQuery. It covers the following topics:
1. Setting the CLASSPATH
2. Configuring Connections
3. Developing a Java Application that Executes a Query1. 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.
NOTE: If you are connecting to PostgreSQL, you must add the PostgreSQL JDBC driver jar file to the CLASSPATH in addition to ddxq.jar. Refer to your PostgreSQL JDBC driver documentation for the name of the jar file.
2. Configuring Connections
DataDirect XQuery provides multiple ways to configure connections to XML data sources and relational data sources. This section shows how to use XQJ to create a DDXQDataSource instance in your Java application explicitly.
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 section shows how to configure connection information to access 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 example. This example specifies a connection URL (represented by URL) for the relational data source that you want to access and the user ID and password required to access the relational data source.
DDXQDataSource ds = new DDXQDataSource(); ds.setJdbcUrl("URL"); XQConnection conn = ds.getConnection("myuserid","mypswd");Sample Connection URLs
The following URLs are examples of the minimum information that must be specified in a connection URL.
DB2 for Linux/UNIX/Windows
DB2 for z/OS and iSeries
Informix
Microsoft SQL Server
MySQL Enterprise
Oracle
PostgreSQL
Sybase
3. 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:
javax.xml.xquery
The Java class name of the DataDirect XQuery implementation of the XQJ standard interface, XQDataSource, is:
com.ddtek.xquery.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 example, this code does not include error handling.
// import the XQJ classes import javax.xml.xquery.*; import com.ddtek.xquery.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, ddxq/lib):
Alternatively, you can specify the path to the lib directory in the command line, for example:
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 perform one of the following actions:
- 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.QueryNOTE: If you are connecting to PostgreSQL, you must add the PostgreSQL JDBC driver jar file to the CLASSPATH in addition to ddxq.jar. Refer to your PostgreSQL JDBC driver documentation for the name of the jar file.
- Add the class path to the command line:
java -cp c:\myClasses com.ddtek.xquery.QuerySee Example 8.
NOTE: If you are connecting to PostgreSQL, you must add the PostgreSQL JDBC driver jar file to the CLASSPATH in addition to ddxq.jar. Refer to your PostgreSQL JDBC driver documentation for the name of the jar file.
The following table lists the options available for the utility.
Table 1. Command Line Utility Options Option Description -cr classname Specifies the CollectionURIResolver class to use. See the NOTE about setting your CLASSPATH for custom URI resolvers. -e [xhtml|xml] Generates an XQuery execution plan and, optionally, specifies the format of the plan. If a format is not specified, XHTML is generated. -jdbc jdbcurl Specifies a connection URI. See Relational Data Source Connections in the DataDirect XQuery User's Guide and Reference for more information.NOTE: On UNIX and Linux, the value for this option must be enclosed with double quotes, for example: -mr classname Specifies the ModuleURIResolver class to use. See the NOTE about setting your CLASSPATH for custom URI resolvers. -noext Disallows calls to Java methods. -o filename Sends results (output) to specified file. -option property=value Specifies XQuery or JDBC global options. See Using Option Declarations and Extension Expressions in the DataDirect XQuery User's Guide and Reference for more information. -prop property=value Specifies data source and connection options. See DDXQDataSource and DDXQJDBCConnection Properties in the DataDirect XQuery User's Guide and Reference for more information. -p Displays a stack trace in case of an exception. -r classname Specifies the URIResolver class to use. See the NOTE about setting your CLASSPATH for custom URI resolvers. -s file|URI Specifies an initial context item in the form of a file name or a URI. -t Displays version and timing information. -u Enables automatic updating of sources. -version Display version information. -? Displays the help for the command-line utility. param=value Specifies a query string parameter and its value. #param=value Specifies a query number parameter and its value. On UNIX and Linux, the value for this option must be enclosed with double quotes, for example:
java -jar ddxq.jar q.xq "#i=2" +param=value Specifies a query document parameter and its value. !option=value Specifies a serialization option and its value.
Example 1: Executes a Simple XQuery
This example executes the simple query {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.
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.
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.
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.
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.
Example 7: Accesses a Relational Data Source
This example executes the XQuery contained in the file myXQuery2.xq that accesses a relational data source. See the NOTE about specifying connection URLs.
java -jar ddxq.jar -jdbc "jdbc:xquery:sqlserver://localhost:1433;databaseName=pubs; user=sa" myXQuery2.xqExample 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}Additional Resources
In addition to this quick start, you might find these resources useful:
- 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.