Installing Components

Topics: Installing Your Protocol Component Providing Protocol Metadata

Components are packaged into jars. These jars can contain any number of listeners and emitters. An example of a jar with more than one component is the iWay FIX jar which contains two listeners, but no emitter.

Some components provide both listeners and emitters, such as Oracle AQ. Some provide only listeners, such as FIX. Still others provide only emitters, such as Print.

Your components are assumed to be in the appropriate packages. You must also provide a loading registration class, in any package. A manifest entry identifies the loading class.

The manifest contains an iXTEComponent section, used by iWay Service Manager to load the component. It might look like:

Manifest-Version: 1.0
Created-By: Apache Ant 1.5.1
Built-On: EDARDB March 16 2005 1622
Version: 5.5.xxxx
Level: Development
Label: IW55xfoc.0190
Build: 0190
Name: IXTEComponent
Register: com.ibi.example.Register

Naturally, you want to set information fields as appropriate. The component installer looks for the IXTEComponent name section.

The Register attribute identifies the class which is run by the engine during startup to load and prepare the component. Note that the .class extension is not used.

Note: The manifest command on the console can display a manifest.

An ANT script might be used to construct the jar:

<target name="jar" depends="compile" >
   <mkdir dir="${build.dir}/meta-inf"/>
   <tstamp/>
   <manifest file="${build.dir}/meta-inf/Manifest.mf">
      <attribute name="Built-On" value="${env.COMPUTERNAME} ${TODAY} ${TSTAMP}"/>
      <attribute name="Version"  value="${version}"/>
      <attribute name="Level"    value="${level}"/>
      <attribute name="Label"    value="${label}"/>
      <attribute name="Build"    value="${build.num}"/>
      <attribute name="Root"     value="${build.root}"/>
      <section name="IXTEComponent">
          <attribute name="Register" value="com.ibi.edaqm.Register"/>
      </section>
   </manifest>
   <echo message="Building ${engine}.jar"/>
   <jar
      jarfile="${out.dir}/${engine}.jar"
      basedir="${build.dir}"
      manifest="${build.dir}/meta-inf/Manifest.mf"/>
</target>

The Register class must implement com.ibi.common.IComponentRegister. This interface provides two methods: register() and unregister(). The register() method is called when the engine needs to load the component. Unregister() must be implemented, but is reserved for future use.

The register() method is called by the engine before the trace mechanism has been established. It is passed a reference to a class that implements the com.ibi.common.IComponentManager interface.

public interface IComponentRegister
{
    /**
     * Register the listener(s) and emitter(s) with the
     * iWay Service Manager engine.
     * This method may be called by a static initializer so you should program
     * accordingly.
     *
     * @param icomponentmanager
     * The component manager's interface provides methods to interact with the
     * engine to register the components.
     */
    public abstract void register(IComponentManager icomponentmanager);
    public abstract void unregister(IComponentManager icomponentmanager);
}
    /*
     * Unregister reserved for future use.
     */

The component manager is a part of iWay Service Manager that loads and unloads components.

public interface IComponentManager
{
public String getLanguage();
  public int addEmitter(com.ibi.config.MasterInfo mi, String shortName,
             String patternName, char separator);
  public int addListener(com.ibi.config.MasterInfo mi, String shortName,
             String patternName);
  public int addExit(String fullName, String shortName);
  public int  addFunction(String name, String className);
}

The IComponentManager interface offers the methods that the register() method can use to identify listeners and emitters to iWay Service Manager. Once these methods have been called, the component can be used by iWay Service Manager. The component appears in the iWay Service Manager Console, sorted into its lists in alphabetic order appropriate to the language. Such loaded external components are indistinguishable at run time from built-in iWay Service Manager components.

import com.ibi.common.*;
public class Register implements com.ibi.common.IComponentRegister
{
    public Register()
    {
    }
    public void register (com.ibi.common.IComponentManager cm)
    {
       cm.addListener(com.ibi.config.MasterInfoFoobar.INFO,"foobar","Foobar");
       cm.addEmitter(com.ibi.config.MasterInfoFoobar.INFO,"foobar","Foobar",'\0');
       cm.addExit("com.pkg.agents.fooagent","FOOAGENT");
    }
    public void unregister (com.ibi.common.IComponentManager cm)
    {
    }
} 

The register method can also add exits to the configuration, as is seen in the addExit() call in the example. The exit's type is automatically determined and the exit is defined for use under the short name provided in the call.

The methods addListener(), addEmitter(), and addExit() are described in detail in the appropriate java for the server.

package com.ibi.config;
import com.ibi.edaqm.XD;
import java.util.Map;
import java.util.List;
import java.util.Collections;
import java.util.Arrays;
import java.util.TreeMap;
/**
 * The MasterInfoFile class is a concrete MasterInfo implementation.
 * It defines the master of type Line.
 *
 */
public class MasterInfoLine extends MasterInfo
{
  // Create the one and only instance of this object
  public static final MasterInfoLine INFO = new MasterInfoLine("line", "Line",
    "Line Handler");
  /**
   * Constructs a new MasterInfo
   * @param type the type of the master.
   */
  private MasterInfoLine(MasterType type)
  {
    super(type);
  }
  private MasterInfoLine(String innerName, String patternName, String description)
  {
    super(innerName,patternName,description);
  }
  public static final MasterPropertyInfo SUFFIX =
      new MasterPropertyInfo("prefix", "Suffix", "", PropertyType.STRING,
                             MasterPropertyInfo.OPTIONAL,
                             "A suffix to be added to each line", null);

/***********************************************************************/
/* Properties specific for this master                                 */
/***********************************************************************/
  // List of all the master properties
  private static final MasterPropertyInfo[] PRIVATE_VALUES =
   { CommonMasterProps.ACTIVE,   // only support active flag
     SUFFIX
   };
  private static final List VALUES =
      Collections.unmodifiableList(Arrays.asList(PRIVATE_VALUES));
  /**
   * Returns a List of the master's properties.
   * @return a List of the master's properties.
   */
  public List getMasterProperties()
  {
    return VALUES;
  }
  public String getReplyToDesc()
  {
    return "Prefix";
  }
  /**
   * Returns description for the replyto type.
   */
  public String getReplyToDescription()
  {
    return "Emit to the console with System.out";
  }
  // List of the reply-to properties
  private static final MasterPropertyInfo[] PRIVATE_REPLYTO_VALUES = {SUFFIX};
  private static final List REPLYTO_VALUES =
    Collections.unmodifiableList(Arrays.asList(PRIVATE_REPLYTO_VALUES));
  public List getReplytoProperties()
  {
    return REPLYTO_VALUES;
  }
  public boolean hasDestination()
  {
    return false;
  }
}