com.softwareag.tamino.db.api.accessor

Interface TStreamAccessor

All Superinterfaces:

TAccessor, TInvalidatableAccessor

All Known Implementing Classes:

TStreamAccessorImpl, TStreamAccessorTimeLoggingImpl

public interface TStreamAccessor
extends TAccessor

The TStreamAccessor is the lowest level of access to data (XML or non-XML) stored in a Tamino database. The basic operations are insert, update, delete, query operations, retrieve cursor operations and schema define and undefine. Each of these operations returns a TInputStream object that contains the Tamino response document. It is the responsibilty of the client to process the stream content. All higher level accessors (e.g. TXMLObjectAccessor, TNonXMLObjectAccessor) are built on top of the TStreamAccessor.

Version:

$Revision: 1.26 $

Author:

Marcus Schreyer

Method Summary

Methods

Modifier and Type	Method and Description
TInputStream	admin(java.lang.String commandValue) Execute an administrative command with the given command value and return the result as an input stream.
TInputStream	close(TPreparedXQuery pQuery) Removes prepared XQuery.
TInputStream	closeCursor(java.lang.String cursorHandle) Releases a cursor.
TInputStream	define(TDataObject dataObject) Defines a schema represented by the dataObject input parameter in the Tamino database.
TInputStream	define(TDataObject[] dataObjects) Defines multiple schemas stored in an array of dataObjects.
TInputStream	define(TDataObject[] dataObjects, TDefineMode defineMode) Defines multiple schemas stored in an array of dataObjects.
TInputStream	define(TDataObject dataObject, boolean asTest) Deprecated. Please use the method define( TDataObject dataObject, TDefineMode defineMode ) instead.
TInputStream	define(TDataObject dataObject, TDefineMode defineMode) Defines a Tamino schema depending on the defineMode indicator into the current database.
TInputStream	delete(TDataObject dataObject) Deletes the document represented by the TDataObject instance in the Tamino database.
TInputStream	delete(TQuery query) Deletes a set of documents specified by the X-Query expression.
TInputStream	execute(TPreparedXQuery xQuery) Executes prepared XQuery.
TInputStream	fetchCursor(java.lang.String cursorHandle, int cursorPosition, int fetchQuantity) Fetches a number of documents from a cursor.
TScroll	getScrollType() Gets the scroll type.
TInputStream	insert(TDataObject dataObject) Inserts the document represented by the TDataObject instance into the Tamino database.
TInputStream	openCursor(TPreparedXQuery xquery) Opens a Tamino cursor for a set of documents that satisfies the PreparedXQuery expression.
TInputStream	openCursor(TPreparedXQuery xquery, int cursorPosition, int fetchQuantity) Opens a Tamino cursor for a set of documents that satisfies the TPreparedXQuery expression.
TInputStream	openCursor(TQuery query) Opens a Tamino cursor for a set of documents that satisfies the query expression.
TInputStream	openCursor(TQuery query, int cursorPosition, int fetchQuantity) Opens a Tamino cursor for a set of documents that satisfies the query expression.
TInputStream	openCursor(TXQuery xquery) Opens a Tamino cursor for a set of documents that satisfies the X-Query expression.
TInputStream	openCursor(TXQuery xquery, int cursorPosition, int fetchQuantity) Opens a Tamino cursor for a set of documents that satisfies the xquery expression.
TInputStream	prepare(TPreparedXQuery xQuery) In order to separate the compilation from the execution of XQuery Tamino provides interfaces for PREPARE and EXECUTE.
TInputStream	query(TQuery query) Queries Tamino to retrieve a set of documents that satisfies the query expression.
TInputStream	retrieve(TDataObject dataObject) Retrieves a single document from Tamino.
TStreamHeader	retrieveHeader(TDataObject dataObject) Just retrieves the ´meta´ data of a single document from Tamino.
void	setScrollType(TScroll scroll) Sets the scroll type ('yes' or 'no').
TInputStream	undefine(java.lang.String collection, java.lang.String schema) Undefines a schema specified by its name from the specified collection.
TInputStream	undefine(TUndefineItem[] undefineItems) In order to undefine a schema cluster, it is possible to specify a list of objects in an _UNDEFINE command: _UNDEFINE=undefineList where- undefineList -> undefineItem[, undefineItem]* undefineItem -> collection[/schema[/doctype]]
TInputStream	update(TDataObject dataObject) Updates the document represented by the TDataObject instance in the Tamino database.
TInputStream	xquery(TXQuery xQuery) Queries for a specific set of XML documents stored within Tamino implicitly given by the specified XQuery statement.

