org.licas

## Class ServiceWrapperLegacy

- java.lang.Object
- - java.lang.Thread
  - - org.licas.module.LicasModule
    - - org.licas.module.FrameworkModule
      - - org.licas.module.ServiceModule
        - - org.licas.Service
          - - org.licas.ServiceWrapperLegacy

- All Implemented Interfaces:
    java.lang.AutoCloseable, java.lang.Runnable, ServiceDef, ServiceWrapperDef

      public class ServiceWrapperLegacy
      extends Service
      implements ServiceWrapperDef

  This class is a wrapper to store any object that may be invoked as a service or from a service. Any service that is loaded onto the network is wrapped first. It can then only be accessed through using the correct password. There are two service wrappers - this stores a `legacy` object and a `ServiceWrapper` stores a licas `Service` object. The autonomic manager is also an extension of `ServiceWrapper` class. This means that any object can actually be loaded and stored as a service. The wrapper class extends either a `FrameworkModule` or a full `Service`, depending on what additional functionality is required. This would mean that any object can be used as part of the licas system and the object methods can be found and invoked.
  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 java.lang.Object` | `legacyObj` The legacy object
    `protected Metrics` | `metrics` Measurements of general message/transaction numbers
    `protected boolean` | `setStructures` True if structures for enclosed service object already set

    - ### 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
    `ServiceWrapperLegacy(java.lang.Object theObj)` Creates a new instance of ServiceWrapperLegacy.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `addCommunicationID(java.lang.String communicationID, java.lang.Object clientUri)` Store the communicationID with the related client uri.
    `void` | `addMetrics(MethodInfo messageObj, java.lang.String theAdminKey)` Add some metrics values relating to the current message.
    `protected java.lang.String` | `addTempPassword(boolean addPassword)` Add a new temporary password to the temp passwords list.
    `boolean` | `canAccess(java.lang.String thePassword)` Return true if the wrapped object can be accessed by the password.
    `boolean` | `canAccess(java.lang.String thePassword, java.lang.reflect.Method theMethod)` Return true if the method on the wrapped object can be accessed by the password.
    `boolean` | `canAccess(java.lang.String thePassword, java.lang.String methodName)` Return true if the method on the wrapped object can be accessed by the password.
    `void` | `copyFromService()` Reset the wrapper settings based on the wrapped object if a service.
    `void` | `copyToService(java.lang.Object parent)` Copy and set certain settings between the service object and the wrapper.
    `ServiceMeta` | `createMetaForRepos(java.lang.String theAdminKey)` Create a metadata description of this service for the server repository.
    `java.lang.Object` | `execute(MethodInfo methodInfo, boolean addTempPassword)` Execute the specified method and return the result.
    `Metrics` | `getMetrics()` Get the default message/transaction metrics.
    `java.lang.Class` | `getObjClass()` Get the class type of the stored object.
    `java.lang.Object` | `getObjService(java.lang.String adminKey)` Get the stored object service.
    `java.lang.String` | `getPassword(java.lang.String theAdminKey)` Get the password for this service.
    `java.lang.String` | `getPassword(java.lang.String clientID, Contract clientContract)` Get this service's password, depending on the calling component's contract description.
    `java.lang.String` | `getPassword(java.lang.String serviceUuid, java.lang.String theAdminKey)` Get the password for the specified service.
    `ServiceWrapperDef` | `getService(java.lang.String serviceName, java.lang.String thePassword)` Return the service for the related service name.
    `java.lang.Object` | `getService(java.lang.String serviceName, java.lang.String thePassword, java.lang.String adminKey)` Return the service for the related service name.
    `WorkInfo` | `getWorkInfo()` Get the work protocol details for the service.
    `boolean` | `interrupt(java.lang.String adminKey)` You must call this method to interrupt the thread.
    `java.lang.Object` | `invokeObj(java.lang.reflect.Method theMethod, java.lang.Object[] params)` Invoke the method on the stored object with the specified parameters.
    `protected void` | `removeTempPassword(java.lang.String tempPassword)` Remove the temporary password from the list if it exists.
    `void` | `run()` This run method tries to start the run method on the embedded object.
    `void` | `setObjService(java.lang.Object theObj)` Set the wrapped object that is typically derived from `Service`, but can be a legacy object of any type.
    `boolean` | `storesLegacy()` Return true if the stored object is legacy code, false if a licas service.
    `java.lang.String` | `threadAliveState()` Return the thread state of the embedded object.

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

      `addDefaultService, addDefaultService, addDefaultService, addDefaultService, addLinkFromService, addLinkToService, addMessageMetrics, addService, addService, addService, addService, addServiceAssociation, addServicePassword, allowAddService, canAccess, canAccess, canAccessMeta, canAccessNested, canAccessTemp, canRun, classNameOK, clearServiceLinks, clearServices, clearServices, close, createMetaFull, createPermanentLinkTo, createServiceWrapper, defaultAdminToRemove, dynamicLinkQuery, dynamicLinksToPermanent, dynamicLinksToXml, dynamicLinksToXml, finaliseInitialisation, finaliseInitialisation, finaliseModule, finaliseThisConfig, GET, getAllLinkToService, getAllowAddService, getAutonomicManagerConfig, getCommunicationClientURI, getData, getData, getDescription, getFullPath, getInstanceValue, getIsRemoteCall, getLinkFromService, getLinkToService, getLocalRemoteID, getParent, getParent, getPasswordHandler, getPrivateMethods, getPublicMethods, getPublicServiceClassname, getServerPassword, getServiceAdmin, getServiceClasses, getServiceGrade, getServiceLinks, getServiceNames, getServiceNames, getServiceNames, getServiceNumber, getServiceOrWrapper, getServiceState, getServiceType, getServiceTypes, handshake, hasCommunicationID, hasLinkTo, hasServerPassword, hasService, hasServiceType, isCorrectPassword, isPrivateMethod, isPublicMethod, isStarted, linksToXml, passwordsStateToXml, permanentLinksToXml, reflectionMethods, reflectionObject, removeAllLinksTo, removeAllServices, removeAllServices, removeCommunicationID, removeLinkFromService, removeLinkToService, removePermanentLinkTo, removeServiceAssociation, removeServiceID, removeServicePath, removeServicePath, serviceNegotiate, serviceToXml, serviceToXml, setAdminInfo, setCanAccessMeta, setCanAccessNested, setData, setDataModule, setDataModule, setDescription, setInstanceValues, setIsRemoteCall, setOtherMeta, setParent, setParent, setSerializeValues, 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

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

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

      `getJarFile, getUUID, loadObject, setJarFile, setUUID`

    - ### 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.ServiceWrapperDef

      `getDescription, getFullPath, getServiceGrade, reflectionMethods`

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

      `canAccessTemp, getServiceType, getUUID, isAdminKey, setJarFile, setServiceType, setUUID`

