XCC Developer's Guide (PDF)

MarkLogic 9 Product Documentation
XCC Developer's Guide — Chapter 4

« Previous chapter

Using the Sample Applications

The XCC packages contain a number of sample applications. Each sample application is provided along with its source code, giving you a starting point for creating your own applications. This chapter describes the sample applications and contains the following sections:

Setting Up Your Environment

Before running the sample applications, be sure to set up the necessary environment to run the application. This section has the following parts:

Setting Up Your MarkLogic Server Environment

Before you run the sample applications, complete the following steps:

  1. Install MarkLogic Server, or have a MarkLogic Server installation to which you can connect. For details on installing MarkLogic Server, see the Installation Guide.
  2. Create and configure an XDBC Server using the Admin Interface. See the Administrator's Guide for details on how to create and configure an XDBC Server.
  3. Configure a user for the XDBC Server you created. For example, add a user to the security database with the username as user and the password as pass. See the Administrator's Guide for details on adding a user to the security database.

Setting Up Your Java Environment

If you are using XCC/J, you must have Java installed on your client machine. Additionally, you will need the following set up to run the sample applications:

  • Set your JAVA_HOME environment variable, if it is not already set. For example, if you are running a Windows machine, set JAVA_HOME in a command window as in the following example:
    set JAVA_HOME=c:\Sun\SDK\jdk

    Substitute the directory in which Java is installed in your environment.

  • Set your CLASSPATH environment variable correctly, or use the -classpath option to pass the appropriate classpath on the command line. Make sure to use the correct name for the marklogic-xcc-N.jar file in your CLASSPATH, where N corresponds to the service release version number.

Sample Applications

The source code and API documentation for the sample applications are includes in the XCC packages.

The Java distribution of XCC includes marklogic-xcc-jar-N.x.jar and marklogic-xcc-examples-N.jar files. The commands to launch the sample programs in this section assume you have renamed these jar files to xcc.jar and xccexamples.jar, respectively. The commands to launch the sample programs also assume the XCC Java distrubtion is installed in XCC_HOME.

The sample applications are as follows:

Sample Description
This class fetches documents from the conentbase and writes their serialized contents to a provided OutputStream.
This program accepts a server URI (in the format expected by ContentSourceFactory.newContentSource(java.net.URI)) and one or more file pathnames of documents to load.
DynamicContentStream This program demonstrates inserting unbuffered, chunkable dynamic content into the database without spawning a new thread.
HelloSecureWorld This simple program prints out the string Hello World, using SSL/TLS to connect to MarkLogic Server.
This simple program prints out the string "Hello World".
This simple program invokes a named XQuery module on the server and return the result.
OutputStreamInserter This program demonstrates inserting unbuffered dynamic content into the database by spawning a new thread to write the data.
This is a very simple class that will submit an XQuery string to the server and return the result.
XA This program demonstrates using MarkLogic Server in a distributed XA transaction, using JBoss as the Transaction Manager.

ContentFetcher

This program fetches a document from MarkLogic Server and serializes its contents. You can serialize the contents to the standard output (display it on the screen) or to a file using the -o option. The following is a sample command to run the ModuleRunner class:

java -classpath "XCC_HOME/lib/xcc.jar:XCC_HOME/lib/xccexamples.jar"
     com.marklogic.xcc.examples.ContentFetcher 
     xcc://username:password@localhost:8021 
     /mydocs/hello.xml -o myHelloFile.xml

This sends the contents of the document at /mydocs/hello.xml to the file myHelloFile.xml (in the same directory in which the command is run). It connects to the default database of the XDBC Server listening on port 8021 of the local machine, using the credentials username and password to authenticate the connection.

ContentLoader

This program loads the specified document in the database. It loads the file with a URI equal to the fully-qualified pathname of the file. The following is a sample command to run the ContentLoader class:

