org.licas

## Class ServiceWrapper

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

- All Implemented Interfaces:
    java.lang.Runnable, ServiceDef, ServiceWrapperDef
  Direct Known Subclasses:
    AutonomicManager

      public class ServiceWrapper
      extends ServiceModule
      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 licas `Service` object and a `ServiceWrapperLegacy` stores a `Legacy` object. The autonomic manager is also an extension of this wrapper, but it only stores an `Auto`-derived object and would also allow for autonomic monitoring capabilities. 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 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.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
    `ServiceWrapper(Service theService)` Creates a new instance of ServiceWrapper.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected boolean` | `addCommunicationID(java.lang.String commID, java.lang.Object clientURI)` Store the commID with the related client URI, on the embedded service.
    `void` | `addMetrics(MethodInfo messageObj, java.lang.String theAdminKey)` Add some metrics values relating to the current message.
    `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 theMethod)` Return true if the method on the wrapped object can be accessed by the password.
    `boolean` | `canAccessTemp(java.lang.String thePassword)` Return true if the password allows the calling component to access this component by a temp 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.
    `java.lang.Object` | `execute(MethodInfo methodInfo, boolean addTempPassword)` Execute the specified method and return the result.
    `org.licas_xml.abs.Element` | `getDescription()` Get the description value.
    `org.licas_xml.abs.Element` | `getFullPath()` Get the fully qualified uuid path back to the first parent object and server.
    `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.
    `java.lang.String` | `getServiceGrade()` Get the grade for this service.
    `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.
    `java.util.ArrayList<java.lang.reflect.Method>` | `reflectionMethods()` Get a list of public methods that can be accessed through the service, not this wrapper.
    `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.
    `protected boolean` | `setParent(Service thisParent)` Set the parent component value.
    `protected void` | `setServerPassword(java.lang.String thePassword)` Set the password that will allow this service to access the server it runs on.
    `void` | `setServiceGrade(java.lang.String thisServiceGrade)` Set the service grade or function class.
    `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.module.ServiceModule

      `getShutDown, setShutDown, setShutDown`

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

      `getPasswordHandler, getPasswordHandler, getServerPassword, 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.ServiceDef

      `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

  - ### Constructor Detail

    - #### ServiceWrapper

          public ServiceWrapper(Service theService)
                         throws java.lang.Exception

      Creates a new instance of ServiceWrapper.
      Parameters:
        `theService` - the service to monitor.
      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:
        false 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`

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

    - #### canAccessTemp

          public boolean canAccessTemp(java.lang.String thePassword)

      Return true if the password allows the calling component to access this component by a temp password.
      Specified by:
        `canAccessTemp` in interface `ServiceDef`
      Overrides:
        `canAccessTemp` in class `FrameworkModule`
      Parameters:
        `thePassword` - the password to use.
      Returns:
        true if the entered password is the valid.

    - #### 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 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.
      Parameters:
        `thePassword` - the password to use.
        `theMethod` - the name of the method to call.
      Returns:
        true if the wrapped object can be accessed or false otherwise.
      Throws:
        `java.lang.Exception` - nay 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.
      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` - nay 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.
      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. If the wrapped object is a service then its `getPassword` method is called, otherwise this wrapper's getPassword method is called.
      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. If the wrapped object is a service then its `getPassword` method is called, otherwise this wrapper's getPassword method is called.
      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.

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

    - #### addCommunicationID

          protected boolean addCommunicationID(java.lang.String commID,
                                               java.lang.Object clientURI)
                                        throws java.lang.Exception

      Store the commID with the related client URI, on the embedded service. Stored as `MessageInfo` objects with timestamps. The method now also checks the timestamps and removes any communicationIDs that are older than 3 days.
      Parameters:
        `commID` - the communication id.
        `clientURI` - the URI/reference for the calling client. If `null` or a server URI, then it is set to `Const`.`ANON` and only the commID is subsequently checked for.
      Returns:
        true if the id is new and can be added, or false if the comm id already exists, or cannot be added.
      Throws:
        `java.lang.Exception` - any error.

    - #### setServiceGrade

          public void setServiceGrade(java.lang.String thisServiceGrade)

      Set the service grade or function class.
      Parameters:
        `thisServiceGrade` - the service grade.

    - #### getServiceGrade

          public java.lang.String getServiceGrade()

      Get the grade for this service.
      Specified by:
        `getServiceGrade` in interface `ServiceWrapperDef`
      Returns:
        the value of serviceGrade.

    - #### getDescription

          public org.licas_xml.abs.Element getDescription()

      Get the description value. This is just the description and not the full set of admin rules.
      Specified by:
        `getDescription` in interface `ServiceWrapperDef`
      Returns:
        the service description.

    - #### getWorkInfo

          public WorkInfo getWorkInfo()

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

    - #### setServerPassword

          protected void setServerPassword(java.lang.String thePassword)
                                    throws java.lang.Exception

      Set the password that will allow this service to access the server it runs on.
      Parameters:
        `thePassword` - the server password.
      Throws:
        `java.lang.Exception` - any error.

    - #### setParent

          protected boolean setParent(Service thisParent)

      Set the parent component value. If the parent is the ESB server then it is not added, so only for child services.
      Parameters:
        `thisParent` - the parent component representation.
      Returns:
        true if set, false if already set, or try to add server.

    - #### getFullPath

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

      Get the fully qualified uuid path back to the first parent object and server.
      Specified by:
        `getFullPath` in interface `ServiceWrapperDef`
      Returns:
        the fully qualified path to access this component on the server.
      Throws:
        `java.lang.Exception` - any error.

    - #### 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. If the wrapped object is a service then its `getService` method is called, otherwise this wrapper's getService method is called.
      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. If the wrapped object is a service then its `getService` method is called, otherwise this wrapper's execute method is called. This method requires the service key as well, but then returns a direct reference.
      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.
      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.

    - #### reflectionMethods

          public java.util.ArrayList<java.lang.reflect.Method> reflectionMethods()

      Get a list of public methods that can be accessed through the service, not this wrapper.
      Specified by:
        `reflectionMethods` in interface `ServiceWrapperDef`
      Returns:
        a list of Reflection method descriptions, not the licas descriptions.

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

    - #### interrupt

          public boolean interrupt(java.lang.String adminKey)

      You must call this method to interrupt the thread. This also interrupts all nested services. You also need to implement an interrupt method in the wrapped object directly to shut it down if a running thread.
      Overrides:
        `interrupt` in class `ServiceModule`
      Parameters:
        `adminKey` - the key to identify unique loading of the service.
      Returns:
        true if the service is stopped.

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