This chapter describes XDBC servers and provides procedures for configuring them. The following sections are included:
This chapter describes how to use the Admin Interface to create and configure XDBC servers. For details on how to create and configure XDBC servers programmatically, see Creating and Configuring App Servers in the Scripting Administrative Tasks Guide.
XDBC (XML Database Connector) servers are defined at the group level and are accessible by all hosts within the group. Each XDBC server provides access to a specific forest, and to a library (root) of XQuery programs that reside within a specified directory structure. Applications execute by default against the database that is connected to the XDBC server.
XDBC Servers allow XML Contentbase Connector (XCC) applications to communicate with MarkLogic Server. XCC is an API used to communicate with MarkLogic Server from Java or .NET middleware applications. XDBC servers also allow old-style XDBC applications to communicate with MarkLogic Server, although XDBC applications cannot use certain 3.1 and newer features (such as point-in-time queries). Both XCC and XDBC applications use the same wire protocol.
XQuery requests submitted via XCC return results as specified by the XQuery code. These results can include XML and a variety of other data types. It is the XCC application's responsibility to parse, process and interpret these results in a manner appropriate to the variety of data types available. There are a number of publicly available libraries for assisting with this task, or you may write your own code. In order to accept connections from XCC-enabled applications, MarkLogic Server must be configured with an XDBC Server listening on the designated port. Each XDBC Server connects by default to a specific database within MarkLogic Server, but XCC provides the ability to communicate with any database in the MarkLogic Server cluster to which your application connects (and for which you have the necessary permissions and privileges).
XDBC servers follow the MarkLogic Server security model, as do HTTP and WebDAV servers. The server authenticates access to those programs using user IDs and passwords stored in the security database for that XDBC server. (Each XDBC server is connected to a database, and each database is in turn connected to a security database in which security objects such as users are stored.)
Granular access control to the system and to the data is achieved through the use of privileges and permissions. For details on configuring security objects in MarkLogic Server, see Security Administration. For conceptual information on the MarkLogic Server security model, see Understanding and Using Security Guide.
Use the following procedures to create and manage XDBC servers:
For the procedure to cancel a running request on an XDBC server, see Canceling a Request.
To create a new server, complete the following steps:
If the Modules field is set to file system, then the root directory is either a fully-qualified pathname or is relative to the directory in which MarkLogic Server is installed. The following table shows the default installation directory for each platform:
Platform | Program Directory |
Microsoft Windows | C:\Program Files\MarkLogic |
Red Hat Linux | /opt/MarkLogic |
Sun Solaris | /opt/MARKlogic |
Unless you specify a shared drive, all hosts in the group will need to have a copy of the XQuery programs in the directory specified above.
Do not create XDBC server root directories named Docs, Data or Admin. These directories are reserved by MarkLogic Server for other purposes. Creating XDBC server root directories with these names can result in unpredictable behavior of the server and may also complicate the software upgrade process.
The port number must not be assigned to any other XDBC, HTTP, or WebDAV server.
A user accessing the XDBC server must have the execute privilege selected in order to access the XDBC server (or be a member of the admin
role).
xdmp:set-request-time-limit
. The time limit, in turn, is the maximum number of seconds allowed for servicing a query request. The App Server gives up on queries which take longer, and returns an error.The new XDBC server is created. Creating an XDBC server is a 'hot' admin task; the changes take effect immediately. For information and setup instructions for managing user sessions and/or keeping track of login attempts, see Managing User Sessions and Monitoring Login Attempts.
For each XDBC Server, you can set various default output options. These output options affect how data returned from the App Server is serialized. You can also set these options at the query level to override any default options. You can set serialization options to override the App Server defaults in XQuery with the declare option
XQuery prolog, and in XSLT using the <xsl:output>
instruction. For details on setting the serialization options in XQuery, see Declaring Options in the XQuery and XSLT Reference Guide. For XSLT output details, see the XSLT specification (http://www.w3.org/TR/xslt20#serialization).
To specify defaults for the App Server, complete the following steps:
For more details about App Server output, see Controlling App Server Access, Output, and Errors in the Application Developer's Guide.
To view the settings for an XDBC server, complete the following steps:
To delete the settings for an XDBC server, complete the following steps:
Deleting an XDBC server is a 'cold' admin task; the server restarts to reflect your changes.