Methods inherited from interface com.softwareag.tamino.db.api.accessor.TAccessor

cancelRequests, getAccessLocation, getApplicationName, getCanBeCancelled, getLockMode, getLockwaitMode, getMaximumRequestDuration, setAccessLocation, setApplicationName, setCanBeCancelled, setLockMode, setLockwaitMode, setMaximumRequestDuration

Methods inherited from interface com.softwareag.tamino.db.api.accessor.TInvalidatableAccessor

invalidate

Method Detail

insert

TInputStream insert(TDataObject dataObject)
                    throws TInsertException

Inserts the document represented by the TDataObject instance into the Tamino database. If the TDataObject carries an id, the insert operation ignores it. If a document already exists with the same docname this object will be replaced and no new document will be inserted.
Upon completion, the TInputStream returned contains the response document as returned by Tamino. The client needs to process this stream to obtain information like id or docname.
The following characterizes this behavior:

!dataObject.hasDocname()	Insert.
dataObject.hasDocname()	Insert, if a document with the given ino:docname does not exist.
dataObject.hasDocname()	Update, if a document with the given ino:docname already exists.

Parameters:

dataObject - the representation of the Tamino document that should be stored within Tamino.

Returns:

TInputStream containing the Tamino response document.

Throws:

TInsertException - signals an error while attempting the insert operation.

update

TInputStream update(TDataObject dataObject)
                    throws TUpdateException

Updates the document represented by the TDataObject instance in the Tamino database. As a prerequisite, the TDataObject either has to provide an id or docname. The id has a higher priority than the docname which means that if both are given, the id is taken as the update parameter instead of the docname. If no document exists with the same docname a new document will be inserted, otherwise the document will be replaced. Upon completion, the TInputStream returned contains the response document as returned by Tamino. The client needs to process this stream to obtain information like id or docname.
The following characterizes this behavior:

dataObject.hasId()	Update, if the document with the given id exists.
dataObject.hasId()	Insert, if the document with the given id does not exist.
!dataObject.hasId() && dataObject.hasDocname()	Update, if the document with the given docname exists.
!dataObject.hasId() && dataObject.hasDocname()	Insert, if the document with the given docname does not exist.

Parameters:

dataObject - the representation of the document that should be updated in Tamino.

Returns:

TInputStream containing the Tamino response document.

Throws:

TUpdateException - signals an error while attempting the update operation.

delete

TInputStream delete(TDataObject dataObject)
                    throws TDeleteException

Deletes the document represented by the TDataObject instance in the Tamino database.

Parameters:

dataObject - the representation of the XML document to be deleted from Tamino.

Returns:

TInputStream containing the Tamino response document.

Throws:

TDeleteException - signals an error while attempting the delete operation.

delete

TInputStream delete(TQuery query)
                    throws TDeleteException

Deletes a set of documents specified by the X-Query expression.

Parameters:

query - query expression which specifies a set of documents to be deleted.

Returns:

TInputStream containing the Tamino response document.

Throws:

TDeleteException - signals an error while attempting the delete operation.

query

TInputStream query(TQuery query)
                   throws TQueryException

Queries Tamino to retrieve a set of documents that satisfies the query expression. This set is returned as a whole. If the result set is to be retrieved in steps, you can use a cursor.

Parameters:

query - query expression which specifies a set of documents to be retrieved.

Returns:

TInputStream containing the Tamino response document.

Throws:

TQueryException - signals an error while attempting the query operation.

xquery

