DMS and Patch Bay make no assumptions about what kinds of messages flow through the various destinations. However, it is often useful to document what kinds of messages are used in the system, and what data is associated with those messages.

Patch Bay provides a Message Registry, which is a facility that maps message types to the data carried by those message types. The data in the Message Registry can then be accessed at runtime through a set of APIs. Application construction tools, such as the ATG Control Center, make use of this data to present lists of available message types or types of data associated with each message type.

The Message Registry works only for Oracle ATG Web Commerce messages—that is, messages that adhere to the conditions specified in the ATG Message Conventions section of this chapter. The important points are:

The Message Registry maps the JMSType string to the class of bean held by messages of that type. For example, messages with JMSType atg.dcs.Purchase are ObjectMessages containing objects of type atg.dcs.messages.PurchaseMessage.

Because there can be many message types in a large system, the Message Registry allows these message types to be grouped into message families. A message family is simply a group of message types that is given a name. For example, each application probably defines its own message family. A message family can itself contain message families, further subdividing the list of message types used by the application.

All of this is declared in the DMS configuration file:

<dynamo-message-system>
  <patchbay>
    ...
  </patchbay>
  <local-jms>
    ...
  </local-jms>

  <message-registry>

    <message-family>
      <message-family-name>
        Commerce
      </message-family-name>

      <message-type>
        <jms-type>
          atg.dcs.Purchase
        </jms-type>
        <message-class>
          atg.dcs.messages.PurchaseMessage
        </message-class>
      </message-type>

    </message-family>

  </message-registry>
</dynamo-message-system>

This declares a message family named Commerce, which contains a single declared message type. The message is identified by JMSType atg.dcs.Purchase, and contains objects of type atg.dcs.messages.PurchaseMessage. The Commerce family might have subfamilies:

<dynamo-message-system>
  <patchbay>
    ...
  </patchbay>
  <local-jms>
    ...
  </local-jms>

  <message-registry>

    <message-family>
      <message-family-name>
        Commerce
      </message-family-name>

      <message-family>
        <message-family-name>
          Purchasing
        </message-family-name>

        <message-type>
          ...
        </message-type>
        ...
      </message-family>

      <message-family>
        <message-family-name>
          CustomerService
        </message-family-name>

        <message-type>
          ...
        </message-type>
        ...
      </message-family>

      <message-family>
        <message-family-name>
          CatalogManagement
        </message-family-name>

        <message-type>
          ...
        </message-type>
        ...
      </message-family>

    </message-family>

  </message-registry>
</dynamo-message-system>

These declarations and subdivisions have no effect on how these messages are handled by the messaging system. They only affect the way that tools see these lists. Tools access these lists through the interfaces in the atg.dms.registry package: MessageRegistry, MessageFamily, and MessageType. The MessagingManager component implements the MessageRegistry interface, which exposes the list of MessageFamily objects and searches for a MessageType by a particular MessageType name. Each MessageFamily then exposes its name, the list of MessageFamilies that it holds in turn, and the list of MessageTypes it holds.

Dynamic Message Types

One purpose of the Message Registry is to provide metadata about the expected dynamic beans properties of messages, in the form of a DynamicBeanInfo associated with each MessageType. In most cases, the properties of an object message can be determined purely by analyzing its object’s Java class (that is, the class specified by the <message-class> element in the Patch Bay configuration file). The Message Registry does this automatically, by default.

However, in some cases properties might need to be determined dynamically from the application environment. A typical case of this is a message with a property of type atg.repository.RepositoryItem; in advance of actually receiving a message, this item’s subproperties can only be determined by locating the appropriate repository within the application and examining its atg.repository.RepositoryItemDescriptor.

To handle this case, the Message Registry includes a facility for dynamic message typing. The optional <message-typer> element can be included immediately following a <message-class> element. It must specify a Nucleus component by use of a child <nucleus-name> element. The component, in turn, must implement the interface atg.dms.registry.MessageTyper; for each message that references the message typer, the typer’s getBeanInfo() method is called with the message’s name and class to determine that message’s DynamicBeanInfo.

Here is an imaginary example:

<message-type>
  <jms-type>
    myproject.auction.BidMessage
  </jms-type>
  <message-class>
    myproject.jms.auction.BidMessage
  </message-class>
  <message-typer>
    <nucleus-name>
      /myproject/messaging/MessageTyper
    </nucleus-name>
  </message-typer>
  <message-context>
    session
  </message-context>
  <display-name>
    Bid on an item
  </display-name>
  <description>
     Message sent when someone bids on a repository item.
  </description>
</message-type>

The MessageTyper interface includes a single method:

public interface MessageTyper
{
  //-------------------------------------
  /**
   * Returns the DynamicBeanInfo associated with a JMS message type
   * and optional message object class.  If a class is provided, the
   * MessageTyper can expect that it is the class to which an object
   * message of this type will belong, and can introspect it to
   * determine the non-dynamic portion of the message metadata.
   *
   * @param pJMSType the JMS message type, which is required
   * @param pMessageClass an optional class which will be used at
   * runtime for an object message.
   **/
  public DynamicBeanInfo getBeanInfo (String pJMSType, Class pMessageClass);
}

A typical implementation of this interface might analyze the class to determine a basic DynamicBeanInfo by calling DynamicBeans.getBeanInfoFromType(pMessageClass), and then return a DynamicBeanInfo that overlays the class-based metadata with dynamically determined metadata.