public interface Session
extends java.io.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.
Session implementation is not thread-safe.
Sessions are created by invoking one of the ContentSource.newSession()
factory methods.
Modifier and Type | Interface and Description |
---|---|
static class |
Session.TransactionMode
Deprecated.
|
static class |
Session.Update
Nature of a transaction: query, update or auto-detect based on the
statement.
|
Modifier and Type | Method and Description |
---|---|
void |
close()
Shutdown and invalidate this Session and release any resources it may be holding.
|
boolean |
commit()
Commits the current transaction.
|
int |
getCachedTxnTimeout()
Get the current transaction timeout cached in XCC.
|
java.net.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.
|
java.lang.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. |
java.math.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 . |
java.util.logging.Logger |
getLogger()
Get the java.util.logging.Logger instance set on this Session.
|
Session.TransactionMode |
getTransactionMode()
Deprecated.
|
int |
getTransactionTimeout()
Get the current transaction timeout by querying the server.
|
Session.Update |
getUpdate()
Returns update mode for the transaction: true, false, or auto.
|
UserCredentials |
getUserCredentials()
Returns the user identity associated with this Session.
|
java.lang.Object |
getUserObject()
Fetch the current user object set for this Session.
|
javax.transaction.xa.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. |
java.util.List<RequestException> |
insertContentCollectErrors(Content[] content)
Insert all the
Content objects in the contentbase. |
boolean |
isAutoCommit()
Returns true if the current session has auto commit enabled; false otherwise.
|
boolean |
isClosed()
True if this Session object is closed.
|
AdhocQuery |
newAdhocQuery(java.lang.String queryText)
Create a new
AdhocQuery object and initialize it with the given query string. |
AdhocQuery |
newAdhocQuery(java.lang.String queryText,
RequestOptions options)
Create a new
AdhocQuery object and initialize it with the given query string and
RequestOptions object. |
ModuleInvoke |
newModuleInvoke(java.lang.String moduleUri)
Create a new
ModuleInvoke object and initialize it with the given module URI. |
ModuleInvoke |
newModuleInvoke(java.lang.String moduleUri,
RequestOptions options)
Create a new
ModuleInvoke object and initialize it with the given module URI and
RequestOptions object. |
ModuleSpawn |
newModuleSpawn(java.lang.String moduleUri)
Create a new
ModuleSpawn object and initialize it with the given module URI. |
ModuleSpawn |
newModuleSpawn(java.lang.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 |
setAutoCommit(boolean autoCommit)
Switches on or off auto commit.
|
void |
setDefaultRequestOptions(RequestOptions options)
This method accepts an instance of
RequestOptions which acts as the default settings
for invocations of submitRequest(Request) . |
void |
setLogger(java.util.logging.Logger logger)
Set the Logger instance to which log messages resulting from operations on this Session
should be written.
|
void |
setTransactionMode(Session.TransactionMode mode)
Deprecated.
|
void |
setTransactionTimeout(int seconds)
Sets the timeout for transactions
|
void |
setUpdate(Session.Update update)
Sets the this session to be in a query or update transaction.
|
void |
setUserObject(java.lang.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 . |
ContentSource getContentSource()
ContentSource
object from which this Session instance was
obtained.ContentSource
from which this session was instantiated.UserCredentials getUserCredentials()
java.lang.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.
ContentSourceFactory.newContentSource(java.net.URI)
,
ContentSourceFactory.newContentSource(String, int, String, String, String)
,
ContentSource.newSession(String)
,
ContentSource.newSession(String, String, String)
,
ContentbaseMetaData
,
getContentbaseMetaData()
javax.transaction.xa.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.
@Deprecated 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. The type of transaction created is determined automatically by the query.
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. If transaction mode is TransactionMode.UPDATE_AUTO_COMMIT, a new transaction is created for every request, and is committed (or rolled back) at the end of that request.
Calling setTransactionMode() while a transaction is active has no effect on the current transaction.
mode
- The new transaction mode@Deprecated Session.TransactionMode getTransactionMode()
boolean isAutoCommit()
void setAutoCommit(boolean autoCommit)
autoCommit
- whether auto commit is true or false.Session.Update getUpdate()
void setUpdate(Session.Update update)
update
- true for update; false for query; or auto for
auto-detect based on the statement.void setTransactionTimeout(int seconds) throws RequestException
seconds
- The number of seconds before the transaction times outRequestException
- If there is a problem communicating with the server.int getTransactionTimeout() throws RequestException
RequestException
- If there is a problem communicating with the server.int getCachedTxnTimeout()
boolean commit() throws RequestException
RequestException
- If there is a problem communicating with the server.void rollback() throws RequestException
java.lang.IllegalStateException
- If transaction mode is set to TransactionMode.AUTO.RequestException
- If there is a problem communicating with the server.void close()
ResultSequence
objects created from this Session will be
invalidated and closed, and any open transaction will be rolled back.close
in interface java.lang.AutoCloseable
close
in interface java.io.Closeable
boolean isClosed()
ResultSequence submitRequest(Request request) throws RequestException
Request
to the contentbase and return the (possibly empty)
ResultSequence
.request
- A Request
instance (either ModuleInvoke
or AdhocQuery
that
specifies the query to be run, associated options and variables.ResultSequence
instance encapsulating the result of the query execution.java.lang.IllegalStateException
- If this Session has been closed.RequestException
- If there is a problem communicating with the server.AdhocQuery newAdhocQuery(java.lang.String queryText, RequestOptions options)
AdhocQuery
object and initialize it with the given query string and
RequestOptions
object.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.AdhocQuery
.AdhocQuery newAdhocQuery(java.lang.String queryText)
AdhocQuery
object and initialize it with the given query string.queryText
- The ad-hoc XQuery code to be evaluated.AdhocQuery
.ModuleInvoke newModuleInvoke(java.lang.String moduleUri, RequestOptions options)
ModuleInvoke
object and initialize it with the given module URI and
RequestOptions
object.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.ModuleInvoke
.ModuleInvoke
ModuleInvoke newModuleInvoke(java.lang.String moduleUri)
ModuleInvoke
object and initialize it with the given module URI.moduleUri
- The URI of a module on the server to be invoked.ModuleInvoke
.ModuleInvoke
ModuleSpawn newModuleSpawn(java.lang.String moduleUri, RequestOptions options)
ModuleSpawn
object and initialize it with the given module URI and
RequestOptions
object.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.ModuleSpawn
.ModuleInvoke
ModuleSpawn newModuleSpawn(java.lang.String moduleUri)
ModuleSpawn
object and initialize it with the given module URI.moduleUri
- The URI of a module on the server to be invoked.ModuleSpawn
.ModuleInvoke
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.
content
- A single Content
instance to be inserted in the contentbase.java.lang.IllegalStateException
- If this Session has been closed.RequestException
- If there is a problem communicating with the server.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.
content
- An array of Content
objects that are inserted as a group atomically.java.lang.IllegalStateException
- If this Session has been closed.RequestException
- If there is a problem communicating with the server.java.util.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 multipleContent
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.
content
- An array of Content
objects that are inserted as a
group in the current transaction.java.lang.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.ContentbaseMetaData getContentbaseMetaData()
ContentbaseMetaData
.void setDefaultRequestOptions(RequestOptions options)
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.options
- An instance of RequestOptions
. A value of null indicates that defaults
should be re-applied.RequestOptions getDefaultRequestOptions()
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.RequestOptions
.RequestOptions getEffectiveRequestOptions()
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.RequestOptions
.java.math.BigInteger getCurrentServerPointInTime() throws RequestException
RequestOptions.setEffectivePointInTime(java.math.BigInteger)
to run queries as-of
that contentbase state.BigInteger
value containing a point-in-time timestamp.RequestException
- If there is a problem communicating with the server.java.util.logging.Logger getLogger()
setLogger(Logger)
, the Logger inherited from the creating ContentSource
is
returned.ContentSource.getDefaultLogger()
,
ContentSource.setDefaultLogger(Logger)
void setLogger(java.util.logging.Logger logger)
logger
- An instance of java.util.Loggervoid setUserObject(java.lang.Object userObject)
userObject
- An opaque Object
that may later be retrieved with getUserObject()
. A value of null is acceptable.java.lang.Object getUserObject()
setUserObject(Object)
, or
null.java.net.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)
.
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.ContentSourceFactory.newContentSource(java.net.URI)
Copyright © 2018 MarkLogic Corporation. All Rights Reserved.
Complete online documentation for MarkLogic Server, XQuery and related components may be found at developer.marklogic.com