org.licas.server.esb

## Class PublishSubscribe

- java.lang.Object
- - org.licas.server.esb.PublishSubscribe

- All Implemented Interfaces:
    PublishSubscribeDef

      public class PublishSubscribe
      extends java.lang.Object
      implements PublishSubscribeDef

  This class records requests for a service from clients and responds with appropriate replies when a service registers it can carry out the request. Requests are submitted in the form of a `MethodInfo` description and a `KeywordInfo` list of keywords. The method description must include a client URI or it will be rejected. This uniquely defines the service or client. The keyword lists may not overlap for any one client or service. They may not share any keywords, but the topic names can be shared.
  Author:
    Kieran Greer

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `PublishSubscribe()` Create a new instance of PublishSubscribe

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `addToRegister(java.lang.String address, WorkInfo workInfo, java.util.HashMap<java.lang.String,java.util.ArrayList<WorkInfo>> register)` Add the request to do work.
    `protected WorkInfo` | `getWorkInfo(java.lang.String address, KeywordInfo keyInfo, java.util.HashMap<java.lang.String,java.util.ArrayList<WorkInfo>> register)` If a work description is already saved under the service address and keyword list then return it, otherwise return null.
    `static MethodInfo` | `methodForPublish(org.licas_xml.abs.Element serverUri, java.lang.String serverPassword, KeywordInfo keywords, MethodInfo replyMethod, PasswordHandler pHandler)` Create and return the full method list for publishing a service's information.
    `static MethodInfo` | `methodForSubscribe(org.licas_xml.abs.Element serverUri, java.lang.String serverPassword, KeywordInfo keywords, MethodInfo replyMethod, PasswordHandler pHandler)` Create and return the full method list for subscribing to a service's information.
    `boolean` | `publish(WorkInfo workInfo)` Publish to do work.
    `protected void` | `removeFromRegister(java.lang.String address, KeywordInfo keyInfo, java.util.HashMap<java.lang.String,java.util.ArrayList<WorkInfo>> register)` Add the request to do work.
    `boolean` | `subscribe(WorkInfo workInfo)` Subscribe for a service.
    `void` | `unpublish(KeywordInfo keyInfo, org.licas_xml.abs.Element clientURI)` 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.Object

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

- - ### Constructor Detail

    - #### PublishSubscribe

          public PublishSubscribe()

      Create a new instance of PublishSubscribe

  - ### Method Detail

    - #### subscribe

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

      Subscribe for a service. Each time a service publishes a matching work description any subscriber is sent the `WorkInfo` details. An immediate check is done to determine if matching work is available.
      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.
        The details method must comply with some specific formatting as follows:
        1. It must include the client URI, as this is what identifies the request. If `getClientURI()` is empty, then the request is ignored.
        2. It must 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.
        3. The return type must be `void` (asynchronous call).
      Returns:
        true if added as a new request, or false if service request is already registered, via keyword or topic overlap, for example.
      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. This triggers a message to all subscribed services each time and any publishing service may publish the same work request any number of times. Only the first published request is saved however and then then sent out each time.
      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 added as a new request, or false if work request is already registered, via keyword or topic overlap, for example.
      Throws:
        `java.lang.Exception` - any error.

    - #### unpublish

          public void unpublish(KeywordInfo keyInfo,
                                org.licas_xml.abs.Element clientURI)
                         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.
        `clientURI` - the client URI defines the request service.
      Throws:
        `java.lang.Exception` - any error.

    - #### addToRegister

          protected void addToRegister(java.lang.String address,
                                       WorkInfo workInfo,
                                       java.util.HashMap<java.lang.String,java.util.ArrayList<WorkInfo>> register)

      Add the request to do work.
      Parameters:
        `address` - unique address for the client.
        `workInfo` - the work request.
        `register` - the register to add to.

    - #### removeFromRegister

          protected void removeFromRegister(java.lang.String address,
                                            KeywordInfo keyInfo,
                                            java.util.HashMap<java.lang.String,java.util.ArrayList<WorkInfo>> register)
                                     throws java.lang.Exception

      Add the request to do work.
      Parameters:
        `address` - unique address for the client.
        `keyInfo` - keywords list to identify the work description.
        `register` - the register to add to.
      Throws:
        `java.lang.Exception` - any error.

    - #### getWorkInfo

          protected WorkInfo getWorkInfo(java.lang.String address,
                                         KeywordInfo keyInfo,
                                         java.util.HashMap<java.lang.String,java.util.ArrayList<WorkInfo>> register)
                                  throws java.lang.Exception

      If a work description is already saved under the service address and keyword list then return it, otherwise return null.
      Parameters:
        `address` - unique address for the client/service.
        `keyInfo` - list of keywords. None must be present in a currently saved work request by the same service.
        `register` - the register to check.
      Returns:
        true if OK.
      Throws:
        `java.lang.Exception` - any error.

    - #### methodForPublish

          public static MethodInfo methodForPublish(org.licas_xml.abs.Element serverUri,
                                                    java.lang.String serverPassword,
                                                    KeywordInfo keywords,
                                                    MethodInfo replyMethod,
                                                    PasswordHandler pHandler)
                                             throws java.lang.Exception

      Create and return the full method list for publishing a service's information.
      Parameters:
        `serverUri` - address for the server to call.
        `serverPassword` - the server password.
        `keywords` - list of keywords to represent the published information.
        `replyMethod` - callback method by the server after publshing.
        `pHandler` - the service password handler.
      Returns:
        a `MethodInfo` object to make a server publish invocation with.
      Throws:
        `java.lang.Exception` - any error.

    - #### methodForSubscribe

          public static MethodInfo methodForSubscribe(org.licas_xml.abs.Element serverUri,
                                                      java.lang.String serverPassword,
                                                      KeywordInfo keywords,
                                                      MethodInfo replyMethod,
                                                      PasswordHandler pHandler)
                                               throws java.lang.Exception

      Create and return the full method list for subscribing to a service's information.
      Parameters:
        `serverUri` - address for the server to call.
        `serverPassword` - the server password.
        `keywords` - list of keywords to represent the published information.
        `replyMethod` - callback method by the server, to send the published data to.
        `pHandler` - the service password handler.
      Returns:
        a `MethodInfo` object to make a server subscribe invocation with.
      Throws:
        `java.lang.Exception` - any error.