org.licas.server

## Class ESB

- java.lang.Object
- - java.lang.Thread
  - - org.licas.module.LicasModule
    - - org.licas.module.FrameworkModule
      - - org.licas.module.ServiceModule
        - - org.licas.Service
          - - org.licas.service.DataService
            - - org.licas.Auto
              - - org.licas.AutoSecure
                - - org.licas.server.ESB

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

      public class ESB
      extends AutoSecure
      implements BusDef, PublishSubscribeDef

  This is a base class that acts as a lightweight server manager for the loaded services. This is based on an `Enterprise Service Bus`, to put it in the context of an SOA architecture. It is derived from a `Service` class and so uses all of those methods. In addition, it has new methods for searching over service metadata and managing the method invocation calls.

  This is stored as a service on an `HttpServer` and anything loaded onto the licas server actually gets stored here. This class therefore controls service creation and making method invocations on them. This class also stores the metadata descriptions in a `ServerMetadata` repository. Remote communications are sent to the HttpServer class through an HTTP protocol that then passes these onto this class for processing. The HttpServer however still has some methods that can be queried for server-only requests.

  Any service that is loaded and registered here is a base service. All services are contained in a wrapper first, where any `Auto`-derived service loaded here is contained by an `AutonomicManager` wrapper. Any non Auto-derived service or any service loaded to some other component does not have an Autonomic Manager, but is wrapped by a `ServiceWrapper` instead. As well as the functionality, these extra wrappers provide some levels of security.

  Author:
    Kieran Greer.

