Working with XQuery

What is XQuery

XQuery is the query language for XML and is currently under development at the W3C. The many benefits of XQuery include:

  • XQuery allows you to work in one common model no matter what type of data you're working with: relational, XML, or object data.

  • XQuery is ideal for queries that must represent results as XML, to query XML stored inside or outside the database, and to span relational and XML sources.

  • XQuery allows you to create many different types of XML representations of the same data.

  • XQuery allows you to query both relational sources and XML sources, and create one XML result.

Syntax Highlight and Content Completion

To create a new XQuery document select File->New (Ctrl+N) and when the New Document dialog appears select XQuery entry.

Once you created the new document <oXygen/> provides syntax highlight for keywords and all known XQuery functions and operators. Also for these there is available a content completion component that can be activated by pressing Ctrl+Space keys. The functions and operators are presented together with a comment about parameters and functionality.

Figure 6.2. XQuery Content Completion

XQuery Content Completion

XQuery Validation

With <oXygen/> you can validate your documents before using them in your transformation scenarios. The validation uses the Saxon 8.7.1 B processor or the 8.7.1 SA, eXist, Berkeley DB XML or X-Hive/DB if you installed them. This is in conformance with the XQuery Working Draft http://www.w3.org/TR/xquery/. The processor is used in two cases: validation of the expression and execution. Although the execution implies a validation, it is faster to syntactically check the expression without executing it. The errors that occurred in the document are presented in the messages view at the bottom of editor window, with a full description message. As with all error messages, if you click on one entry, the line where the error appeared is highlighted.

Figure 6.3. XQuery Validation

XQuery Validation

Please note that if you choose a processor that doesn't support XQuery validation you will receive a warning when trying to validate.

Other XQuery editing actions

The XQuery editor type offers a reduced version of the popup menu available in the XML editor type, that means only the folding actions, the edit actions a part of the source actions (only the actions To lower case, To upper case, Capitalize lines) and Open file at cursor, Open in system application.

Transforming XML Documents Using XQuery

XQueries are very similar to the XSL stylesheets in the sense they both are capable of transforming an XML input into another format. You can define transformation scenarios that specify the input URL, the preview mode, XML or XHTML. The result can be saved and opened in the associated application. You can even run a FO processor on the output of an XQuery. The transformation scenarios may be shared between many XQuery files, and are exported at the same time with the XSLT scenarios. The transformation performed can be based on the XML document specified in the Input field, or, if this field is empty, the documents referred from the query expression are used instead. The parameters of XQuery transforms must be set in the Parameters dialog. Parameters that are in a namespace must be specified using the qualified name, for example a param parameter in the http://www.oxygenxml.com/ns namespace must be set with the name {http://www.oxygenxml.com/ns}param.

The transformation uses the processor Saxon 8.7.1 B or Saxon 8.7.1 SA, eXist, Berkeley DB XML, X-Hive/DB, MarkLogic or TigerLogic if you installed them. In order to use the transformation engines you have to enable the appropriate preferences here: Saxon 8.7.1 SA, eXist, Berkeley DB XML, X-Hive/DB, MarkLogic, TigerLogic preference pages.

How to configure eXist support in <oXygen/>

The latest instructions on how to configure eXist support in <oXygen/> can be found on our website.

  1. Copy eXist database jar resources. You have to copy the following eXist specific files in the [Eclipse-install-folder]/plugins/com.oxygenxml.editor_7.2.0/lib directory

    • exist.jar (check for it into your eXist installation root directory)

    • xmldb.jar (check for it into /lib/core subdirectory of your eXist installation root directory)

    • xmlrpc-1.2-patched.jar (check for it into /lib/core subdirectory of your eXist installation root directory)

    If you skip this step the application will display an error message when you try to validate or run the query.

  2. Add the following elements to the <runtime> section of the [Eclipse-install-folder]/plugins/com.oxygenxml.editor_7.2.0/plugin.xml file which specifies the runtime libraries of the <oXygen/> plugin.

    <library name="lib/exist.jar"/>
    <library name="lib/xmldb.jar"/>
    <library name="lib/xmlrpc-1.2-patched.jar"/>
                            
  3. Restart Eclipse with the -clean parameter in the command line.

  4. Configure the eXist connection.

    Go to Preferences -> XML->XSLT/FO/XQuery->XQuery->eXist and configure the XML DB URI, user and password. If you like to set a default collection you have to first press the Refresh button in order for the list to be populated.

  5. Configure eXist as main validator for XQuery files.

    Go to Preferences -> XML -> XSLT/FO/XQuery -> XQuery and set eXist for XQuery validation. Additionally you can set the other options.

  6. Validate XQuery.

    After step 4, you will benefit of the automatic validation feature and you can use Validate button to get a list of validation errors.

  7. Execute XQuery.

    Go to associated scenario configuration and select eXist as the transformation engine.

