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

Field Summary

static int	EXTRA_DATA_SERVICE_AUDIT Constant for getExtraData() requesting the DataServiceAudit for the execution be returned.
static int	EXTRA_QUERY_PLAN Constant for getExtraData() requesting the Query Plan be returned (as a String containing XML).
static int	EXTRA_STRUCTURAL_TYPE Constant for getExtraData() requesting the structural type of the result be returned.
static int	EXTRA_TOPLEVEL_TYPE Constant for getExtraData() requesting the result top-level return type be returned (as a String containing XML).

Method Summary

void	dispose() Call when you do not intend to request any more results from this DASResult.
java.lang.Object	getExtraData(int datatype) Obtain extra "out of band" data from the 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 disposed (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.
<C> DASResult<E>	setGenericClass(java.lang.Class<C> generic_class) Specify a default component class for the array returned from getItems().

Field Detail

EXTRA_QUERY_PLAN

static final int EXTRA_QUERY_PLAN

Constant for getExtraData() requesting the Query Plan be returned (as a String containing XML). Will only be available if the RequestConfig feature RETURN_QUERY_PLAN was enabled.

See Also:

Constant Field Values

Exclude:

EXTRA_TOPLEVEL_TYPE

static final int EXTRA_TOPLEVEL_TYPE

Constant for getExtraData() requesting the result top-level return type be returned (as a String containing XML). Will only be available if the RequestConfig feature RETURN_TOPLEVEL_TYPE was enabled

See Also:

Constant Field Values

Exclude:

EXTRA_STRUCTURAL_TYPE

static final int EXTRA_STRUCTURAL_TYPE

Constant for getExtraData() requesting the structural type of the result be returned. Will only be available if the RequestConfig feature RETURN_STRUCTURAL_TYPE was enabled

See Also:

Constant Field Values

Exclude:

EXTRA_DATA_SERVICE_AUDIT

static final int EXTRA_DATA_SERVICE_AUDIT

Constant for getExtraData() requesting the DataServiceAudit for the execution be returned. Will only be available if the RequestConfig feature RETURN_DATA_SERVICE_AUDIT was enabled. Note that this is provided for completeness; generally clients should obtain the DataServiceAudit from the RequestConfig rather than DASResult, and DASResult implementations are not required to honor this flag.

See Also:

Constant Field Values

Exclude:

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

setGenericClass

<C> DASResult<E> setGenericClass(java.lang.Class<C> generic_class)

Specify a default component class for the array returned from getItems().

Exclude:

Only for static mediator.

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 disposed (see dispose()). If it has not yet been disposed, it may still be holding open resources on the server. Note that being disposed 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.

getExtraData

java.lang.Object getExtraData(int datatype)
                              throws DASException

Obtain extra "out of band" data from the DASResult. Generally, this method will return null unless specific features were requested via RequestConfig when the data service operation was invoked. It is required to call this method before calling dispose().

Parameters:

datatype - One of the DASResult.EXTRA_* constants.

Returns:

Object The type of this Object will be defined by the particular EXTRA_* constant.

Throws:

DASException - if there is some problem obtaining the data. Note that implementations should NOT throw an exception if the requested datatype is not known to them, but should just return null; this provides for seamless additions of more types later.

Exclude: