com.bea.dsp
Class RequestConfig

java.lang.Object
  com.bea.dsp.RequestConfig

public final class RequestConfig
extends java.lang.Object

A collection of attributes which control how a Data Service method is to be invoked. RequestConfig also serves as a channel for returning "out-of-band" information, such as server audit reports, to the client.

Feature flags are attributes that are simply either enabled or disabled. By default, all features are disabled. You enable them with enableFeature(String), and disable them with disableFeature(java.lang.String).

String attributes are assigned values with setStringAttribute(String,String). All default to null.

String array attributes are assigned values with setStringArrayAttribute(String,String[]). All default to null.

Integer attributes are assigned values with setIntegerAttribute(String,int). All default to 0.

The set of valid attributes are represented by public String constants on this class.

Enumerated attributes are specified with setEnumAttribute(Enum). Unlike the rest, there is no String name for the attribute; the enum class itself is used to identify the attribute, and the particular instance of the class is the value.

Nested Class Summary

static class

RequestConfig.ReadTransactionMode Enumerated attribute indicating how the DSP server should handle transactions when executing read-only function or ad-hoc query.

Field Summary

static java.lang.String	BLOCK_SIZE Integer attribute specifying the network block size the server should use when streaming results to the client.
static java.lang.String	COMPILE_ONLY Feature flag requesting query processor only compile the query, not execute it.
static java.lang.String	DO_NOT_CACHE_QUERY_PLAN Feature flag requesting the DSP server not to cache compiled execution plan.
static java.lang.String	FETCH_ALL_IMMEDIATELY Feature flag indicating that the client should immediately retrieve all available results from the server, rather than demand-loading them as the user iterates through the results.
static java.lang.String	GET_CURRENT_DATA Feature flag requesting that previously cached results should be ignored, new data computed and cached entries used in the current operation refreshed.
static java.lang.String	OUTPUT_FILENAME Deprecated. This feature has been removed from ALDSP 3.0 due to security concerns. Specifying this flag will have no effect.
static java.lang.String	REFRESH_CACHE_EARLY Integer attribute requesting that a cached data record must be valid for at least the specified number of seconds.
static java.lang.String	RETURN_AUDIT_PROPERTIES String array attribute which allows you to list the audit properties which should be collected during this function/query execution.
static java.lang.String	RETURN_DATA_SERVICE_AUDIT Feature flag requesting DSP server return all returnable audit properties collected during query execution.
static java.lang.String	TIMEOUT Integer attribute specifying maximum time the query engine should allow for this request to complete (in milliseconds).

Constructor Summary

RequestConfig()

Method Summary

RequestConfig	assignFilter(FilterXQuery filter) Sets a filtering condition to be applied to the results of data service function execution.
void	disableFeature(java.lang.String featureName) Disable a specified feature flag for this query execution.
RequestConfig	enableFeature(java.lang.String featureName) Enable a specified feature flag for this query execution.
boolean	featureEnabled(java.lang.String featureName) Inquire whether a particular feature is enabled or not for this query execution.
<E extends java.lang.Enum<E>> E	getEnumAttribute(java.lang.Class<E> attr) Return the current value of an enumerated attribute.
FilterXQuery	getFilter() Retrieve a previously-assigned FilterXQuery for further manipulation.
int	getIntegerAttribute(java.lang.String attributeName) Return the current value of an integer attribute.
java.lang.String[]	getStringArrayAttribute(java.lang.String attributeName) Return the current value of a String array attribute.
java.lang.String	getStringAttribute(java.lang.String attributeName) Return the current value of a String attribute.
DataServiceAudit	retrieveDataServiceAudit() Retrieve the collected audit materials from query execution.
<E extends java.lang.Enum<E>> RequestConfig	setEnumAttribute(java.lang.Enum<E> value) Assign an enumerated attribute.
static <E extends java.lang.Enum<E>> java.lang.Enum<E>	setEnumAttribute(java.lang.Enum<E> value, com.bea.ld.QueryAttributes attributes) Assign an enumerated attribute.
void	setFilter(FilterXQuery filter) Sets a filtering condition to be applied to the results of data service function execution.
RequestConfig	setIntegerAttribute(java.lang.String attributeName, int value) Assign an integer value to an integer attribute.
RequestConfig	setStringArrayAttribute(java.lang.String attributeName, java.lang.String[] value) Assign a String[] value to a String array attribute.
RequestConfig	setStringAttribute(java.lang.String attributeName, java.lang.String value) Assign a String value to a String attribute.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