java -classpath "XCC_HOME/lib/xcc.jar:XCC_HOME/lib/xccexamples.jar"
     com.marklogic.xcc.examples.ContentLoader 
     xcc://username:password@localhost:8021 hello.xml

This loads the file at hello.xml to a document with the fully-qualified pathname of hello.xml (for example, c:\xcc\examples\hello.xml). It loads it into the default database of the XDBC Server listening on port 8021 of the local machine, using the credentials username and password to authenticate the connection.

DynamicContentStream

This program demonstrates inserting dynamic content without spawning a new thread, by using ContentFactory.newUnBufferedContent. The following is a sample command to run the DynamicContentStream program:

java -classpath "XCC_HOME/lib/xcc.jar:XCC_HOME/lib/xccexamples.jar"
     com.marklogic.xcc.examples.DynamicContentStream 
     xcc://username:password@localhost:8021
     /any/valid/docURI

This inserts a new document at /any/valid/docURI in the contentbase described by the XDBC App Server URI xcc://username:password@localhost:8021. For demonstration purposes, the document contents are generated dynamically by the sample application.

HelloSecureWorld

This program runs a query on MarkLogic Server that returns the string "Hello World", using an SSL/TLS connection to MarkLogic Server.

This example can load a specified key store of trusted signing authorities, use the Java default key store, or use a stub that accepts any server certificate. It can also load client certificates from a specified key store, or connect without a certificate.

The server certificate command line parameter may be any of the following:

  • the path to a Java Key Store containing trusted signing authorities
  • DEFAULT - use the Java default cacerts
  • ANY - accept any server certificate

Optionally, you may also specify the path to a Java Key Store containing client certificates, along with its passphrase.

The following is a sample command to run the HelloSecureWorld class, accepting any certificate and no client authentication (the XDBC App Server needs ssl require client certificate set to false for this configuration).

java -classpath "XCC_HOME/lib/xcc.jar:XCC_HOME/lib/xccexamples.jar"
     com.marklogic.xcc.examples.HelloSecureWorld 
     xccs://username:password@localhost:8021 ANY