TInputStream xquery(TXQuery xQuery)
                    throws TXQueryException

Queries for a specific set of XML documents stored within Tamino implicitly given by the specified XQuery statement.

This feature requires Tamino 4.1

Parameters:

xQuery - is the xquery expression.

Returns:

TInputStream containing Tamino's response document as a core input stream.

Throws:

TXQueryException - due to access problems.

prepare

TInputStream prepare(TPreparedXQuery xQuery)
                     throws TXQueryException

In order to separate the compilation from the execution of XQuery Tamino provides interfaces for PREPARE and EXECUTE. The PREPARE command gets the XQuery string as argument. It returns a handle that identifies the prepared query within a session. This handle is stored in TXQuery object which is used afterwards to execute the prepared XQuery. A query can only be prepared in a session context. Therfore the live time of a prepared query is bounded to the enclosing session. All prepared queries die with closing the session.

This feature requires Tamino 4.4

Parameters:

xQuery - is the xquery expression.

Returns:

TInputStream containing Tamino's response document as a core input stream.

Throws:

TXQueryException - due to access problems.

execute

TInputStream execute(TPreparedXQuery xQuery)
                     throws TXQueryException

Executes prepared XQuery.

This feature requires Tamino 4.4

Parameters:

xQuery - is the xquery expression.

Returns:

TInputStream containing Tamino's response document as a core input stream.

Throws:

TXQueryException - due to access problems.

retrieve

TInputStream retrieve(TDataObject dataObject)
                      throws TRetrieveException

Retrieves a single document from Tamino. The document is retrieved by its docname or id as set in the TDataObject instance passed as input parameter and not by a query expression. If both docname and id are present in the TDataObject instance, the docname is used.

The document returned is in principle the same as the document contained in the result set returned by a query expression of the following format:

 <Root>/[ino:id=<id>]
 <Root>/[ino:docname=<docname>]
 

If an XML document is retrieved, there is a number of differences between the XML document as returned by one of these queries and the XML document as returned by the retrieve method. The retrieve method returns the XML document as it was originally stored in Tamino without additional Tamino-specific attributes and complete with XML meta-information like prologue information. In detail the differences are:

• A query returns the Tamino response document as a TInputStream instance, which contains all XML documents. The retrieve method returns the XML document itself as a TInputStream instance.
• The XML document as returned by a query contains the Tamino specific attributes, like ino:id and ino:docname. The XML document returned by retrieve does not include these attributes.
• The XML document as returned by a query contains no prolog information. The XML document returned by retrieve includes this information as it was in the originally stored document.
• Tamino response information is only available in the Tamino response document. This implies that no detailed response information is available via the retrieve method.
• In case of an exception, the exception thrown during the processing of the query method will include detailed information via the TAccessFailure instance contained in the exception. This information is not available in an exception thrown during the processing of a retrieve method.

Parameters:

dataObject - a TDataObject instance specifying by its doctype, id or docname information which document to retrieve from Tamino.

Returns:

a TInputStream instance containing the document retrieved from Tamino. Note that the document is not wrapped in a Tamino response structure.

Throws:

TRetrieveException - signals an error while attempting the retrieve operation.

retrieveHeader

TStreamHeader retrieveHeader(TDataObject dataObject)
                             throws TRetrieveException

Just retrieves the ´meta´ data of a single document from Tamino. This data is retrieved by its docname or id as set in the TDataObject instance passed as input parameter and not by a query expression. If both docname and id are present in the TDataObject instance, the docname is used.

This method behaves like the retrieve() method except that it does not retieve the whole document but only it ´meta´ data, which is contained in the TStreamHeader.

Parameters:

dataObject - a TDataObject instance specifying by its doctype, id or docname information which document to retrieve from Tamino.

Returns:

a TStreamHeader instance containing the documents ´meta´ data.

Throws:

TRetrieveException - signals an error while attempting the retrieve operation.

See Also:

retrieve(TDataObject)

define

TInputStream define(TDataObject dataObject)
                    throws TDefineException

