oracle.xml.xquery

Interface OXQCloseable

All Known Subinterfaces:

OXQSequence

All Known Implementing Classes:

OXQEntity

public interface OXQCloseable

Extension methods for closeable objects.

The XQJ user is responsible for explicitly calling close() on streaming resources bound to external variables and on sequences that are returned as a streaming resource. This is inconvenient in a streaming execution pipeline scenario where it may be difficult to keep track of what needs to be closed at each step in the pipeline. For example, suppose we need to bind an instance of XMLStreamReader to an expression, execute this expression and obtain the result sequence, and then return the result sequence as an instance of XMLStreamReader. In order to properly close all resources after we are done processing the output, we have to explicitly invoke close() on the output XMLStreamReader instance, the result sequence, and the input XMLStreamReader instance. If the pipeline is long and the objects are passed around between multiple methods, the user may not have access to all the resources that must be closed at the end of the pipeline. The enlistCloseable methods provide a way to declare that when a resource is closed, one or more other resources should be closed as well. Thus the closing of streaming resources is declaratively specified as they are used, with the user only having to explicitly call close() on the final streaming resource at the end of the pipeline.

The precise semantics are as follows: during this object's close() invocation, close() will be invoked for all closeable objects that were registered using the enlistCloseable() methods in the order they were registered.

Example:

 XQConnection conn = ...;
 XQPreparedExpression xqExpression1 = conn.prepareExpression("(1, 2, 3)");
 XQSequence xqSequence1 = xqExpression1.executeQuery();
 XQPreparedExpression xqExpression2 = conn.prepareExpression("declare variable $x9 as item()* external;
                                      declare variable $x10 as item() external; ($x9, $x10)");
 //Bind XQSequnce
 xqExpression2.bindSequence(new QName("x9"), xqSequence1);

 //Bind an InputStream
 String data = "<num>33</num>";
 InputStream inputStream = new ByteArrayInputStream(data.getBytes());
 xqExpression2.bindDocument(new QName("x10"), inputStream, null, null);

 //Get the result sequence
 XQSequence xqFinalSequence = xqExpression2.executeQuery();

 XMLStreamReader strmReader = xqFinalSequence.getSequenceAsStream();
 
 //Declare that input sequence should be closed when the final sequence is closed
 OXQView.getCloseable(xqFinalSequence).enlistCloseable(xqSequence1);

 //Declare that the input stream should be closed when the final sequence is closed
 OXQView.getCloseable(xqFinalSequence).enlistCloseable(inputStream);

 //Declare that the final sequence should be closed when the stream reader is closed
 OXQView.getCloseable(strmReader).enlistCloseable(xqFinalSequence);
 
 while (strmReader.hasNext()) {
   ...
 }

 //This will close the stream reader and all of the dependent resources, ie
 //the final sequence, the input sequence, and the input stream.
 strmReader.close()
 

If exceptions occur during invocation of close() on any of the closeable objects, a single exception will be thrown by this object's close(). The first of the exceptions thrown by the closeable objects will be the cause of that exception.

Thread-safety semantics of registered resources

The XQuery processor assumes that each registered resource, while not necessarily generally thread-safe, has a thread-safe implementation of the "close" method that can be invoked in parallel with any "read" method, in order to stop reading activity and close gracefully. Many of the JDK implementations of java.io.Closeable satisfy this requirement. The Oracle implementation of XQSequence satisfies this requirement as well, in the case where it, in turn, relies only on resources that are thread-safe with respect to closing. Registration of resources not following this assumption might result in unpredictable behavior in a multi-threaded environment.

Since:

12.1

Method Summary

Modifier and Type	Method and Description
void	enlistCloseable(java.io.Closeable closeable) Declares a closeable object that will be closed when this object is closed.
void	enlistCloseable(javax.xml.stream.XMLStreamReader closeable) Declares an XMLStreamReader object that will be closed when this object is closed.
void	enlistCloseable(XQSequence closeable) Declares an XQSequence object that will be closed when this object is closed.

Method Detail

enlistCloseable

void enlistCloseable(XQSequence closeable)
              throws XQException

Declares an XQSequence object that will be closed when this object is closed.

Parameters:

closeable - object that close() must be invoked on after close() is invoked on this object.

Throws:

XQException - if (1) closeable is null, (2) this object is in a closed state, or (3) provided closeable object is not supported for this main object.

See Also:

Detailed description

enlistCloseable

void enlistCloseable(java.io.Closeable closeable)
              throws XQException

Declares a closeable object that will be closed when this object is closed.

Parameters:

closeable - input streaming object that close() must be invoked on after close() is invoked on this object.

Throws:

XQException - if (1) closeable is null, (2) this object is in a closed state, or (3) provided closeable object is not supported for this main object.

See Also:

Detailed description

enlistCloseable

void enlistCloseable(javax.xml.stream.XMLStreamReader closeable)
              throws XQException

Declares an XMLStreamReader object that will be closed when this object is closed.

Note: XMLStreamReader implementations don't usually conform to the thread-safety semantics defined above, so their use as resources is not recommended in multi-threaded environments.

Parameters:

closeable - object that close() must be invoked on after close() is invoked on this object.

Throws:

XQException - if (1) closeable is null, (2) this object is in a closed state, or (3) provided closeable object is not supported for this main object.

See Also:

Detailed description