com.ibm.wsspi.collective.repository.publisher

Interface RepositoryPublisher



  • public interface RepositoryPublisher
    The RepositoryPublisher service will listen to the ROOT_PUBLISH_TOPIC topic and handle all requests for publishing. If the requests for publishing requires status, a status event will be posted to the ROOT_STATUS_TOPIC topic.

    The RepositoryPublisher will be registered into the OSGi service registry when the RepositoryPublisher is available to receive events. The presence of this service in the SCR can be used to block event publishing until the RepositoryPublisher is ready to process requests. Doing this is optional.

    Terminology

    • Publish Event - a request (in the form of an OSGi Event) from a component to publish data to the repository. A Publish Event is always a write operation, and may either update or delete content within the repository.
    • Status Event - an OSGi Event fired by the RepositoryPublisher to report the requested Publish Event has completed, and to indicate the status of the operation. A Status Event must be requested by the Publish Event.
    It is strongly recommended that events intended for this service are delivered asynchronously using EventAdmin.postEvent(Event) as no guarantees are made with respect to the amount of time it takes to receive and process a Publish Event.

    EventAdmin will ensure that the order of the delivered events will be preserved. For example:

    postEvent(A);
    postEvent(C);
    postEvent(B);

    The events will be delivered to the RepositoryPublisher in the order: A -> C -> B.

    The RepositoryPublisher supports publishing information about MBeans as well as arbitrary data. The topic to which the Publish Event is posted indicates the type of information to be published (either MBean or arbitrary data). Publishing MBean data results in a specific path syntax in the repository while publishing arbitrary data allows for non-MBean information to be published to an arbitrary path relative to the server's path within the repository.

    Publishing Information About MBeans

    MBeans can directly expose their attributes to the collective controller by publishing their information via Publish Events. Doing so will result in the data being stored in the repository in the following format:
    serverNode/sys.mbeans/mbean_object_name/attributes/attribute_name (attribute_value)

    The path within the repository is constructed using the payload of the Publish Event.

    An MBean will be automatically published if the following conditions are met:

    • The MBean exists in the OSGi Service Registry with the "jmx.objectname" property defined.
    • The MBean implements javax.management.NotificationBroadcaster (or javax.management.NotificationEmitter).
    • The MBean indicates it emits AttributeChangeNotifications via NotificationBroadcaster.getNotificationInfo()

    Examples

    Create or update an MBean attribute

    Map<String,Object> eventProps = new HashMap<String,Object>();
    eventProps.put(KEY_OPERATION, OPERATION_UPDATE);
    eventProps.put(MBEAN_OBJECT_NAME, "objectName");
    eventProps.put(MBEAN_ATTRIBUTE_NAME, "attribute");
    eventProps.put(MBEAN_ATTRIBUTE_VALUE, "value");
    eventAdmin.postEvent(new Event(PUBLISH_MBEAN_TOPIC, eventProps));

    Deleting an MBean attribute

    Map<String,String> eventProps = new HashMap<String,String>();
    eventProps.put(KEY_OPERATION, OPERATION_DELETE);
    eventProps.put(MBEAN_OBJECT_NAME, "objectName");
    eventProps.put(MBEAN_ATTRIBUTE_NAME, "attribute");
    eventAdmin.postEvent(new Event(PUBLISH_MBEAN_TOPIC, eventProps));

    Deleting an MBean

    Map<String,String> eventProps = new HashMap<String,String>();
    eventProps.put(KEY_OPERATION, OPERATION_DELETE);
    eventProps.put(MBEAN_OBJECT_NAME, "objectName");
    eventAdmin.postEvent(new Event(PUBLISH_MBEAN_TOPIC, eventProps));

    Publishing Arbitrary Data

    All management capabilities should be exposed via MBeans. However, certain types of information do not fit within the MBean model, such as a server started / stopped state. In such cases, arbitrary (non-MBean) information can be published to the repository. Note: This information will only be available when the server is part of a collective, and has no meaning in a single server environment.

    Examples

    Create or update arbitrary data

    Map<String,Object> eventProps = new HashMap<String,Object>();
    eventProps.put(KEY_OPERATION, OPERATION_UPDATE);
    eventProps.put(DATA_NAME, "myData/data1");
    eventProps.put(DATA_VALUE, "value");
    eventAdmin.postEvent(new Event(PUBLISH_DATA_TOPIC, eventProps));

    Deleting arbitrary data

    Map<String,String> eventProps = new HashMap<String,String>();
    eventProps.put(KEY_OPERATION, OPERATION_DELETE);
    eventProps.put(DATA_NAME, "myData/data1");
    eventAdmin.postEvent(new Event(PUBLISH_DATA_TOPIC, eventProps));

    • Field Detail

      • ROOT_PUBLISH_TOPIC

        static final java.lang.String ROOT_PUBLISH_TOPIC
        The root topic to which the publisher will listen for Publish Events.

        All Publish Events must be sent to one of the publishing topics:

        Events posted to this topic may have one of the following properties:

        See each supported property for more details.
        See Also:
        Constant Field Values
      • KEY_OPERATION

        static final java.lang.String KEY_OPERATION
        Indicates the operation to perform.

        If this property is not specified, OPERATION_UPDATE is assumed.

        See Also:
        Constant Field Values
      • OPERATION_UPDATE

        static final java.lang.String OPERATION_UPDATE
        Indicates the operation to perform is an update.

        If the node does not yet exist, it will be created with the requested value (including all parent nodes).

        See Also:
        Constant Field Values
      • OPERATION_UPDATE_ONLY

        static final java.lang.String OPERATION_UPDATE_ONLY
        Indicates the operation to perform is a simple update.

        If the node does not yet exist, it will not be created.

        See Also:
        Constant Field Values
      • OPERATION_DELETE

        static final java.lang.String OPERATION_DELETE
        Indicates the operation to perform is a deletion.

        The specified node and all of its children will be removed (recursive deletion).

        See Also:
        Constant Field Values
      • KEY_SEND_STATUS_EVENT

        static final java.lang.String KEY_SEND_STATUS_EVENT
        Indicates whether a Status Event should be sent for the Publish Event.

        If this property is not specified, no Status Event will be sent. Note the value of this property is not checked, only whether the property has been set.

        See Also:
        Constant Field Values
      • MBEAN_OBJECT_NAME

        static final java.lang.String MBEAN_OBJECT_NAME
        The MBean's object name.

        This attribute is required for all MBean Publish Events.

        See Also:
        Constant Field Values
      • MBEAN_ATTRIBUTE_NAME

        static final java.lang.String MBEAN_ATTRIBUTE_NAME
        An MBean's attribute name.

        This attribute is required for MBean UPDATE Publish Events. If this attribute is omitted for MBean DELETE Publish Events, all of the information about the MBean will be deleted. If this attribute is specified for MBean DELETE Publish Events, then only the specified attribute will be deleted.

        See Also:
        Constant Field Values
      • MBEAN_ATTRIBUTE_VALUE

        static final java.lang.String MBEAN_ATTRIBUTE_VALUE
        An MBean's attribute value.

        This attribute is required for MBean UPDATE Publish Events. This attribute is ignored for MBean DELETE Publish Events.

        See Also:
        Constant Field Values
      • PUBLISH_DATA_TOPIC

        static final java.lang.String PUBLISH_DATA_TOPIC
        The topic for Arbitrary Data Publish Events.

        Events posted to this topic may have the following properties:

        See each property for details.
        See Also:
        Constant Field Values
      • DATA_NAME

        static final java.lang.String DATA_NAME
        The name of the data to store.

        This attribute is required for all Arbitrary Data Publish Events. The name must take the form of a relative path. If the name begins with a leading slash, then the event will be ignored.

        See Also:
        Constant Field Values
      • DATA_VALUE

        static final java.lang.String DATA_VALUE
        The value to store.

        This attribute is required for Arbitrary Data UPDATE Publish Events. This attribute is ignored for Arbitrary Data DELETE Publish Events.

        See Also:
        Constant Field Values
      • ROOT_STATUS_TOPIC

        static final java.lang.String ROOT_STATUS_TOPIC
        The root topic to which the publisher will post the Status Events.

        If a component wishes to learn of the status of their Publish Event, it must set KEY_SEND_STATUS_EVENT in the Publish Event properties, and establish an EventHandler which will listen on the ROOT_STATUS_TOPIC.

        Events posted to this topic will have all of the properties from the original Publish Event, and may have the following properties:

        If the KEY_STATUS_ERROR_MESSAGE property is not set then the operation completed successfully.
        See Also:
        Constant Field Values
      • STATUS_MBEAN_TOPIC

        static final java.lang.String STATUS_MBEAN_TOPIC
        The topic for MBean Status Events.
        See Also:
        Constant Field Values
      • STATUS_DATA_TOPIC

        static final java.lang.String STATUS_DATA_TOPIC
        The topic for Arbitrary Data Status Events.
        See Also:
        Constant Field Values
      • KEY_STATUS_ERROR_MESSAGE

        static final java.lang.String KEY_STATUS_ERROR_MESSAGE
        Indicates the error message (if any) which was captured while handling the Publish Event.

        If this property is not set, then the Publish Event completed successfully.

        See Also:
        Constant Field Values