org.licas.server

## Class LocalServer

- java.lang.Object
- - org.licas.server.LocalServer

-     public class LocalServer
      extends java.lang.Object

  API for invoking methods on the `HttpServer` or `ESB`. These are both admin key protected now and so direct access is more difficult.
  Author:
    Kieran Greer

- - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `LocalServer()` Create a new instance of LocalServer

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `addRootNode(java.lang.String theRootNode, java.lang.String adminKey)` Add a service uuid to the list of root nodes.
    `boolean` | `addService(java.lang.String thePassword, java.lang.String serviceName, java.lang.String serviceType, java.lang.Object theService)` Add a new service to the ESB but do not start its thread.
    `boolean` | `addServiceMeta(java.lang.String thePassword, java.lang.String theAdminKey, ServiceMeta theServiceMeta)` Add the metadata for the service.
    `boolean` | `allowAddService(java.lang.String adminKey, boolean allow)` Set the `allowAddService` variable to allow services to be added.
    `java.util.HashMap<java.lang.String,Metrics>` | `allServiceMetrics(java.lang.String adminKey)` Get a list of all available services' metrics.
    `boolean` | `canAccess(java.lang.String thePassword, java.lang.reflect.Method theMethod)` Return true if the password allows the calling component to access this component.
    `boolean` | `canAccess(java.lang.String thePassword, java.lang.String methodName)` Return true if the password allows the calling component to access this component.
    `boolean` | `cancelMessage(java.lang.String ticket, java.lang.String adminKey)` Remove the message with the specified ticket number from the queue.
    `static boolean` | `checkAddress(java.lang.String host, int port)` Return true if the ip address and port compares to the address the server is running on.
    `static java.lang.String` | `contactInfo()` Get a server administrator contact address, email or something.
    `java.lang.Object` | `execute(MethodInfo methodInfo)` Execute the specified method and return the result.
    `boolean` | `getAllowAddService(java.lang.String adminKey)` Return true if the ESB allows adding services.
    `static LocalServer` | `getApi(java.lang.String serverPassword)` Get the local server instance.
    `Link_NM` | `getFaultsTree(java.lang.String adminKey)` Get the faults list tree, for display purposes.
    `FileObject` | `getJarForService(java.lang.String jarName)` Load a jar file into a file object and return.
    `java.lang.String` | `getPassword(java.lang.String clientID, Contract clientContract)` Get this service's password, depending on the calling component's contract description.
    `static org.licas_xml.abs.Element` | `getServerHandle()` Return the server handle of the static http server.
    `boolean` | `getServerShutDown()` Return a value indicating if the static http server should be shut down.
    `static java.lang.String` | `getServerURL()` Return the http address of the static http server.
    `java.lang.Object` | `getService(java.lang.String serviceName, java.lang.String thePassword, java.lang.String adminKey)` Return the service for the related service name.
    `org.licas_xml.abs.Element` | `getServiceMeta(java.lang.String theServiceID)` Get the metadata for the service from the server repository.
    `ServiceMeta` | `getServiceMeta(java.lang.String theServiceID, java.lang.String theAdminKey)` Get the service metadata from the server repository.
    `java.util.ArrayList<java.lang.String>` | `getServiceNames()` Get a list of services running on the ESB.
    `java.util.ArrayList<java.lang.String>` | `getServiceNames(java.util.ArrayList<java.lang.String> thisServiceTypes)` Return all child service names for a list of service types.
    `java.util.ArrayList<java.lang.String>` | `getServiceNames(java.util.ArrayList<java.lang.String> thisServiceTypes, boolean reciprocal)` Return all child service names for a list of service types.
    `java.lang.String` | `getServiceType(java.lang.String serviceID)` Get the service type for the specified service.
    `java.util.ArrayList<java.lang.String>` | `getServiceTypes()` Get a list of all of the service types in the network.
    `java.util.ArrayList<java.lang.String>` | `getServiceTypes(java.lang.String category)` Get a list of all of the service types in the network for a particular category.
    `ServiceWrapperDef` | `getServiceWrapper(java.lang.String serviceName, java.lang.String thePassword, java.lang.String adminKey)` Return the service wrapper for the related service name.
    `boolean` | `hasESB(java.lang.String thePassword)` Return true if an enterprise service bus is running on this server.
    `boolean` | `hasJarFactory(java.lang.String thePassword)` Return true if this server is running a jar factory.
    `static boolean` | `hasServer()` Return true if an `HttpServer` instance is created.
    `static boolean` | `isAdminKey(java.lang.String theAdminKey)` Return true if the correct admin key.
    `boolean` | `isBlockedService(java.lang.String serviceID)` Return true if the service is a blocked service.
    `static boolean` | `isLocalIPAddress(java.lang.String theIPAddress)` Return true if the ip address represents a local server.
    `static boolean` | `isPassword(java.lang.String theServerPassword)` Return true if the correct password.
    `static boolean` | `isRunning()` Return true if an enterprise service bus is stored and running in this server.
    `boolean` | `isStoredService(java.lang.String serviceID)` Return true if the service id entered relates to a stored service.
    `boolean` | `messageToBus(MessageInfo ro, java.lang.String adminKey)` Add the next message to the message bus, to be returned in order for processing by a service.
    `void` | `notifyOfFault(FaultDetails fault, java.lang.String adminKey)` This method should be called to notify the server about a problem or fault.
    `org.licas_xml.abs.Element` | `passwordsStateToXml(java.lang.String adminKey)` Serialize the stored ESB passwords list and return as an XML-based description.
    `boolean` | `removeServiceMeta(java.lang.String theServiceID, java.lang.String theAdminKey)` Remove the service metadata from the server repository.
    `boolean` | `serverHasService(java.lang.String serviceID)` Return true if a service with the specified id is running on this server.
    `boolean` | `serverHasServiceType(java.lang.String serviceType)` Return true if a service with the specified type is running on this server.
    `boolean` | `setESB(java.lang.String serviceName, java.lang.String serviceType, java.util.ArrayList<java.lang.String> jarFile, java.lang.String className, java.util.ArrayList<java.lang.Object> params)` Creates a user-defined instance of ESB and set with the config values.
    `boolean` | `setESB(java.lang.String serviceName, java.lang.String serviceType, org.licas_xml.abs.Element adminXml)` Creates a default instance of ESB and set with the config values.
    `protected static void` | `setPasswords(java.lang.String thePassword, java.lang.String theAdminKey)` Set the password and admin key for accessing the server.
    `boolean` | `shutDown(java.lang.String theAdminKey)` Shut down the server and stop the request thread.
    `void` | `startRequestThread(java.lang.String adminKey)` Start the server request thread.

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

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

