com.softwareag.tamino.db.api.accessor
Interface TXMLObjectAccessor

All Superinterfaces:
TAccessor, TInvalidatableAccessor
All Known Implementing Classes:
TXMLObjectAccessorImpl, TXMLObjectAccessorTimeLoggingImpl

public interface TXMLObjectAccessor
extends TAccessor

TXMLObjectAccessor is the interface for the access of native XML data stored in a Tamino database. The basic operations are insert, update, delete and query. Each of these operations returns a TResponse object that contains the information as returned by Tamino in its response document. The TResponse instance returned by a query operation also contains a TXMLObjectIterator which can be used to iterate over the result set of XML documents. The type of XML instances depends on the XML object model that was used to instantiate the TXMLObjectAccessor.

Version:
$Revision: 1.33 $
Author:
Marcus Schreyer

Method Summary
 TResponse close(TPreparedXQuery pQuery)
          Removes prepared XQuery.
 TResponse delete(TQuery query)
          Deletes a set of XML documents specified by the query expression.
 TResponse delete(TXMLObject xmlObject)
          Deletes the XML document represented by the TXMLObject instance in the Tamino database.
 TScroll getScrollType()
          Gets the scroll type.
 TResponse insert(TXMLObject xmlObject)
          Inserts the XML document represented by the TXMLObject instance into the Tamino database.
 TResponse query(TQuery query)
          Queries Tamino to retrieve a set of XML documents that satisfies the query expression.
 TResponse query(TQuery query, int quantity)
          Queries Tamino to retrieve a set of XML documents that satisfies the query expression.
 TXMLObject retrieve(TXMLObject xmlObject)
          Retrieves a single XML document from Tamino.
 TStreamHeader retrieveHeader(TXMLObject xmlObject)
          Just retrieves the �meta� data of a single document from Tamino.
 void setScrollType(TScroll scroll)
          Sets the scroll type ('yes' or 'no').
 TResponse update(TXMLObject xmlObject)
          Updates the XML document represented by the TXMLObject instance in the Tamino database.
 TResponse xquery(TPreparedXQuery xquery)
          Queries Tamino to retrieve a set of XML documents that satisfies the prepared xquery expression.
 TResponse xquery(TPreparedXQuery xquery, int quantity)
          Queries Tamino to retrieve a set of XML documents that satisfies the prepared xquery expression.
 TResponse xquery(TXQuery xquery)
          Queries Tamino to retrieve a set of XML documents that satisfies the xquery expression.
 TResponse xquery(TXQuery xquery, int quantity)
          Queries Tamino to retrieve a set of XML documents that satisfies the xquery expression.
 
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

TResponse insert(TXMLObject xmlObject)
                 throws TInsertException
Inserts the XML document represented by the TXMLObject instance into the Tamino database. If the TXMLObject carries an id, the insert operation ignores it. If an XML document already exists with the same docname this object will be replaced and no new object will be inserted. If the insert succeeds, the id, collection and doctype properties are set on the TXMLObject instance.

The following characterizes this behavior:

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

Parameters:
xmlObject - the representation of the XML document that should be stored in Tamino.
Returns:
TResponse containing the Tamino result information of the insert operation.
Throws:
TInsertException - signals an error while attempting the insert operation.

update

TResponse update(TXMLObject xmlObject)
                 throws TUpdateException
Updates the XML document represented by the TXMLObject instance in the Tamino database. As a prerequisite, the TXMLObject 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 an update is done based on an id and the XML object being updated had a docname, the docname is deleted, i.e. the XML object no longer has a docname after the update operation.

If the TXMLObject instance carries no id and no XML object exists with the same docname a new object will be inserted, otherwise the object will be replaced.

The following characterizes this behavior:

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

Parameters:
xmlObject - the representation of the XML document to be updated in Tamino.
Returns:
TResponse containing the Tamino result information of the update operation.
Throws:
TUpdateException - signals an error while attempting the update operation.

delete

TResponse delete(TXMLObject xmlObject)
                 throws TDeleteException
Deletes the XML document represented by the TXMLObject instance in the Tamino database.

Parameters:
xmlObject - the representation of the XML document to be deleted from Tamino.
Returns:
TResponse containing the Tamino result information of the delete operation.
Throws:
TDeleteException - signals an error while attempting the delete operation.

delete

TResponse delete(TQuery query)
                 throws TDeleteException
Deletes a set of XML documents specified by the query expression.

Parameters:
query - query expression which specifies a set of XML documents to be deleted.
Returns:
TResponse containing the Tamino result information of the delete operation.
Throws:
TDeleteException - signals an error while attempting the delete operation.

query

TResponse query(TQuery query)
                throws TQueryException
Queries Tamino to retrieve a set of XML documents that satisfies the query expression. This set is returned as a whole. You can iterate over the result set of TXMLObject instances by using a TXMLObjectIterator instance.

Parameters:
query - query expression which specifies a set of XML documents to be retrieved.
Returns:
TResponse containing the Tamino result information of the query operation. You can use the TResponse object to obtain a TXMLObjectIterator to iterate over the result set of TXMLObject instances.
Throws:
TQueryException - signals an error while attempting the query operation.

xquery

TResponse xquery(TXQuery xquery)
                 throws TXQueryException
Queries Tamino to retrieve a set of XML documents that satisfies the xquery expression. This set is returned as a whole. You can iterate over the result set of TXMLObject instances by using a TXMLObjectIterator instance.

This feature requires Tamino 4.1

Parameters:
xquery - query expression which specifies a set of XML documents to be retrieved.
Returns:
TResponse containing the Tamino result information of the xquery operation. You can use the TResponse object to obtain a TXMLObjectIterator to iterate over the result set of TXMLObject instances.
Throws:
TXQueryException - signals an error while attempting the query operation.