- - ### 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 AutoMetaSearch` | `autoMetaSearch` Stats search facility over the loaded services.
    `protected java.util.ArrayList<java.lang.String>` | `blockedServices` A list of services that cannot be accessed because permission is blocked.
    `protected static java.lang.String` | `commFault` Fault communication id
    `protected HttpServer` | `httpBase` Base http server.
    `protected LicasDocSearch` | `licasDocSearch` Text document search facility over the allowed folders.
    `protected MessageMediator` | `messageMediator` This class mediates the process of passing messages between the server and the services.
    `protected PacketMessages` | `messagePackets` Stores communication ids with related message packet info for receiving messages in packets.
    `protected Metrics` | `metrics` Server metrics.
    `protected java.util.ArrayList<java.lang.String>` | `rootNodes` The uuids of services that are root nodes in a hierarchical network.
    `protected ServerMetadata` | `serverMetadata` Metadata repository for registered services.
    `protected ServerMetaSearch` | `serverMetaSearch` Metadata search facility over the registered services, based on XML pattern matching.
    `protected java.util.HashMap<java.lang.String,java.util.ArrayList<java.lang.String>>` | `serverServices` List of global services that can be called by any other service and are controlled by the server.
    `protected UtilsManagerDef` | `utilsManager` Server utilities manager.

    - ### Fields inherited from class org.licas.Auto

      `autoEngine, autoManager, bm, iterations, sleepTime`

    - ### Fields inherited from class org.licas.service.DataService

      `dataCompare, dataMethod, resultObj`

    - ### Fields inherited from class org.licas.Service

      `canAccessMeta, canAccessNested, dm, finalised, isRemoteCall, messageStore, serviceAdmin, serviceGrade, serviceInitialise, serviceLinks, serviceState, sm, toLoadScript`

    - ### Fields inherited from class org.licas.module.ServiceModule

      `shutDown`

    - ### Fields inherited from class org.licas.module.FrameworkModule

      `passwordHandler, service, serviceType`

    - ### Fields inherited from class org.licas.module.LicasModule

      `jarFile, syncOn, uuid`

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

      `MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ESB(java.lang.String password, java.lang.String thisAdminKey)` Creates a new instance of ESB.
    `ESB(java.lang.String thisPassword, java.lang.String thisAdminKey, org.licas_xml.abs.Element adminXml)` Creates a new instance of ESB.
    `ESB(java.lang.String thisPassword, java.lang.String thisAdminKey, org.licas_xml.abs.Element adminXml, java.lang.String resManClass)` Creates a new instance of ESB.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `addLoader(java.lang.String thePassword, java.util.ArrayList<java.lang.String> uris)` Add a new class loader from remote uris.
    `protected void` | `addMessageMetrics(MethodInfo messageInfo, java.lang.String thePassword)` Add metric or stat values for the message object.
    `boolean` | `addMessagePacket(java.lang.String communicationID, java.lang.String packetObject)` Add the message packet to the appropriate file as indicated by the communication id.
    `boolean` | `addObject(java.lang.String thePassword, java.lang.String className, java.util.ArrayList<java.lang.String> uris)` Create a new instance of an object, with no initialisation parameters.
    `boolean` | `addPacketCommunicationID(java.lang.String communicationID, int packetSize)` Add the communication id and packet info to the packetInfo structure.
    `boolean` | `addParser(java.lang.String thePassword, java.lang.String objectClass, java.lang.String parserClass, java.util.ArrayList<java.lang.String> uris, java.util.ArrayList<java.lang.Object> params)` Add a new parser to the parsers.
    `protected boolean` | `addRootNode(java.lang.String theRootNode, java.lang.String theAdminKey)` Add a service uuid to the list of root nodes.
    `boolean` | `addServiceMeta(java.lang.String thePassword, java.lang.String theAdminKey, ServiceMeta theServiceMeta)` Add the metadata for the service.
    `java.util.HashMap<java.lang.String,Metrics>` | `allServiceMetrics(java.lang.String adminKey)` Get the stats for all services.
    `protected void` | `autoManFault(Link_NM message)` Add the fault tree to the autonomic manager queue for processing.
    `protected MessageInfo` | `behaviourAction(MessageInfo messageInfo)` Periodically run some server utility functions to monitor the system state.
    `boolean` | `blockService(java.lang.String serviceUuid, java.lang.String adminKey)` Block the service from being accessed.
    `void` | `calculateRootNodes(java.lang.String theAdminKey)` Calculate what nodes are root nodes, that is, are not children of any other nodes.
    `boolean` | `cancelMessage(java.lang.String ticket, java.lang.String adminKey)` Remove the message with the specified ticket number from the queue.
    `void` | `clearNetwork(java.util.ArrayList<java.lang.String> serviceTypes, boolean keepRemove, java.lang.String adminKey)` Remove all components of the network currently running on this server, but only of the specified service type.
    `void` | `clearNetwork(java.lang.String adminKey)` Remove all components of the network currently running on this server.
    `void` | `close()` Clean-up before shutting down the service.
    `protected ServiceWrapperDef` | `createServiceWrapper(java.lang.Object serviceObj, java.lang.String serviceName, java.lang.String serviceType, java.util.ArrayList<java.lang.String> jarFiles, org.licas_xml.abs.Element adminXml)` Create a service wrapper for storing the service object.
    `java.lang.Object` | `endOfMessage(java.lang.String communicationID)` Call this to indicate that the whole message has been sent and should now be executed.
    `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 owned locally.
    `void` | `executeServiceTypeAsync(java.lang.String serviceType, MethodInfo methodInfo)` Execute an asynchronous method on the server, or a service type known by the server.
    `java.lang.String` | `getAdminKey(java.lang.String serviceID, java.lang.String thisAdminKey)` Get the service key for the specified service.
    `org.licas_xml.abs.Element` | `getAllServiceMeta()` Get a default subset of the metadata for the full service list, for info purposes only.
    `org.licas_xml.abs.Element` | `getAllServiceMeta(java.util.ArrayList<java.lang.String> serviceNames)` Get a default subset of the metadata for the specified list of services, for info purposes only.
    `java.util.ArrayList<java.lang.String>` | `getRootNodes(java.lang.String theAdminKey)` Get a copy list of the root nodes.
    `protected java.util.ArrayList<java.lang.String>` | `getSecureMethods()` Get the list of methods that can be safely called on a secure server.
    `org.licas_xml.abs.Element` | `getServerDetails(java.lang.String theAdminKey)` Retrieve a description of the server itself in XML format.
    `protected java.lang.String` | `getServerPassword()` Get the local server password, which is the ESB password as well.
    `java.util.HashMap<java.lang.String,org.licas_xml.abs.Element>` | `getServerSOA(java.lang.String theAdminKey)` Retrieve a description of the whole network structure in XML format.
    `org.licas_xml.abs.Element` | `getServiceMeta(java.lang.String theServiceID)` Get a default subset of the metadata for the service, for info purposes only.
    `ServiceMeta` | `getServiceMeta(java.lang.String theServiceID, java.lang.String theAdminKey)` Get the full service metadata description from the repository.
    `org.licas_xml.abs.Element` | `getServiceMeta(java.lang.String theServiceID, java.lang.String theAdminKey, java.util.ArrayList<java.lang.String> toInclude)` Get a default subset of the metadata for the service, plus other sections.
    `org.licas_xml.abs.Element` | `getServiceMetaPart(java.lang.String theServiceID, java.lang.String theAdminKey, java.lang.String toInclude)` Retrieve just one part of the metadata description, not the whole object.
    `protected java.util.ArrayList<java.lang.String>` | `getServiceNamesPermission()` Return all registered service names.
    `protected java.util.ArrayList<java.lang.String>` | `getServiceTypeNamesPermission(java.util.ArrayList<java.lang.String> thisServiceTypes)` Return all registered service names for a list of service types.
    `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.
    `protected ServiceWrapperDef` | `getServiceWrapper(java.lang.String serviceName, java.lang.String thePassword, java.lang.String adminKey)` Return the service wrapper for the related service name.
    `org.licas_xml.abs.Element` | `getStats(java.lang.String queryType, java.lang.String adminKey)` Get the query stats.
    `protected boolean` | `hasServerPassword()` Return true if the local server password is stored.
    `protected boolean` | `isBlockedService(java.lang.String serviceID)` Return true if the service is blocked from access.
    `boolean` | `isServer()` Return true if this module is a base server module.
    `protected boolean` | `isStoredService(java.lang.String theServiceID)` Return true if the service id is stored for a loaded service.
    `boolean` | `loadServerDetails(org.licas_xml.abs.Element serverXml, java.lang.String theAdminKey)` Add the details as specified in the xml script to the server.
    `java.util.HashMap<java.lang.String,java.util.ArrayList<java.lang.String>>` | `loadServerSOA(java.util.HashMap<java.lang.String,org.licas_xml.abs.Element> networkXML, java.lang.String theAdminKey)` Load the network described by the list of XML-based documents onto the server.
    `java.util.HashMap<java.lang.String,java.util.ArrayList<java.lang.String>>` | `loadServerSOA(java.lang.String dirPath, java.lang.String theAdminKey)` Load the network described by the list of XML-based documents onto the server.
    `boolean` | `loadServiceFromXml(org.licas_xml.abs.Element serviceXml, java.lang.String theAdminKey)` Create and load a serialized service from its XML description.
    `java.lang.Object` | `messageBus(MethodInfo methodInfo)` Execute a call on the system message bus.
    `protected boolean` | `messageToBus(MessageInfo ro, java.lang.String adminKey)` Add the message to the message bus queue for subsequent processing.
    `org.licas_xml.abs.Element` | `passwordsStateToXml(java.lang.String adminKey)` Serialize the stored passwords list and return as an XML-based description.
    `boolean` | `publish(WorkInfo workInfo)` Publish to provide information as an `Information` service.
    `boolean` | `removeAllLinksTo(java.lang.String theServiceID, java.lang.String theAdminKey)` Remove all non-dynamic links to the specified service from all other services.
    `boolean` | `removeParser(java.lang.String thePassword, java.lang.String objectClass)` Remove the parser from the parsers if it exists.
    `boolean` | `removeRootNode(java.lang.String theRootNode, java.lang.String theAdminKey)` Remove a service uuid from the list of root nodes.
    `protected boolean` | `removeServiceMeta(java.lang.String theServiceID, java.lang.String theAdminKey)` Remove the service metadata from the repository.
    `Metrics` | `serviceMetrics(java.lang.String serviceID, java.lang.String serverAdminKey)` Get the stats for the specified service.
    `protected void` | `setServer(HttpServer thisHttpBase)` Set the base http server.
    `boolean` | `subscribe(WorkInfo workInfo)` Subscribe to receive information from an `Information` service.
    `boolean` | `unblockService(java.lang.String serviceUuid, java.lang.String adminKey)` Unblock the service to re-allow access.
    `void` | `unpublish(KeywordInfo keyInfo, org.licas_xml.abs.Element serviceURI)` Un-publish to provide information.
    `void` | `unsubscribe(KeywordInfo keyInfo, org.licas_xml.abs.Element clientURI)` Un-subscribe from a service.

    - ### Methods inherited from class org.licas.AutoSecure

      `canAccess, classNameOK, getInstanceValue, getPublicMethods, isSecureMethod, setInstanceValues, setSerializeValues`

    - ### Methods inherited from class org.licas.Auto

      `autoAction, autoQueueMessage, getAutoEngine, getMessageState, interrupt, invokeBehaviour, messageReply, removeCommunicationID, run, setAutoEngine, setAutonomicManager, setBehaviourModule, setProcessScript`

    - ### Methods inherited from class org.licas.service.DataService

      `createEvaluateData, createEvaluateData, dataTypeOK, dataXmlBM, dataXmlBM, dataXmlDH, dataXmlDH, evaluate, getData, getData, getDataType, getResultObj, resetValues, setData, setData, setFixedDataValue, setGenData, setResultObj`

    - ### Methods inherited from class org.licas.Service

      `addCommunicationID, addDefaultService, addDefaultService, addDefaultService, addDefaultService, addLinkFromService, addLinkToService, addService, addService, addService, addService, addServiceAssociation, addServicePassword, addTempPassword, allowAddService, canAccess, canAccess, canAccess, canAccessMeta, canAccessNested, canAccessTemp, canRun, clearServiceLinks, clearServices, clearServices, createMetaForRepos, createMetaFull, createPermanentLinkTo, defaultAdminToRemove, dynamicLinkQuery, dynamicLinksToPermanent, dynamicLinksToXml, dynamicLinksToXml, execute, finaliseInitialisation, finaliseInitialisation, finaliseModule, finaliseThisConfig, GET, getAllLinkToService, getAllowAddService, getAutonomicManagerConfig, getCommunicationClientURI, getDescription, getFullPath, getIsRemoteCall, getLinkFromService, getLinkToService, getLocalRemoteID, getParent, getParent, getPassword, getPassword, getPassword, getPasswordHandler, getPrivateMethods, getPublicServiceClassname, getService, getService, getServiceAdmin, getServiceClasses, getServiceGrade, getServiceLinks, getServiceNames, getServiceNames, getServiceNames, getServiceNumber, getServiceOrWrapper, getServiceState, getServiceType, handshake, hasCommunicationID, hasLinkTo, hasService, hasServiceType, isCorrectPassword, isPrivateMethod, isPublicMethod, isStarted, linksToXml, permanentLinksToXml, reflectionMethods, reflectionObject, removeAllServices, removeAllServices, removeLinkFromService, removeLinkToService, removePermanentLinkTo, removeServiceAssociation, removeServiceID, removeServicePath, removeServicePath, removeTempPassword, serviceNegotiate, serviceToXml, serviceToXml, setAdminInfo, setCanAccessMeta, setCanAccessNested, setData, setDataModule, setDataModule, setDescription, setIsRemoteCall, setOtherMeta, setParent, setParent, setServerPassword, setServiceGrade, setServiceModule, setServiceState, startAllThreads, startThread, stopAllThreads, syncToAsync, syncToAsyncReply, syncToAsyncTransit, xmlToDynamicLinks, xmlToService`

    - ### Methods inherited from class org.licas.module.ServiceModule

      `getShutDown, setShutDown, setShutDown`

    - ### Methods inherited from class org.licas.module.FrameworkModule

      `canAccess, getPasswordHandler, getServicePassword, getServiceType, isAdminKey, setServiceDetails, setServiceType`

    - ### Methods inherited from class org.licas.module.LicasModule

      `getJarFile, getUUID, loadObject, setJarFile, setUUID, threadAliveState`

    - ### 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`

    - ### Methods inherited from interface org.licas.def.DataServiceDef

      `setData`

    - ### Methods inherited from interface org.licas.def.ServiceDef

      `getUUID, setJarFile, setUUID`

