1 Quick Start
This quick start provides basic information for getting started with DataDirect XQuery immediately after installation, including 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, read the other chapters in this book.
For information about product requirements, refer to "System and Product Requirements" in the DataDirect XQuery Installation Guide.
NOTES:
- For information about getting started with the examples shipped with DataDirect XQuery, see "Examples".
- 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 the DataDirect XQuery Editor for Eclipse, refer to:
http://www.xquery.com/xml_tools/eclipse1. 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
ClassNotFoundExceptionexception when trying to use DataDirect XQuery.Set your CLASSPATH to include:
install_dir/lib/ddxq.jarwhere
install_diris the path to your DataDirect XQuery installation directory.NOTE: If you are connecting to MySQL Community Server or PostgreSQL, you must add the MySQL Connector/J driver jar file and PostgreSQL JDBC driver jar file, respectively, to the CLASSPATH in addition to ddxq.jar. Refer to your MySQL Connector/J driver documentation or 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 (see "Choosing a Connection Method"). 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 "Configuring Connections Explicitly".
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");The format of the connection URL depends on whether you are using a built-in JDBC driver or a third-party driver, and the database you are connecting to. See "Specifying Connection URLs" for details.
See "Sample Connection URLs" for examples of the minimum information, including any required connection properties, that you must specify in a connection URL.
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 Community 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:
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 example, this code does not include 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.