com.softwareag.tamino.db.api.accessor
Class TXMLObjectAccessorImpl

java.lang.Object
  extended by com.softwareag.tamino.db.api.accessor.TAbstractAccessor
      extended by com.softwareag.tamino.db.api.accessor.TXMLObjectAccessorImpl
All Implemented Interfaces:
TAccessor, TInvalidatableAccessor, TXMLObjectAccessor
Direct Known Subclasses:
TXMLObjectAccessorTimeLoggingImpl

public class TXMLObjectAccessorImpl
extends TAbstractAccessor
implements TXMLObjectAccessor

TXMLObjectAccessorImpl is the implementation class for TXMLObjectAccessor.

Version:
$Revision: 1.53 $
Author:
Marcus Schreyer

Field Summary
 
Fields inherited from class com.softwareag.tamino.db.api.accessor.TAbstractAccessor
canBeCancelled, clientRequests, requestCounter, SGUAI
 
Constructor Summary
TXMLObjectAccessorImpl(TStreamAccessor streamAccessor, TResponseBuilder responseBuilder)
          Special Constructor.
 
Method Summary
 void cancelRequests()
          Cancels all requests issued using current accessor.
 TResponse close(TPreparedXQuery pQuery)
          Removes prepared XQuery.
 TResponse delete(TQuery xPath)
          Deletes a set of XML documents implicitly given by the specified xpath query.
 TResponse delete(TXMLObject xmlObject)
          Deletes the XML document represented by the TXMLObject instance within the Tamino database.
 java.lang.String getApplicationName()
          Returns Client Application Name
 boolean getCanBeCancelled()
          Gets whether request can be canBeCanceled.
 long getMaximumRequestDuration()
          Gets the maximum request duration in seconds.
 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 xPath)
          Queries for a specific set of XML documents stored within Tamino.
 TResponse query(TQuery xPath, int quantity)
          Queries for a specific set of XML documents stored within Tamino.
 TXMLObject retrieve(TXMLObject xmlObject)
          Retrieves a single XML document from Tamino in the state as it has been inserted.
 TStreamHeader retrieveHeader(TXMLObject xmlObject)
          Just retrieves the �meta? data of a single document from Tamino.
 void setAccessLocation(TAccessLocation accessLocation)
          Sets the accessor properties.
 void setApplicationName(java.lang.String applicationName)
          Sets Client Applicatin Name.
 void setCanBeCancelled(boolean canBeCancelled)
          Sets whether request can be canBeCanceled.
 void setMaximumRequestDuration(long maximumRequestDuration)
          Sets the maximum request duration in seconds.
 void setScrollType(TScroll type)
          Sets the scroll type.
 TResponse update(TXMLObject xmlObject)
          Updates the XML document represented by the TXMLObject instance within 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 class com.softwareag.tamino.db.api.accessor.TAbstractAccessor
getAccessCollection, getAccessLocation, getDatabaseUri, getInvocation, getLocale, getLockMode, getLockwaitMode, invalidate, invoke, invoke, invoke, setInvocation, setLockMode, setLockwaitMode
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface com.softwareag.tamino.db.api.accessor.TAccessor
getAccessLocation, getLockMode, getLockwaitMode, setLockMode, setLockwaitMode
 
Methods inherited from interface com.softwareag.tamino.db.api.accessor.TInvalidatableAccessor
invalidate
 

Constructor Detail

TXMLObjectAccessorImpl

public TXMLObjectAccessorImpl(TStreamAccessor streamAccessor,
                              TResponseBuilder responseBuilder)
Special Constructor. Initializes the accessor with the given TCommandInvocation, TStreamAccessor and TResponseBuilder.

Parameters:
streamAccessor -
responseBuilder -
Method Detail

insert

public TResponse insert(TXMLObject xmlObject)
                 throws TInsertException
Inserts the XML document represented by the TXMLObject instance into the Tamino database. If the insert succeeds the id, collection and doctype property are set on the TXMLObject instance. An insert can only be assured if no docname property is provided. Please note, that the insert operation might lead for specific settings of the docname property to an update operation on Tamino if such a document is already given. The following characterizes regarding the setting of the docname property which operation takes place on Tamino database:
!xmlObject.hasDocname() Insert.
xmlObject.hasDocname() Insert, if a document with the given ino:docname is not given yet.
xmlObject.hasDocname() Update, if a document with the given ino:docname is already given yet.

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