COMPILE_ONLY

public static final java.lang.String COMPILE_ONLY

Feature flag requesting query processor only compile the query, not execute it. Note: If this flag is specified, the method this RequestConfig object is passed to (eg., DataAccessService.invoke(String, Object[], RequestConfig)) will return an empty DASResult.

See Also:

Constant Field Values

DO_NOT_CACHE_QUERY_PLAN

public static final java.lang.String DO_NOT_CACHE_QUERY_PLAN

Feature flag requesting the DSP server not to cache compiled execution plan.

See Also:

Constant Field Values

RETURN_DATA_SERVICE_AUDIT

public static final java.lang.String RETURN_DATA_SERVICE_AUDIT

Feature flag requesting DSP server return all returnable audit properties collected during query execution. If this flag is enabled, or when specific audit properties had been requested using RETURN_AUDIT_PROPERTIES, the DataServiceAudit containing the collected audit materials will be available via retrieveDataServiceAudit() after operation execution.

See Also:

Constant Field Values

RETURN_AUDIT_PROPERTIES

public static final java.lang.String RETURN_AUDIT_PROPERTIES

String array attribute which allows you to list the audit properties which should be collected during this function/query execution.

See Also:

Constant Field Values

GET_CURRENT_DATA

public static final java.lang.String GET_CURRENT_DATA

Feature flag requesting that previously cached results should be ignored, new data computed and cached entries used in the current operation refreshed.

See Also:

Constant Field Values

REFRESH_CACHE_EARLY

public static final java.lang.String REFRESH_CACHE_EARLY

Integer attribute requesting that a cached data record must be valid for at least the specified number of seconds. This effectively shortens TTL specified for that chached value.

See Also:

Constant Field Values

OUTPUT_FILENAME

public static final java.lang.String OUTPUT_FILENAME

Deprecated. This feature has been removed from ALDSP 3.0 due to security concerns. Specifying this flag will have no effect.

See Also:

Constant Field Values

TIMEOUT

public static final java.lang.String TIMEOUT

Integer attribute specifying maximum time the query engine should allow for this request to complete (in milliseconds). After this time has elapsed, the query will be terminated, much as it can be via the DSP administration console's Monitoring tab.

Note: If the request is participating in an EJB transaction, then the EJB's transaction timeout (trans-timeout-seconds in the deployment descriptor) may override this timeout if the EJB's timeout is smaller.

See Also:

Constant Field Values

FETCH_ALL_IMMEDIATELY

public static final java.lang.String FETCH_ALL_IMMEDIATELY

Feature flag indicating that the client should immediately retrieve all available results from the server, rather than demand-loading them as the user iterates through the results. Note that this only makes sense when using the DSP 3.0-style DataAccessService APIs which return DASResult. Note also that the DASResult returned when this flag is specified will be dispose()d from the start.

Specifying this flag may slightly improve network performance. On the down side, it will cause the mediator to load all results into client memory at once. It may also require the ALDSP server to hold all results in memory at once, rather than streaming through them. Thus, this flag should be used with caution, and only in circumstances where it is assured that the entire result set can be comfortably held in memory on both client and server.

See Also:

Constant Field Values

BLOCK_SIZE

public static final java.lang.String BLOCK_SIZE

Integer attribute specifying the network block size the server should use when streaming results to the client. Note that this will be unused if FETCH_ALL_IMMEDIATELY is enabled, and is also unused when using the webservices mediator transport. Note also that the maximum allowable block size is 8 megabytes (8388608 bytes) due to WLS message-size default limits, and also to prevent unusually large values from consuming excessive memory on the server or client.

See Also:

Constant Field Values

Constructor Detail

RequestConfig

public RequestConfig()

Method Detail

enableFeature

public RequestConfig enableFeature(java.lang.String featureName)

Enable a specified feature flag for this query execution.

Returns:

this RequestConfig (for chained calls).

disableFeature

public void disableFeature(java.lang.String featureName)

Disable a specified feature flag for this query execution. (All features are disabled by default until enabled by calling enableFeature().)

featureEnabled

public boolean featureEnabled(java.lang.String featureName)

Inquire whether a particular feature is enabled or not for this query execution.