Defines a schema represented by the dataObject input parameter in the Tamino database. If the schema already exists in the same collection, Tamino attempts to update the schema, otherwise a new schema is created. The input schema may be a TSD2 or TSD3 schema. It is recommended to use TSD3 whenever possible.

Parameters:

dataObject - containing the schema to be defined in Tamino.

Returns:

TInputStream containing the Taminos response document.

Throws:

TDefineException - signals an error while attempting the define operation.

define

TInputStream define(TDataObject[] dataObjects)
                    throws TDefineException

Defines multiple schemas stored in an array of dataObjects. If the schema already exists in the same collection, Tamino attempts to update the schema, otherwise a new schema is created.

Parameters:

array - of dataObjects containing the schemas to be defined in Tamino.

Returns:

TInputStream containing the Taminos response document.

Throws:

TDefineException - signals an error while attempting the define operation.

define

TInputStream define(TDataObject dataObject,
                  boolean asTest)
                    throws TDefineException

Deprecated. Please use the method define( TDataObject dataObject, TDefineMode defineMode ) instead.

Defines a schema represented by the dataObject input parameter in the Tamino database. The input schema must be a TSD3 schema. If the asTest parameter is true, Tamino only tests the input schema, but the schema is not defined in the database. If asTest is false the behaviour is the same as the define(dataObject). Please note, that the usage of this method is for Software AG internal use only.

Parameters:

dataObject - containing the TSD3 schema to be defined in Tamino.

asTest - indicates if the input schema should only be tested. If true the schema is tested otherwise the schema is physically defined.

Returns:

TInputStream containing the Taminos response document.

Throws:

TDefineException - signals an error while attempting the define operation. Note that this exception is not thrown in case of logical errors in the input schema. These errors are indicated in the response document returned by Tamino.

define

TInputStream define(TDataObject dataObject,
                  TDefineMode defineMode)
                    throws TDefineException

Defines a Tamino schema depending on the defineMode indicator into the current database. If defineMode.isTest() is true, Tamino only tests the input schema, but the schema is not defined in the database. If defineMode.isValidate() is true, first structure-based updefine tests are being performed for each doctype. If they fail, all instances of that doctype are validated against the new schema. No validation is being performed for the instances of non-XML doctypes. Please note, that the usage of this method is for Software AG internal use only.

Parameters:

dataObject - denotes the schema instance which should be defined on Tamino. There is no side effect when the schemaObject is being defined on Tamino.

defineMode - indicates if the input schema should only be tested and if it should be validated.

Returns:

TInputStream containing Tamino's response document as a core input stream.

Throws:

TDefineException - if the define for the given schema instance fails. This is the case regardless of the value for the asTest parameter.

define

TInputStream define(TDataObject[] dataObjects,
                  TDefineMode defineMode)
                    throws TDefineException

Defines multiple schemas stored in an array of dataObjects. If the schema already exists in the same collection, Tamino attempts to update the schema, otherwise a new schema is created.

Parameters:

array - of dataObjects containing the schemas to be defined in Tamino.

defineMode - indicates if the input schema should only be tested and if it should be validated.

Returns:

TInputStream containing the Taminos response document.

Throws:

TDefineException - signals an error while attempting the define operation.

undefine

TInputStream undefine(java.lang.String collection,
                    java.lang.String schema)
                      throws TUndefineException

Undefines a schema specified by its name from the specified collection. If no schema name is specified Tamino is requested to undefine the entire collection.

Parameters:

collection - name of the Tamino collection.

schema - name of a Tamino schema, if null or an empty string the collection is undefined.

Returns:

TInputStream containing the Tamino response document.

Throws:

TUndefineException - signals an error while attempting the undefine operation.

undefine

TInputStream undefine(TUndefineItem[] undefineItems)
                      throws TUndefineException

In order to undefine a schema cluster, it is possible to specify a list of objects in an _UNDEFINE command: _UNDEFINE=undefineList where- undefineList -> undefineItem[, undefineItem]* undefineItem -> collection[/schema[/doctype]]

