org.licas

## Class ServiceSerialize

- java.lang.Object
- - org.licas.ServiceSerialize

-     public class ServiceSerialize
      extends java.lang.Object

  This can be used to serialize a service to or from XML, using reflection. It can also be configured so that only parts of a service are serialized, when only those parts would then be added to the re-constructed service. This includes most of the admin and metadata objects, including the linking.
  Author:
    Kieran Greer

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `ServiceSerialize()`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `org.licas_xml.abs.Element` | `allLinksToXml(Service theService, boolean allLevels, boolean includeValues)` Return all linked sources in XML format - permanent, dynamic or association.
    `org.licas_xml.abs.Element` | `associationLinksToXml(Service theService)` Return all association linked sources in XML format.
    `org.licas_xml.abs.Element` | `childServiceMetaToXml(Service theService)` Return a list of child service uuids.
    `org.licas_xml.abs.Element` | `dynamicLinkQuery(Service theService, LinkQueryConfig queryConfig)` Perform a query over the link paths to return matching sources.
    `org.licas_xml.abs.Element` | `dynamicLinksToXml(Service theService, boolean allLevels, boolean includeValues)` Return all dynamic linked sources in XML format.
    `protected void` | `parseSerializeAdmin(Service theService, java.util.ArrayList<java.lang.String> toSerialize, java.util.ArrayList<java.lang.String> adminToRemove)` If an admin serialize variables section exists, then retrieve and parse.
    `org.licas_xml.abs.Element` | `passwordsPlusStateToXml(Service theService)` Serialize the stored passwords list and return as an XML-based description.
    `org.licas_xml.abs.Element` | `permanentLinksToXml(Service theService)` Return all permanent linked sources in XML format.
    `protected org.licas_xml.abs.Element` | `serviceToXml(Service theService)` Serialize the service admin info and return as an XML-based description.
    `protected org.licas_xml.abs.Element` | `serviceToXml(Service theService, java.util.ArrayList<java.lang.String> adminToRemove, java.util.ArrayList<java.lang.String> toSerialize)` Serialize the full service admin info, minus `adminToRemove` and return as an XML-based description.
    `protected void` | `xmlToDynamicLinks(Service theService, org.licas_xml.abs.Element linksXml)` Parse the dynamic links descriptions and add to the service.
    `protected java.lang.Object` | `xmlToService(org.licas_xml.abs.Element serviceXml, java.lang.String password)` Read the contents of the admin document and re-create the service from it.

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

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

