com.bea.dsp.das
Class HelperContextCache

java.lang.Object
  com.bea.dsp.das.HelperContextCache

public final class HelperContextCache
extends java.lang.Object

ALDSP maintains a global cache of SDO HelperContexts. (See footnote below about how this may not be truly "global" in all cases.) This cache is keyed by a String "name", which is one of two things:

• When using the mediator APIs over the EJB-based transport (the default), the key is the name of your dataspace project; that is, the name passed to DataAccessServiceFactory.newDataAccessService(Context, String, String) or DataAccessServiceFactory.prepareExpression(Context, String, String).
• When using the mediator APIs over the Webservices-based transport, the key is the URL of the WSDL; that is, the URL passed to DataAccessServiceFactory.newDataAccessService(Context, String).

If you need to use a HelperContext, for instance to create new DataObjects, it is very important that you use the correct HelperContext. Generally it is best and easiest to obtain this HelperContext from the DataAccessService or PreparedExpression instance itself by calling DataAccessService.getHelperContext(). or PreparedExpression.getHelperContext(). However, if you need to perform some actions with the HelperContext prior to creating any DataAccessService/PreparedExpression instances, you may inquire the HelperContext from this class. This class also contains methods to let you manipulate this cache.

One of the most important things contained in an SDO HelperContext is the XSDHelper, which contains all XML schemas known to the HelperContext. When the mediator APIs construct DataObjects, these DataObjects will be untyped unless the XSDHelper knows the schema for the data returned from the ALDSP server. In general, untyped DataObjects perform more slowly; they also will not behave correctly when enabled for change-logging (see SDOUtil.enableChanges(commonj.sdo.DataObject)), and so cannot be passed to update procedure on the ALDSP server.

Therefore, it is important to ensure that the schemas are loaded whenever possible. There are several ways to accomplish this:

1. If the static mediator jar is available to the current Thread's context ClassLoader, then all schemas known to the dataspace project or WSDL (depending on which the static mediator jar was generated for) will be known to the HelperContext. This means that static DataObject types from jars on the system classpath for stand-alone applications, or jars on the WEB-INF classpath for web applications, will be automatically available, even when using the dynamic mediator API.
2. You can request that schemas be downloaded from the ALDSP server (when using the EJB transport) by using methods on this class. This is also done by default when instantiating a DataAccessService instance using the EJB transport.
3. You can request that schemas be loaded from the WSDL (when using the Webservices transport) by using methods on this class. This is also done by default when instantiating a DataAccessService instance using the WS transport.
4. You can obtain the appropriate HelperContext using methods on this class and load the schemas into the XSDHelper yourself, using the various XSDHelper.define() methods. This is the only way to load schemas which are not available on the ALDSP server, for example if you have a custom schema for the return value from an ad-hoc query.

For invoking DS operations through a DataAccessService (that is, using the dynamic mediator API), the mediator will by default ensure that the schemas are loaded from the ALDSP server using method (2) or (3) above, as appropriate. For the static mediator API, the schemas are not downloaded from the ALDSP server as they are automatically available inside the same jar as the static mediator classes.

When using the dynamic mediator API, if you wish you can override the default automatic download behaviour using DataAccessServiceFactory.newDataAccessService(Context, String, String, boolean) (for the EJB transport) or DataAccessServiceFactory.newDataAccessService(Context, String, boolean) (for the WS transport), and manage the HelperContext yourself using the methods on this class. This is perhaps useful if the dataspace has a large number of schemas and you wish to download only a subset.

However, for ad-hoc queries (see PreparedExpression), the mediator cannot know which schemas are necessary, nor is it always the case that the appropriate schemas for DataObjects returned from ad-hoc queries exist on the ALDSP server. Therefore it is up to the user to ensure that the schemas are loaded into the HelperContext prior to executing any ad-hoc queries. You may use any of methods (1) - (4) to accomplish this, depending on your query and where the schemas are located.

Footnote: For internal reasons, the "global" cache represented by this class is not necessarily truly global, although this likely will affect only a very small number of customers. In an application where multiple threads exist with different context ClassLoaders, such as a web application, the cache will be different for each context ClassLoader. The most important result of this is that schemas manually loaded in one thread (using methods 2, 3, or 4 above) will not be known on other threads. To ensure consistent behavior, such applications should arrange to have the schema-loading code executed in each thread.