xquery

TResponse xquery(TPreparedXQuery xquery)
                 throws TXQueryException
Queries Tamino to retrieve a set of XML documents that satisfies the prepared xquery expression. This set is returned as a whole. You can iterate over the result set of TXMLObject instances by using a TXMLObjectIterator instance.

This feature requires Tamino 4.4

Parameters:
xquery - prepared query expression which specifies a set of XML documents to be retrieved.
Returns:
TResponse containing the Tamino result information of the xquery operation. You can use the TResponse object to obtain a TXMLObjectIterator to iterate over the result set of TXMLObject instances.
Throws:
TXQueryException - signals an error while attempting the query operation.

xquery

TResponse xquery(TPreparedXQuery xquery,
                 int quantity)
                 throws TXQueryException
Queries Tamino to retrieve a set of XML documents that satisfies the prepared xquery expression. This set is returned as a whole. You can iterate over the result set of TXMLObject instances by using a TXMLObjectIterator instance.

This feature requires Tamino 4.4

Parameters:
xquery - prepared query expression which specifies a set of XML documents to be retrieved.
quantity - the number of documents to be retrieved in each step.
Returns:
TResponse containing the Tamino result information of the xquery operation. You can use the TResponse object to obtain a TXMLObjectIterator to iterate over the result set of TXMLObject instances.
Throws:
TXQueryException - signals an error while attempting the query operation.

query

TResponse query(TQuery query,
                int quantity)
                throws TQueryException
Queries Tamino to retrieve a set of XML documents that satisfies the query expression. The result set of the query operation is the same as if a quantity parameter had not been specified. The TXMLObjectIterator retrieves the resulting TXMLObject instances not as a whole, but in steps. The number of objects retrieved in each step is specified by the quantity parameter.

Please note, this operation can only be used in a local transaction mode. This is due to the fact that it makes use of a Tamino cursor which can only be used in a transactional context. The obtained result set is only available while the current local transaction is open. A commit, rollback or change of the transaction mode will terminate the transaction and invalidate the TXMLObjectIterator.

This feature requires Tamino 3.1

Parameters:
query - query expression which specifies a set of XML documents to be retrieved.
quantity - the number of documents to be retrieved in each step.
Returns:
TResponse containing the Tamino result information of the query operation. You can use the TResponse object to obtain a TXMLObjectIterator to iterate over the result set of TXMLObject instances.
Throws:
TQueryException - signals an error while attempting the query operation.

xquery

TResponse xquery(TXQuery xquery,
                 int quantity)
                 throws TXQueryException
Queries Tamino to retrieve a set of XML documents that satisfies the xquery expression. The result set of the xquery operation is the same as if a quantity parameter had not been specified. The TXMLObjectIterator retrieves the resulting TXMLObject instances not as a whole, but in steps. The number of objects retrieved in each step is specified by the quantity parameter.

Please note, this operation can only be used in a local transaction mode. This is due to the fact that it makes use of a Tamino cursor which can only be used in a transactional context. The obtained result set is only available while the current local transaction is open. A commit, rollback or change of the transaction mode will terminate the transaction and invalidate the TXMLObjectIterator. The Tamino cursor mentioned above 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 - query expression which specifies a set of XML documents to be retrieved.
quantity - the number of documents to be retrieved in each step.
Returns:
TResponse containing the Tamino result information of the xquery operation. You can use the TResponse object to obtain a TXMLObjectIterator to iterate over the result set of TXMLObject instances.
Throws:
TXQueryException - signals an error while attempting the query operation.

retrieve

TXMLObject retrieve(TXMLObject xmlObject)
                    throws TRetrieveException

Retrieves a single XML document from Tamino. The document is retrieved by its docname or id as set in the TXMLObject instance passed as input parameter and not by a query expression. If both docname and id are present in the TXMLObject 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>]
 

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 complete with XML meta-information like prologue information. In detail the differences are:

The TXMLObject instance returned is the same instance passed as the input parameter; no new instance is created. This may cause side effects in the following situation: In case both id and docname are set in the input TXMLObject instance, and the XML document is therefore retrieved using the docname attribute, the id returned by the getId method of the TXMLObject instance may not reflect the actual id of the XML document. This is because the id and docname attributes are not returned by Tamino when using the the single document retrieve method. The docname is obviously correct as it was used to retrieve the XML document in the first place. Note that if a TXMLObject instance retrieved via the retrieve method is subsequently used for an update, the update logic prefers the id over the docname.

Parameters:
xmlObject - a TXMLObject instance specifying by its doctype, id or docname information which XML document to retrieve from Tamino.
Returns:
a TXMLObject instance containing the XML document retrieved from Tamino. The instance returned is the same instance passed as the input parameter.
Throws:
TRetrieveException - signals an error while attempting the retrieve operation.

retrieveHeader

TStreamHeader retrieveHeader(TXMLObject xmlObject)
                             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 TXMLObject instance passed as input parameter and not by a query expression. If both docname and id are present in the TXMLObject instance, the docname is used.

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

Parameters:
xmlObject - a TXMLObject 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:
com.softwareag.tamino.db.api.accessor.TStreamAccessor#retrieve(TXMLObject)

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

TResponse close(TPreparedXQuery pQuery)
                throws TXQueryException
Removes prepared XQuery.

Parameters:
pQuery - is the Prepared XQuery to be removed.
Returns:
TResponse containing the Tamino result information of the close operation.
Throws:
TXQueryException - due to access problems.


Copyright (c) 2013 Software AG. All Rights Reserved.