Parameters:

undefineItems - Array of undefineItems.

Returns:

TResponse containing the Tamino result information of the undefine operation.

Throws:

TUndefineException - signals an error while attempting the undefine operation.

See Also:

TUndefineItem

openCursor

TInputStream openCursor(TQuery query)
                        throws TCursorException

Opens a Tamino cursor for a set of documents that satisfies the query expression. The purpose of a cursor is to retrieve the documents in steps instead of as a complete set as it is the case for the query method. Tamino establishes a cursor for the result set and returns a cursor handle for this set. You can obtain the cursor handle from the response document. You can retrieve the documents of the result set by using the fetchCursor method and passing it the cursor handle. Note that a cursor can only be established in the context of a local transaction.

This feature requires Tamino 3.1

Parameters:

query - expression which specifies a set of XML documents to be retrieved.

Returns:

TInputStream containing the Tamino response document. The response document contains the cursor handle.

Throws:

TCursorException - signals an error while attempting the open cursor operation.

openCursor

TInputStream openCursor(TXQuery xquery)
                        throws TCursorException

Opens a Tamino cursor for a set of documents that satisfies the X-Query expression. The purpose of a cursor is to retrieve the documents in steps instead of as a complete set as it is the case for the xquery method. Tamino establishes a cursor for the result set and returns a cursor handle for this set. You can obtain the cursor handle from the response document. You can retrieve the documents of the result set by using the fetchCursor method and passing it the cursor handle. Note that a cursor can only be established in the context of a local transaction.

This feature requires Tamino 4.1

Parameters:

xquery - expression which specifies a set of XML documents to be retrieved.

Returns:

TInputStream containing the Tamino response document. The response document contains the cursor handle.

Throws:

TCursorException - signals an error while attempting the open cursor operation.

openCursor

TInputStream openCursor(TPreparedXQuery xquery)
                        throws TCursorException

Opens a Tamino cursor for a set of documents that satisfies the PreparedXQuery expression. The purpose of a cursor is to retrieve the documents in steps instead of as a complete set as it is the case for the xquery method. Tamino establishes a cursor for the result set and returns a cursor handle for this set. You can obtain the cursor handle from the response document. You can retrieve the documents of the result set by using the fetchCursor method and passing it the cursor handle. Note that a cursor can only be established in the context of a local transaction.

This feature requires Tamino 4.1

Parameters:

xquery - expression which specifies a set of XML documents to be retrieved.

Returns:

TInputStream containing the Tamino response document. The response document contains the cursor handle.

Throws:

TCursorException - signals an error while attempting the open cursor operation.

openCursor

TInputStream openCursor(TQuery query,
                      int cursorPosition,
                      int fetchQuantity)
                        throws TCursorException

Opens a Tamino cursor for a set of documents that satisfies the query expression. The purpose of a cursor is to retrieve the documents in steps instead of as a complete set as it is the case for the query method. Tamino establishes a cursor for the result set and returns a cursor handle for this set. You can obtain the cursor handle from the response document. The response document also contains a number of the documents included in the result set. The documents returned are specified by the cursorPosition and fetchQuantity parameters. You can retrieve further documents of the result set by using the fetchCursor method and passing it the cursor handle. Note that a cursor can only be established in the context of a local transaction.

This feature requires Tamino 3.1

Parameters:

query - expression which specifies a set of XML documents to be retrieved.

cursorPosition - the index of the first document in the result set to be returned. The first document in the result set has index 1.

fetchQuantity - the number of documents to be returned.

Returns:

TInputStream containing the Tamino response document.

Throws:

TCursorException - signals an error while attempting the open cursor operation.

openCursor

TInputStream openCursor(TXQuery xquery,
                      int cursorPosition,
                      int fetchQuantity)
                        throws TCursorException

