net.xqj.marklogic
Class MarkLogicXQDataSource

java.lang.Object
  extended by GenericXQDataSource
      extended by net.xqj.marklogic.MarkLogicXQDataSource
All Implemented Interfaces:
XQDataSource

public class MarkLogicXQDataSource
extends GenericXQDataSource
implements XQDataSource

MarkLogic implementation of the XQJ XQDataSource interface. (JSR 225).

This class has a default public constructor, so it may be instantiated easily via the reflection API.

The two approaches to create an implementation of this class are as follows:

Direct initialization
XQDataSource xqDataSource = new MarkLogicXQDataSource();
Java Reflection
XQDataSource xqDataSource = Class.forName("net.xqj.marklogic.MarkLogicXQDataSource").newInstance();

Author:
Charles Foster

Field Summary
static String FORCE_XDBC4
          Force XDBC4 protocol constant.
static String MODE_CONFORMANCE
          Conformance mode constant, allowing driver to pass 100% of XQJ TCK.
static String MODE_XDBC
          XDBC mode constant, allowing driver to pass 94%+ of XQJ TCK.
 
Constructor Summary
MarkLogicXQDataSource()
          Creates a new instance of a MarkLogicXQDataSource.
 
Method Summary
 XQConnection getConnection()
          Creates an XQConnection / XQConnection2 instance.
 XQConnection getConnection(Connection con)
          Deprecated.  
 XQConnection getConnection(String username, String passwd)
          Creates a XQConnection instance manually specifying user credentials.
 String getDatabaseName()
          Get the name of the target Database.
 String getMode()
          Gets the mode setting of this MarkLogicXQDataSource
 String getPassword()
          Gets the password value of this MarkLogicXQDataSource
 int getPort()
          Get the target port of the XDBC Server.
 String getProperty(String name)
          Returns the current value of the named property if set, else null.
 String getServerName()
          Gets the MarkLogic Server's name, which will be a hostname or an IP address.
 String[] getSupportedPropertyNames()
          Returns an array containing the property names supported by this XQDataSource.
 String getUser()
          Gets the user value of this MarkLogicXQDataSource
 boolean isForceXDBC4()
          Retrieves whether or not all new XQConnection instances are forced to use the XDBC4 protocol.
 void setDatabaseName(String databaseName)
          Set the MarkLogic Server's target Database.
 void setForceXDBC4(boolean forceXDBC4)
          Force all new XQConnection instances to use the XDBC4 protocol.
 void setForceXDBC4(String forceXDBC4)
          Force all new XQConnection instances to use the XDBC4 protocol.
 void setMode(String mode)
          Sets the mode of the XQDataSource, values can be either "xdbc" or "conformance".
 void setPassword(String password)
          Sets the password value of this MarkLogicXQDataSource
 void setPort(int port)
          Sets the target port of the XDBC Server.
 void setPort(String port)
          Sets the target port of the XDBC Server.
 void setProperty(String name, String value)
          Sets the named property to the specified value.
 void setServerName(String serverName)
          Sets the MarkLogic Server's name
 void setUser(String user)
          Sets the user value of this MarkLogicXQDataSource
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface javax.xml.xquery.XQDataSource
getLoginTimeout, getLogWriter, setLoginTimeout, setLogWriter, setProperties
 

Field Detail

MODE_CONFORMANCE

public static final String MODE_CONFORMANCE
Conformance mode constant, allowing driver to pass 100% of XQJ TCK. Can be used with the setMode method.

See Also:
Constant Field Values

MODE_XDBC

public static final String MODE_XDBC
XDBC mode constant, allowing driver to pass 94%+ of XQJ TCK. Can be used with the setMode method.

See Also:
Constant Field Values

FORCE_XDBC4

public static final String FORCE_XDBC4
Force XDBC4 protocol constant.

See Also:
Constant Field Values
Constructor Detail

MarkLogicXQDataSource

public MarkLogicXQDataSource()
Creates a new instance of a MarkLogicXQDataSource.

Method Detail

getConnection

public XQConnection getConnection()
                           throws XQException

Creates an XQConnection / XQConnection2 instance. Credentials must have already been defined.

The XQConnection instance returned from this method may be cast into a XQConnection2.

Consider the following code:

XQConnection2 conn = (XQConnection2)MarkLogicXQDataSourceInstance.getConnection();

Specified by:
getConnection in interface XQDataSource
Returns:
an instance of XQConnection / XQConnection2.
Throws:
XQException - if a datasource access error occurs
See Also:
XQConnection2

getConnection

public XQConnection getConnection(String username,
                                  String passwd)
                           throws XQException

Creates a XQConnection instance manually specifying user credentials.

The XQConnection instance returned from this method may be cast into a XQConnection2.

Consider the following code:

XQConnection2 conn = (XQConnection2)MarkLogicXQDataSourceInstance.getConnection("user","password");

Specified by:
getConnection in interface XQDataSource
Parameters:
username - the username which will be used when communicating with the XDBC Server.
passwd - the password which will be used when communicating with the XDBC Server.
Returns:
an instance of XQConnection / XQConnection2.
Throws:
XQException - if a datasource access error occurs
See Also:
XQConnection2

