org.licas.service.resource

## Class Resource

- java.lang.Object
- - org.licas.service.resource.Resource

- Direct Known Subclasses:
    InfoBinary, InfoStreamXml, InfoString, InfoText, InfoURL, InfoXml, ObjResource, ResourceContainer

      public abstract class Resource
      extends java.lang.Object

  This is used by a service, such as the `InformationService`, to store a single resource instance. The resource could store static content or access an online link, for example.
  Author:
    Kieran Greer

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected java.lang.String` | `dataType` The data type
    `static java.lang.String` | `INFOANYTYPE` Resource types
    `static java.lang.String` | `INFOBINARYTYPE`
    `static java.lang.String` | `INFOHTMLTYPE`
    `static java.lang.String` | `INFOSTREAMXMLTYPE`
    `static java.lang.String` | `INFOSTRINGTYPE`
    `static java.lang.String` | `INFOTEXTTYPE`
    `static java.lang.String` | `INFOURLTYPE`
    `static java.lang.String` | `INFOXMLTYPE`
    `static java.lang.String` | `LISTCONTAINERTYPE`
    `static java.lang.String` | `QUERYCONTAINERTYPE`
    `static java.lang.String` | `RANDOMCONTAINERTYPE`
    `protected java.lang.String` | `uuid` A unique id for the resource

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Resource(java.lang.String theDataType)` Create a new instance of Resource.

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static Resource` | `createResource(java.lang.String dataType, org.licas_xml.abs.Element dataXml)` Create an info resource object and return.
    `static java.lang.String` | `dataFromResourceType(java.lang.String theResourceType)` Get the data type from the resource type.
    `protected java.lang.String` | `getDataType()` Get the data type.
    `abstract org.licas_xml.abs.Element` | `getInfo(org.licas_xml.abs.Element infoDescr)` Get the currently loaded source information wrapped in an XML element.
    `java.lang.String` | `getUUID()` Get the ID value.
    `abstract java.lang.Object` | `getValue(org.licas_xml.abs.Element infoDescr)` Get the value itself and not a wrapped description.
    `protected abstract boolean` | `parseInfo(org.licas_xml.abs.Element dataXml)` Parse the data description in the admin document to create the data object.
    `protected org.licas_xml.abs.Element` | `parseValueElem(org.licas_xml.abs.Element dataXml)` Try to find the value element, but only for a specific structure at the start of the document, so find the first instance and the rest can include any element name.
    `static java.lang.String` | `resourceTypeForDataType(java.lang.String dataType)` Get the most appropriate info resource type for the specified data type.
    `protected void` | `setUUID(org.licas_xml.abs.Element adminXml)` Check if there is a `UUID` attribute specified in the admin script root element and set the resource ID if there is.
    `void` | `setUUID(java.lang.String theUuid)` Set the resource uuid.

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

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

- - ### Field Detail

    - #### INFOANYTYPE

          public static final java.lang.String INFOANYTYPE

      Resource types

    - #### INFOBINARYTYPE

          public static final java.lang.String INFOBINARYTYPE

    - #### INFOTEXTTYPE

          public static final java.lang.String INFOTEXTTYPE

    - #### INFOXMLTYPE

          public static final java.lang.String INFOXMLTYPE

    - #### INFOHTMLTYPE

          public static final java.lang.String INFOHTMLTYPE

    - #### INFOSTREAMXMLTYPE

          public static final java.lang.String INFOSTREAMXMLTYPE

    - #### INFOURLTYPE

          public static final java.lang.String INFOURLTYPE

    - #### INFOSTRINGTYPE

          public static final java.lang.String INFOSTRINGTYPE

    - #### LISTCONTAINERTYPE

          public static final java.lang.String LISTCONTAINERTYPE

    - #### RANDOMCONTAINERTYPE

          public static final java.lang.String RANDOMCONTAINERTYPE

    - #### QUERYCONTAINERTYPE

          public static final java.lang.String QUERYCONTAINERTYPE

    - #### uuid

          protected java.lang.String uuid

      A unique id for the resource

    - #### dataType

          protected java.lang.String dataType

      The data type

  - ### Constructor Detail

    - #### Resource

          public Resource(java.lang.String theDataType)
                   throws java.lang.Exception

      Create a new instance of Resource.
      Parameters:
        `theDataType` - the resource data type.
      Throws:
        `java.lang.Exception` - any error.

  - ### Method Detail

    - #### parseInfo

          protected abstract boolean parseInfo(org.licas_xml.abs.Element dataXml)
                                        throws java.lang.Exception

      Parse the data description in the admin document to create the data object.
      Parameters:
        `dataXml` - the outermost element is not checked for, but might be a `DATA` or `DATASET` element. This should include a `VALUE` element that stores a String or XML-based value description and possibly an `Action` element. If there is no specified action, then the data is loaded into the resource as default. An action of `AiConst`.`LOADREMOTE`, for example, will retrieve the data dynamically upon request, from the file link.
      Returns:
        true if the resource was successfully initialised, false otherwise.
      Throws:
        `java.lang.Exception` - any error.

    - #### getInfo

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

      Get the currently loaded source information wrapped in an XML element.
      Parameters:
        `infoDescr` - a description of the info resource value that should be retrieved.
      Returns:
        the value of the resource info as an XML element. This format is consistent with adding data through an admin document.
      Throws:
        `java.lang.Exception` - any error.

    - #### getValue

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

      Get the value itself and not a wrapped description.
      Parameters:
        `infoDescr` - a description of the info resource value that should be retrieved, but can be null.
      Returns:
        the info value.
      Throws:
        `java.lang.Exception` - any error.

    - #### setUUID

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

      Check if there is a `UUID` attribute specified in the admin script root element and set the resource ID if there is. If there is not then assign a unique random one. The resource
      Parameters:
        `adminXml` - the initialisation admin script.
      Throws:
        `java.lang.Exception` - any error.

    - #### setUUID

          public void setUUID(java.lang.String theUuid)

      Set the resource uuid.
      Parameters:
        `theUuid` - the uuid value.

    - #### getUUID

          public java.lang.String getUUID()

      Get the ID value.
      Returns:
        the value of uuid.

    - #### getDataType

          protected java.lang.String getDataType()

      Get the data type.
      Returns:
        the value of dataType.

    - #### parseValueElem

          protected org.licas_xml.abs.Element parseValueElem(org.licas_xml.abs.Element dataXml)
                                                      throws java.lang.Exception

      Try to find the value element, but only for a specific structure at the start of the document, so find the first instance and the rest can include any element name.
      Parameters:
        `dataXml` - the resource admin document. Should have a `Data` element as the first element, and a `Value` element at the immediate next level.
      Returns:
        the value element, or `null` if the structure does not exist.
      Throws:
        `java.lang.Exception` - any error.

    - #### dataFromResourceType

          public static java.lang.String dataFromResourceType(java.lang.String theResourceType)

      Get the data type from the resource type. This is a best guess or generalisation of possible types that might be returned. Text is considered to be a text file, whereas String is for a stored text string.
      Parameters:
        `theResourceType` - the resource type to convert.
      Returns:
        the type of data from the resource type, or the resource type if it is not recognised, is the ResourceObject, or a Resource Container.

    - #### resourceTypeForDataType

          public static java.lang.String resourceTypeForDataType(java.lang.String dataType)

      Get the most appropriate info resource type for the specified data type.
      Parameters:
        `dataType` - the data type, for example, Integer.class.getName(), String.class.getName(), URL.class.getName(). Basic types are covered. An HTML source should be represented by URL.class.getName().
      Returns:
        the type of Resource that would be created for that data type.

    - #### createResource

          public static Resource createResource(java.lang.String dataType,
                                                org.licas_xml.abs.Element dataXml)
                                         throws java.lang.Exception

      Create an info resource object and return. The resource that is created is selected automatically from the data type and so is a best match guess.
      Parameters:
        `dataType` - the data type of the value to be stored, for example, `Class.getName()`.
        `dataXml` - a description of the initialisation parameters, ideally with a `Data-Value` structure. Can be null, when no value is set.
      Returns:
        a matched info resource or ObjResource if the type is not recognised.
      Throws:
        `java.lang.Exception` - any error.