- - ### Field Detail

    - #### setStructures

          protected boolean setStructures

      True if structures for enclosed service object already set

    - #### metrics

          protected Metrics metrics

      Measurements of general message/transaction numbers

    - #### legacyObj

          protected java.lang.Object legacyObj

      The legacy object

  - ### Constructor Detail

    - #### ServiceWrapperLegacy

          public ServiceWrapperLegacy(java.lang.Object theObj)
                               throws java.lang.Exception

      Creates a new instance of ServiceWrapperLegacy.
      Parameters:
        `theObj` - the object to wrap.
      Throws:
        `java.lang.Exception` - any error.

  - ### Method Detail

    - #### storesLegacy

          public boolean storesLegacy()

      Return true if the stored object is legacy code, false if a licas service.
      Specified by:
        `storesLegacy` in interface `ServiceWrapperDef`
      Returns:
        true in this case.

    - #### run

          public void run()

      This run method tries to start the run method on the embedded object. You should override run in the embedded object to include your own process.
      Specified by:
        `run` in interface `java.lang.Runnable`
      Overrides:
        `run` in class `java.lang.Thread`

    - #### interrupt

          public boolean interrupt(java.lang.String adminKey)

      You must call this method to interrupt the thread. This also interrupts all nested services.
      Overrides:
        `interrupt` in class `Service`
      Parameters:
        `adminKey` - the key to identify unique loading of the service.
      Returns:
        true if the service is stopped.

    - #### copyToService

          public final void copyToService(java.lang.Object parent)
                                   throws java.lang.Exception

      Copy and set certain settings between the service object and the wrapper.
      Specified by:
        `copyToService` in interface `ServiceWrapperDef`
      Parameters:
        `parent` - the parent of the wrapper.
      Throws:
        `java.lang.Exception` - any error.

    - #### copyFromService

          public final void copyFromService()

      Reset the wrapper settings based on the wrapped object if a service.
      Specified by:
        `copyFromService` in interface `ServiceWrapperDef`

    - #### addMetrics

          public void addMetrics(MethodInfo messageObj,
                                 java.lang.String theAdminKey)

      Add some metrics values relating to the current message.
      Specified by:
        `addMetrics` in interface `ServiceWrapperDef`
      Parameters:
        `messageObj` - the message object.
        `theAdminKey` - the admin key for the parent service.

    - #### getMetrics

          public Metrics getMetrics()

      Get the default message/transaction metrics.
      Specified by:
        `getMetrics` in interface `ServiceWrapperDef`
      Returns:
        the value of metrics.

    - #### createMetaForRepos

          public ServiceMeta createMetaForRepos(java.lang.String theAdminKey)
                                         throws java.lang.Exception

      Create a metadata description of this service for the server repository. This wrapper is used to process the licas information for the legacy object.
      Overrides:
        `createMetaForRepos` in class `Service`
      Parameters:
        `theAdminKey` - the unique service key for admin purposes.
      Returns:
        a metadata description of this service.
      Throws:
        `java.lang.Exception` - any error.

    - #### addCommunicationID

          public boolean addCommunicationID(java.lang.String communicationID,
                                            java.lang.Object clientUri)
                                     throws java.lang.Exception

      Store the communicationID with the related client uri.
      Overrides:
        `addCommunicationID` in class `Service`
      Parameters:
        `communicationID` - the communication id.
        `clientUri` - the uri/reference for the calling client.
      Returns:
        true if the id is new and can be added, or false if the id already exists or cannot be added.
      Throws:
        `java.lang.Exception` - any error.

    - #### addTempPassword

          protected java.lang.String addTempPassword(boolean addPassword)
                                              throws java.lang.Exception

      Add a new temporary password to the temp passwords list.
      Overrides:
        `addTempPassword` in class `Service`
      Parameters:
        `addPassword` - true if add a password.
      Returns:
        the newly created password or null if do not add.
      Throws:
        `java.lang.Exception` - any error.

    - #### removeTempPassword

          protected void removeTempPassword(java.lang.String tempPassword)

      Remove the temporary password from the list if it exists.
      Overrides:
        `removeTempPassword` in class `Service`
      Parameters:
        `tempPassword` - the temporary password.

    - #### canAccess

          public boolean canAccess(java.lang.String thePassword)

      Return true if the wrapped object can be accessed by the password. If the object is of type `Service` then its `canAccess` method is called, otherwise true is automatically returned.
      Specified by:
        `canAccess` in interface `ServiceDef`
      Overrides:
        `canAccess` in class `FrameworkModule`
      Parameters:
        `thePassword` - the password to use.
      Returns:
        true if the wrapped object can be accessed or false otherwise.

    - #### canAccess

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

      Return true if the method on the wrapped object can be accessed by the password. If the object is of type `Service` then its `canAccess` method is called, otherwise true is automatically returned.
      Overrides:
        `canAccess` in class `Service`
      Parameters:
        `thePassword` - the password to use.
        `methodName` - the name of the method to call.
      Returns:
        true if the wrapped object can be accessed or false otherwise.
      Throws:
        `java.lang.Exception` - any error.

    - #### canAccess

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

      Return true if the method on the wrapped object can be accessed by the password. If the object is of type `Service` then its `canAccess` method is called, otherwise true is automatically returned.
      Overrides:
        `canAccess` in class `Service`
      Parameters:
        `thePassword` - the password to use.
        `theMethod` - the method reflection description.
      Returns:
        true if the wrapped object can be accessed or false otherwise.
      Throws:
        `java.lang.Exception` - any error.

    - #### 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.
      Overrides:
        `getPassword` in class `Service`
      Parameters:
        `clientID` - the clientID of the calling component.
        `clientContract` - the description of the calling component's contract proposal.
      Returns:
        the value of the password for the specified service level if the contract is accepted, or null if it is not accepted. The default 'yes' contract always returns the password.
      Throws:
        `java.lang.Exception` - any error.

    - #### getPassword

          public java.lang.String getPassword(java.lang.String theAdminKey)

      Get the password for this service. The wrapper's getPassword method is called.
      Overrides:
        `getPassword` in class `Service`
      Parameters:
        `theAdminKey` - the service key.
      Returns:
        the access password for this service.

    - #### getPassword

          public java.lang.String getPassword(java.lang.String serviceUuid,
                                              java.lang.String theAdminKey)
                                       throws java.lang.Exception

      Get the password for the specified service. The wrapper's getPassword method is called.
      Overrides:
        `getPassword` in class `Service`
      Parameters:
        `serviceUuid` - the id of the service to ask the password for.
        `theAdminKey` - the service key.
      Returns:
        the password for the specified service or null if it cannot be retrieved.
      Throws:
        `java.lang.Exception` - any error.

    - #### getWorkInfo

          public WorkInfo getWorkInfo()

      Get the work protocol details for the service. The wrapper's `serviceAdmin` is used.
      Specified by:
        `getWorkInfo` in interface `ServiceWrapperDef`
      Returns:
        the service wrapper's `workInfo` details.

    - #### getService

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

      Return the service for the related service name. The wrapper's getService method is called.
      Overrides:
        `getService` in class `Service`
      Parameters:
        `serviceName` - the name of the service.
        `thePassword` - the password to access the service to retrieve.
      Returns:
        the wrapped service, or null if no service exists.
      Throws:
        `ServiceException` - is access to any nested services is blocked.
        `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 for the related service name. The wrapper's getService method is called, where this version requires the admin key as well, but then returns a direct reference.
      Overrides:
        `getService` in class `Service`
      Parameters:
        `serviceName` - the name of the service.
        `thePassword` - the password to access the service.
        `adminKey` - the service key for this server.
      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.

    - #### setObjService

          public void setObjService(java.lang.Object theObj)

      Set the wrapped object that is typically derived from `Service`, but can be a legacy object of any type.
      Specified by:
        `setObjService` in interface `ServiceWrapperDef`
      Parameters:
        `theObj` - the value of obj.

    - #### getObjService

          public java.lang.Object getObjService(java.lang.String adminKey)

      Get the stored object service.
      Specified by:
        `getObjService` in interface `ServiceWrapperDef`
      Parameters:
        `adminKey` - the admin key for the object or wrapper.
      Returns:
        the stored object, or null if not the admin key.

    - #### getObjClass

          public java.lang.Class getObjClass()

      Get the class type of the stored object.
      Specified by:
        `getObjClass` in interface `ServiceWrapperDef`
      Returns:
        the stored object class name.

    - #### execute

          public java.lang.Object execute(MethodInfo methodInfo,
                                          boolean addTempPassword)
                                   throws ServiceException,
                                          java.lang.Exception

      Execute the specified method and return the result. If the wrapped object is a service then its execute method is called, otherwise this wrapper's execute method is called.
      Overrides:
        `execute` in class `Service`
      Parameters:
        `methodInfo` - the method call description with all of the required information.
        `addTempPassword` - if true add a temporary password to allow traversal through this service. If the service is referenced directly as an object then set this to false so that the caller must know this service's password.
      Returns:
        the reply, any object.
      Throws:
        `ServiceException` - any service specific error.
        `java.lang.Exception` - any other error.

    - #### invokeObj

          public java.lang.Object invokeObj(java.lang.reflect.Method theMethod,
                                            java.lang.Object[] params)
                                     throws java.lang.Exception

      Invoke the method on the stored object with the specified parameters.
      Specified by:
        `invokeObj` in interface `ServiceWrapperDef`
      Parameters:
        `theMethod` - the method to invoke.
        `params` - the parameter list.
      Returns:
        the result of the method invocation.
      Throws:
        `java.lang.Exception` - any error.

    - #### threadAliveState

          public java.lang.String threadAliveState()

      Return the thread state of the embedded object.
      Overrides:
        `threadAliveState` in class `LicasModule`
      Returns:
        the embedded object state if a thread.