Overview | Package | Class | Tree | Deprecated | Index | Help
| XCC/J 4.2-9
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.marklogic.xcc
Interface Session

    public interface Session

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.

Method Summary
`void` | `close()` Shutdown and invalidate this Session and release any resources it may be holding.
`void` | `commit()` Not currently implemented
`boolean` | `getAutoCommit()` Deprecated.
`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.
`UserCredentials` | `getUserCredentials()` Returns the user identity associated with this Session.
`Object` | `getUserObject()` Fetch the current user object set for this Session.
`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.
`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()` Not currently implemented
`void` | `setAutoCommit(boolean newValue)` Deprecated.
`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` | `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()`

### setAutoCommit

    @Deprecated
    void setAutoCommit(boolean newValue)

  Deprecated.

### getAutoCommit

    @Deprecated
    boolean getAutoCommit()

  Deprecated.

### commit

    void commit()

  Not currently implemented

### rollback

    void rollback()

  Not currently implemented

### 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 also be invalidated and closed.

### 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. Upon successful return, all documents will have been committed. 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.

### 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)`

Overview | Package | Class | Tree | Deprecated | Index | Help
| XCC/J 4.2-9
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2003-2012 MarkLogic Corporation, All Rights Reserved.

Complete online documentation for MarkLogic Server, XQuery and related components may be found at developer.marklogic.com