org.licas.service.resource.info

## Class InfoStreamXml

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

-     public class InfoStreamXml
      extends Resource

  This is used by the `InformationService` to return a remote stream value parsed into xml. The URL link to the online source is stored and the contents are returned upon request. This should close the stream after each request. The `getValue` method logs any error but then returns `null` instead of throwing an exception. An alternative to this would be the `InfoHtml` resource for more basic HTML pages.

  This class tries to read the event stream as an input stream. If that fails, it tries to retrieve the whole stream first as a string, check formatting and then create the event stream. If that fails, it resets SSL to accept any certificate and repeats the process. The TrustManager is then re-loaded at the end if it has been reset.

  The default is to parse the stream to format it as an rss feed. As well as the `Const`.`VALUE` element, it is possible to add a `<Keywords><Keyword>kw1</Keyword><Keyword>kw2</Keyword>...</Keywords>` section to the initialisation script to define a different set of element names to keep. In that case, both the data value element and the keywords element probably need to be both wrapped in an outer element.

  Author:
    Kieran Greer

- - ### Field Summary

    - ### Fields inherited from class org.licas.service.resource.Resource

      `dataType, INFOANYTYPE, INFOBINARYTYPE, INFOHTMLTYPE, INFOSTREAMXMLTYPE, INFOSTRINGTYPE, INFOTEXTTYPE, INFOURLTYPE, INFOXMLTYPE, LISTCONTAINERTYPE, QUERYCONTAINERTYPE, RANDOMCONTAINERTYPE, uuid`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `InfoStreamXml(java.lang.String theDataType, org.licas_xml.abs.Element dataXml)` Create a new instance of InfoStreamXml.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `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` | `getURL()` Get the url address.
    `java.lang.Object` | `getValue(org.licas_xml.abs.Element infoDescr)` Get the value itself and not a wrapped description.
    `boolean` | `parseInfo(org.licas_xml.abs.Element dataXml)` Parse the data description in the document to create the data object.

    - ### Methods inherited from class org.licas.service.resource.Resource

      `createResource, dataFromResourceType, getDataType, getUUID, parseValueElem, resourceTypeForDataType, setUUID, setUUID`

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

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

- - ### Constructor Detail

    - #### InfoStreamXml

          public InfoStreamXml(java.lang.String theDataType,
                               org.licas_xml.abs.Element dataXml)
                        throws java.lang.Exception

      Create a new instance of InfoStreamXml.
      Parameters:
        `theDataType` - the resource data type. One of the stream types. This returns the stream as a String by default.
        `dataXml` - a description of the initialisation parameters. Can be null.
      Throws:
        `java.lang.Exception` - any error.

  - ### Method Detail

    - #### parseInfo

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

      Parse the data description in the document to create the data object. This version should read a URL address and store that. It also only returns the URL address upon request.
      Specified by:
        `parseInfo` in class `Resource`
      Parameters:
        `dataXml` - this must include a `Const`.`VALUE` element that stores a String-based URL path description. It can also include a `Keywords` element that stores a specific list of element tag names to keep. If not present, then a default rss set of element names are kept.
      Returns:
        true if the file was successfully loaded, false otherwise.
      Throws:
        `java.lang.Exception` - any error.

    - #### getInfo

          public 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.
      Specified by:
        `getInfo` in class `Resource`
      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 a `Data` element through an admin document.
      Throws:
        `java.lang.Exception` - any error.

    - #### getValue

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

      Get the value itself and not a wrapped description.
      Specified by:
        `getValue` in class `Resource`
      Parameters:
        `infoDescr` - a description of the info resource value that should be retrieved. Ignored in this case as the whole source stream, parsed into XML, is returned.
      Returns:
        the info value.
      Throws:
        `java.lang.Exception` - any error.

    - #### getURL

          public java.lang.String getURL()

      Get the url address.
      Returns:
        the value of `url.toExternalForm()`.