- - ### Field Detail

    - #### commFault

          protected static java.lang.String commFault

      Fault communication id

    - #### rootNodes

          protected java.util.ArrayList<java.lang.String> rootNodes

      The uuids of services that are root nodes in a hierarchical network.

    - #### serverServices

          protected java.util.HashMap<java.lang.String,java.util.ArrayList<java.lang.String>> serverServices

      List of global services that can be called by any other service and are controlled by the server. Key is the service type and value is a list of service UUIDs.

    - #### blockedServices

          protected java.util.ArrayList<java.lang.String> blockedServices

      A list of services that cannot be accessed because permission is blocked.

    - #### metrics

          protected Metrics metrics

      Server metrics.

    - #### messageMediator

          protected MessageMediator messageMediator

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

    - #### utilsManager

          protected UtilsManagerDef utilsManager

      Server utilities manager.

    - #### serverMetadata

          protected ServerMetadata serverMetadata

      Metadata repository for registered services.

    - #### serverMetaSearch

          protected ServerMetaSearch serverMetaSearch

      Metadata search facility over the registered services, based on XML pattern matching.

    - #### licasDocSearch

          protected LicasDocSearch licasDocSearch

      Text document search facility over the allowed folders.

    - #### autoMetaSearch

          protected AutoMetaSearch autoMetaSearch

      Stats search facility over the loaded services. This is based on accumulated stats produced by the autonomic managers.

    - #### messagePackets

          protected PacketMessages messagePackets

      Stores communication ids with related message packet info for receiving messages in packets. Keys are the communication ids of type String, while values are the PacketInfo objects.

    - #### httpBase

          protected HttpServer httpBase

      Base http server.

  - ### Constructor Detail

    - #### ESB

          public ESB(java.lang.String password,
                     java.lang.String thisAdminKey)
              throws java.lang.Exception

      Creates a new instance of ESB.
      Parameters:
        `password` - the password to access the server with.
        `thisAdminKey` - a unique key to protect loading/removal.
      Throws:
        `java.lang.Exception` - any error.

    - #### ESB

          public ESB(java.lang.String thisPassword,
                     java.lang.String thisAdminKey,
                     org.licas_xml.abs.Element adminXml)
              throws java.lang.Exception

      Creates a new instance of ESB.
      Parameters:
        `thisPassword` - the component password.
        `thisAdminKey` - the unique service key.
        `adminXml` - the admin info or description of this service.
      Throws:
        `java.lang.Exception` - any error.

    - #### ESB

          public ESB(java.lang.String thisPassword,
                     java.lang.String thisAdminKey,
                     org.licas_xml.abs.Element adminXml,
                     java.lang.String resManClass)
              throws java.lang.Exception

      Creates a new instance of ESB.
      Parameters:
        `thisPassword` - the component password.
        `thisAdminKey` - the unique service key.
        `adminXml` - the admin info or description of this service.
        `resManClass` - the class type for the resource manager. No constructor parameters and jar file must be available.
      Throws:
        `java.lang.Exception` - any error.

  - ### Method Detail

    - #### isServer

          public boolean isServer()

      Return true if this module is a base server module.
      Returns:
        true in this case.

    - #### behaviourAction

          protected MessageInfo behaviourAction(MessageInfo messageInfo)
                                         throws java.lang.Exception

      Periodically run some server utility functions to monitor the system state.
      Specified by:
        `behaviourAction` in class `Auto`
      Parameters:
        `messageInfo` - the message to evaluate.
      Returns:
        null in this case, as this is only a periodic monitoring check.
      Throws:
        `java.lang.Exception` - any error.

    - #### setServer

          protected void setServer(HttpServer thisHttpBase)
                            throws java.lang.Exception

      Set the base http server.
      Parameters:
        `thisHttpBase` - the http server.
      Throws:
        `java.lang.Exception` - any error.

    - #### messageToBus

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

      Add the message to the message bus queue for subsequent processing.
      Parameters:
        `ro` - the request object to add.
        `adminKey` - the server admin key.
      Returns:
        true if 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.

    - #### addMessageMetrics

          protected void addMessageMetrics(MethodInfo messageInfo,
                                           java.lang.String thePassword)
                                    throws java.lang.Exception

      Add metric or stat values for the message object.
      Overrides:
        `addMessageMetrics` in class `Service`
      Parameters:
        `messageInfo` - the message info with the message object.
        `thePassword` - the service password.
      Throws:
        `java.lang.Exception` - any error.

    - #### autoManFault

          protected void autoManFault(Link_NM message)
                               throws java.lang.Exception

      Add the fault tree to the autonomic manager queue for processing. Remove the existing message if it exists, so there is no repeat.
      Parameters:
        `message` - the whole fault tree.
      Throws:
        `java.lang.Exception` - any error.

    - #### allServiceMetrics

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

      Get the stats for all services.
      Parameters:
        `adminKey` - the admin key of this server.
      Returns:
        list of stats objects, one for each service, key is service id.

    - #### serviceMetrics

          public Metrics serviceMetrics(java.lang.String serviceID,
                                        java.lang.String serverAdminKey)
                                 throws PasswordException,
                                        ServiceException,
                                        java.lang.Exception

      Get the stats for the specified service.
      Parameters:
        `serviceID` - the id of the service to retrieve the stats for.
        `serverAdminKey` - the admin key of this server.
      Returns:
        the stats object.
      Throws:
        `PasswordException` - incorrect admin key.
        `ServiceException` - service processing error.
        `java.lang.Exception` - any other error.

    - #### isBlockedService

          protected boolean isBlockedService(java.lang.String serviceID)

      Return true if the service is blocked from access.
      Parameters:
        `serviceID` - the uuid of the service to check.
      Returns:
        true if blocked from access, false otherwise.

    - #### blockService

          public boolean blockService(java.lang.String serviceUuid,
                                      java.lang.String adminKey)
                               throws PasswordException

      Block the service from being accessed. This only applies to a service running directly on the server.
      Parameters:
        `serviceUuid` - the uuid of the service to block.
        `adminKey` - the unique admin key for the service.
      Returns:
        true if blocked, false otherwise.
      Throws:
        `PasswordException` - incorrect admin key.

    - #### unblockService

          public boolean unblockService(java.lang.String serviceUuid,
                                        java.lang.String adminKey)
                                 throws PasswordException

      Unblock the service to re-allow access. This only applies to a service running directly on the server.
      Parameters:
        `serviceUuid` - the uuid of the service to unblock.
        `adminKey` - the unique admin key for the service.
      Returns:
        true if unblocked, false otherwise.
      Throws:
        `PasswordException` - incorrect admin key.

    - #### createServiceWrapper

          protected ServiceWrapperDef createServiceWrapper(java.lang.Object serviceObj,
                                                           java.lang.String serviceName,
                                                           java.lang.String serviceType,
                                                           java.util.ArrayList<java.lang.String> jarFiles,
                                                           org.licas_xml.abs.Element adminXml)
                                                    throws java.lang.Exception

      Create a service wrapper for storing the service object. This version returns an autonomic manager if the service object is derived from `Auto`, or a service wrapper if it is not. Only base services added to the server can be wrapped with an autonomic manager and then only if they also implement the auto logic. There is a default `AutonomicManagerDefault` class with empty monitoring modules, or you can declare a different autonomic manager in your admin document and load those classes instead.
      Overrides:
        `createServiceWrapper` in class `Service`
      Parameters:
        `serviceObj` - the service object that is wrapped and managed.
        `serviceName` - the name of the service.
        `serviceType` - the type of the service.
        `jarFiles` - the jar files for a remote loading. Values are jar paths of type String.
        `adminXml` - an admin document describing the service wrapper. This is probably empty, but it can declare different manager classes, config or policy scripts, for example.
      Returns:
        the correct service wrapper type.
      Throws:
        `java.lang.Exception` - any error.

    - #### getServiceWrapper

          protected 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, but 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.

    - #### clearNetwork

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

      Remove all components of the network currently running on this server.
      Parameters:
        `adminKey` - the service key for this server.
      Throws:
        `java.lang.Exception` - any error.

    - #### clearNetwork

          public void clearNetwork(java.util.ArrayList<java.lang.String> serviceTypes,
                                   boolean keepRemove,
                                   java.lang.String adminKey)
                            throws java.lang.Exception

      Remove all components of the network currently running on this server, but only of the specified service type. This can also specify to only keep services of the specified type.
      Parameters:
        `serviceTypes` - list of service types to keep or remove.
        `keepRemove` - if true types to keep, if false types to remove.
        `adminKey` - the service key for this server.
      Throws:
        `java.lang.Exception` - any error.

    - #### isStoredService

          protected boolean isStoredService(java.lang.String theServiceID)

      Return true if the service id is stored for a loaded service.
      Parameters:
        `theServiceID` - the unique service id.
      Returns:
        true if registered for a loaded service of false otherwise.

    - #### 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 known 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 version 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, see `executeServiceType`.
        `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 owned locally. This method calls `executeServerService` to invoke the parameter `methodInfo` spec. This version 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. For example, the server search type is specified as `MetaConst`.`SEARCHMETADATA`, `SEARCHAUTODATA`, or `SEARCHWEBFOLDER`, `SEARCHALLWEB`. A metadata search queries all of the service metadata, and a web folder search queries the server's root web directory for matching text documents. Only services owned by the server are recognised by this method call. To execute on a service type in general, you replace the service name by it's type in the service URI and make a standard call through the system. Then any services subscribed to reply can process the message.
        `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 search 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.

    - #### subscribe

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

      Subscribe to receive information from an `Information` 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 from 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 provide information as an `Information` service.
      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 provide information.
      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.

    - #### getAdminKey

          public java.lang.String getAdminKey(java.lang.String serviceID,
                                              java.lang.String thisAdminKey)
                                       throws PasswordException

      Get the service key for the specified service. This is a child service of the server, or any service running on this server.
      Parameters:
        `serviceID` - the id of the service to retrieve the admin key for.
        `thisAdminKey` - the admin key of this server.
      Returns:
        the service key for the requested service.
      Throws:
        `PasswordException` - incorrect admin key.

    - #### 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 or false if it already exists.

    - #### getAllServiceMeta

          public org.licas_xml.abs.Element getAllServiceMeta()
                                                      throws java.lang.Exception

      Get a default subset of the metadata for the full service list, for info purposes only.
      Returns:
        the metadata in XML format if it exists or null if it does not.
      Throws:
        `java.lang.Exception` - any error.

    - #### getAllServiceMeta

          public org.licas_xml.abs.Element getAllServiceMeta(java.util.ArrayList<java.lang.String> serviceNames)
                                                      throws java.lang.Exception

      Get a default subset of the metadata for the specified list of services, for info purposes only.
      Parameters:
        `serviceNames` - list of services to retrieve.
      Returns:
        the metadata in XML format if it exists or null if it does not.
      Throws:
        `java.lang.Exception` - any error.

    - #### getServiceMeta

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

      Get a default subset of the metadata for the service, for info purposes only.
      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 org.licas_xml.abs.Element getServiceMeta(java.lang.String theServiceID,
                                                          java.lang.String theAdminKey,
                                                          java.util.ArrayList<java.lang.String> toInclude)
                                                   throws java.lang.Exception

      Get a default subset of the metadata for the service, plus other sections. This is instead of returning the full metadata description.
      Parameters:
        `theServiceID` - the unique id of the service to retrieve metadata for.
        `theAdminKey` - for administrator-level access to the service. The admin key for the server is also allowed here.
        `toInclude` - list of additional meta parts to return. See the `ServiceMeta` class for a description of the field names.
      Returns:
        the metadata in XML format if it exists, or null if it does not.
      Throws:
        `java.lang.Exception` - any error.

    - #### getServiceMetaPart

          public org.licas_xml.abs.Element getServiceMetaPart(java.lang.String theServiceID,
                                                              java.lang.String theAdminKey,
                                                              java.lang.String toInclude)
                                                       throws java.lang.Exception

      Retrieve just one part of the metadata description, not the whole object.
      Parameters:
        `theServiceID` - the unique id of the service to retrieve metadata for.
        `theAdminKey` - for administrator-level access to the service. The admin key for the server is also allowed here.
        `toInclude` - meta part to return. See the `ServiceMeta` class for a description of the field names.
      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 full service metadata description from the repository.
      Parameters:
        `theServiceID` - the unique id of the service meta to retrieve.
        `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

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

      Remove the service metadata from the 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.

    - #### hasServerPassword

          protected boolean hasServerPassword()

      Return true if the local server password is stored. Must be true here.
      Overrides:
        `hasServerPassword` in class `Service`
      Returns:
        true as this is the server.

    - #### getServerPassword

          protected java.lang.String getServerPassword()
                                                throws java.lang.Exception

      Get the local server password, which is the ESB password as well.
      Overrides:
        `getServerPassword` in class `Service`
      Returns:
        the local server password.
      Throws:
        `java.lang.Exception` - any error.

    - #### removeAllLinksTo

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

      Remove all non-dynamic links to the specified service from all other services.
      Overrides:
        `removeAllLinksTo` in class `Service`
      Parameters:
        `theServiceID` - the unique id of the service to remove links to.
        `theAdminKey` - the unique admin key for the service to remove links to.
      Returns:
        true if the admin key allows access, false otherwise.
      Throws:
        `java.lang.Exception` - any error.

    - #### getServiceTypes

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

      Get a list of all of the service types in the network.
      Overrides:
        `getServiceTypes` in class `Service`
      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.

    - #### getServiceNamesPermission

          protected java.util.ArrayList<java.lang.String> getServiceNamesPermission()

      Return all registered service names. This method performs a second filtering stage, to return only the services that allow point-to-point access, or have not specified, for a service ID message.
      Returns:
        the service names for the service types list.

    - #### getServiceTypeNamesPermission

          protected java.util.ArrayList<java.lang.String> getServiceTypeNamesPermission(java.util.ArrayList<java.lang.String> thisServiceTypes)
                                                                                 throws LicasException

      Return all registered service names for a list of service types. This method performs a second filtering stage, to return only the services that allow subscribe access, for a service type message.
      Parameters:
        `thisServiceTypes` - the service types list.
      Returns:
        the service names for the service types list.
      Throws:
        `LicasException` - if the service types input is `null`.

    - #### calculateRootNodes

          public void calculateRootNodes(java.lang.String theAdminKey)

      Calculate what nodes are root nodes, that is, are not children of any other nodes.
      Parameters:
        `theAdminKey` - the admin key for this server.

    - #### addRootNode

          protected boolean addRootNode(java.lang.String theRootNode,
                                        java.lang.String theAdminKey)

      Add a service uuid to the list of root nodes. Note that the service itself must already be added to the server and this method is only to declare it as a root node in some hierarchical structure.
      Parameters:
        `theRootNode` - the uuid of the root service to add.
        `theAdminKey` - the server admin key.
      Returns:
        true if the node is added or false otherwise.

    - #### removeRootNode

          public boolean removeRootNode(java.lang.String theRootNode,
                                        java.lang.String theAdminKey)
                                 throws PasswordException

      Remove a service uuid from the list of root nodes. Note that the service itself is not removed. This method is only to remove a root node in some hierarchical organisation structure.
      Parameters:
        `theRootNode` - the root node service uuid.
        `theAdminKey` - the unique key for the service to remove.
      Returns:
        true if the node is removed or false otherwise.
      Throws:
        `PasswordException` - incorrect admin key.

    - #### getRootNodes

          public java.util.ArrayList<java.lang.String> getRootNodes(java.lang.String theAdminKey)

      Get a copy list of the root nodes.
      Parameters:
        `theAdminKey` - the unique key for the service to add.
      Returns:
        true if the node is added or false otherwise.

    - #### addLoader

          public boolean addLoader(java.lang.String thePassword,
                                   java.util.ArrayList<java.lang.String> uris)
                            throws java.lang.Exception

      Add a new class loader from remote uris.
      Parameters:
        `thePassword` - the password to access this server.
        `uris` - a list of remote uris to load the classes from.
      Returns:
        true if loader loaded.
      Throws:
        `java.lang.Exception` - any error.

    - #### addObject

          public boolean addObject(java.lang.String thePassword,
                                   java.lang.String className,
                                   java.util.ArrayList<java.lang.String> uris)
                            throws java.lang.Exception

      Create a new instance of an object, with no initialisation parameters. This loads the related java classes into the system.
      Parameters:
        `thePassword` - the password to access this server.
        `className` - the name of the object class to load.
        `uris` - a list of remote uris to load the classes from.
      Returns:
        true if loader loaded.
      Throws:
        `java.lang.Exception` - any error.

    - #### addParser

          public boolean addParser(java.lang.String thePassword,
                                   java.lang.String objectClass,
                                   java.lang.String parserClass,
                                   java.util.ArrayList<java.lang.String> uris,
                                   java.util.ArrayList<java.lang.Object> params)
                            throws java.lang.Exception

      Add a new parser to the parsers.
      Parameters:
        `thePassword` - the password to access this server.
        `objectClass` - the class name of the object to parse.
        `parserClass` - the class name of the parser.
        `uris` - a list of remote uris to load the classes from.
        `params` - any initialisation parameters.
      Returns:
        true if parser added.
      Throws:
        `java.lang.Exception` - any error.

    - #### removeParser

          public boolean removeParser(java.lang.String thePassword,
                                      java.lang.String objectClass)

      Remove the parser from the parsers if it exists.
      Parameters:
        `thePassword` - the password to access this server.
        `objectClass` - the class name of the object the parser parses.
      Returns:
        true if parser removed.

    - #### getServerSOA

          public java.util.HashMap<java.lang.String,org.licas_xml.abs.Element> getServerSOA(java.lang.String theAdminKey)
                                                                                     throws java.lang.Exception

      Retrieve a description of the whole network structure in XML format.
      Parameters:
        `theAdminKey` - the unique key to allow admin operations on this server.
      Returns:
        a list of XML-based files that describe the network.
      Throws:
        `java.lang.Exception` - any error.

    - #### loadServerSOA

          public java.util.HashMap<java.lang.String,java.util.ArrayList<java.lang.String>> loadServerSOA(java.lang.String dirPath,
                                                                                                         java.lang.String theAdminKey)
                                                                                                  throws java.lang.Exception

      Load the network described by the list of XML-based documents onto the server.
      Parameters:
        `dirPath` - path to the local directory to read the files from. The network is identified as having a root `Const.NETWORK` element, while the links document has a root `Const.LINKS` element.
        `theAdminKey` - the unique key to allow admin operations on this server.
      Returns:
        a list of the service ids with related passwords. Keys are the service ids of type string and values are password/service related values of type vector of Objects.
      Throws:
        `java.lang.Exception` - any error.

    - #### loadServerSOA

          public java.util.HashMap<java.lang.String,java.util.ArrayList<java.lang.String>> loadServerSOA(java.util.HashMap<java.lang.String,org.licas_xml.abs.Element> networkXML,
                                                                                                         java.lang.String theAdminKey)
                                                                                                  throws java.lang.Exception

      Load the network described by the list of XML-based documents onto the server.
      Parameters:
        `networkXML` - an XML description of the network. The network file is identified as having the key value `Const.NETWORK` element, while the links document has a root `Const.LINKS` element.
        `theAdminKey` - the unique key to allow admin operations on this server.
      Returns:
        a list of the service ids with related passwords. Keys are the service ids of type string and values are password/service related values of type vector of Objects.
      Throws:
        `java.lang.Exception` - any error.

    - #### loadServiceFromXml

          public boolean loadServiceFromXml(org.licas_xml.abs.Element serviceXml,
                                            java.lang.String theAdminKey)
                                     throws java.lang.Exception

      Create and load a serialized service from its XML description. Note that if this loads utility services through the script, these will not get registered with the server as they are created before the main service is added.
      Parameters:
        `serviceXml` - the full serialized description of the service, typically created by calling `Service`.`serviceToXml` on the service itself.
        `theAdminKey` - the unique key to allow admin operations on this server.
      Returns:
        true if the services was created and loaded, false otherwise.
      Throws:
        `java.lang.Exception` - any error.

    - #### passwordsStateToXml

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

      Serialize the stored passwords list and return as an XML-based description.
      Overrides:
        `passwordsStateToXml` in class `Service`
      Parameters:
        `adminKey` - the service admin key.
      Returns:
        an XML representation of all passwords, or null if the admin key is incorrect.
      Throws:
        `java.lang.Exception` - any error.

    - #### getServerDetails

          public org.licas_xml.abs.Element getServerDetails(java.lang.String theAdminKey)
                                                     throws java.lang.Exception

      Retrieve a description of the server itself in XML format. This is probably only passwords and links to other servers, so that it can be re-constructed.
      Parameters:
        `theAdminKey` - the unique key to allow admin operations on this server.
      Returns:
        a list of XML-based files that describe the network.
      Throws:
        `java.lang.Exception` - any error.

    - #### loadServerDetails

          public boolean loadServerDetails(org.licas_xml.abs.Element serverXml,
                                           java.lang.String theAdminKey)
                                    throws java.lang.Exception

      Add the details as specified in the xml script to the server. This is probably only links to other servers at the moment.
      Parameters:
        `serverXml` - the server description to add.
        `theAdminKey` - the unique key to allow admin operations on this server.
      Returns:
        true if added OK, or false if there was an error.
      Throws:
        `java.lang.Exception` - any error.

    - #### addPacketCommunicationID

          public boolean addPacketCommunicationID(java.lang.String communicationID,
                                                  int packetSize)
                                           throws java.lang.Exception

      Add the communication id and packet info to the packetInfo structure.
      Parameters:
        `communicationID` - the id to identify the communication thread.
        `packetSize` - the maximum size of the packet to send.
      Returns:
        true if the id and the file name are new and the file can be created.
      Throws:
        `java.lang.Exception` - any error.

    - #### addMessagePacket

          public boolean addMessagePacket(java.lang.String communicationID,
                                          java.lang.String packetObject)
                                   throws java.lang.Exception

      Add the message packet to the appropriate file as indicated by the communication id.
      Parameters:
        `communicationID` - the id to identify the communication thread.
        `packetObject` - the next part of the message to save.
      Returns:
        true if the packet is successfully added to the file.
      Throws:
        `java.lang.Exception` - any error.

    - #### endOfMessage

          public java.lang.Object endOfMessage(java.lang.String communicationID)
                                        throws java.lang.Exception

      Call this to indicate that the whole message has been sent and should now be executed.
      Parameters:
        `communicationID` - the id to identify the communication thread.
      Returns:
        the result of executing the method represented by the message.
      Throws:
        `java.lang.Exception` - any error.

    - #### getStats

          public org.licas_xml.abs.Element getStats(java.lang.String queryType,
                                                    java.lang.String adminKey)
                                             throws java.lang.Exception

      Get the query stats.
      Parameters:
        `queryType` - the query engine service type on the server.
        `adminKey` - the admin key for the server.
      Returns:
        the reply as an Element.
      Throws:
        `java.lang.Exception` - any error.

    - #### getSecureMethods

          protected java.util.ArrayList<java.lang.String> getSecureMethods()

      Get the list of methods that can be safely called on a secure server.
      Overrides:
        `getSecureMethods` in class `AutoSecure`
      Returns:
        the list of safe method names, but might still require passwords.

    - #### close

          public void close()

      Clean-up before shutting down the service.
      Specified by:
        `close` in interface `java.lang.AutoCloseable`
      Overrides:
        `close` in class `Service`