- - ### Constructor Detail

    - #### LocalServer

          protected LocalServer()

      Create a new instance of LocalServer

  - ### Method Detail

    - #### getApi

          public static LocalServer getApi(java.lang.String serverPassword)

      Get the local server instance.
      Parameters:
        `serverPassword` - the server password or admin key.
      Returns:
        the local server api instance, or `null` if there is an error.

    - #### setPasswords

          protected static void setPasswords(java.lang.String thePassword,
                                             java.lang.String theAdminKey)

      Set the password and admin key for accessing the server. Can be set only once.
      Parameters:
        `thePassword` - the password for accessing the server.
        `theAdminKey` - the admin key for accessing the server.

    - #### hasServer

          public static boolean hasServer()

      Return true if an `HttpServer` instance is created.
      Returns:
        true if a server instance has been created, false otherwise.

    - #### isRunning

          public static boolean isRunning()

      Return true if an enterprise service bus is stored and running in this server.
      Returns:
        true if this server is running with all components.

    - #### contactInfo

          public static java.lang.String contactInfo()

      Get a server administrator contact address, email or something.
      Returns:
        a server contact address.

    - #### isLocalIPAddress

          public static boolean isLocalIPAddress(java.lang.String theIPAddress)

      Return true if the ip address represents a local server.
      Parameters:
        `theIPAddress` - the ip address to compare, 127.0.0.1, for example.
      Returns:
        true if a local ipAddress.

    - #### canAccess

          public boolean canAccess(java.lang.String thePassword,
                                   java.lang.String methodName)

      Return true if the password allows the calling component to access this component.
      Parameters:
        `thePassword` - the password to use.
        `methodName` - the method name that needs to be called.
      Returns:
        true if the entered password is the correct password or there is no password.

    - #### canAccess

          public boolean canAccess(java.lang.String thePassword,
                                   java.lang.reflect.Method theMethod)

      Return true if the password allows the calling component to access this component.
      Parameters:
        `thePassword` - the password to use.
        `theMethod` - the method that needs to be called.
      Returns:
        true if the entered password is the correct password or there is no password.

    - #### getPassword

          public java.lang.String getPassword(java.lang.String clientID,
                                              Contract clientContract)
                                       throws java.lang.Exception

      Get this service's password, depending on the calling component's contract description. By default, a service is assigned a 'yes' contract, meaning that it is open and will always return its password to allow for method invocation. The other default option is a 'no' contract, meaning that there is no negotiation and the password must be known. This can also be changed by adding a different 'sla' contract for each service level in the service. You can therefore override this method to provide your own checks, using this as a guide.
      Parameters:
        `clientID` - the clientID of the calling component.
        `clientContract` - the description of the calling component's contract proposal.
      Returns:
        this overridden method passes the call to the nested `ESB` object that also uses the same password set. The server by default will always or never return its password.
      Throws:
        `java.lang.Exception` - any error.

    - #### checkAddress

          public static boolean checkAddress(java.lang.String host,
                                             int port)

      Return true if the ip address and port compares to the address the server is running on.
      Parameters:
        `host` - the host address. Can include 'localhost' or '127.0.0.1'.
        `port` - the port.
      Returns:
        true if the whole address agrees with the server address.

    - #### getServerURL

          public static java.lang.String getServerURL()

      Return the http address of the static http server.
      Returns:
        the server URL address, with ip and port, or null if the server is not running.

    - #### getServerHandle

          public static org.licas_xml.abs.Element getServerHandle()

      Return the server handle of the static http server.
      Returns:
        the server URI, same as calling `Handle`.`getLocalServerURI()`.

    - #### setESB

          public boolean setESB(java.lang.String serviceName,
                                java.lang.String serviceType,
                                org.licas_xml.abs.Element adminXml)

      Creates a default instance of ESB and set with the config values. Note that the ESB can be added only once, at the start of the server initialisation.
      Parameters:
        `serviceName` - the service name.
        `serviceType` - the service type.
        `adminXml` - the admin info or description of this service.
      Returns:
        true if added OK, false otherwise.

    - #### setESB

          public boolean setESB(java.lang.String serviceName,
                                java.lang.String serviceType,
                                java.util.ArrayList<java.lang.String> jarFile,
                                java.lang.String className,
                                java.util.ArrayList<java.lang.Object> params)

      Creates a user-defined instance of ESB and set with the config values. Note that the ESB can be added only once, at the start of the server initialisation.
      Parameters:
        `serviceName` - the name of the service.
        `serviceType` - the type of the service.
        `jarFile` - the jar files for a remote loading. Values are jar paths of type String.
        `className` - the name of the service class.
        `params` - a list of initialisation parameters.
      Returns:
        true if added OK, false otherwise.

    - #### startRequestThread

          public void startRequestThread(java.lang.String adminKey)
                                  throws java.lang.Exception

      Start the server request thread.
      Parameters:
        `adminKey` - the server admin key.
      Throws:
        `java.lang.Exception` - any error.

    - #### messageToBus

          public boolean messageToBus(MessageInfo ro,
                                      java.lang.String adminKey)

      Add the next message to the message bus, to be returned in order for processing by a service.
      Parameters:
        `ro` - the message to add, as the whole request object, that then executes itself and returns the result.
        `adminKey` - admin key to access the server.
      Returns:
        true if the request object is added, false otherwise.

    - #### cancelMessage

          public boolean cancelMessage(java.lang.String ticket,
                                       java.lang.String adminKey)

      Remove the message with the specified ticket number from the queue.
      Parameters:
        `ticket` - unique ticket number, equivalent to a communication ID.
        `adminKey` - the server admin key.
      Returns:
        true if cancelled, false otherwise.

    - #### execute

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

      Execute the specified method and return the result. This executes on the ESB directly. Note that you can execute on a single instance of a service type by setting the `methodInfo.serviceURI` to be something like `Handle`.`createServiceHandle(serviceType)`.
      Parameters:
        `methodInfo` - the method call description with all of the required information.
      Returns:
        the reply, any object.
      Throws:
        `ServiceException` - for non-critical service related problems, such as if the method password is incorrect.
        `java.lang.Exception` - any error.

    - #### isBlockedService

          public boolean isBlockedService(java.lang.String serviceID)

      Return true if the service is a blocked service.
      Parameters:
        `serviceID` - the service uuid.
      Returns:
        true if (temporarily) blocked from being accessed, false otherwise.

    - #### allowAddService

          public boolean allowAddService(java.lang.String adminKey,
                                         boolean allow)

      Set the `allowAddService` variable to allow services to be added.
      Parameters:
        `adminKey` - the admin key for this service.
        `allow` - true if reset to allow adding of services, false to reset to block of adding services.
      Returns:
        true if the variable is set (adminKey OK), false otherwise.

    - #### getAllowAddService

          public boolean getAllowAddService(java.lang.String adminKey)

      Return true if the ESB allows adding services.
      Parameters:
        `adminKey` - the admin key for the server.
      Returns:
        true if services can be added, false otherwise.

    - #### addRootNode

          public boolean addRootNode(java.lang.String theRootNode,
                                     java.lang.String adminKey)

      Add a service uuid to the list of root nodes. Note that the service itself must have been added previously. This method is only to declare it a root node in some hierarchical organisation structure.
      Parameters:
        `theRootNode` - the uuid of the root service to add.
        `adminKey` - the server admin key.
      Returns:
        true if the node is added or false otherwise.

    - #### getService

          public java.lang.Object getService(java.lang.String serviceName,
                                             java.lang.String thePassword,
                                             java.lang.String adminKey)
                                      throws ServiceException,
                                             java.lang.Exception

      Return the service for the related service name. This method requires the service admin key as well, but then returns a direct reference. A direct reference to the service itself is returned, no matter what the object type is.
      Parameters:
        `serviceName` - the name of the service you want to retrieve.
        `thePassword` - the password for the service you want to retrieve.
        `adminKey` - the admin key for the service you want to retrieve.
      Returns:
        the service object if it exists or null if it does not.
      Throws:
        `ServiceException` - for service specific error.
        `java.lang.Exception` - any other error.

    - #### addService

          public boolean addService(java.lang.String thePassword,
                                    java.lang.String serviceName,
                                    java.lang.String serviceType,
                                    java.lang.Object theService)
                             throws java.lang.Exception

      Add a new service to the ESB but do not start its thread.
      Parameters:
        `thePassword` - the password to protect access to this component.
        `serviceName` - the name of the service.
        `serviceType` - the type of the service.
        `theService` - the service.
      Returns:
        true if the service has been added, false otherwise.
      Throws:
        `java.lang.Exception` - any error.

    - #### addServiceMeta

          public boolean addServiceMeta(java.lang.String thePassword,
                                        java.lang.String theAdminKey,
                                        ServiceMeta theServiceMeta)

      Add the metadata for the service.
      Parameters:
        `thePassword` - the service password. Register if not already added.
        `theAdminKey` - the admin key for the service. Register if not already added.
        `theServiceMeta` - the metadata for the service.
      Returns:
        true if added OK, false otherwise.

    - #### getServiceMeta

          public org.licas_xml.abs.Element getServiceMeta(java.lang.String theServiceID)
                                                   throws java.lang.Exception

      Get the metadata for the service from the server repository.
      Parameters:
        `theServiceID` - the unique id to define the service.
      Returns:
        the metadata in XML format if it exists or null if it does not.
      Throws:
        `java.lang.Exception` - any error.

    - #### getServiceMeta

          public ServiceMeta getServiceMeta(java.lang.String theServiceID,
                                            java.lang.String theAdminKey)
                                     throws java.lang.Exception

      Get the service metadata from the server repository.
      Parameters:
        `theServiceID` - the unique id to define the service.
        `theAdminKey` - the unique admin key for the service.
      Returns:
        a direct reference to the object itself so that it can be changed.
      Throws:
        `java.lang.Exception` - any error.

    - #### removeServiceMeta

          public boolean removeServiceMeta(java.lang.String theServiceID,
                                           java.lang.String theAdminKey)
                                    throws java.lang.Exception

      Remove the service metadata from the server repository.
      Parameters:
        `theServiceID` - the unique id of the service to remove.
        `theAdminKey` - the unique admin key for the service.
      Returns:
        true if the info is removed or false otherwise.
      Throws:
        `java.lang.Exception` - any error.

    - #### getServiceWrapper

          public ServiceWrapperDef getServiceWrapper(java.lang.String serviceName,
                                                     java.lang.String thePassword,
                                                     java.lang.String adminKey)
                                              throws ServiceException,
                                                     java.lang.Exception

      Return the service wrapper for the related service name. This method requires the admin key as well, and then returns a direct reference to the wrapper only. Some methods may be executed on the wrapper and not the service.
      Parameters:
        `serviceName` - the name of the service you want to retrieve.
        `thePassword` - the password to access the service you want to retrieve.
        `adminKey` - the admin key for the service you want to retrieve.
      Returns:
        the service object if it exists or null if it does not.
      Throws:
        `ServiceException` - for service specific error.
        `java.lang.Exception` - any other error.

    - #### getServiceNames

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

      Get a list of services running on the ESB. This is public information.
      Returns:
        all service uuids, of type String.

    - #### getServiceNames

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

      Return all child service names for a list of service types.
      Parameters:
        `thisServiceTypes` - the service types list.
      Returns:
        the service names for the service types list.
      Throws:
        `LicasException` - if the service types input is `null`.

    - #### getServiceNames

          public java.util.ArrayList<java.lang.String> getServiceNames(java.util.ArrayList<java.lang.String> thisServiceTypes,
                                                                       boolean reciprocal)
                                                                throws LicasException

      Return all child service names for a list of service types.
      Parameters:
        `thisServiceTypes` - the service types list.
        `reciprocal` - is false return all service names of the service types, if true return all service names of all other types.
      Returns:
        the service names for the service types list.
      Throws:
        `LicasException` - if the service types input is `null`.

    - #### getServiceType

          public java.lang.String getServiceType(java.lang.String serviceID)

      Get the service type for the specified service.
      Parameters:
        `serviceID` - id of the service to retrieve.
      Returns:
        a list of all of the service types, of type String.

    - #### getServiceTypes

          public java.util.ArrayList<java.lang.String> getServiceTypes()

      Get a list of all of the service types in the network.
      Returns:
        a list of all of the service types, of type String.

    - #### getServiceTypes

          public java.util.ArrayList<java.lang.String> getServiceTypes(java.lang.String category)

      Get a list of all of the service types in the network for a particular category.
      Parameters:
        `category` - the category to return service types for.
      Returns:
        a list of all of the service types, of type String.

    - #### passwordsStateToXml

          public org.licas_xml.abs.Element passwordsStateToXml(java.lang.String adminKey)

      Serialize the stored ESB passwords list and return as an XML-based description.
      Parameters:
        `adminKey` - the ESB admin key.
      Returns:
        an XML representation of all passwords, or null if the admin key is incorrect.

    - #### allServiceMetrics

          public java.util.HashMap<java.lang.String,Metrics> allServiceMetrics(java.lang.String adminKey)

      Get a list of all available services' metrics.
      Parameters:
        `adminKey` - the admin key for the server.
      Returns:
        the service metric stats, key is the service id.

    - #### notifyOfFault

          public void notifyOfFault(FaultDetails fault,
                                    java.lang.String adminKey)

      This method should be called to notify the server about a problem or fault. It could also happen automatically through the autonomic manager, for example, but extra coding is required for that. The fault details are read and stored in a tree structure for analysis. Only minimal additional action is taken, such as removing or blocking the offending entity. See the documentation for more details.
      Parameters:
        `fault` - a description of the fault.
        `adminKey` - server admin key. If this is incorrect, then the fault is not recorded.

    - #### getFaultsTree

          public Link_NM getFaultsTree(java.lang.String adminKey)

      Get the faults list tree, for display purposes.
      Parameters:
        `adminKey` - the admin key for the server.
      Returns:
        the value of faults.

    - #### isPassword

          public static boolean isPassword(java.lang.String theServerPassword)

      Return true if the correct password.
      Parameters:
        `theServerPassword` - the password to check for.
      Returns:
        true if the correct password.

    - #### isAdminKey

          public static boolean isAdminKey(java.lang.String theAdminKey)

      Return true if the correct admin key.
      Parameters:
        `theAdminKey` - the admin key to check for.
      Returns:
        true if the correct admin key.

    - #### hasESB

          public boolean hasESB(java.lang.String thePassword)

      Return true if an enterprise service bus is running on this server.
      Parameters:
        `thePassword` - the password for this server.
      Returns:
        true if an ESB has already been loaded.

    - #### hasJarFactory

          public boolean hasJarFactory(java.lang.String thePassword)

      Return true if this server is running a jar factory.
      Parameters:
        `thePassword` - the password for this server.
      Returns:
        true if a jar factory is installed.

    - #### serverHasService

          public boolean serverHasService(java.lang.String serviceID)
                                   throws java.lang.Exception

      Return true if a service with the specified id is running on this server.
      Parameters:
        `serviceID` - the service uuid to check for.
      Returns:
        true if a service with that ID is running, false otherwise.
      Throws:
        `java.lang.Exception` - any error.

    - #### serverHasServiceType

          public boolean serverHasServiceType(java.lang.String serviceType)

      Return true if a service with the specified type is running on this server.
      Parameters:
        `serviceType` - the service type to check for.
      Returns:
        true if a service of that type is running, false otherwise.

    - #### isStoredService

          public boolean isStoredService(java.lang.String serviceID)

      Return true if the service id entered relates to a stored service. This relates to metadata stored in the repository and so it might be a utility service or a base service, so it is slightly different to the `serverHasService` method.
      Parameters:
        `serviceID` - the unique service id.
      Returns:
        true if the related service is stored on this server.

    - #### getJarForService

          public FileObject getJarForService(java.lang.String jarName)

      Load a jar file into a file object and return. The jar file must be stored in the default services folder location. It must also be compiled into a single package as no third party jar files will be loaded as well.
      Parameters:
        `jarName` - the name of the jar file.
      Returns:
        the created file object.

    - #### getServerShutDown

          public boolean getServerShutDown()

      Return a value indicating if the static http server should be shut down.
      Returns:
        a value if the server should be shut down.

    - #### shutDown

          public boolean shutDown(java.lang.String theAdminKey)

      Shut down the server and stop the request thread.
      Parameters:
        `theAdminKey` - the unique key to protect loading/removal of the server.
      Returns:
        true if shut down OK.