org.licas

## Class ServiceAdmin

- java.lang.Object
- - org.licas.ServiceAdmin

- Direct Known Subclasses:
    AutoMetaSearch, LicasDocSearch, ServerMetaSearch

      public class ServiceAdmin
      extends java.lang.Object

  This class stores admin details for a service, including the metadata description in an `AdminInfo` object. Other information includes details of the child services, keywords list and service contract. Any related metadata in the server's `ServiceRepository` is not automatically updated, but would require an update method call from the service itself. This object however creates its metadata dynamically upon request and so it should be up to date, but not automatically synced with the server's.
  Author:
    Kieran Greer

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected AdminInfo` | `adminInfo` The service admin information
    `protected ContractManager` | `contractManager` Stores the contracts for each service level
    `protected KeywordHandler` | `keywordHandler` For processing any service-general keyword lists
    `protected Service` | `service` The parent service
    `protected java.lang.String` | `serviceAdminKey` The admin key of the parent service
    `protected java.util.HashMap<java.lang.String,ServiceInfo>` | `services` A list of services that are child services of this one.
    `protected java.util.HashMap<java.lang.String,java.util.ArrayList<java.lang.String>>` | `serviceTypes` A list of service types that are stored under this service.
    `protected WorkInfo` | `workInfo` Type of work protocol for the service - point-to-point, subscribe, or both.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ServiceAdmin(Service theService, java.lang.String theAdminKey, org.licas_xml.abs.Element adminXml)` Create a new instance of ServiceAdmin.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `clearInstanceValues()` After parsing the instance values, call this to set it to `null`.
    `protected ServiceMeta` | `createFullServiceMeta(java.util.ArrayList<java.lang.String> jarFile, java.lang.String adminKey)` Create a full metadata description of this service.
    `protected ServiceMeta` | `createMetaForRepos()` Create a metadata description of the parent service for the server repository.
    `protected ServiceMeta` | `createServiceMeta(java.util.ArrayList<java.lang.String> jarFile, java.lang.String adminKey)` Create a full metadata description of this service.
    `AdminInfo` | `getAdminInfo()` Get the admin info object itself.
    `ContractManager` | `getContractManager()` Get the contract manager.
    `org.licas_xml.abs.Element` | `getInstanceValues()` Get the script part describing actual variable instance values, if one was included.
    `KeywordHandler` | `getKeywordHandler()` Get the keyword handler that processes keywords.
    `protected ServiceWrapperDef` | `getService(java.lang.String serviceName, java.lang.String thePassword)` Return the service or module for the related service name.
    `java.lang.Object` | `getService(java.lang.String serviceName, java.lang.String thePassword, java.lang.String adminKey)` Return the service or module for the related service name.
    `java.util.HashMap<java.lang.String,java.lang.String>` | `getServiceClasses()` Get the class types for all services that are stored.
    `java.util.ArrayList<java.lang.String>` | `getServiceNames()` Get all child service or module names.
    `java.util.ArrayList<java.lang.String>` | `getServiceNames(java.util.ArrayList<java.lang.String> thisServiceTypes, boolean reciprocal)` Return all child service or module names for a list of service types.
    `java.util.ArrayList<java.lang.String>` | `getServiceNames(java.lang.String serviceType)` Return all child service or module names for the specified service type.
    `FrameworkModule` | `getServiceOrWrapper(java.lang.String serviceName, java.lang.String thePassword, java.lang.String adminKey)` Return the service, module or its wrapper for the related service name.
    `java.lang.String` | `getServiceType(java.lang.String serviceName)` Get the service type for the named service if it exists.
    `java.util.ArrayList<java.lang.String>` | `getServiceTypes()` Return all service types for all stored services.
    `protected void` | `removeAllServices(java.util.ArrayList<?> serviceIDs, java.lang.String adminKey)` Remove all child services and modules from this service and terminate their threads.
    `protected void` | `removeAllServices(java.lang.String adminKey)` Remove all child services and modules from this service and terminate their threads.
    `protected boolean` | `removeService(org.licas_xml.abs.Element servicePath, java.lang.String adminKey, boolean stopThread)` Remove the service or module with the indicated path from the list.
    `protected boolean` | `removeService(java.lang.String serviceUuid, java.lang.String adminKey, boolean stopThread)` Remove the service or module with the indicated ID from the list.
    `protected void` | `setAdminInfo(org.licas_xml.abs.Element adminXml)` Set a full admin info description for the service.
    `void` | `setWorkInfo(WorkInfo theWorkInfo)` Set the work info description for the message bus.

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

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

