3 Developing Communication Services

Retrieving Implementation Instances Using InstanceFactory

Services Gatekeeper retrieves instances of a specified interface, class, or abstract class by using InstanceFactory. You retrieve an instance of the Instance Factory using the public static method getInstance. The factory itself has a single method called getImplementation which retrieves a class that implements a given interface or extends a given class.

To use an implementation:

1. Locate the list that maps a given interface, class, or abstract class to the preferred implementation of that functionality. This list is provided in the JAR file's instancemap, a standard java.util.Properties file. Every JAR file can have its own instancemap. See Example 3-1 for an example.

   Note:

   The interface name used in the instancemap file must be unique across all plug-ins for a given service enabler. It is not possible to use the same interface in two instancemap files belonging to two different plug-ins and still map them to two different implementations.

2. If a mapping is provided, instantiate the public constructor or static singleton method in the target class.

3. If there is no explicit mapping, or if there is no public constructor or static singleton method for a mapped class, instantiate an object named according to the following pattern: theClass.getClass().getName() +”Impl” if this exists and has a public constructor or static singleton method.

com.bea.wlcp.wlng.MyInterface=com.bea.wlcp.wlng.MyImplementation
com.bea.wlcp.wlng.MyOtherInterface=com.bea.wlcp.wlng.MyOtherImplementation

Obtaining JNDI Context with ClusterHelper

ClusterHelper is a helper class in the com.bea.wlcp.wlng.api.util.cluster package. It is used to obtain the JNDI Context for the network and access tier.

For details see ClusterHelper in the ”All Classes” section of the Services Gatekeeper Java API Reference.

Broadcasting Events

You can use EventChannel, a utility service interface, to broadcast events by other Services Gatekeeper server instances and register listeners for events originating in other Services Gatekeeper server instances. An event has a name and a value, where the name is an identifier for the event and the value is any object implementing the java.io.Serializable interface.

Retrieve an EventChannel instance using com.bea.wlcp.wlng.api.event_channel.EventChannelFactory. Use the methods of the EventChannel interface to do the following:

• Deactivate all registered listeners (deactivateAllListeners)

• Publish an event to all registered listeners (publishEvent)

• Publish an event to one Services Gatekeeper instance (publishEventToOneNode)

• Register an EventListener (registerEventListener)

• Unregisters an EventListener (unregisterEventListener)

Use the EventChannelListener interface to receive events published using EventChannel. It contains the processEvent(String eventType, Serializable event, String source) method which receives an event.

Generating Statistics with Statistics Service

You can generate standard statistics or exception-related statistics. In addition to this, you can generate custom statistics explicitly. Register the type of statistics by using the addStatisticType operation in the Administration Console. For extensions, the statistics ID should be in the range 1000 to 2250.

About Service Correlation Identifiers

This service correlation ID is a string that is captured in all CDRs and EDRs generated by Services Gatekeeper. It is propagated in the SOAP header sent to and from the application. The CDRs and EDRs use this data to provide special treatment for a given chain of service invocations, such as applying charging to the chain as a whole rather than to the individual invocations.

Services Gatekeeper does not provide the SCID and it does not check whether the SCID is unique. The SCID is stored in the Oracle Label Security (OLS) work context, so that it can be accessed by both the access tier and the network tier.

The Service Correlation class registers itself as a RequestContextListener. The application or by an external mechanism that the communication service provides the SCID in the following way:

• When the chain of services is initiated by an application-initiated request, the application provides and ensures a unique SCID within the chain of service invocations.

  Note:

  If a custom service correlation service supplies the SCID, it is the responsibility of the custom service to ensure the uniqueness of the SCID.

  When the application-initiated request traffic enters the plug-in, the Service Correlation service takes the SCID from the WorkContext interface instance and places it in the RequestContext class object, where it will be available to the EDR service.

• When the chain of services is initiated by a network-triggered request, Services Gatekeeper calls an external interface to get the SCID. This interface must be implemented by an external system. No utility or integration is provided out of the box; this must be a part of a system integration project. It is the responsibility of the external system to provide a unique SCID.

  When the network-initiated request traffic leaves the plug-in, the Service Correlation service takes the SCID from the RequestContext object and places it in the WorkContext object, where it can be retrieved by the SOAP Handler and passed along to the application.

Managing Service Correlation Identifiers

A communication service needs to create a way of storing and retrieving the Service Correlator ID (SCIDs), because a RequestContext object exists only for the lifetime of a single request and SCIDs may need to be stored across several invocations.