setServerName

public void setServerName(String serverName)
Sets the MarkLogic Server's name

Parameters:
serverName - the MarkLogic Server's name, this can be a hostname or an IP address.

getServerName

public String getServerName()
Gets the MarkLogic Server's name, which will be a hostname or an IP address.

Returns:
MarkLogic Server's hostname or IP address.

setDatabaseName

public void setDatabaseName(String databaseName)
Set the MarkLogic Server's target Database.

Parameters:
databaseName - the name of the Database which queries run against.

getDatabaseName

public String getDatabaseName()
Get the name of the target Database.

Returns:
the name of the target Database which queries run against.

setMode

public void setMode(String mode)
             throws XQException
Sets the mode of the XQDataSource, values can be either "xdbc" or "conformance". Please read the MarkLogic XQJ API documentation for further information.

Parameters:
mode - the mode of future XQConnection instances, value may be "xdbc" or "conformance".
Throws:
XQException - if the mode parameter is not recognised.

getMode

public String getMode()
Gets the mode setting of this MarkLogicXQDataSource

Returns:
the mode of the MarkLogicXQDataSource, value will be either "xdbc" or "conformance"

setUser

public void setUser(String user)
Sets the user value of this MarkLogicXQDataSource

Parameters:
user - a username which will be sent to an XDBC server.

getUser

public String getUser()
Gets the user value of this MarkLogicXQDataSource

Returns:
The username this MarkLogicXQDataSource is using to send to an XDBC Server.

setPassword

public void setPassword(String password)
Sets the password value of this MarkLogicXQDataSource

Parameters:
password - a password which will be sent to an XDBC server.

getPassword

public String getPassword()
Gets the password value of this MarkLogicXQDataSource

Returns:
The password this MarkLogicXQDataSource is using to send to an XDBC Server.

setPort

public void setPort(int port)
Sets the target port of the XDBC Server.

Parameters:
port - the XDBC Server port

setPort

public void setPort(String port)
             throws XQException
Sets the target port of the XDBC Server.

Parameters:
port - the XDBC Server port
Throws:
XQException - if the supplied port is not a valid port.

getPort

public int getPort()
Get the target port of the XDBC Server.

Returns:
the current port defined in this MarkLogicXQDataSource

setForceXDBC4

public void setForceXDBC4(boolean forceXDBC4)
Force all new XQConnection instances to use the XDBC4 protocol.

Parameters:
forceXDBC4 - true to use the XDBC4 protocol, false to use the XDBC5+ protocol.

setForceXDBC4

public void setForceXDBC4(String forceXDBC4)
                   throws XQException
Force all new XQConnection instances to use the XDBC4 protocol.

Parameters:
forceXDBC4 - "true" to use the XDBC4 protocol, "false" to use the XDBC5+ protocol.
Throws:
XQException - if the supplied value is not a valid String representation of a Boolean.

isForceXDBC4

public boolean isForceXDBC4()
Retrieves whether or not all new XQConnection instances are forced to use the XDBC4 protocol.

Returns:
a flag to indicate whether XDBC4 protocol will be used.

getSupportedPropertyNames

public String[] getSupportedPropertyNames()
Description copied from interface: XQDataSource
Returns an array containing the property names supported by this XQDataSource. Implementations that support user name and password must recognize the user name and password properties listed below.

user the user name to use for creating a connection
password the password to use for creating a connection

Any additional properties are implementation-defined.

Specified by:
getSupportedPropertyNames in interface XQDataSource
Returns:
String[] an array of property names supported by this implementation

setProperty

public void setProperty(String name,
                        String value)
                 throws XQException
Description copied from interface: XQDataSource
Sets the named property to the specified value. If a property with the same name was already set, then this method will override the old value for that property with the new value.

If the implementation does not support the given property or if it can determine that the value given for this property is invalid, then an exception is thrown. If an exception is thrown, then no previous value is overwritten.

Specified by:
setProperty in interface XQDataSource
Parameters:
name - the name of the property to set
value - the value of the named property
Throws:
XQException - if (1) the given property is not recognized, (2) the value for the given property is determined to be invalid, or (3) the name parameter is null

getProperty

public String getProperty(String name)
                   throws XQException
Description copied from interface: XQDataSource
Returns the current value of the named property if set, else null. If the implementation does not support the given property then an exception is raised.

Specified by:
getProperty in interface XQDataSource
Parameters:
name - the name of the property whose value is needed
Returns:
String representing the value of the required property if set, else null
Throws:
XQException - if (1) a given property is not supported, or (2) the name parameter is null

getConnection

public XQConnection getConnection(Connection con)
                           throws XQException
Deprecated. 

Calling this method will throw an XQException. MarkLogic XQConnections can not be built from JDBC Connections.

Specified by:
getConnection in interface XQDataSource
Parameters:
con - an existing JDBC connection
Returns:
a connection to the XML datasource
Throws:
XQException - calling this method will throw an XQException