Returns:

this RequestConfig (for chained calls).

setStringAttribute

public RequestConfig setStringAttribute(java.lang.String attributeName,
                                        java.lang.String value)

Assign a String value to a String attribute.

getStringAttribute

public java.lang.String getStringAttribute(java.lang.String attributeName)

Return the current value of a String attribute.

setStringArrayAttribute

public RequestConfig setStringArrayAttribute(java.lang.String attributeName,
                                             java.lang.String[] value)

Assign a String[] value to a String array attribute.

getStringArrayAttribute

public java.lang.String[] getStringArrayAttribute(java.lang.String attributeName)

Return the current value of a String array attribute.

setIntegerAttribute

public RequestConfig setIntegerAttribute(java.lang.String attributeName,
                                         int value)

Assign an integer value to an integer attribute.

getIntegerAttribute

public int getIntegerAttribute(java.lang.String attributeName)

Return the current value of an integer attribute.

setEnumAttribute

public <E extends java.lang.Enum<E>> RequestConfig setEnumAttribute(java.lang.Enum<E> value)

Assign an enumerated attribute. The enum instance passed in represents both the particular attribute to set and the value to set it to. For example:

   RequestConfig config = new RequestConfig();
   config.setEnumAttribute(RequestConfig.ReadTransactionMode.SUPPORTS);
 

would set the ReadTransactionMode attribute to "SUPPORTS".

getEnumAttribute

public <E extends java.lang.Enum<E>> E getEnumAttribute(java.lang.Class<E> attr)

Return the current value of an enumerated attribute. Pass in the class of the attribute, and this will return the current instance that is active. For example:

   if(config.getEnumAttribute(RequestConfig.ReadTransactionMode.class)
      == RequestConfig.ReadTransactionMode.SUPPORTS) {
     ..
   }
 

setEnumAttribute

public static <E extends java.lang.Enum<E>> java.lang.Enum<E> setEnumAttribute(java.lang.Enum<E> value,
                                                                               com.bea.ld.QueryAttributes attributes)

Assign an enumerated attribute. The enum instance passed in represents both the particular attribute to set and the value to set it to. For example:

   RequestConfig config = new RequestConfig();
   config.setEnumAttribute(RequestConfig.ReadTransactionMode.SUPPORTS);
 

would set the ReadTransactionMode attribute to "SUPPORTS".

setFilter

public void setFilter(FilterXQuery filter)

Sets a filtering condition to be applied to the results of data service function execution. Filters will be applied to any of the objects in the hierarchy of the field path, e.g., either to CUSTOMER or ORDER if the field is CUSTOMER/ORDER/TOTAL_ORDER_AMOUNT.

Parameters:

filter - The FilterXQuery

assignFilter

public RequestConfig assignFilter(FilterXQuery filter)

Sets a filtering condition to be applied to the results of data service function execution. Filters will be applied to any of the objects in the hierarchy of the field path, e.g., either to CUSTOMER or ORDER if the field is CUSTOMER/ORDER/TOTAL_ORDER_AMOUNT.

Note: This function is identical to setFilter(FilterXQuery) except that it returns the RequestConfig object. This is useful for chaining RequestConfig calls, such as:

  RequestConfig rc = new RequestConfig().assignFilter(filt).enableFeature(...);
 

The version named setFilter must return void so that it may serve as a Javabean getter method.

Parameters:

filter - The FilterXQuery

Returns:

this RequestConfig (for chained calls).

getFilter

public FilterXQuery getFilter()

Retrieve a previously-assigned FilterXQuery for further manipulation.

retrieveDataServiceAudit

public DataServiceAudit retrieveDataServiceAudit()

Retrieve the collected audit materials from query execution. It only makes sense to call this method *after* this RequestConfig object has been passed to a client invoke method and that method has returned. When using the DSP 3.0 mediator APIs (in the com.bea.dsp.das package), it is necessary to call dispose() on the DASResult to signal that the client is done processing the results prior to calling this method.

This will return null unless the feature flag RETURN_DATA_SERVICE_AUDIT was enabled or a set of audit properties was specified for the attribute RETURN_AUDIT_PROPERTIES.

This field will be populated in all cases possible, including most cases where the invocation throws an exception.

Note: This method is not called getDataServiceAudit() to prevent being treated as a Javabean getter method.