update

public TResponse update(TXMLObject xmlObject)
                 throws TUpdateException
Updates the XML document represented by the TXMLObject instance within the Tamino database. As a prerequesite the TXMLObject either has to provide an id or docname. The id has a higher priority then the docname which means that if both are given, the id is taken as the update parameter instead of the docname. An update can only be assured when an id is provided. Please note, that the update operation might lead for specific settings of the docname property to an insert operation on Tamino if such a document is not given yet. The following characterizes regarding the setting of the id and docname properties which operation takes place on Tamino database:
xmlObject.hasId() Update.
!xmlObject.hasId() && xmlObject.hasDocname() Update, if the document with the given docname is existant.
!xmlObject.hasId() && xmlObject.hasDocname() Insert, if the document with the given docname is not existant.

Specified by:
update in interface TXMLObjectAccessor
Parameters:
xmlObject - is the representation of the XML document that should be updated within Tamino.
Returns:
TResponse containing the Tamino result information for the update operation.
Throws:
TUpdateException - due to problems when initiating the update request.

delete

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

Specified by:
delete in interface TXMLObjectAccessor
Parameters:
xmlObject - is the representation of the XML document that should be deleted within Tamino.
Returns:
TResponse containing the Tamino result information that is contained within the Tamino response XML document.
Throws:
TDeleteException - due to any problems during the deletion of the given TXMLObject instance.

delete

public TResponse delete(TQuery xPath)
                 throws TDeleteException
Deletes a set of XML documents implicitly given by the specified xpath query.

Specified by:
delete in interface TXMLObjectAccessor
Parameters:
xpath - denotes the XPath expresssion which references a set of XML documents that should be deleted.
Returns:
TResponse containing the Tamino result information that is contained within the Tamino response XML document.
Throws:
TDeleteException - due to any problems during the deletion of the query set specified by the query.

query

public TResponse query(TQuery xPath)
                throws TQueryException
Queries for a specific set of XML documents stored within Tamino. This query will obtain the entire result set of documents at once. The TXMLObjectIterator instance returned within the TResponse instance can be used to navigate over the result set of TXMLObject instances.

Specified by:
query in interface TXMLObjectAccessor
Parameters:
xpath - denotes the XPath expresssion which references a set of XML documents that should be retrieved.
Returns:
TResponse containing the Tamino query content that is contained within the Tamino response XML document. If the query leads to a set of result XML documents handed back by Tamino, the response contains a TXMLObjectIterator instance that can be used to navigate over the result set of TXMLObject instances.
Throws:
TQueryException - due to any problems during the query of the implicitly given query set.

xquery

public 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

Specified by:
xquery in interface TXMLObjectAccessor
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

public 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

Specified by:
xquery in interface TXMLObjectAccessor
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

public 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

Specified by:
xquery in interface TXMLObjectAccessor
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

public TResponse query(TQuery xPath,
                       int quantity)
                throws TQueryException
Queries for a specific set of XML documents stored within Tamino. This query will not obtain the entire result set at once but rather in pieces. The management of those pieces (reloading,..) is done automatically by the TXMLObjectIterator. Please note, this operation can only be used within a local transaction mode. This is due to the fact that it makes use of a Tamino cursor which can only be used within a transactional context. The obtained result set is only available within the local transaction mode. Additionally the iterator will become invalid after commiting or rolling back your transaction.

Specified by:
query in interface TXMLObjectAccessor
Parameters:
xpath - denotes the XPath expresssion which references a set of XML documents that should be retrieved.
quantity - denotes the quantity of documents which will be loaded with a single call from Tamino. However, the iterator returned from the response object hides this.
Returns:
TResponse containing the Tamino result information that is contained within the Tamino response XML document. If the query leads to a set of result XML documents handed back by Tamino, the response also contains a TXMLObjectIterator instance.
Throws:
TQueryException - due to any problems during the query of the implicitly given query set.

xquery

public 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.

This feature requires Tamino 3.1

Specified by:
xquery in interface TXMLObjectAccessor
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

public TXMLObject retrieve(TXMLObject xmlObject)
                    throws TRetrieveException
Retrieves a single XML document from Tamino in the state as it has been inserted. The internal object model given within the TXMLObject instance is updated by the retrieved XML document. Please note that the object is retrieved by either id or the docname property given within the TXMLObject instance. The document is not retrieved by an xpath query but rather by a single document retrieval mechanism. The prerequesite for this is, that the TXMLObject instance needs to provide a doctype and either the id or docname information.

Specified by:
retrieve in interface TXMLObjectAccessor
Parameters:
xmlObject - represents an instance which internal object model shall be updated by a retrieved document that is specified thru the doctype and id or docname information of the xmlObject.
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 - due to any problems during the retrieval of the single document.

retrieveHeader

public 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.

Specified by:
retrieveHeader in interface TXMLObjectAccessor
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)

setAccessLocation

public void setAccessLocation(TAccessLocation accessLocation)
Sets the accessor properties.

Specified by:
setAccessLocation in interface TAccessor
Overrides:
setAccessLocation in class TAbstractAccessor
Parameters:
accessLocation - the TAccessLocation instance to be used by the accessor.

setScrollType

public void setScrollType(TScroll type)
Sets the scroll type.

Specified by:
setScrollType in interface TXMLObjectAccessor
Parameters:
type - - specifies whether cursor is scrollable or not.

getScrollType

public TScroll getScrollType()
Gets the scroll type.

Specified by:
getScrollType in interface TXMLObjectAccessor
Returns:
TScroll - specifies whether cursor is scrollable or not.

setMaximumRequestDuration

public void setMaximumRequestDuration(long maximumRequestDuration)
Sets the maximum request duration in seconds.
Note that for pooled connections obtained frlom a connection pool which configured to pool Tamino physical connections, the invocation of this method has no effect. The default value is set once and for all for all connections in a pool when the pool is created.

Specified by:
setMaximumRequestDuration in interface TAccessor
Overrides:
setMaximumRequestDuration in class TAbstractAccessor
Parameters:
maximumRequestDuration - the maximum request duration in seconds in seconds be set, TConnection.DEFAULT_TIMEOUT for Tamino default.

getMaximumRequestDuration

public long getMaximumRequestDuration()
Gets the maximum request duration in seconds.

Specified by:
getMaximumRequestDuration in interface TAccessor
Overrides:
getMaximumRequestDuration in class TAbstractAccessor
Parameters:
maximumRequestDuration - the maximum request duration in seconds in seconds be set, TConnection.DEFAULT_TIMEOUT for Tamino default.
Returns:
the maximum transaction duration in seconds.

setCanBeCancelled

public void setCanBeCancelled(boolean canBeCancelled)
                       throws TAdminException
Sets whether request can be canBeCanceled.

Specified by:
setCanBeCancelled in interface TAccessor
Overrides:
setCanBeCancelled in class TAbstractAccessor
Throws:
TAdminException

getCanBeCancelled

public boolean getCanBeCancelled()
Gets whether request can be canBeCanceled.

Specified by:
getCanBeCancelled in interface TAccessor
Overrides:
getCanBeCancelled in class TAbstractAccessor
Throws:
TAdminException

cancelRequests

public void cancelRequests()
                    throws TAdminException
Cancels all requests issued using current accessor.

Specified by:
cancelRequests in interface TAccessor
Overrides:
cancelRequests in class TAbstractAccessor
Throws:
TAdminException

close

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

Specified by:
close in interface TXMLObjectAccessor
Parameters:
pQuery - the TPreparedXQuery to be removed.
Returns:
TResponse containing the Tamino result information of the close operation.
Throws:
TXQueryException - due to Prepared XQuery access problems.

setApplicationName

public void setApplicationName(java.lang.String applicationName)
Sets Client Applicatin Name.

Specified by:
setApplicationName in interface TAccessor
Overrides:
setApplicationName in class TAbstractAccessor

getApplicationName

public java.lang.String getApplicationName()
Returns Client Application Name

Specified by:
getApplicationName in interface TAccessor
Overrides:
getApplicationName in class TAbstractAccessor


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