Opens a Tamino cursor for a set of documents that satisfies the xquery expression. The purpose of a cursor is to retrieve the documents in steps instead of as a complete set as it is the case for the xquery method. Tamino establishes a cursor for the result set and returns a cursor handle for this set. You can obtain the cursor handle from the response document. The response document also contains a number of the documents included in the result set. The documents returned are specified by the cursorPosition and fetchQuantity parameters. You can retrieve further documents of the result set by using the fetchCursor method and passing it the cursor handle. Note that a cursor can only be established in the context of a local transaction. The Tamino cursor is realized as an insensitive scrollable cursor. Please refer to the description of the XQuery cursor in the Tamino Server documentation for details.

This feature requires Tamino 4.1

Parameters:

xquery - expression which specifies a set of XML documents to be retrieved.

cursorPosition - the index of the first document in the result set to be returned. The first document in the result set has index 1.

fetchQuantity - the number of documents to be returned.

Returns:

TInputStream containing the Tamino response document.

Throws:

TCursorException - signals an error while attempting the open cursor operation.

openCursor

TInputStream openCursor(TPreparedXQuery xquery,
                      int cursorPosition,
                      int fetchQuantity)
                        throws TCursorException

Opens a Tamino cursor for a set of documents that satisfies the TPreparedXQuery expression. The purpose of a cursor is to retrieve the documents in steps instead of as a complete set as it is the case for the xquery method. Tamino establishes a cursor for the result set and returns a cursor handle for this set. You can obtain the cursor handle from the response document. The response document also contains a number of the documents included in the result set. The documents returned are specified by the cursorPosition and fetchQuantity parameters. You can retrieve further documents of the result set by using the fetchCursor method and passing it the cursor handle. Note that a cursor can only be established in the context of a local transaction. The Tamino cursor is realized as an insensitive scrollable cursor. Please refer to the description of the XQuery cursor in the Tamino Server documentation for details.

This feature requires Tamino 4.1

Parameters:

xquery - expression which specifies a set of XML documents to be retrieved.

cursorPosition - the index of the first document in the result set to be returned. The first document in the result set has index 1.

fetchQuantity - the number of documents to be returned.

Returns:

TInputStream containing the Tamino response document.

Throws:

TCursorException - signals an error while attempting the open cursor operation.

fetchCursor

TInputStream fetchCursor(java.lang.String cursorHandle,
                       int cursorPosition,
                       int fetchQuantity)
                         throws TCursorException

Fetches a number of documents from a cursor. The documents returned are specified by the cursorPosition and fetchQuantity parameters.

This feature requires Tamino 3.1

Parameters:

cursorHandle - the cursor handle identifying the Tamino cursor.

cursorPosition - the index of the first document in the result set to be returned. The first document in the result set has index 1.

fetchQuantity - the number of documents to be returned.

Returns:

TInputStream containing the Tamino response document.

Throws:

TCursorException - signals an error while attempting the fetch cursor operation.

closeCursor

TInputStream closeCursor(java.lang.String cursorHandle)
                         throws TCursorException

Releases a cursor. This operation releases the cursor specific resources. After a cursor is closed, no further operations referring to this cursor are possible.

This feature requires Tamino 3.1

Parameters:

cursorHandle - the cursor handle identifying the Tamino cursor.

Returns:

TInputStream containing the Tamino response document.

Throws:

TCursorException - signals an error while attempting the close cursor operation.

admin

TInputStream admin(java.lang.String commandValue)
                   throws TAdminException

Execute an administrative command with the given command value and return the result as an input stream.

Returns:

TInputStream containing Tamino's response document as a core input stream.

Throws:

TAdminException - signals an error while executimg the command.

setScrollType

void setScrollType(TScroll scroll)

Sets the scroll type ('yes' or 'no').

Parameters:

scroll - - specifies whether cursor is scrollable or not.

getScrollType

TScroll getScrollType()

Gets the scroll type.

Returns:

TScroll - specifies whether cursor is scrollable or not.

close

TInputStream close(TPreparedXQuery pQuery)
                   throws TXQueryException

Removes prepared XQuery.

Parameters:

pQuery - is the Prepared XQuery to be removed.

Returns:

TInputStream containing Tamino's response document as a core input stream.

Throws:

TXQueryException - due to access problems.