com.marklogic.xcc
Interface Session

All Superinterfaces:

Closeable

public interface Session
extends Closeable

A Session object represents a conversation with a contentbase (database) on a MarkLogic Server instance (ContentSource) and holds state information related to that conversation. Connections to the server are created and released as needed and are automatically pooled.

Sessions are created by invoking one of the ContentSource.newSession() factory methods.

Nested Class Summary

static class

Session.TransactionMode The transaction mode for the session, which governs how transactions are created, and whether they are automatically committed.

Method Summary

void	close() Shutdown and invalidate this Session and release any resources it may be holding.
void	commit() Commits the current transaction.
URI	getConnectionUri() Return a URI that describes connection information for this Session, if available.
ContentbaseMetaData	getContentbaseMetaData() Meta-information about the contentbase associated with this Session.
String	getContentBaseName() Return the contentbase name provided when this Session was created, if any.
ContentSource	getContentSource() Obtain a reference to the ContentSource object from which this Session instance was obtained.
BigInteger	getCurrentServerPointInTime() Issues a query to the server and returns the most recent system commit timestamp.
RequestOptions	getDefaultRequestOptions() Returns the RequestOptions instance set on this Session object.
RequestOptions	getEffectiveRequestOptions() Returns an instance of RequestOptions that represents the effective default request options for this Session (ie, the options that would be applied if no options are applied to a specific Request.
Logger	getLogger() Get the java.util.logging.Logger instance set on this Session.
Session.TransactionMode	getTransactionMode() Get the current transaction mode.
int	getTransactionTimeout() Get the current transaction timeout.
UserCredentials	getUserCredentials() Returns the user identity associated with this Session.
Object	getUserObject() Fetch the current user object set for this Session.
XAResource	getXAResource() Returns an instance of the XAResource interface, specific to this Session object.
void	insertContent(Content content) Insert the given Content into the contentbase.
void	insertContent(Content[] content) Insert all the Content objects in the contentbase as a transactional unit.
List<RequestException>	insertContentCollectErrors(Content[] content) Insert all the Content objects in the contentbase.
boolean	isClosed() True if this Session object is closed.
AdhocQuery	newAdhocQuery(String queryText) Create a new AdhocQuery object and initialize it with the given query string.
AdhocQuery	newAdhocQuery(String queryText, RequestOptions options) Create a new AdhocQuery object and initialize it with the given query string and RequestOptions object.
ModuleInvoke	newModuleInvoke(String moduleUri) Create a new ModuleInvoke object and initialize it with the given module URI.
ModuleInvoke	newModuleInvoke(String moduleUri, RequestOptions options) Create a new ModuleInvoke object and initialize it with the given module URI and RequestOptions object.
ModuleSpawn	newModuleSpawn(String moduleUri) Create a new ModuleSpawn object and initialize it with the given module URI.
ModuleSpawn	newModuleSpawn(String moduleUri, RequestOptions options) Create a new ModuleSpawn object and initialize it with the given module URI and RequestOptions object.
void	rollback() Rolls back the current transaction.
void	setDefaultRequestOptions(RequestOptions options) This method accepts an instance of RequestOptions which acts as the default settings for invocations of submitRequest(Request).
void	setLogger(Logger logger) Set the Logger instance to which log messages resulting from operations on this Session should be written.
void	setTransactionMode(Session.TransactionMode mode) Sets the transaction mode to the given value.
void	setTransactionTimeout(int seconds) Sets the timeout for transactions
void	setUserObject(Object userObject) Attach, or clear, an opaque user-provided object to this Session.
ResultSequence	submitRequest(Request request) Submit a Request to the contentbase and return the (possibly empty) ResultSequence.

Method Detail

getContentSource

ContentSource getContentSource()

Obtain a reference to the ContentSource object from which this Session instance was obtained.

Returns:

The ContentSource from which this session was instantiated.

getUserCredentials

UserCredentials getUserCredentials()

Returns the user identity associated with this Session.

Returns:

The user identity as a String.

getContentBaseName

String getContentBaseName()

Return the contentbase name provided when this Session was created, if any. Note that this is the name given, if any, when the Session and/or ContentSource was created. If no explicit name was given then a default was used and this method will return null. To determine the actual name of the contentbase associated with a Session, call ContentbaseMetaData.getContentBaseName().

For example:

String cbname = session.getContentbaseMetaData().getContentBaseName();

The above code makes a round-trip call to the server. This method is a convenience that returns a locally stored String, or null.

Returns:

The contentbase name stored in the Session, or null.

See Also:

ContentSourceFactory.newContentSource(java.net.URI), ContentSourceFactory.newContentSource(String, int, String, String, String), ContentSource.newSession(String), ContentSource.newSession(String, String, String), ContentbaseMetaData, getContentbaseMetaData()

getXAResource

XAResource getXAResource()

Returns an instance of the XAResource interface, specific to this Session object. This can be used to take part in JTA distributed transactions using an implementation of javax.transaction.TransactionManager.

Returns:

The XAResource object.

setTransactionMode

void setTransactionMode(Session.TransactionMode mode)

Sets the transaction mode to the given value. The initial value is TransactionMode.AUTO.

If the transaction mode is TransactionMode.AUTO, a new transaction is created for every request, and committed (or rolled back) at the end of that request. The type of transaction created is determined automatically by query analysis.

If transaction mode is TransactionMode.QUERY or TransactionMode.UPDATE, requests are grouped under transactions bounded by calls to Session.commit() or Session.rollback(). If transaction mode is TransactionMode.QUERY, then a read-only query transaction is created to group requests. If transaction mode is TransactionMode.UPDATE, then a locking update transaction is created. If an updating request is executed under a read-only TransactionMode.QUERY transaction, a RequestException is thrown.

Calling setTransactionMode() while a transaction is active has no effect on the current transaction.

Parameters:

mode - The new transaction mode

getTransactionMode

Session.TransactionMode getTransactionMode()

Get the current transaction mode.

Returns:

The current transaction mode setting.

setTransactionTimeout

void setTransactionTimeout(int seconds)
                           throws RequestException

Sets the timeout for transactions

Parameters:

seconds - The number of seconds before the transaction times out

Throws:

RequestException - If there is a problem communicating with the server.

getTransactionTimeout

int getTransactionTimeout()
                          throws RequestException

Get the current transaction timeout.

Returns:

The current transaction timeout setting.

Throws:

RequestException - If there is a problem communicating with the server.

commit

void commit()
            throws RequestException

Commits the current transaction.

Throws:

IllegalStateException - If transaction mode is set to TransactionMode.AUTO.

RequestException - If there is a problem communicating with the server.

rollback

void rollback()
              throws RequestException

Rolls back the current transaction.

Throws:

IllegalStateException - If transaction mode is set to TransactionMode.AUTO.

RequestException - If there is a problem communicating with the server.

close

void close()

Shutdown and invalidate this Session and release any resources it may be holding. Any currently open ResultSequence objects created from this Session will be invalidated and closed, and any open transaction will be rolled back.

Specified by:

close in interface Closeable

isClosed

boolean isClosed()

True if this Session object is closed.

Returns:

true if this Session has been closed.

submitRequest

ResultSequence submitRequest(Request request)
                             throws RequestException

Submit a Request to the contentbase and return the (possibly empty) ResultSequence.

Parameters:

request - A Request instance (either ModuleInvoke or AdhocQuery that specifies the query to be run, associated options and variables.

Returns:

A ResultSequence instance encapsulating the result of the query execution.

Throws:

IllegalStateException - If this Session has been closed.

RequestException - If there is a problem communicating with the server.

newAdhocQuery

AdhocQuery newAdhocQuery(String queryText,
                         RequestOptions options)

Create a new AdhocQuery object and initialize it with the given query string and RequestOptions object.

Parameters:

queryText - The ad-hoc XQuery code to be evaluated.

options - An instance of RequestOptions to be set on the return AdhocQuery object. This can be overridden later.

Returns:

An initialized instance of AdhocQuery.

newAdhocQuery

AdhocQuery newAdhocQuery(String queryText)

Create a new AdhocQuery object and initialize it with the given query string.

Parameters:

queryText - The ad-hoc XQuery code to be evaluated.

Returns:

An initialized instance of AdhocQuery.

newModuleInvoke

ModuleInvoke newModuleInvoke(String moduleUri,
                             RequestOptions options)

Create a new ModuleInvoke object and initialize it with the given module URI and RequestOptions object.

Parameters:

moduleUri - The URI of a module on the server to be invoked.

options - An instance of RequestOptions to be set on the returned ModuleInvoke object. This can be overridden later.

Returns:

An initialized instance of ModuleInvoke.

See Also:

ModuleInvoke

newModuleInvoke

ModuleInvoke newModuleInvoke(String moduleUri)

Create a new ModuleInvoke object and initialize it with the given module URI.

Parameters:

moduleUri - The URI of a module on the server to be invoked.

Returns:

An initialized instance of ModuleInvoke.

See Also:

ModuleInvoke

newModuleSpawn

ModuleSpawn newModuleSpawn(String moduleUri,
                           RequestOptions options)

Create a new ModuleSpawn object and initialize it with the given module URI and RequestOptions object.

Parameters:

moduleUri - The URI of a module on the server to be invoked.

options - An instance of RequestOptions to be set on the returned ModuleSpawn object. This can be overridden later.

Returns:

An initialized instance of ModuleSpawn.

See Also:

ModuleInvoke

newModuleSpawn

ModuleSpawn newModuleSpawn(String moduleUri)

Create a new ModuleSpawn object and initialize it with the given module URI.

Parameters:

moduleUri - The URI of a module on the server to be invoked.

Returns:

An initialized instance of ModuleSpawn.

See Also:

ModuleInvoke

insertContent

void insertContent(Content content)
                   throws RequestException

Insert the given Content into the contentbase. This is equivalent to calling insertContent(Content[]) with an array length of one. Upon return, the content will have been inserted and committed.

Content objects that are rewindable will be automatically retried if a recoverable error occurs during transmission to the server. To specify the maximum number of retry attemtps, set an instance of RequestOptions with the desired value ( RequestOptions.setMaxAutoRetry(int)) using the setDefaultRequestOptions(RequestOptions) method prior to invoking this method.

The retry/timeout algorithm is different for document insert than for query requests. For queries, a constant delay ocurrs between each retry. For inserts, an exponentially increasing backoff delay is used. Retryable exceptions usually ocurr during document insert when a cluster communication recover is in progress. Inter-try delays increase up to a maximum of about two seconds until the retry count is exhausted. The default first delay is 125 milliseconds with a count of 64, which works out to an overall retry interval of about two minutes before giving up.

Parameters:

content - A single Content instance to be inserted in the contentbase.

Throws:

IllegalStateException - If this Session has been closed.

RequestException - If there is a problem communicating with the server.

insertContent

void insertContent(Content[] content)
                   throws RequestException

Insert all the Content objects in the contentbase as a transactional unit. If this is called within an auto-commit transaction, all documents will have been committed upon successful return. If an exception is thrown, none of the documents will have been committed.

The presence in the array of multiple Content objects with the same URI is not considered an error. Though all of the documents are committed together, each document insertion is processed separately, in array order, and the last write wins.

Parameters:

content - An array of Content objects that are inserted as a group atomically.

Throws:

IllegalStateException - If this Session has been closed.

RequestException - If there is a problem communicating with the server.

insertContentCollectErrors

List<RequestException> insertContentCollectErrors(Content[] content)
                                                  throws RequestException

Insert all the Content objects in the contentbase. If a RequestServerException is caught the remaining documents will continue to be submitted.

If the session's TransactionMode is UPDATE, the transaction contains all successful inserts, and all failed inserts are rolled back automatically.

If the session's TransactionMode is AUTO, all successful inserts will be committed upon return except if the last document in the array caused an error. In that case, the entire transaction will be rolled back.

The presence in the array of multiple Content objects with the same URI is not considered an error. Though all of the documents are committed together, each document insertion is processed separately, in array order, and the last write wins.

Parameters:

content - An array of Content objects that are inserted as a group in the current transaction.

Returns:

null if no error is caught; otherwise, a list of RequestException.

Throws:

IllegalStateException - If this Session has been closed or if the session is not in UPDATE transaction mode.

RequestException - If there is a problem communicating with the server.

getContentbaseMetaData

ContentbaseMetaData getContentbaseMetaData()

Meta-information about the contentbase associated with this Session.

Returns:

An instance of ContentbaseMetaData.

setDefaultRequestOptions

void setDefaultRequestOptions(RequestOptions options)

This method accepts an instance of RequestOptions which acts as the default settings for invocations of submitRequest(Request). These defaults may be overridden by a RequestOptions instance on individual requests. If a RequestOptions object is set on both the Session and the Request, then both are applied with the values of the Request object taking precedence.

Parameters:

options - An instance of RequestOptions. A value of null indicates that defaults should be re-applied.

getDefaultRequestOptions

RequestOptions getDefaultRequestOptions()

Returns the RequestOptions instance set on this Session object. An instance of RequestOptions with default settings is created when the Session is created and whenever you pass null to setDefaultRequestOptions(RequestOptions), so this method always returns a non-null value.

Returns:

An instance of RequestOptions.

getEffectiveRequestOptions

RequestOptions getEffectiveRequestOptions()

Returns an instance of RequestOptions that represents the effective default request options for this Session (ie, the options that would be applied if no options are applied to a specific Request. The values in the returned instance reflect the builtin defaults merged with the values in the options set by setDefaultRequestOptions(RequestOptions) (if any). The object returned is a copy, making changes to it will not affect option settings for the Session.

Returns:

An instance of RequestOptions.

getCurrentServerPointInTime

BigInteger getCurrentServerPointInTime()
                                       throws RequestException

Issues a query to the server and returns the most recent system commit timestamp. The value returned is as-of the time the query executes on the server. The returned value represents a point-in-time, or snapshot, of the contentbase. This value may be passed to RequestOptions.setEffectivePointInTime(java.math.BigInteger) to run queries as-of that contentbase state.

Returns:

A BigInteger value containing a point-in-time timestamp.

Throws:

RequestException - If there is a problem communicating with the server.

getLogger

Logger getLogger()

Get the java.util.logging.Logger instance set on this Session. If not explictly set with setLogger(Logger), the Logger inherited from the creating ContentSource is returned.

Returns:

A Logger instance

See Also:

ContentSource.getDefaultLogger(), ContentSource.setDefaultLogger(Logger)

setLogger

void setLogger(Logger logger)

Set the Logger instance to which log messages resulting from operations on this Session should be written.

Parameters:

logger - An instance of java.util.Logger

setUserObject

void setUserObject(Object userObject)

Attach, or clear, an opaque user-provided object to this Session. This object is not used or examined in any way by XCC. Client code may use this hook in any way it sees fit to associate state with the Session.

Parameters:

userObject - An opaque Object that may later be retrieved with getUserObject() . A value of null is acceptable.

getUserObject

Object getUserObject()

Fetch the current user object set for this Session.

Returns:

Return the object reference previously passed to setUserObject(Object), or null.

getConnectionUri

URI getConnectionUri()

Return a URI that describes connection information for this Session, if available. Connection information is dependent on the ConnectionProvider encapsulated in the ContentSource that created this Session. In most cases, the provider will be the built-in socket-based provider included with XCC. If a custom provider is in use and does not implement point-to-point socket connections, then this method will return null.

Otherwise, a URI instance is returned that contains information describing the connections that will be made to the server. For security reasons, the password provided when the ContentSource or Session was created is not returned. The password will be masked as "xxxx". The returned URI may be used to instantiate a new ContentSource, but the real password will need to be provided when calling ContentSource.newSession(String, String).

Returns:

An instance of URI, or null if the underlying ConnectionProvider does not implement convetional point-to-point socket connections, or if a URI object cannot be created from this Session.

Since:

3.2

See Also:

ContentSourceFactory.newContentSource(java.net.URI)