- - ### Constructor Detail

    - #### ServiceSerialize

          public ServiceSerialize()

  - ### Method Detail

    - #### serviceToXml

          protected org.licas_xml.abs.Element serviceToXml(Service theService)
                                                    throws java.lang.Exception

      Serialize the service admin info and return as an XML-based description. This version will automatically remove some of the admin meta elements, for safety reasons. Note that only the admin elements are serialized, not any other variables in the service. As well as this, local Service variables such as passwords, or comm IDs are serialized.
      Parameters:
        `theService` - the service to serialize.
      Returns:
        an XML representation of all named elements.
      Throws:
        `java.lang.Exception` - any error.

    - #### serviceToXml

          protected org.licas_xml.abs.Element serviceToXml(Service theService,
                                                           java.util.ArrayList<java.lang.String> adminToRemove,
                                                           java.util.ArrayList<java.lang.String> toSerialize)
                                                    throws java.lang.Exception

      Serialize the full service admin info, minus `adminToRemove` and return as an XML-based description. This will create a full admin description and then remove the elements specified in the adminToRemove list. An empty list will serialize everything and therefore is less safe. As well as this, local Service variables such as passwords, or comm IDs are serialized. An additional list specified other service-local variables to serialize and store.
      Parameters:
        `theService` - the service to serialize.
        `adminToRemove` - if any section is indicated here through the XML tag name, it is removed first.
        `toSerialize` - list of variable names to serialize.
      Returns:
        an XML representation of all named elements, or null if the admin key is incorrect.
      Throws:
        `java.lang.Exception` - any error.

    - #### parseSerializeAdmin

          protected void parseSerializeAdmin(Service theService,
                                             java.util.ArrayList<java.lang.String> toSerialize,
                                             java.util.ArrayList<java.lang.String> adminToRemove)

      If an admin serialize variables section exists, then retrieve and parse. If not, then do not change the input parameter lists.
      Parameters:
        `theService` - the service to serialize.
        `toSerialize` - to list the local variables to serialize. This must be an empty initialised list, to be added to.
        `adminToRemove` - to list the admin variables to remove. This must be an empty initialised list, to be added to.

    - #### xmlToService

          protected java.lang.Object xmlToService(org.licas_xml.abs.Element serviceXml,
                                                  java.lang.String password)
                                           throws java.lang.Exception

      Read the contents of the admin document and re-create the service from it.
      Parameters:
        `serviceXml` - a full XML description of the service.
        `password` - parent password, probably the server currently running. Need to use this instead of the stored value if a server.
      Returns:
        the re-created service, probably derived from `Service`, but it might be a wrapped object.
      Throws:
        `java.lang.Exception` - any error.

    - #### childServiceMetaToXml

          public org.licas_xml.abs.Element childServiceMetaToXml(Service theService)

      Return a list of child service uuids.
      Parameters:
        `theService` - the parent service.
      Returns:
        an XML representation of the nested service uuids.

    - #### dynamicLinkQuery

          public org.licas_xml.abs.Element dynamicLinkQuery(Service theService,
                                                            LinkQueryConfig queryConfig)
                                                     throws java.lang.Exception

      Perform a query over the link paths to return matching sources.
      Parameters:
        `theService` - the parent service.
        `queryConfig` - the query configuration.
      Returns:
        a list of source uris that match with the query.
      Throws:
        `java.lang.Exception` - any error.

    - #### allLinksToXml

          public org.licas_xml.abs.Element allLinksToXml(Service theService,
                                                         boolean allLevels,
                                                         boolean includeValues)
                                                  throws java.lang.Exception

      Return all linked sources in XML format - permanent, dynamic or association.
      Parameters:
        `theService` - the parent service.
        `allLevels` - if true, return all 3 levels, if false only return the top link level references.
        `includeValues` - if false, return just the path and source info. If true, include other values as well.
      Returns:
        an XML representation of all linked sources.
      Throws:
        `java.lang.Exception` - any error.

    - #### permanentLinksToXml

          public org.licas_xml.abs.Element permanentLinksToXml(Service theService)
                                                        throws java.lang.Exception

      Return all permanent linked sources in XML format.
      Parameters:
        `theService` - the parent service.
      Returns:
        an XML representation of all linked sources.
      Throws:
        `java.lang.Exception` - any error.

    - #### associationLinksToXml

          public org.licas_xml.abs.Element associationLinksToXml(Service theService)
                                                          throws java.lang.Exception

      Return all association linked sources in XML format.
      Parameters:
        `theService` - the parent service.
      Returns:
        an XML representation of all linked sources.
      Throws:
        `java.lang.Exception` - any error.

    - #### dynamicLinksToXml

          public org.licas_xml.abs.Element dynamicLinksToXml(Service theService,
                                                             boolean allLevels,
                                                             boolean includeValues)
                                                      throws java.lang.Exception

      Return all dynamic linked sources in XML format.
      Parameters:
        `theService` - the parent service.
        `allLevels` - if true, return all 3 levels, if false only return the top link level references.
        `includeValues` - if false, return just the path and source info. If true, include other values as well.
      Returns:
        an XML representation of all linked sources.
      Throws:
        `java.lang.Exception` - any error.

    - #### xmlToDynamicLinks

          protected void xmlToDynamicLinks(Service theService,
                                           org.licas_xml.abs.Element linksXml)
                                    throws java.lang.Exception

      Parse the dynamic links descriptions and add to the service.
      Parameters:
        `theService` - the parent service.
        `linksXml` - a full set of dynamic links descriptions for the service.
      Throws:
        `java.lang.Exception` - any error.

    - #### passwordsPlusStateToXml

          public org.licas_xml.abs.Element passwordsPlusStateToXml(Service theService)
                                                            throws java.lang.Exception

      Serialize the stored passwords list and return as an XML-based description.
      Parameters:
        `theService` - the service to parse.
      Returns:
        an XML representation of all passwords, or null if the admin key is incorrect.
      Throws:
        `java.lang.Exception` - any error.