org.licas.service

## Class DataService

- 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

- All Implemented Interfaces:
    java.lang.AutoCloseable, java.lang.Runnable, DataServiceDef, ServiceDef
  Direct Known Subclasses:
    Auto

      public class DataService
      extends Service
      implements DataServiceDef

  This is a `Service` implementation that includes basic data and evaluation handling. Storing and evaluating data objects is likely to be useful for a lot of services. Data is at a lower level than information and so the `InformationService` is a super class of this one, but all services from `Service` up use the same resources to store and return the data values. This class also accepts a data generator and can create the data module later from it.
  Note the `infoXmlDH` method to link any derived service with a `DataHub`, or the `infoXmlBM` method to link any derived service with a `BehaviourMediator`, for example.
  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 org.ai_heuristic.def.EvaluateMathDef` | `dataCompare` Default math evaluator, of basic java types
    `protected MethodInfo` | `dataMethod` Single operator method to invoke
    `protected java.lang.Object` | `resultObj` The result object is typically an evaluation over the data

    - ### 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
    `DataService()` Creates a new instance of DataService.
    `DataService(java.lang.String thisPassword, java.lang.String thisAdminKey)` Creates a new instance of DataService.
    `DataService(java.lang.String thisPassword, java.lang.String thisAdminKey, org.licas_xml.abs.Element adminXml)` Creates a new instance of DataService.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected EvaluateData` | `createEvaluateData(DataQueryModel dataQueryModel)` Create the data evaluator based on the input specification.
    `EvaluateData` | `createEvaluateData(DataQueryModel dataQueryModel, java.lang.String adminKey)` Create the data evaluator based on the input specification.
    `protected boolean` | `dataTypeOK(java.lang.String dataType)` Return true if the input data type is OK with the current service type.
    `protected void` | `dataXmlBM(org.licas_xml.abs.Element dataXml, org.licas_xml.abs.Element otherXml, boolean links)` This is the implementation used to send the current data result to a behaviour mediator if one is running.
    `void` | `dataXmlBM(java.lang.String adminKey)` This is used to send the current data and result to a behaviour mediator if one is running.
    `protected void` | `dataXmlDH(org.licas_xml.abs.Element dataXml, org.licas_xml.abs.Element otherXml)` This is used to send the current data result to a data hub if one is running.
    `void` | `dataXmlDH(java.lang.String adminKey)` This is used to send the current data result to a data hub if one is running.
    `org.licas_xml.abs.Element` | `evaluate(DataQueryModel dataQueryModel)` Evaluate the data.
    `java.lang.Object` | `getData()` Get the whole data value.
    `java.lang.Object` | `getData(org.licas_xml.abs.Element infoDescr)` Get the data value only, based on some condition.
    `java.lang.String` | `getDataType()` Get the data type.
    `protected java.lang.Object` | `getInstanceValue(java.lang.String varName)` Get the value of the specified variable if it exists.
    `java.lang.Object` | `getResultObj()` Get the result object value.
    `void` | `resetValues()` Reset values for the next run, empty here.
    `protected void` | `setData(DataQueryModel dataQueryModel)` Set the value for the local `DataModule` dataset, from the query parameters.
    `boolean` | `setData(java.lang.String dataType, java.lang.Object dataObj, java.lang.String adminKey)` Set the value that this service will use as its data source.
    `protected void` | `setFixedDataValue()` If a data generator has been loaded, use it to set a single fixed data value for this service.
    `void` | `setGenData(java.lang.String adminKey)` Set the random data value, created using the installed data generator.
    `protected void` | `setInstanceValues(org.licas_xml.abs.Element instanceValues)` Set actual values for variable instances if they are defined.
    `void` | `setResultObj(java.lang.Object thisObj)` Set the result value, which is usually an evaluation over the data source.
    `protected void` | `setSerializeValues(org.licas_xml.abs.Element serializeXml)` Set actual values for serialized variable instances if they are defined.

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

      `addCommunicationID, addDefaultService, addDefaultService, addDefaultService, addDefaultService, addLinkFromService, addLinkToService, addMessageMetrics, addService, addService, addService, addService, addServiceAssociation, addServicePassword, addTempPassword, allowAddService, canAccess, canAccess, canAccess, canAccess, canAccessMeta, canAccessNested, canAccessTemp, canRun, classNameOK, clearServiceLinks, clearServices, clearServices, close, createMetaForRepos, createMetaFull, createPermanentLinkTo, createServiceWrapper, 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, getPublicMethods, getPublicServiceClassname, getServerPassword, getService, getService, getServiceAdmin, getServiceClasses, getServiceGrade, getServiceLinks, getServiceNames, getServiceNames, getServiceNames, getServiceNumber, getServiceOrWrapper, getServiceState, getServiceType, getServiceTypes, handshake, hasCommunicationID, hasLinkTo, hasServerPassword, hasService, hasServiceType, interrupt, isCorrectPassword, isPrivateMethod, isPublicMethod, isStarted, linksToXml, passwordsStateToXml, permanentLinksToXml, reflectionMethods, reflectionObject, removeAllLinksTo, removeAllServices, removeAllServices, removeCommunicationID, 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, run, 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

    - #### dataMethod

          protected MethodInfo dataMethod

      Single operator method to invoke

    - #### dataCompare

          protected org.ai_heuristic.def.EvaluateMathDef dataCompare

      Default math evaluator, of basic java types

    - #### resultObj

          protected java.lang.Object resultObj

      The result object is typically an evaluation over the data

  - ### Constructor Detail

    - #### DataService

          public DataService()
                      throws java.lang.Exception

      Creates a new instance of DataService. Password and service key set to `anon` by default.
      Throws:
        `java.lang.Exception` - any error.

    - #### DataService

          public DataService(java.lang.String thisPassword,
                             java.lang.String thisAdminKey)
                      throws java.lang.Exception

      Creates a new instance of DataService.
      Parameters:
        `thisPassword` - password to invoke this service.
        `thisAdminKey` - admin key for this service.
      Throws:
        `java.lang.Exception` - any error.

    - #### DataService

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

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

  - ### Method Detail

    - #### resetValues

          public void resetValues()

      Reset values for the next run, empty here.
      Specified by:
        `resetValues` in interface `DataServiceDef`

    - #### setInstanceValues

          protected void setInstanceValues(org.licas_xml.abs.Element instanceValues)
                                    throws java.lang.Exception

      Set actual values for variable instances if they are defined.

      `NOTE:` you must add this method to your own derived class if you use it, so that the private variables in that class can be accessed. It is ignored unless it gets called through the script initialisation process.

      Overrides:
        `setInstanceValues` in class `Service`
      Parameters:
        `instanceValues` - the admin script part that defines instance values.
      Throws:
        `java.lang.Exception` - any error.

    - #### getInstanceValue

          protected java.lang.Object getInstanceValue(java.lang.String varName)
                                               throws java.lang.Exception

      Get the value of the specified variable if it exists.

      `NOTE:` you must add this method to your own derived class if you use it, so that the private variables in that class can be accessed. It is ignored unless it gets called through the script initialisation process.

      Overrides:
        `getInstanceValue` in class `Service`
      Parameters:
        `varName` - the name of the variable to check for.
      Returns:
        the variable value, or null if it does not exist.
      Throws:
        `java.lang.Exception` - any error.

    - #### setSerializeValues

          protected void setSerializeValues(org.licas_xml.abs.Element serializeXml)
                                     throws java.lang.Exception

      Set actual values for serialized variable instances if they are defined.

      `NOTE:` you must add this method to your own derived class if you use it, so that the private variables in that class can be accessed.

      Overrides:
        `setSerializeValues` in class `Service`
      Parameters:
        `serializeXml` - the admin script part that defines serialize instance values.
      Throws:
        `java.lang.Exception` - any error.

    - #### evaluate

          public org.licas_xml.abs.Element evaluate(DataQueryModel dataQueryModel)
                                             throws java.lang.Exception

      Evaluate the data.
      Parameters:
        `dataQueryModel` - evaluator query. For this version it must be a `ComparisonQueryModel`.
      Returns:
        the evaluation reply.
      Throws:
        `java.lang.Exception` - and error.

    - #### createEvaluateData

          protected EvaluateData createEvaluateData(DataQueryModel dataQueryModel)
                                             throws java.lang.Exception

      Create the data evaluator based on the input specification.
      Parameters:
        `dataQueryModel` - to store the data evaluator values.
      Returns:
        the created data evaluator.
      Throws:
        `java.lang.Exception` - any error.

    - #### createEvaluateData

          public EvaluateData createEvaluateData(DataQueryModel dataQueryModel,
                                                 java.lang.String adminKey)
                                          throws java.lang.Exception

      Create the data evaluator based on the input specification.
      Parameters:
        `dataQueryModel` - to store the data evaluator values.
        `adminKey` - the admin key for the parent service.
      Returns:
        the created data evaluator, or `null` if the admin key is incorrect.
      Throws:
        `java.lang.Exception` - any error.

    - #### setGenData

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

      Set the random data value, created using the installed data generator.
      Parameters:
        `adminKey` - the admin key for this service.
      Throws:
        `java.lang.Exception` - any error.

    - #### setFixedDataValue

          protected void setFixedDataValue()
                                    throws java.lang.Exception

      If a data generator has been loaded, use it to set a single fixed data value for this service. Add it to the admin details.
      Throws:
        `java.lang.Exception` - any error.

    - #### setData

          protected void setData(DataQueryModel dataQueryModel)
                          throws java.lang.Exception

      Set the value for the local `DataModule` dataset, from the query parameters.
      Parameters:
        `dataQueryModel` - to store the data evaluator values.
      Throws:
        `java.lang.Exception` - any error.

    - #### setData

          public boolean setData(java.lang.String dataType,
                                 java.lang.Object dataObj,
                                 java.lang.String adminKey)
                          throws java.lang.Exception

      Set the value that this service will use as its data source. This method creates a `Resource` in the `DataModule` and stores the value directly.
      Specified by:
        `setData` in interface `DataServiceDef`
      Parameters:
        `dataType` - the data type.
        `dataObj` - the data object.
        `adminKey` - the admin key for the service.
      Returns:
        true if set OK, false otherwise.
      Throws:
        `java.lang.Exception` - any error.

    - #### getDataType

          public java.lang.String getDataType()

      Get the data type.
      Specified by:
        `getDataType` in interface `DataServiceDef`
      Returns:
        the data type.

    - #### dataTypeOK

          protected boolean dataTypeOK(java.lang.String dataType)

      Return true if the input data type is OK with the current service type. The check can be used when updating the data module or resource, for example.
      Parameters:
        `dataType` - the data type, should match with the service and data module.
      Returns:
        true if OK, false otherwise.

    - #### getData

          public java.lang.Object getData()
                                   throws java.lang.Exception

      Get the whole data value.
      Overrides:
        `getData` in class `Service`
      Returns:
        the data value in its original format.
      Throws:
        `java.lang.Exception` - any error.

    - #### getData

          public java.lang.Object getData(org.licas_xml.abs.Element infoDescr)
                                   throws java.lang.Exception

      Get the data value only, based on some condition.
      Overrides:
        `getData` in class `Service`
      Parameters:
        `infoDescr` - a description of the info resource value that should be retrieved, but can be null.
      Returns:
        the data value in its original format.
      Throws:
        `java.lang.Exception` - any error.

    - #### dataXmlBM

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

      This is used to send the current data and result to a behaviour mediator if one is running.
      1. The data object is the static metadata `Data` entry.
      2. The result object is retrieved and assumed to be in XMl here.
      3. This default method also sends link information.
      The behaviour service can aggregate all of the service info's, to produce graphs or other results.

      This version sends the data information to a service identified by `ServiceConst`.`BEHAVIOURMEDIATOR`. It includes the data element of this service, any links that it has formed and also the result of the evaluation process.

      Specified by:
        `dataXmlBM` in interface `DataServiceDef`
      Parameters:
        `adminKey` - as it would typically be called internally, it is protected by the service's admin key.
      Throws:
        `java.lang.Exception` - any other error.
        `PasswordException` - incorrect password for the server or mediator service.
        `MethodNotFoundException` - the mediator does not have the calling method.

    - #### dataXmlBM

          protected void dataXmlBM(org.licas_xml.abs.Element dataXml,
                                   org.licas_xml.abs.Element otherXml,
                                   boolean links)
                            throws java.lang.Exception

      This is the implementation used to send the current data result to a behaviour mediator if one is running. The behaviour service can aggregate all of the service info's, to produce graphs or other results.

      This version sends the data information to a service identified by `ServiceConst`.`BEHAVIOURMEDIATOR`. It includes the data element of this service, any links that it has formed and also the result of the evaluation process.

      Parameters:
        `dataXml` - this is the service's `Data` section. It can be null if it should not be sent.
        `otherXml` - is any additional information, such as an evaluation result, or anything that has been dynamically created. It gets added as a sub-element of the outermost reply element.
        `links` - true if include linking information.
      Throws:
        `java.lang.Exception` - any other error.

    - #### dataXmlDH

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

      This is used to send the current data result to a data hub if one is running. The data hub service can aggregate all of the service info's and make it available.

      This version sends the data information to a service identified by `ServiceConst`.`DATAHUB`. It includes the data element of this service, any links that it has formed and also the result of the evaluation process.

      Specified by:
        `dataXmlDH` in interface `DataServiceDef`
      Parameters:
        `adminKey` - as it would typically be called internally, it is protected by the service's admin key.
      Throws:
        `java.lang.Exception` - any other error.
        `PasswordException` - incorrect password for the server or mediator service.
        `MethodNotFoundException` - the mediator does not have the calling method.

    - #### dataXmlDH

          protected void dataXmlDH(org.licas_xml.abs.Element dataXml,
                                   org.licas_xml.abs.Element otherXml)
                            throws java.lang.Exception

      This is used to send the current data result to a data hub if one is running. The data hub service can aggregate all of the service info's and make it available. This method uses the `Data-Value` metadata structure to send the data.

      This version sends the data information to a service identified by `ServiceConst`.`DATAHUB`. It includes the data element of this service, any links that it has formed and also the result of the evaluation process.

      Parameters:
        `dataXml` - this is the service's `Data` section. It can be null if it should not be sent.
        `otherXml` - this is a result or other xml piece of data to send. It can be null if it should not be sent.
      Throws:
        `java.lang.Exception` - any error.

    - #### setResultObj

          public void setResultObj(java.lang.Object thisObj)

      Set the result value, which is usually an evaluation over the data source. This is typically in XML format.
      Parameters:
        `thisObj` - the value to set the result object to.

    - #### getResultObj

          public java.lang.Object getResultObj()

      Get the result object value. This is typically in XML format.
      Returns:
        the value of resultObj.