com.h3c.dist.bus

## Interface Bus

-     public interface Bus

  `Bus` provides a publish-subscribe service where multiple applications register for receiving messages of different types that they are interested. To operate on a `Bus`, an application must get a handle to the `Bus` using `BusFactory.getBus(Class)`. Application can then subscribe for the message types it is interested in receiving notifications on the bus using `registerListener(Set, BusListener)`

  Application can push a message to the `post(BusMessage)`. Applications receives messages posted from then on, onto the `Bus` via the registered `BusListener.processBusMsg(BusMessage)` for all message types it has registered. When any application pushes a message,all subscribers to that message type (including the application that pushed the message, if it has subscribed) will be notified.

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `ackMessage(long msgId, BusListener listener)` Acknowledge for message received.
    `boolean` | `changeMessageOwner(BusMessage msg, BusListener listener)` Take ownership of an existing `BusMessage`.
    `void` | `delete(long msgId)` Delete a Bus message.
    `List<BusMessage>` | `getMessages(Set<Integer> msgTypes)` Get the list of messages of the specified types that are currently posted on the `Bus`.
    `List<BusMessage>` | `getMessagesByOwner(List<BusListenerId> appNameInst, Set<Integer> msgTypes)` Get the list of messages of the specified types posted by given owners on the `Bus`.
    `long` | `post(BusMessage msg)` Push a message to the `Bus`
    `long` | `post(BusMessage msg, BusListener listener)` Push a message to the `Bus`.
    `void` | `registerListener(Set<Integer> msgTypes, BusListener listener)` Register listener for the message types on the `Bus` Notifications will be sent to the listener for messages posted to the `Bus` from then
    `void` | `unregisterListener(BusListener listener)` Unregister listener for all message types on the `Bus` No notifications will be sent to the listener for any messages posted to the `Bus` from then on.
    `void` | `unregisterListener(Set<Integer> msgTypes, BusListener listener)` Unregister listener on the `Bus` for the specified message types.

- - ### Method Detail

    - #### ackMessage

          void ackMessage(long msgId,
                        BusListener listener)
                          throws ServiceNotAvailableException,
                                 InterruptedException

      Acknowledge for message received.
      Parameters:
        `msgId` - message ID to acknowledge
        `listener` - Bus listener object
      Throws:
        `InterruptedException` - Operation interrupted exception
        `ServiceNotAvailableException` - Bus service is not up

    - #### registerListener

          void registerListener(Set<Integer> msgTypes,
                              BusListener listener)

      Register listener for the message types on the `Bus` Notifications will be sent to the listener for messages posted to the `Bus` from then
      Parameters:
        `msgTypes` - message types
        `listener` - Bus listener object

    - #### unregisterListener

          void unregisterListener(Set<Integer> msgTypes,
                                BusListener listener)

      Unregister listener on the `Bus` for the specified message types. No notifications will be sent to the listener for messages posted to the `Bus` from then on.
      Parameters:
        `msgTypes` - message types
        `listener` - Bus listener object

    - #### unregisterListener

          void unregisterListener(BusListener listener)

      Unregister listener for all message types on the `Bus` No notifications will be sent to the listener for any messages posted to the `Bus` from then on.
      Parameters:
        `listener` - Bus listener object

    - #### post

          long post(BusMessage msg)
                    throws ServiceNotAvailableException,
                           IOException,
                           InterruptedException

      Push a message to the `Bus`
      Parameters:
        `msg` - message to be pushed
      Returns:
        message id of the newly posted message
      Throws:
        `ServiceNotAvailableException` - Bus service is down
        `InterruptedException` - Operation interrupted exception
        `IOException` - IO Exception while data serialization

    - #### post

          long post(BusMessage msg,
                  BusListener listener)
                    throws ServiceNotAvailableException,
                           IOException,
                           InterruptedException

      Push a message to the `Bus`. This method will be called by an application when acknowledgment is required.
      Parameters:
        `msg` - message to be pushed
        `listener` - Bus listener object
      Returns:
        message id of the newly posted message
      Throws:
        `ServiceNotAvailableException` - Bus service is down
        `IOException` - IO Exception while data serialization
        `InterruptedException` - Operation interrupted exception

    - #### delete

          void delete(long msgId)
                      throws ServiceNotAvailableException,
                             InterruptedException

      Delete a Bus message. Its a NOOP if the message to be deleted is not found.
      Parameters:
        `msgId` - Bus message id to be deleted
      Throws:
        `ServiceNotAvailableException` - Bus service is down
        `InterruptedException` - Operation interrupted exception

    - #### getMessages

          List<BusMessage> getMessages(Set<Integer> msgTypes)
                                       throws ServiceNotAvailableException,
                                              InterruptedException

      Get the list of messages of the specified types that are currently posted on the `Bus`. The messages are ordered by the time of insertion onto the `Bus`
      Parameters:
        `msgTypes` - list of message types to be retrieved
      Returns:
        List of Bus message
      Throws:
        `ServiceNotAvailableException` - Bus service is down
        `InterruptedException` - Operation interrupted exception

    - #### getMessagesByOwner

          List<BusMessage> getMessagesByOwner(List<BusListenerId> appNameInst,
                                            Set<Integer> msgTypes)
                                              throws ServiceNotAvailableException,
                                                     InterruptedException

      Get the list of messages of the specified types posted by given owners on the `Bus`. The messages are ordered by the time of insertion onto the `Bus`
      Parameters:
        `appNameInst` - list of message owner's name and instance
        `msgTypes` - list of message types to be retrieved
      Returns:
        List of Bus message
      Throws:
        `ServiceNotAvailableException` - Bus service is down
        `InterruptedException` - Operation interrupted exception

    - #### changeMessageOwner

          boolean changeMessageOwner(BusMessage msg,
                                   BusListener listener)
                                     throws ServiceNotAvailableException,
                                            InterruptedException

      Take ownership of an existing `BusMessage`.
      Parameters:
        `msg` - message to change ownership
        `listener` - listener of the new owner
      Returns:
        `true` on success, `false` otherwise
      Throws:
        `ServiceNotAvailableException` - Bus service is down
        `InterruptedException` - Operation interrupted exception

Copyright © 2014. All Rights Reserved.