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. 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 from the global cache for the transport you are using. This class contains methods to let you query and 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 on the client CLASSPATH, 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.
2. You can request that schemas be downloaded from the ALDSP server (when using the EJB transport) by using methods on this class.
3. You can request that schemas be loaded from the WSDL (when using the Webservices transport) by using methods on this class.
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 invoking DS operations through a DataAccessService, the mediator will by default ensure that the schemas are loaded from the ALDSP server using method (2) or (3) above, as appropriate. For maximum efficiency, you can override this 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.

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.

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) Assign a ClassLoader to be used when creating HelperContexts for a given dataspace name or WSDL URL via get(String).

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)

Assign a ClassLoader to be used when creating HelperContexts for a given dataspace name or WSDL URL via get(String). If you do not call this, ClassLoader.getSystemClassLoader() will be used. IMPORTANT NOTE: Calling this method will implicitly call flush(String) if the current ClassLoader for the named dataspace/WSDL is not the same as the specified ClassLoader, because it is not possible to change the ClassLoader associated with an already-existing HelperContext. You will need to call get(String) again after changing the ClassLoader to obtain the new HelperContext after calling this method.

Parameters:

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

classloader - The ClassLoader to use when looking up compiled schemas. May be null to reset default behaviour for this name.

Returns:

true if flush(String) was called because the ClassLoader was changed.

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