Note

Validation (points 4 and 5) works only with the development snapshot of eXist database. In order to take advantage of it, you should check-out the current CVS sources (http://sourceforge.net/cvs/?group_id=17691) and make your own build (after check-out just run ant). For previous versions (eXist-1.0b2 or the current eXist-snapshot-20060124.jar kit available on eXist site) you will get an warning that the validation operation is not available.

Collection/resource management can be done using WebDAV (see http://wiki.exist-db.org/space/WebDAV, oxygenXML section).

How to configure Berkeley DB XML support in <oXygen/>

The latest instructions on how to configure eXist support in <oXygen/> can be found on our website.

The following directory definitions shall apply:

  • OXY_DIR - oXygen installation root directory. (for example on Windows C:\Program Files\Oxygen 7.0)

  • DBXML_DIR - Berkeley DB XML database root directory. (for example on Windows C:\Program Files\Sleepycat Software\Berkeley DB XML 2.2.13)

  • DBXML_LIBRARY_DIR (usually on Mac and Unix is DBXML_DIR/lib and on Windows is DBXML_DIR/bin)

  1. You should have Berkeley DB XML database installed on your machine.

    http://www.sleepycat.com/products/bdbxml.html

  2. Copy Berkeley DB XML jar resources

    You have to copy the following Berkeley DB specific files in the [Eclipse-install-folder]/plugins/com.oxygenxml.editor_7.2.0/lib directory

    • db.jar (check for it into DBXML_DIR/lib or DBXML_DIR/jar)

    • dbxml.jar (check for it into DBXML_DIR/lib or DBXML_DIR/jar)

    In case the needed jars are not found you should use --enable-java switch when you build the libraries (more info on http://www.sleepycat.com/xmldocs/ref_xml/xml_unix/intro.html). If you skip this step the application will display an error message when you try to validate or run the query.

  3. Add the following elements to the <runtime> section of the [Eclipse-install-folder]/plugins/com.oxygenxml.editor_7.2.0/plugin.xml file which specifies the runtime libraries of the <oXygen/> plugin.

    <library name="lib/db.jar"/>
    <library name="lib/dbxml.jar"/>
                            
  4. Restart Eclipse with the -clean parameter in the command line.

  5. Add Berkeley DB XML libraries directory to your PATH environment variables.

    When running the application, each of the Berkeley DB XML DLLs must be available in a directory in the PATH. You can achieve this by adding the library directory to the LD_LIBRARY_PATH (linux), DYLD_LIBRARY_PATH (OS X), or PATH (windows) environment variable. On Windows the PATH might be already changed properly by the Berkeley DB XML installation. A common example is PATH=C:\Program Files\Sleepycat Software\Berkeley DB XML 2.2.13\bin

    An alternative way is to modify the following:

    • On UNIX: Create a file called oxygen7.0.vmoptions (in case it is not already created) in the OXY_DIR. The content of the file must be: -Djava.library.path=DBXML_LIBRARY_DIR

    • On Mac: Right-click on the <oXygen/> application icon and in the pop-up menu select Show Package Contents, then in the Contents directory you edit the file Info.plist: in the key VMOptions add -Djava.library.path=DBXML_LIBRARY_DIR

  6. Configure the Berkeley DB environment.

    Go to Oxygen and open Preferences -> XML -> XSLT/FO/XQuery->XQuery->Berkeley DB XML to configure the environment home directory. This is the directory where your databases are stored (the DB_HOME setting). You can also set a verbosity level for the messages to be provided during execution.

  7. Configure Berkeley DB XML as main validator for XQuery files.

    Go to Preferences->XSLT/FO/XQuery->XQuery and set Berkeley DBXML for XQuery validation.

  8. Execute XQuery.

    Go to associated scenario configuration and select Berkeley DBXML as the transformation engine. The collections from your XQuery are automatically opened if they are available in the environment home directory you set. For example in the below Query

    <clients> {     
        for $client in collection("invoices.dbxml")
            /e5Notification/OrderNotification/Purchase/CustomerData    
        let $bc := $client//BillingContact    
        return 
        <client id="{$bc/Email/text()}">        
            <name>{$bc/LastName/text()," ",$bc/FirstName/text()}</name>        
            <company>{$bc/Company/text()}</company>        
        </client> 
    } </clients>
                                

How to configure TigerLogic support in <oXygen/>

The latest instructions on how to configure TigerLogic support in <oXygen/> can be found on our website.

  1. Copy jar resources. Check your TigerLogic JDK lib directory from the server side (for example C:\Program Files\rainingdata\tigerlogic\tljdk\lib) and copy the following files to [Eclipse-install-folder]/plugins/com.oxygenxml.editor_7.2.0/lib directory

    • connector.jar
    • jca-connector.jar
    • tlapi.jar
    • tlerror.jar
    • utility.jar
    • xmlparser.jar
    • xmltypes.jar

    If you skip this step the application will display an error message when you try to run the query.

  2. Add the following elements to the <runtime> section of the [Eclipse-install-folder]/plugins/com.oxygenxml.editor_7.2.0/plugin.xml file which specifies the runtime libraries of the <oXygen/> plugin.

    <library name="lib/connector.jar"/>
    <library name="lib/jca-connector.jar"/>
    <library name="lib/tlapi.jar"/>
    <library name="lib/tlerror.jar"/>
    <library name="lib/utility.jar"/>
    <library name="lib/xmlparser.jar"/>
    <library name="lib/xmltypes.jar"/>
                            
  3. Restart Eclipse with the -clean parameter in the command line.

  4. Configure the TigerLogic connection.

    Go to Preferences -> XML->XSLT/FO/XQuery->XQuery->TigerLogic and configure the server host, port, user, password and the database name.

  5. Execute XQuery.

    Go to associated scenario configuration and select TigerLogic as the transformation engine.

How to configure X-Hive/DB support in <oXygen/>

The latest instructions on how to configure X-Hive/DB support in <oXygen/> can be found on our website.

  1. Copy jar resources. Check your X-Hive/DB lib directory from the server side (for example C:\Program Files\xhive-7.2\lib on Windows or /usr/local/X-Hive_7_2_2/lib on Linux) and copy the following files to [Eclipse-install-folder]/plugins/com.oxygenxml.editor_7.2.0/lib directory

    • icu4j.jar
    • retroweaver-rt.jar
    • xhive.jar

    If you skip this step the application will display an error message when you try to run the query.

  2. Add the following elements to the <runtime> section of the [Eclipse-install-folder]/plugins/com.oxygenxml.editor_7.2.0/plugin.xml file which specifies the runtime libraries of the <oXygen/> plugin.

    <library name="lib/icu4j.jar"/>
    <library name="lib/retroweaver-rt.jar"/>
    <library name="lib/xhive.jar"/>
                            
  3. Restart Eclipse with the -clean parameter in the command line.

  4. Configure the X-Hive/DB connection.

    Go to Preferences -> XML->XSLT/FO/XQuery->XQuery->X-Hive/DB and configure the xhive.bootstrap, user, password and the database name.

  5. Configure X-Hive/DB as main validator for XQuery files.

    Go to Preferences -> XML -> XSLT/FO/XQuery -> XQuery and set X-Hive/DB for XQuery validation.

  6. Validate XQuery.

    After step 4, you will benefit of the automatic validation feature and you can use Validate button to get a list of validation errors.

  7. Execute XQuery.

    Go to associated scenario configuration and select X-Hive/DB as the transformation engine.

How to configure MarkLogic support in <oXygen/>

The latest instructions on how to configure MarkLogic support in <oXygen/> can be found on our website.

  1. Copy jar resources. Go to http://xqzone.marklogic.com/download/ and download Java and .NET XDBC distributions (XSDB Connectivity Packages) http://xqzone.marklogic.com/svn/xdbc/releases/MarkXDBC.Java-3.0-6.zip. Extract the following files to [Eclipse-install-folder]/plugins/com.oxygenxml.editor_7.2.0/lib directory

    • xdbc.jar
    • xdmp.jar

    If you skip this step the application will display an error message when you try to run the query.

  2. Add the following elements to the <runtime> section of the [Eclipse-install-folder]/plugins/com.oxygenxml.editor_7.2.0/plugin.xml file which specifies the runtime libraries of the <oXygen/> plugin.

    <library name="lib/xdbc.jar"/>
    <library name="lib/xdmp.jar"/>
                            
  3. Restart Eclipse with the -clean parameter in the command line.

  4. Configure the MarkLogic connection.

    Go to Preferences -> XML->XSLT/FO/XQuery->XQuery->MarkLogic and configure the server host, port, user and password.

  5. Execute XQuery.

    Go to associated scenario configuration and select MarkLogic as the transformation engine.