org.licas.server

## Class MessageMediator

- java.lang.Object
- - java.lang.Thread
  - - org.licas.server.MessageMediator

- All Implemented Interfaces:
    java.lang.Runnable, BusDef, PublishSubscribeDef

      public class MessageMediator
      extends java.lang.Thread
      implements BusDef, PublishSubscribeDef

  This class mediates the process of passing messages between the server and the services

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class java.lang.Thread

      `java.lang.Thread.State, java.lang.Thread.UncaughtExceptionHandler`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected ESB` | `esb` The parent ESB server
    `protected MessageStore` | `messageStore` Communication IDs to identify the calling components and replies for stored method results.
    `protected MonitorServer` | `monitorServer` To monitor the server resource allocation
    `protected PasswordHandler` | `passwordHandler` The parent password handler
    `protected PublishSubscribeDef` | `pubSub` The publish-subscribe facility for registering and notifying about service work.

    - ### Fields inherited from class java.lang.Thread

      `MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `MessageMediator(ESB theESB, PasswordHandler thePasswordHandler, MessageStore theMessageStore)` Create a new instance of MessageMediator.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `cancelMessage(java.lang.String ticket)` Remove the message with the specified ticket number from the queue.
    `protected org.licas_xml.abs.Element` | `executeServerService(java.lang.String serviceType, MethodInfo methodInfo)` Execute a method on the server or a type of service owned by the server.
    `org.licas_xml.abs.Element` | `executeServiceType(java.lang.String serviceType, MethodInfo methodInfo)` Execute a synchronous method on a service type known by the server and probably stored locally.
    `void` | `executeServiceTypeAsync(java.lang.String serviceType, MethodInfo methodInfo)` Execute an asynchronous method on the server, or a service type owned by the server.
    `java.util.ArrayList<java.lang.String>` | `getServiceNames()` Get a list of current services on the server that allow ptp comm.
    `java.util.ArrayList<java.lang.String>` | `getServiceTypeNames(java.lang.String serviceType)` Get a list of current services on the server for a service type that allow subscribe comm.
    `java.lang.Object` | `messageBus(MethodInfo methodInfo)` Execute a call on the system message bus.
    `boolean` | `messageToBus(MessageInfo ro)` Add the message to the message bus queue for subsequent processing.
    `boolean` | `publish(WorkInfo workInfo)` Publish to do work.
    `void` | `run()` Run the thread loop to process the message bus queue.
    `boolean` | `subscribe(WorkInfo workInfo)` Subscribe for a service.
    `void` | `unpublish(KeywordInfo keyInfo, org.licas_xml.abs.Element serviceURI)` Un-publish to do work.
    `void` | `unsubscribe(KeywordInfo keyInfo, org.licas_xml.abs.Element clientURI)` Un-subscribe for a service.

    - ### Methods inherited from class java.lang.Thread

      `activeCount, checkAccess, clone, countStackFrames, currentThread, destroy, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, start, stop, stop, suspend, toString, yield`

    - ### Methods inherited from class java.lang.Object

      `equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### monitorServer

          protected MonitorServer monitorServer

      To monitor the server resource allocation

    - #### pubSub

          protected PublishSubscribeDef pubSub

      The publish-subscribe facility for registering and notifying about service work.

    - #### messageStore

          protected MessageStore messageStore

      Communication IDs to identify the calling components and replies for stored method results.

    - #### passwordHandler

          protected PasswordHandler passwordHandler

      The parent password handler

    - #### esb

          protected ESB esb

      The parent ESB server

  - ### Constructor Detail

    - #### MessageMediator

          public MessageMediator(ESB theESB,
                                 PasswordHandler thePasswordHandler,
                                 MessageStore theMessageStore)

      Create a new instance of MessageMediator.
      Parameters:
        `theESB` - the parent ESB server.
        `thePasswordHandler` - the parent password handler.
        `theMessageStore` - the message store.

  - ### Method Detail

    - #### run

          public void run()

      Run the thread loop to process the message bus queue.
      Specified by:
        `run` in interface `java.lang.Runnable`
      Overrides:
        `run` in class `java.lang.Thread`

    - #### messageToBus

          public boolean messageToBus(MessageInfo ro)

      Add the message to the message bus queue for subsequent processing.
      Parameters:
        `ro` - the request object to add.
      Returns:
        true if added, false otherwise.

    - #### cancelMessage

          public void cancelMessage(java.lang.String ticket)

      Remove the message with the specified ticket number from the queue.
      Parameters:
        `ticket` - unique ticket number, equivalent to a communication ID.

    - #### getServiceNames

          public java.util.ArrayList<java.lang.String> getServiceNames()
                                                                throws LicasException

      Get a list of current services on the server that allow ptp comm.
      Returns:
        list of current service IDs.
      Throws:
        `LicasException` - licas error.

    - #### getServiceTypeNames

          public java.util.ArrayList<java.lang.String> getServiceTypeNames(java.lang.String serviceType)
                                                                    throws LicasException

      Get a list of current services on the server for a service type that allow subscribe comm.
      Parameters:
        `serviceType` - the service type to check for.
      Returns:
        list of current service IDs.
      Throws:
        `LicasException` - licas error.

    - #### messageBus

          public java.lang.Object messageBus(MethodInfo methodInfo)
                                      throws java.lang.Exception

      Execute a call on the system message bus. This passes the message to a queue on the server from where it gets selected for processing by a service.
      Specified by:
        `messageBus` in interface `BusDef`
      Parameters:
        `methodInfo` - the method call description with all of the required information.
      Returns:
        Object the reply to the call.
      Throws:
        `java.lang.Exception` - any error.

    - #### executeServiceTypeAsync

          public void executeServiceTypeAsync(java.lang.String serviceType,
                                              MethodInfo methodInfo)
                                       throws java.lang.Exception

      Execute an asynchronous method on the server, or a service type owned by the server. This method calls `executeServerService` to invoke the `methodInfo` spec. The asynchronous call does not return a value, thereby freeing the client sooner. After executing the method, it instead saves any reply to a `messageStore` under the `methodInfo`'s `communicationID`. This method forces a return type of `Element` on the method it invokes or `void` return type. If that is not correct the method to invoke will not be found.
      Parameters:
        `serviceType` - the service type on the server.
        `methodInfo` - this is the actual method call as it would be invoked from any place. It requires the correct method name and parameter list.
      Throws:
        `java.lang.Exception` - any error.

    - #### executeServiceType

          public org.licas_xml.abs.Element executeServiceType(java.lang.String serviceType,
                                                              MethodInfo methodInfo)
                                                       throws java.lang.Exception

      Execute a synchronous method on a service type known by the server and probably stored locally. This method calls `executeServerService` to invoke the parameter `methodInfo` spec. This method forces a return type of `Element` on the method it invokes. If that is not correct the method to invoke will not be found.
      Parameters:
        `serviceType` - the service type on the server.
        `methodInfo` - this is the actual method description as it would be invoked from any place. It requires the correct method name and parameter list. It is not restricted to the two query types, but the further programming might be required to add other ones. The invoked method is assumed to return XML elements only.
      Returns:
        the reply as an Element.
      Throws:
        `java.lang.Exception` - any error.

    - #### executeServerService

          protected org.licas_xml.abs.Element executeServerService(java.lang.String serviceType,
                                                                   MethodInfo methodInfo)
                                                            throws java.lang.Exception

      Execute a method on the server or a type of service owned by the server. The service password is not required and so the server itself should have more control over the execution of these methods.
      Parameters:
        `serviceType` - the service type on the server.
        `methodInfo` - this is the actual method call as it would be made from a remote server. It requires the correct method name and parameter list. The service itself is replaced by a direct reference to one of the specified type, if one exists. The method is assumed to return XML elements only.
      Returns:
        the reply as an Element, or null if a void reply type.
      Throws:
        `java.lang.Exception` - any error.

    - #### subscribe

          public boolean subscribe(WorkInfo workInfo)
                            throws java.lang.Exception

      Subscribe for a service.
      Specified by:
        `subscribe` in interface `PublishSubscribeDef`
      Parameters:
        `workInfo` - new client details. It must include the keyword list and the method to reply with.
        1. A list of descriptive keywords and topic to match with.
        2. Details of the client method to reply with if a service work matches with the keywords request.
        If `getClientURI()` is empty, then the request is ignored. It must also contain a parameter list of size 1, that is either an `Object` or a `WorkInfo` object, as that is what will be sent as a reply.
      Returns:
        true if service request registered, false if keyword overlap.
      Throws:
        `java.lang.Exception` - any error.

    - #### unsubscribe

          public void unsubscribe(KeywordInfo keyInfo,
                                  org.licas_xml.abs.Element clientURI)
                           throws java.lang.Exception

      Un-subscribe for a service.
      Specified by:
        `unsubscribe` in interface `PublishSubscribeDef`
      Parameters:
        `keyInfo` - list of descriptive keywords to uniquely identify the service.
        `clientURI` - the client URI defines the request client.
      Throws:
        `java.lang.Exception` - any error.

    - #### publish

          public boolean publish(WorkInfo workInfo)
                          throws java.lang.Exception

      Publish to do work.
      Specified by:
        `publish` in interface `PublishSubscribeDef`
      Parameters:
        `workInfo` - full work details, including an optional contract. The method description must include the client URI as this is what identifies the request. If `getClientURI()` is empty, then the request is ignored.
      Returns:
        true if work request registered, false if keyword overlap.
      Throws:
        `java.lang.Exception` - any error.

    - #### unpublish

          public void unpublish(KeywordInfo keyInfo,
                                org.licas_xml.abs.Element serviceURI)
                         throws java.lang.Exception

      Un-publish to do work.
      Specified by:
        `unpublish` in interface `PublishSubscribeDef`
      Parameters:
        `keyInfo` - list of descriptive keywords to uniquely identify the work.
        `serviceURI` - the client URI defines the request service.
      Throws:
        `java.lang.Exception` - any error.