- - ### Field Detail

    - #### serviceAdminKey

          protected java.lang.String serviceAdminKey

      The admin key of the parent service

    - #### service

          protected Service service

      The parent service

    - #### services

          protected java.util.HashMap<java.lang.String,ServiceInfo> services

      A list of services that are child services of this one. Keys are service names of type String and values are the `ServiceInfo` objects.

    - #### serviceTypes

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

      A list of service types that are stored under this service. Keys are the service types of type String and values are Lists of names of services of that type.

    - #### adminInfo

          protected AdminInfo adminInfo

      The service admin information

    - #### keywordHandler

          protected KeywordHandler keywordHandler

      For processing any service-general keyword lists

    - #### contractManager

          protected ContractManager contractManager

      Stores the contracts for each service level

    - #### workInfo

          protected WorkInfo workInfo

      Type of work protocol for the service - point-to-point, subscribe, or both. This can include other keyword lists specific to the protocol conditions and/or method. This can be `null`, when it is assumed that the service has no additional conditions and is accessed point-to-point, or by calling its ID only.

  - ### Constructor Detail

    - #### ServiceAdmin

          public ServiceAdmin(Service theService,
                              java.lang.String theAdminKey,
                              org.licas_xml.abs.Element adminXml)
                       throws java.lang.Exception

      Create a new instance of ServiceAdmin.
      Parameters:
        `theService` - the parent service.
        `theAdminKey` - the parent service admin key.
        `adminXml` - the admin xml document. Can be null.
      Throws:
        `java.lang.Exception` - any error.

  - ### Method Detail

    - #### createServiceMeta

          protected ServiceMeta createServiceMeta(java.util.ArrayList<java.lang.String> jarFile,
                                                  java.lang.String adminKey)
                                           throws java.lang.Exception

      Create a full metadata description of this service. If this is a wrapper for a legacy object, then ask the server for any stored metadata description and use that if available. It may have been created or initialised from one. If it is derived from `Service` then create a new one so that the settings are the most recent. The description describes only this service and no nested services.
      Parameters:
        `jarFile` - list of remote jar files if loaded remotely.
        `adminKey` - the unique service key for admin purposes.
      Returns:
        a metadata description of this service.
      Throws:
        `java.lang.Exception` - any error.

    - #### createFullServiceMeta

          protected ServiceMeta createFullServiceMeta(java.util.ArrayList<java.lang.String> jarFile,
                                                      java.lang.String adminKey)
                                               throws java.lang.Exception

      Create a full metadata description of this service. The description describes only this service and no nested services.
      Parameters:
        `jarFile` - list of remote jar files if loaded remotely.
        `adminKey` - the unique service key for admin purposes.
      Returns:
        a metadata description of this service.
      Throws:
        `java.lang.Exception` - any error.

    - #### createMetaForRepos

          protected ServiceMeta createMetaForRepos()
                                            throws java.lang.Exception

      Create a metadata description of the parent service for the server repository. The description describes only this service and no nested services.
      Returns:
        a metadata description of this service.
      Throws:
        `java.lang.Exception` - any error.

    - #### getService

          protected ServiceWrapperDef getService(java.lang.String serviceName,
                                                 java.lang.String thePassword)
                                          throws ServiceException,
                                                 java.lang.Exception

      Return the service or module for the related service name. This method returns a wrapper for the service with limited functionality. It should be used only to allow access to nested services on the called service or for invoking methods.
      Parameters:
        `serviceName` - the name of the service you want to retrieve.
        `thePassword` - the password for the service you want to retrieve.
      Returns:
        a wrapper containing the service that is retrieved.
      Throws:
        `ServiceException` - for service specific error.
        `java.lang.Exception` - any other error.

    - #### getServiceOrWrapper

          public FrameworkModule getServiceOrWrapper(java.lang.String serviceName,
                                                     java.lang.String thePassword,
                                                     java.lang.String adminKey)
                                              throws ServiceException,
                                                     java.lang.Exception

      Return the service, module or its wrapper for the related service name. This method requires the admin key as well, so that it can try to return a direct reference to the service object. If the service object is not derived from `Service`, then the wrapper is returned. If it is derived from Service, then a direct reference is returned.
      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.

    - #### 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 or module for the related service name. This method requires the service admin key as well, but then returns a direct reference to the service object, 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.

    - #### removeAllServices

          protected void removeAllServices(java.lang.String adminKey)
                                    throws PasswordException,
                                           java.lang.Exception

      Remove all child services and modules from this service and terminate their threads.
      Parameters:
        `adminKey` - the unique key to protect this service.
      Throws:
        `PasswordException` - incorrect admin key.
        `java.lang.Exception` - any other error.

    - #### removeAllServices

          protected void removeAllServices(java.util.ArrayList<?> serviceIDs,
                                           java.lang.String adminKey)
                                    throws PasswordException,
                                           java.lang.Exception

      Remove all child services and modules from this service and terminate their threads.
      Parameters:
        `serviceIDs` - id list for service passwords to remove. Should be String key or Element path.
        `adminKey` - the unique key to protect this service.
      Throws:
        `PasswordException` - incorrect admin key.
        `java.lang.Exception` - any other error.

    - #### removeService

          protected boolean removeService(java.lang.String serviceUuid,
                                          java.lang.String adminKey,
                                          boolean stopThread)
                                   throws java.lang.Exception

      Remove the service or module with the indicated ID from the list.
      Parameters:
        `serviceUuid` - the uuid of the child service to remove.
        `adminKey` - the unique key to protect the service.
        `stopThread` - true if stop the thread running.
      Returns:
        true if the service has been removed.
      Throws:
        `java.lang.Exception` - any error.

    - #### removeService

          protected boolean removeService(org.licas_xml.abs.Element servicePath,
                                          java.lang.String adminKey,
                                          boolean stopThread)
                                   throws java.lang.Exception

      Remove the service or module with the indicated path from the list.
      Parameters:
        `servicePath` - the path to the service.
        `adminKey` - the unique key to protect the service.
        `stopThread` - true if stop the thread running.
      Returns:
        true if the service has been removed.
      Throws:
        `java.lang.Exception` - any error.

    - #### setWorkInfo

          public void setWorkInfo(WorkInfo theWorkInfo)

      Set the work info description for the message bus.
      Parameters:
        `theWorkInfo` - the work info description.

    - #### getServiceNames

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

      Get all child service or module names.
      Returns:
        all service uuids, of type String.

    - #### getServiceNames

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

      Return all child service or module names for the specified service type.
      Parameters:
        `serviceType` - the service type.
      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 or module names for a list of service types.
      Parameters:
        `thisServiceTypes` - the service types list.
        `reciprocal` - if 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`.

    - #### getServiceTypes

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

      Return all service types for all stored services.
      Returns:
        all service types.

    - #### getServiceType

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

      Get the service type for the named service if it exists.
      Parameters:
        `serviceName` - the name of the service to look for.
      Returns:
        the service type if it exists, or null otherwise.

    - #### getServiceClasses

          public java.util.HashMap<java.lang.String,java.lang.String> getServiceClasses()

      Get the class types for all services that are stored.
      Returns:
        the service handles with the class types for the services of this component.

    - #### setAdminInfo

          protected void setAdminInfo(org.licas_xml.abs.Element adminXml)
                               throws java.lang.Exception

      Set a full admin info description for the service.
      Parameters:
        `adminXml` - the full admin description.
      Throws:
        `java.lang.Exception` - any error.

    - #### getAdminInfo

          public AdminInfo getAdminInfo()

      Get the admin info object itself.
      Returns:
        the value of adminInfo.

    - #### getContractManager

          public ContractManager getContractManager()

      Get the contract manager.
      Returns:
        the value of contractManager.

    - #### getKeywordHandler

          public KeywordHandler getKeywordHandler()

      Get the keyword handler that processes keywords.
      Returns:
        the value of keywordHandler.

    - #### clearInstanceValues

          public void clearInstanceValues()

      After parsing the instance values, call this to set it to `null`.

    - #### getInstanceValues

          public org.licas_xml.abs.Element getInstanceValues()

      Get the script part describing actual variable instance values, if one was included.
      Returns:
        the value of instanceValues.