To store and retrieve SCIDs, you use the following:

• ExternalInvocation interface

  The ExternalInvocation interface has two methods, one to store the Service Correlation ID and the other to retrieve it. The ExternalInvocation implementation class should have an empty public constructor or a static method that returns itself. The implementor is free to modify the ID once it has been stored, or to use the ExternalInvocation object to create IDs in the first place.

  For an application-initiated request, the Service Correlation service takes the SCID (should there be one) out of the WorkContext of the request, and automatically attempts to store it in an object of this type before putting the SCID in the RequestContext.

  When a network-initiated request is leaving the plug-in, the Service Correlation service verifies the SCID before storing it in the WorkContext. The service automatically attempts to retrieve an SCID from an object of this type using the SCID (should there be one) it finds in the RequestContext object. In this way, if the ExternalInvocation object has modified the SCID in any way, the modified version is put in the WorkContext and sent on to the application.

• ExternalInvocationFactory class

  The ExternalInvocationFactory class is used by the Service Correlation service to locate and instantiate the correct ExternalInvocation object. It does this by using an instancemap entry such as:

  com.bea.wlcp.wlng.api.servicecorrelation.ExternalInvocation=myPackageStructure.myImplClass

  where, myImplClass is the ExternalInvocation implementation.

• ServiceCorrelation package

  This package manages the transport and storage of the Service Correlation ID across multiple service invocations.

Storing Configuration Data with ConfigurationStore

The Services Gatekeeper container exposes a ConfigurationStore Java API that communication services can use to store simple configuration parameters instead of using JDBC and caching algorithms in each module.

All data stored in a ConfigurationStore are stored in a database table and cached in memory.

Below are the characteristics of a ConfigurationStore:

• It is a named store.

• Parameters stored in it must be initialized before they can be used.

• Stores can be either domain wide (shared) or limited to a single Services Gatekeeper server (local). The domain wide store type replicates all data changes to all servers in the cluster, while the local store type keeps a different view of the parameters on different servers and data changes affect only the view for that particular server.

• Parameters stored in a ConfigurationStore are persisted to the database.

• Data in all ConfigurationStores are also cached in memory.

• Only one instance of each named ConfigurationStore is cached in memory per server.

• Updates to a cluster wide named ConfigurationStore is reflected in all cluster nodes.

• The named ConfigurationStore only supports parameters of type Boolean, Integer, Long, String, and Serializable.

public abstract ConfigurationStore getStore(String moduleName, String name, int storeType) throws ConfigurationException;

package com.acompany.plugin.example.netex.management;
import com.bea.wlcp.wlng.api.storage.configuration.*;
/**
 * Class used for handling the configuration store.
 *
 * @author Copyright (c) 2007 by BEA Systems, Inc. All Rights Reserved.
 */
public class ConfigurationStoreHandler {
/**
   * Constants used for the values stored in the store.
   */
  public static final String KEY_NETWORK_HOST = "KEY_NETWORK_HOST";
  public static final String KEY_NETWORK_PORT = "KEY_NETWORK_PORT";
/**
   * Constant to access either the local store. Note that these are
   * just names for the store.
   */
  private static final String LOCAL_STORE = "local";
/**
   * Local configuration store instance.
   */
  private ConfigurationStore localConfigStore;
/**
   * Constructor.
   *
   * @param pluginId The plugin id
   * @throws ConfigurationException An exception thrown if the initialization failed
   */
  public ConfigurationStoreHandler(String pluginId)
    throws ConfigurationException {

    ConfigurationStoreFactory factory = ConfigurationStoreFactory.getInstance();
    localConfigStore = factory.getStore(pluginId, LOCAL_STORE,
            ConfigurationStore.STORE_TYPE_LOCAL);
    // To obtain a shared configuration store, use ConfigurationStore.STORE_TYPE_SHARED

    localConfigStore.initialize(KEY_NETWORK_HOST, "localhost");
    localConfigStore.initialize(KEY_NETWORK_PORT, 5001);
  }

