org.licas.service

## Class InformationService

- 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.service.sci.LinkService
                - - org.licas.service.InformationService

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

      public class InformationService
      extends LinkService

  This class can be used to retrieve information from a `Resource` source. The resource is initialised in the service through the admin XML `Data` element, which is now configurable for different dat2a types and even nested lists or containers.

  Information may typically be used as part of a `Publish-Subscribe` process and not a data calculation one. The behaviour loop has therefore been set to 1 whole day, instead of the AI value of `ServiceConst`.`BEHAVIOURSLEEP` of a few milliseconds. You can change this value to whatever in your code via `sleepTime = milliseconds;`

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

  - ### Method Summary

    All Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected MessageInfo` | `behaviourAction(MessageInfo messageInfo)` This behaviour retrieves the resource information and publishes it on the server.
    `java.lang.String` | `GET()` This is a method to be invoked by something like a RESTFul or HTTP Server call.
    `org.licas_xml.abs.Element` | `getInfoElement()` Get the currently loaded source information as an XML element.
    `org.licas_xml.abs.Element` | `getInfoElement(org.licas_xml.abs.Element infoDescr)` Get the currently loaded source information as an XML element.
    `java.lang.String` | `getSourceInfo(org.licas_xml.abs.Element infoDescr)` Deprecated. this method is inefficient because it codes and decodes too many times, so use `getInfoElement` instead.
    `void` | `loadDataContents(java.lang.String dataType, java.lang.String urlPath)` Load data contents onto the service, so store the information directly on the service.
    `void` | `loadDataDetails(java.lang.String dataType, java.lang.String urlPath)` Load data details onto the service, which is a description of the external source and the information is retrieved from the external source each time.
    `void` | `loadDataScript(org.licas_xml.abs.Element adminDataXml)` Create a new resource object from a new admin document.
    `void` | `setGenData(java.lang.String adminKey)` Set the random data value, created using the installed data generator.

    - ### Methods inherited from class org.licas.service.sci.LinkService

      `addDynamicLink, addDynamicLinks, addPermanentLink, createProcessScript, getDataRandomID, getMessageState, removeAllPermanentLinks, removePermanentLink, resetValues, updateDynamicLinks`

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

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

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

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

    - ### 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, 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, isCorrectPassword, isPrivateMethod, isPublicMethod, isStarted, linksToXml, passwordsStateToXml, permanentLinksToXml, reflectionMethods, reflectionObject, removeAllLinksTo, 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`

- - ### Constructor Detail

    - #### InformationService

          public InformationService()
                             throws java.lang.Exception

      Create a new instance of InformationService.
      Throws:
        `java.lang.Exception` - any error.

    - #### InformationService

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

      Creates a new instance of InformationService.
      Parameters:
        `thisPassword` - the component password.
        `thisAdminKey` - the unique service key.
      Throws:
        `java.lang.Exception` - any error.

    - #### InformationService

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

      Creates a new instance of InformationService.
      Parameters:
        `thisPassword` - the component password.
        `thisAdminKey` - the unique service key.
        `adminXml` - the admin info or description of this service. This can include a resource to load, so do not pass to parent class, but initialise separately.
      Throws:
        `java.lang.Exception` - any error.

  - ### Method Detail

    - #### GET

          public java.lang.String GET()
                               throws java.lang.Exception

      This is a method to be invoked by something like a RESTFul or HTTP Server call. It is supposed to copy the HTTP GET protocol method and return the content of this service, as a String. This version returns the `getValue(...)` value of the information service. Note that the value `Const`.`SEPCHARS` can be used to parse the String reply.
      Overrides:
        `GET` in class `Service`
      Returns:
        a String-based value representing the content of the service.
      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.
      Overrides:
        `setGenData` in class `DataService`
      Parameters:
        `adminKey` - the admin key for this service.
      Throws:
        `java.lang.Exception` - any error.

    - #### behaviourAction

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

      This behaviour retrieves the resource information and publishes it on the server. Any other service that subscribes for it is then sent the information through a push activity. The result is also sent to a `Behaviour Mediator` service for viewing, but that is probably optional. The evaluation result is then returned as the method result.
      Overrides:
        `behaviourAction` in class `LinkService`
      Parameters:
        `messageInfo` - the message to evaluate. This behaviour works internally only, and so the external message can be `null`.
      Returns:
        the result of executing the behaviour.
      Throws:
        `java.lang.Exception` - any error.

    - #### getSourceInfo

          public java.lang.String getSourceInfo(org.licas_xml.abs.Element infoDescr)
                                         throws java.lang.Exception

      Deprecated. this method is inefficient because it codes and decodes too many times, so use `getInfoElement` instead.
      Get the source information, as parsed and coded XML in String format. This is the most reliable method for a remote call, as it also codes the String so that it can be transferred across the servers.
      Parameters:
        `infoDescr` - a description of the info resource value that should be retrieved. This can be null if there is no query description.
      Returns:
        the value of `infoResource` as a coded string. This is a string in XML format that is consistent with the `Data` format in the admin document. It is automatically decoded when received by the client-side methods and can then be parsed back into XML using the `XmlHandler.stringToElement` method.
      Throws:
        `java.lang.Exception` - any error.

    - #### getInfoElement

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

      Get the currently loaded source information as an XML element. This probably returns the format `<Data><Value>Info value here</Value><Value_Type>Info value type</Value_Type></Data>`.
      Returns:
        the value of `infoResource` as an XML element.
      Throws:
        `java.lang.Exception` - any error.

    - #### getInfoElement

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

      Get the currently loaded source information as an XML element. This probably returns the format `<Data><Value>Info value here</Value><Value_Type>Info value type</Value_Type></Data>`.
      Parameters:
        `infoDescr` - a description of the info resource value that should be retrieved, or can be `null`.
      Returns:
        the value of `infoResource` as an XML element.
      Throws:
        `java.lang.Exception` - any error.

    - #### loadDataContents

          public void loadDataContents(java.lang.String dataType,
                                       java.lang.String urlPath)
                                throws java.lang.Exception

      Load data contents onto the service, so store the information directly on the service. This can be dangerous because it will overwrite the current data module. The contents description is then copied to the metadata `Data` element.
      Parameters:
        `dataType` - the type of data to load.
        `urlPath` - the file path as a local or remote url.
      Throws:
        `java.lang.Exception` - any error.

    - #### loadDataDetails

          public void loadDataDetails(java.lang.String dataType,
                                      java.lang.String urlPath)
                               throws java.lang.Exception

      Load data details onto the service, which is a description of the external source and the information is retrieved from the external source each time. This can be dangerous because it will overwrite the current data module. The contents description is then copied to the metadata `Data` element. The external source an be local or remote.
      Parameters:
        `dataType` - the type of data to load.
        `urlPath` - the file path as a local or remote url.
      Throws:
        `java.lang.Exception` - any error.

    - #### loadDataScript

          public void loadDataScript(org.licas_xml.abs.Element adminDataXml)
                              throws java.lang.Exception

      Create a new resource object from a new admin document.
      Parameters:
        `adminDataXml` - the new admin data section. Replaces the existing data section completely.
      Throws:
        `java.lang.Exception` - any error.