com.bea.dsp.das
Interface DASResult<E>

public interface DASResult<E>

DASResult represents the result of invoking a data service operation or an ad-hoc query on a data service. It is an iterator, allowing forward-only access to each item in the result in turn. (The definition of "item" is consistent with the definition in the XQuery Data Model specification.)

Method Summary

void	dispose() Call when you do not intend to request any more results from this DASResult.
E[]	getItems() Returns all items represented by this result.
<C> C[]	getItems(java.lang.Class<C> component) Returns all items represented by this result.
boolean	hasNext() Returns true if there are any remaining items in this result.
boolean	isDisposed() Inquire whether this DASResult has been dispose()d (see dispose()).
E	next() Returns the next item in the result.
java.lang.String	nextAsString() Returns the next item in the result as a simple String.

Method Detail

hasNext

boolean hasNext()
                throws DASException

Returns true if there are any remaining items in this result.

Throws:

DASException - if there is an unexpected problem determining if there are more items.

next

E next()
       throws DASException

Returns the next item in the result. This will either be a DataObject if the item is complex, or a simple type (such as Integer or Float) if the item is simple. The mapping of simple types to Java conforms to the SDO specification.

Throws:

DASException - if there is a problem retrieving the next item.

java.lang.IllegalStateException - if getItems() has previously been called on this DASResult.

nextAsString

java.lang.String nextAsString()
                              throws DASException

Returns the next item in the result as a simple String. If the next item is an XML element, it will be serialized to XML. If the next item is a schema simple value, it will be serialized to text according to the rules of XML Schema.

Throws:

DASException - if there is a problem retrieving the next item.

java.lang.IllegalStateException - if getItems() has previously been called on this DASResult.

getItems

E[] getItems()
             throws DASException

Returns all items represented by this result. Note that you must call this method without having previously called next(); next() and getItems() cannot be mixed.

After this method is called, the DASResult will be dispose()d automatically.

Note that the component type of the returned array will be the same as the generic type E - that is, Object if this DASResult was obtained from a dynamic DataAccessService or PreparedExpression, or the specified type if the DASResult was obtained from a static DataAccessService subclass. If you wish to control the component type of the array more directly - for instance, if you know that all returned Objects will be DataObjects and you'd like to cast the return value to DataObject[] - use getItems(Class).

Throws:

DASException - if there is a problem retrieving the results.

java.lang.IllegalStateException - if next() has previously been called on this DASResult.

getItems

<C> C[] getItems(java.lang.Class<C> component)
             throws DASException

Returns all items represented by this result. Note that you must call this method without having previously called next(); next() and getItems() cannot be mixed.

After this method is called, the DASResult will be dispose()d automatically.

Parameters:

component - The class to use as the component type of the returned array. Must not be null. Must represent a legitimate superclass of all objects that will be returned.

Throws:

DASException - if there is a problem retrieving the results.

java.lang.IllegalStateException - if next() has previously been called on this DASResult.

java.lang.ArrayStoreException - if component represents a class which is not a superclass of all elements of the array.

dispose

void dispose()
             throws DASException

Call when you do not intend to request any more results from this DASResult. This allows the client to free up any server resources it may be holding open. Note that it is not an error to call this method if the DASResult is already disposed (see isDisposed()); this method will silently return in that case.

Throws:

DASException - if there are unexpected problems in attempting to free up server resources.

isDisposed

boolean isDisposed()

Inquire whether this DASResult has been dispose()d (see dispose()). If it has not yet been disposed, it may still be holding open resources on the server. Note that being dispose()d does NOT necessarily mean that no more results can be returned from next(); in particular, a DASResult obtained when the RequestConfig option RequestConfig.FETCH_ALL_IMMEDIATELY is specified will be disposed before it is returned to the client.