When FIPS mode is enabled (which is the default), you need to use strong client ciphers, and you need to download and install the Java Cryptography Extension (JCE) Unlimited Strength package (http://www.oracle.com/technetwork/java/javase/downloads/jce-7-download-432124.html).

HelloWorld

This program runs a query on MarkLogic Server that returns the string "Hello World". The following is a sample command to run the HelloWorld class:

java -classpath "XCC_HOME/lib/xcc.jar:XCC_HOME/lib/xccexamples.jar"
     com.marklogic.xcc.examples.HelloWorld 
     xcc://username:password@localhost:8021

ModuleRunner

This program allows you to invoke a module on the server. The module must exist under the XDBC server root, either in the database (when a modules database is configured) or on the filesystem (when the filesystem is configured for modules). The following is a sample command to run the ModuleRunner class:

java -classpath "XCC_HOME/lib/xcc.jar:XCC_HOME/lib/xccexamples.jar"
     com.marklogic.xcc.examples.ModuleRunner 
     xcc://username:password@localhost:8021 hello.xqy

This invokes the module named hello.xqy. The request is submitted to the XDBC Server running on the local machine at port 8021, using the credentials username and password to authenticate the connection. The module path is resolved relative to the XDBC Server root.

OutputStreamInserter

This program demonstrates inserting dynamic content by spawning a new thread to write data to the receiving end of an input stream. For an alternative method of inserting dynamically generated streamed content, see the example DynamicContentStream.

The following is a sample command to run the OutputStreamInserter program:

java -classpath "XCC_HOME/lib/xcc.jar:XCC_HOME/lib/xccexamples.jar"
     com.marklogic.xcc.examples.OutputStreamInserter 
     xcc://username:password@localhost:8021
     /any/valid/docURI

This inserts a new document at /any/valid/docURI in the contentbase described by the XDBC App Server URI xcc://username:password@localhost:8021. For demonstration purposes, the document contents are generated dynamically by the sample application.

SimpleQueryRunner

This program allows you to store XQuery in a file and then submit the XQuery to MarkLogic Server. The following is a sample command to run the SimpleQueryRunner class:

java -classpath "XCC_HOME/lib/xcc.jar:XCC_HOME/lib/xccexamples.jar"
     com.marklogic.xcc.examples.SimpleQueryRunner 
     xcc://username:password@localhost:8021 hello.xqy

This submits the contents of the hello.xqy file to a MarkLogic Server XDBC Server running on the local machine at port 8021, using the credentials username and password to authenticate the connection.

XA

This program demonstrates using MarkLogic Server in a distributed XA transaction. The sample uses JBoss as a Transaction Manager, with two MarkLogic Server clusters participating in the distributed transaction.

The sample uses libraries from JBossTS. Download and install JBossTS 4.15.0 or later from the following location. The JBoss Application Server is not needed.

http://www.jboss.org/jbosstm

Include the following libraries from the JBossTS package on your classpath. JBOSS_HOME is the directory where JBossTS is installed.

  • JBOSSTS_HOME/lib/jbossjta.jar
  • JBOSSTS_HOME/lib/ext/jboss-transaction-api_1.1_spec.jar (or other JTA implementation)
  • JBOSSTS_HOME/lib/ext/jboss-logging.jar

The participating MarkLogic Server clusters may simply be two XDBC App Servers on the same instance, serving different databases.

The following is a sample command to run the ModuleRunner class. Change XCC_HOME, JBOSSTS_HOME, and the two content base URIs to match your installation.

java -classpath "XCC_HOME/lib/xcc.jar:XCC_HOME/lib/xccexamples.jar:
     JBOSSTS_HOME/lib/jbossjta.jar:
     JBOSSTS_HOME/lib/ext/jboss-transaction-api_1.1_spec.jar:
     JBOSSTS_HOME/lib/ext/jboss-logging.jar"
     com.marklogic.xcc.examples.XA 
     xcc://username1:password1@host1:port1/contentbase1
     xcc://username2:password2@host2:port2/contentbase2

The sample program enlists each contentbase as a resource with the JBoss Transaction Manager, and then inserts a document in each contentbase, as part of a single global transaction. The output from xdmp:host-status relevant to each branch's transaction is printed out. This information includes the global transaction id and branch qualifer, as well as the local transaction id:

<transaction xmlns="http://marklogic.com/xdmp/status/host">
  <transaction-id>750821115632601886</transaction-id>
  <host-id>8814043795788656336</host-id>
  <server-id>4366002345564888063</server-id>
  <xid format-id="131076" xmlns="http://marklogic.com/xdmp/xa">
    <global-transaction-id>...825D0000000931</global-transaction-id>
    <branch-qualifier>...825D0000000A</branch-qualifier>
  </xid>
  <name/>
  <mode>update</mode>
  <timestamp>0</timestamp>
  <state>active</state>
  <database>2901782035623219290</database>
  <canceled>false</canceled>
  ...
</transaction>
<transaction xmlns="http://marklogic.com/xdmp/status/host">
  <transaction-id>4949312806261581854</transaction-id>
  <host-id>8814043795788656336</host-id>
  <server-id>7579943212553445602</server-id>
  <xid format-id="131076" xmlns="http://marklogic.com/xdmp/xa">
    <global-transaction-id>0...825D0000000931</global-transaction-id>
    <branch-qualifier>...825D0000000D</branch-qualifier>
  </xid>
  <name/>
  <mode>update</mode>
  <timestamp>0</timestamp>
  <state>active</state>
  <database>2852559629722654718</database>
  <canceled>false</canceled>
  ...
</transaction>

For details on use XA with MarkLogic Server, see Multi-Statement Transactions.

« Previous chapter
Powered by MarkLogic Server | Terms of Use | Privacy Policy