  /**
   * Sets an integer value in the local store.
   *
   * @param key The key associated with the value.
   * @param value The value to store.
   * @throws ConfigurationException An exception thrown if the operation failed
   */
  public void setLocalInteger(String key, Integer value)
    throws ConfigurationException {
    localConfigStore.setInteger(key, value);
  }
/**
   * Gets an integer value from the local store.
   *
   * @param key The key associated with the value.
   * @return The value associated with the key.
   * @throws InvalidTypeException thrown if type is invalid.
   * @throws NotInitializedException thrown if key value has not been
   * initialized.
   */
  public Integer getLocalInteger(String key)
    throws InvalidTypeException, NotInitializedException {
    return localConfigStore.getInteger(key);
  }
/**
   * Sets a string value in the local store.
   *
   * @param key The key associated with the value.
   * @param value The value to store.
   * @throws ConfigurationException An exception thrown if the operation failed
   */
  public void setLocalString(String key, String value)
    throws ConfigurationException {
    localConfigStore.setString(key, value);
  }
/**
   * Gets a string value from the local store.
   *
   * @param key The key associated with the value.
   * @return The value associated with the key.
   * @throws InvalidTypeException thrown if type is invalid.
   * @throws NotInitializedException thrown if key value has not been
   * initialized.
   */
  public String getLocalString(String key)
    throws InvalidTypeException, NotInitializedException {
    return localConfigStore.getString(key);
  }
}

Storing Traffic Data with StorageService

The Storage Service is used for storing data that is not configuration-related, but related to the traffic flow through a communication service, in a cluster-wide store. See ”Managing and Configuring Storage Service” in Services Gatekeeper System Administrator's Guide for an overview.

It provides mechanisms for:

• Store initialization

  A store is created using the StoreFactory singleton class, by specifying either a key/value class pair where the value class should be a class that is unique to the Store (recommended), or a Store name.

• Basic Map usage

  Since the Store interface extends the java.util.Map interface, it can be used as any other Map interface, and it is extended to be a cluster-wide view of the store.

• Named queries

  In addition to the standard java.util.Map interface, Stores have support for a StoreQuery interface. The behaviors of these named queries are configured as part of the Storage Service configuration files. There is an option to define a cache filter and/or SQL query. An index specified for the Store can be used by implementing the IndexFilter interface for the cache filter. The index is automatically used for SQL queries that can make use of these indexes.

• Store listener

  The Store API has support for registering StoreListeners. These listeners get notified if the Storage Service decides to automatically remove Store entries (based on configuration parameters). It is not notified if the extension itself removes entries from the Store.

• Cluster locking

  Cluster-wide locking can be done using the Store interface. If the same entry in a Store may be modified on multiple servers at the same time, use cluster locking to avoid errors from concurrent modification when a transaction commits.

A communication service extension uses the StorageService through an API. The API functionality is implemented by a storage provider.

The storage provider offers a set these store types which are described in ”Understanding the Storage Service” in Services Gatekeeper System Administrator's Guide.

• Cluster store

• Write-behind database store

• Write-through database store

• Refresh-ahead database store

• Database log store

All stores except for the cluster store are backed by a database table that is configured in a store configuration file.

When choosing a store type, take into consideration what kind of data that will be stored, how often it is written and read, and how long the data will stay in the store.

In general, if the lifetime for data is short enough that having the data duplicated in memory on two servers in the cluster, the cluster cache type should provide sufficient persistence. In other cases, a trade-off can be made between the data integrity transaction synchronized write-through operation gives and the performance given by asynchronous write behind. For data that just needs to be added to a database table, and is never read, the database log store is recommended. This store type could be optimized to avoid keeping cache entries in memory that will never be read anyway.

Table 3-2 outlines the recommendations on how to choose a store type.

Extensions can use the com.bea.wlcp.wlng.api.storage.Store interface. This interface extends a java.util.Map interface and adds the following methods:

• addListener: Adds a listener for the store.

• getQuery: Gets a named query.

• lock: Takes a cluster-wide lock.

• release: Releases the current store instance.

• removeListener: Removes a registered listener.

• unlock: Unlocks a previously obtained cluster-wide lock.

The storage service uses configuration files that define the configuration for stores and the relationship between the cluster-wide store and the database table that backs the store. In each configuration file it is possible to define named queries towards the store. There is one configuration file for each plug-in. Each configuration store configuration file together with its XSD and any complex data types should be stored, created, and packaged in a JAR file in the directory domain_Home/config/store_schema, where domain_Home is the home directory of the Services Gatekeeper domain. The configuration file must be named wlng-cachestore-config-extensions.xml and it must be present in the root of the JAR file.

For details about the store configuration file, see the corresponding xsd: com.bea.wlcp.wlng.storage_6.0.0.0.jar/wlng-cachestore-config.xsd in Middleware_home/ocsg/modules where Middleware_home is the home directory of the WebLogic Server domain.