If you are not using multiple threads with different context ClassLoaders, or you are using DSP's default behaviors for loading schemas, this should not affect you.

Footnote 2: The cache is not infinitely persistent. If no mediator client code is holding a reference to a particular HelperContext, it may fall out of the cache with the next garbage collection in the JVM. If this happens, a subsequent call to get(String) will return a new HelperContext. If the previous HelperContext for a given name was modified (say by manually loading schemas into it), this information will be lost. This is to prevent the cache from consuming an ever-increasing amount of memory. To prevent this from occurring, client code should keep a reference to the HelperContext returned from get(String).

Constructor Summary

HelperContextCache()

Method Summary

static boolean	flush(java.lang.String name) Flush the SDO HelperContext associated with a particular dataspace or WSDL URL.
static commonj.sdo.helper.HelperContext	get(java.lang.String name) Obtain the SDO HelperContext associated with a particular dataspace or WSDL URL.
static boolean	loadSchemasForDataspace(javax.naming.Context context, java.lang.String dataspace, java.lang.String dsname) Populates the HelperContext for a given dataspace name with schemas by downloading them from the ALDSP server.
static boolean	loadSchemasForWsdl(java.lang.String wsdl_url) Populates the HelperContext for a given WSDL URL with all schemas from the WSDL.
static boolean	setClassLoader(java.lang.String name, java.lang.ClassLoader classloader) Deprecated. - use thread context classloader

Methods inherited from class java.lang.Object

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

Constructor Detail

HelperContextCache

public HelperContextCache()

Method Detail

get

public static commonj.sdo.helper.HelperContext get(java.lang.String name)

Obtain the SDO HelperContext associated with a particular dataspace or WSDL URL. Clients must use this HelperContext to obtain XMLHelpers, etc., as only this HelperContext will have the appropriate schemas loaded (potentially downloaded from the DSP server).

Parameters:

name - Either a dataspace name, or a WSDL URL.

Returns:

the HelperContext. If 'name' was not previously known, a new HelperContext will be returned that only contains any types known from the classpath.

flush

public static boolean flush(java.lang.String name)

Flush the SDO HelperContext associated with a particular dataspace or WSDL URL. Client may call this when they know that the status of the dataspace schemas has changed on the DSP server, for instance, and wish to cause the mediator to re-load the schemas in future. Note: As SDO HelperContext are strictly additive, any HelperContexts previously returned from get(String) must be discarded by the client. It is the client's responsibility to manage obtaining a correct HelperContext at any point in time.

Parameters:

name - Either a dataspace name, or a WSDL URL.

Returns:

true if the name was previously known (and has now been flushed), or false if the name was not previously known.

setClassLoader

public static boolean setClassLoader(java.lang.String name,
                                     java.lang.ClassLoader classloader)

Deprecated. - use thread context classloader

loadSchemasForDataspace

public static boolean loadSchemasForDataspace(javax.naming.Context context,
                                              java.lang.String dataspace,
                                              java.lang.String dsname)
                                       throws DASException

Populates the HelperContext for a given dataspace name with schemas by downloading them from the ALDSP server.

This method will attempt not to repeat downloads; if it is called twice with the same arguments without an intervening call to flush(String), the second invocation will return with no effect. In particular, passing a null dsname a second time for a particular dataspace will never result in any schemas being downloaded, even if new schemas have been added to the dataspace in the meantime.

Parameters:

context - Context to use when connecting to ALDSP server (same as that passed to DataAccessServiceFactory.newDataAccessService(Context, String, String)).

dataspace - the dataspace name.

dsname - the data service name (an "ld:" URI). All schemas describing XML types referred to by any input parameter or return type of any operations on the named data service will be downloaded. If the data service name is null, schemas will be downloaded for ALL data services in the dataspace. Warning - This could be a large number of schemas and hence be quite slow!

Returns:

true if schemas were in fact loaded; false if no action was taken because the schemas for this dataspace/dsname were already loaded.

Throws:

DASException

loadSchemasForWsdl

public static boolean loadSchemasForWsdl(java.lang.String wsdl_url)
                                  throws DASException

Populates the HelperContext for a given WSDL URL with all schemas from the WSDL. If this method has been previously called for this WSDL (and flush(String) has not been called in the meantime), this method will return with no effect.

Parameters:

wsdl_url - URL of the WSDL.

Returns:

true if schemas were in fact loaded; false if no action was taken because this WSDL was already known.

Throws:

DASException