Create and accessing SDO HelperContext objects

The Service Component Architecture (SCA) implementation complies with Service Data Objects (SDO) 2.1.1 (JSR 235), and provides some implementation-specific extensions. These extensions align with the latest direction of the OASIS SDO 3.0 specification under development. One of the extensions introduces an API for creating and managing HelperContext objects, which are in the SDO class and HelperContextFactory interface.

This topic describes how to create and access SDO HelperContext in non-SCA applications.

In versions of SDO previous to 3.0, including SDO 2.1.1, there is no standard way to create HelperContext objects. SDO helper classes are accessible from the default HelperContext and are typically accessed using their corresponding INSTANCE fields, for example, TypeHelper.INSTANCE. The use of INSTANCE fields is discouraged in SDO 2.1.1, and will likely be deprecated in SDO 3.0. Instead of using INSTANCE fields, code the applications to access helpers using their corresponding accessor method on the HelperContext interface, for example, helperContext.getTypeHelper(). In SDO 2.1.1, the only HelperContext available through standard APIs is the default helper context: HelperProvider.getDefaultContext().

The proposed SDO 3.0 scoping solution, which is available in the product, is more flexible and is described in this topic.

A HelperContext represents a metadata scope in SDO. In SDO 3.0 available in the product, a HelperContext is created using a HelperContextFactory. The HelperContextFactory interface is as follows:

public interface HelperContextFactory {
   /**
  * Create a new HelperContext in this implementation.  Once created the HelperContext
  * can be looked up as follows (Note if the identifier is null or "" it is not registered):
  * SDO.getHelperContext(identifier);
  * @param identifier - A unique identifier that can be used to access the HelperContext.
  * @param properties - Properties  required to initialize the HelperContext.
  * @return a HelperContext object   * @throws IllegalArgumentException If a different HelperContext is already
  * registered with the specified identifier.
  */
  public HelperContext createHelperContext(String identifier, Map<String, Object> properties)
       throws IllegalArgumentException;           /**           * Create a new HelperContext in this implementation.  Once created the HelperContext
    * can be looked up as follows (Note if the identifier is null or "" it is not registered):
    * SDO.getHelperContext(identifier);
    * @param identifier - A unique identifier that can be used to access the HelperContext.
    * @param classLoader - The class loader for the generated static classes (if any).
    * @param properties - Properties  required to initialize the HelperContext.
    * @return a HelperContext object     * @throws IllegalArgumentException If a different HelperContext is already
    * registered with the specified identifier.
    */        public HelperContext createHelperContext(String identifier, ClassLoader classLoader,         Map<String, Object> properties) throws IllegalArgumentException;
} 

There can be more than one HelperContextFactory available in an SDO environment, but one is the default. The default HelperContextFactory is accessible through the interface commonj.sdo.helper.SDO.

1. Use the default factory, create a HelperContext object in the code.

   The following example uses the default factory to create the HelperContext hc:

   HelperContext hc = SDO.getHelperContextFactory().createHelperContext("ScopeManagerTestID", options);

   The identifier string, "ScopeManagerTestID", must be unique within a JVM. If we are not concerned with the actual value, generate a guaranteed unique one using the Java UUID class, for example:

   hc = SDO.getHelperContextFactory().createHelperContext(
       UUID.randomUUID().toString(), options);

2. Access the HelperContext object in the code.

   The SDO run time manages HelperContext objects. Access an existing HelperContext object using the SDO.getHelperContext(identifier) method:

   hc = SDO.getHelperContext("ScopeManagerTestID");

   The identifier of a HelperContext can be accessed using the getIdentifier() method:

   String id = hc.getIdentifier();

Results

A HelperContext object is defined and accessible.

What to do next

Use SDO in an SCA application. When SDO is used in an SCA application, the SCA run time typically creates the HelperContext objects and identifiers. Refer to topics on using SDO 2.1.1 in SCA applications.

Because the SCA run time manages the HelperContext objects and identifiers when using SDO in SCA applications, the method used to create and access SDO HelperContext in SCA applications is different than that used in non-SCA applications. An SCA application can access SDO HelperContext using a DefaultHelperContext annotation; for example:

import com.ibm.websphere.soa.sca.sdo.DefaultHelperContext;
 @DefaultHelperContext
public HelperContext defaultHelperContext;

Related concepts

Service Data Objects version 2.1.1

Data access with Service DataObjects, API versions 1.0 and 2.01

Related tasks

Specify bindings in an SCA environment

Related information:

JSR 235: Service Data Objects

OASIS Service Data Objects (SDO) TC