A Store is retrieved from com.bea.wlcp.wlng.api.storage.StoreFactory, either by the name of the store or by the class names of the key/value names. How to retrieve the Store depends on how the store is configured.

The store interface needs to be released when it is no longer needed. The programming model is to retrieve the Store from the StoreFactory when the Store is used, and to release it once it has finished, using try { .. } finally { store.release(); }.

Example 3-4 shows how to retrieve a store identified by key/value classes, operate on it, and release it.

Store<String, NotificationData> store = StoreFactory.getInstance().getStore(String.class, NotificationData.class);
try {
   notificationData = store.put(address.toString(), notificationData);
} finally {
   store.release();
}

Store<Serializable,Serializable> store = StoreFactory.getInstance().getStore("A", this.getClass().getClassLoader());

<store-config>
  <db_table name="example_store_notification">

    <key_column name="address" data_type="VARCHAR(255)"/>
    <!-- bucket_column using default BLOB type -->
    <bucket_column name="notification_data_value"/>

    <value_column name="correlator" data_type="VARCHAR(255)">
      <methods>
        <get_method name="getCorrelator"/>
        <set_method name="setCorrelator"/>
      </methods>
    </value_column>

  </db_table>

  <store type_id="wlng.db.wt.example_store_notification"
         db_table_name="example_store_notification">
    <identifier>
      <classes key-class="java.lang.String"
               value-class="com.acompany.plugin.example.netex.notification.NotificationData"/>
    </identifier>
    <index>
      <get_method name="getCorrelator"/>
    </index>
  </store>

  <query name="com.bea.wlcp.wlng.plugin.example.netex.Query">
    <sql>
      <![CDATA[
    SELECT * FROM example_store_notification WHERE correlator = ?
   ]]>
    </sql>
    <filter-class>com.acompany.plugin.example.netex.store.FilterImpl</filter-class>
  </query>
</store-config>

...
<db_table name="single_key_store">
  <key_column name="sample_key_1" data_type="VARCHAR(30)">
    <methods>
      <get_method name="getSampleKey1"/>
      <set_method name="setSampleKey1"/>
    </methods>
  </key_column>
  <value_column name="sample_value" data_type="VARCHAR(30)">
    <methods>
      <get_method name="getSampleValue"/>
      <set_method name="setSampleValue"/>
    </methods>
  </value_column>
</db_table>

...
<db_table name="combined_key_store">
  <multi_key_column name="sample_key_1" data_type="VARCHAR(30)">
    <methods>
      <get_method name="getSampleKey1"/>
      <set_method name="setSampleKey1"/>
    </methods>
  </multi_key_column>
  <multi_key_column name="sample_key_2" data_type="INT">
    <methods>
      <get_method name="getSampleKey2"/>
      <set_method name="setSampleKey2"/>
    </methods>
  </multi_key_column>
  <value_column name="sample_value" data_type="VARCHAR(30)">
    <methods>
      <get_method name="getSampleValue"/>
      <set_method name="setSampleValue"/>
    </methods>
  </value_column>
</db_table>

<query name="com.bea.wlcp.wlng.plugin.example.netex.Query">
    <sql>
      <![CDATA[
    SELECT * FROM example_store_notification WHERE correlator = ?
   ]]>
    </sql>
    <filter-class>com.acompany.plugin.example.netex.store.FilterImpl</filter-class>
  </query>

StoreQuery<String, NotificationData> storeQuery = store.getQuery("com.bea.wlcp.wlng.plugin.example.netex.Query");
storeQuery.setParameters(correlator);
set = storeQuery.entrySet();

public class FilterImpl implements Filter {

  /**
   * The query parameters.
   */
  private Serializable[] parameters;

  /**
   * Default constructor.
   */
  public FilterImpl() {

  }

  /**
   * Evaluate if a store entry matches the filter.
   *
   * @param value The store entry value to evaluate.
   */
  public boolean matches(Object value) {

     if (parameters == null || value == null || parameters.length == 0) {

       return false;
    }

    if (value instanceof NotificationData) {
      String compareValue = ((NotificationData) value).getCorrelator();

      if (compareValue != null) {
        return compareValue.equals(parameters[0]);
      }
      return compareValue == parameters[0];
    }

    return false;
  }

  /**
   * Set query parameters. The parameters will be ordered as provided to the
   * StoreQuery and it it the responsibility of the implementation to handle
   * them in this order.
   *
   * @param parameters The query parameters to use.
   */
  public void setParameters(Serializable ... parameters)
    throws StorageException {

    this.parameters = parameters;
  }


}