org.licas

## Class ServiceLinks

- java.lang.Object
- - org.licas.ServiceLinks

-     public class ServiceLinks
      extends java.lang.Object

  This class stores all of the different service link types and processes them as required. This includes nested child services (not strictly links) and permanent or association links. The dynamic links are stored in the dynamic linking structure, but an XML-based description of that can be retrieved here as well.
  Author:
    Kieran Greer

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `java.util.ArrayList<java.lang.String>` | `childServices` The child service ids.
    `protected PasswordHandler` | `passwordHandler` The parent service's password handler
    `protected PermanentLink` | `permanentLinks` This stores references to other local services that are permanently linked to this one.
    `protected java.util.HashMap<java.lang.String,java.lang.Object>` | `serviceAssociations` This stores references to other, probably remote, services that this service knows about.
    `protected org.licas_xml.abs.Element` | `serviceRef` The parent service reference
    `protected java.lang.String` | `uuid` This is the ID of the parent component

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ServiceLinks(java.lang.String theUuid, org.licas_xml.abs.Element theServiceRef, PasswordHandler ph)` Create a new instance of ServiceLinks.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `addChildService(java.lang.String serviceID)` Add the service id as a nested child service.
    `boolean` | `addLinkFromService(java.lang.String serviceID, java.lang.Object theReference)` Add a link from another service locally in this service.
    `protected boolean` | `addLinkToService(java.lang.String serviceID, java.lang.Object theReference)` Add a link reference to another service locally in this service.
    `protected boolean` | `addServiceAssociation(java.lang.String serviceKey, java.lang.Object servicePath)` Add a new uri for a link to a (probably remote) service.
    `protected void` | `clearLinks(java.util.ArrayList<?> serviceIDs, java.lang.String adminKey)` Reset the linking structures, by removing links for the specified services.
    `protected void` | `clearLinks(java.lang.String adminKey)` Reset the linking structures.
    `boolean` | `createPermanentLinkTo(java.lang.String serviceTo, java.lang.String servicePassword, org.licas_xml.abs.Element servicePath)` Create a permanent link from this service to another service.
    `protected java.util.ArrayList<java.lang.Object>` | `getAllLinkToService()` Get all source references for a links to another service.
    `java.lang.Object` | `getLinkFromService(java.lang.String serviceID)` Get the source reference for a link from another service.
    `java.lang.Object` | `getLinkToService(java.lang.String serviceID)` Get the source reference for a link to another service.
    `PermanentLink` | `getPermanentLinks()` Get the list of permanent links.
    `java.util.ArrayList<org.licas_xml.abs.Element>` | `getServiceAssociations()` Get the list of (probably remote) service links to other known about services.
    `void` | `removeChildService(java.lang.String serviceID)` Remove the child service id from the metadata.
    `void` | `removeLinkFromService(java.lang.String serviceID)` Remove the local link from the specified service if it exists.
    `protected void` | `removeLinkToService(java.lang.String serviceID)` Remove the local link to the specified service if it exists.
    `boolean` | `removePermanentLinkTo(java.lang.String serviceTo, java.lang.String servicePassword, org.licas_xml.abs.Element servicePath)` Remove a permanent link from this service to another service.
    `protected void` | `removeServiceAssociation(java.lang.String serviceKey)` Remove a uri for a link to a (probably remote) service association.

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

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

- - ### Field Detail

    - #### uuid

          protected java.lang.String uuid

      This is the ID of the parent component

    - #### serviceRef

          protected org.licas_xml.abs.Element serviceRef

      The parent service reference

    - #### passwordHandler

          protected PasswordHandler passwordHandler

      The parent service's password handler

    - #### childServices

          public java.util.ArrayList<java.lang.String> childServices

      The child service ids. Values are the ids of type String.

    - #### permanentLinks

          protected PermanentLink permanentLinks

      This stores references to other local services that are permanently linked to this one. This forms the local network structure.

    - #### serviceAssociations

          protected java.util.HashMap<java.lang.String,java.lang.Object> serviceAssociations

      This stores references to other, probably remote, services that this service knows about. Could be called a link or just an association. The information is stored as String-based descriptions of the other services' full path locations.

  - ### Constructor Detail

    - #### ServiceLinks

          public ServiceLinks(java.lang.String theUuid,
                              org.licas_xml.abs.Element theServiceRef,
                              PasswordHandler ph)

      Create a new instance of ServiceLinks.
      Parameters:
        `theUuid` - the uuid of the parent service.
        `theServiceRef` - the parent service reference.
        `ph` - the parent service password handler.

  - ### Method Detail

    - #### clearLinks

          protected void clearLinks(java.lang.String adminKey)

      Reset the linking structures.
      Parameters:
        `adminKey` - the parent service's admin key to allow access.

    - #### clearLinks

          protected void clearLinks(java.util.ArrayList<?> serviceIDs,
                                    java.lang.String adminKey)
                             throws java.lang.Exception

      Reset the linking structures, by removing links for the specified services.
      Parameters:
        `serviceIDs` - list of services to remove linking info for.
        `adminKey` - the parent service's admin key to allow access.
      Throws:
        `java.lang.Exception` - any error.

    - #### addServiceAssociation

          protected boolean addServiceAssociation(java.lang.String serviceKey,
                                                  java.lang.Object servicePath)
                                           throws java.lang.Exception

      Add a new uri for a link to a (probably remote) service. This is simply an association link created from a single call. It is different to a permanent link in the sense that it probably does not make up any permanent network structure. It can act in the same way though. It is also different from a dynamic link which is built up over time through reinforcement. Including this link type simply covers the different types of service associations that you might want to make.
      Parameters:
        `serviceKey` - the key value that the service association is stored under.
        `servicePath` - the service association reference. It might not contain the key value.
      Returns:
        true if added or false if it already exists.
      Throws:
        `java.lang.Exception` - any other error.

    - #### removeServiceAssociation

          protected void removeServiceAssociation(java.lang.String serviceKey)
                                           throws java.lang.Exception

      Remove a uri for a link to a (probably remote) service association.
      Parameters:
        `serviceKey` - the key value that the service association is stored under.
      Throws:
        `java.lang.Exception` - any other error.

    - #### getServiceAssociations

          public java.util.ArrayList<org.licas_xml.abs.Element> getServiceAssociations()
                                                                                throws java.lang.Exception

      Get the list of (probably remote) service links to other known about services.
      Returns:
        the value of serviceAssociations, as a list of Elements.
      Throws:
        `java.lang.Exception` - any error.

    - #### createPermanentLinkTo

          public boolean createPermanentLinkTo(java.lang.String serviceTo,
                                               java.lang.String servicePassword,
                                               org.licas_xml.abs.Element servicePath)
                                        throws java.lang.Exception

      Create a permanent link from this service to another service. This method also calls the other service remotely to ask it to create a link to this service as well.
      Parameters:
        `serviceTo` - the unique ID of the service to create a link to.
        `servicePassword` - the password to call the other service.
        `servicePath` - the path to the other service.
      Returns:
        true if the link is successfully created.
      Throws:
        `java.lang.Exception` - any error.

    - #### removePermanentLinkTo

          public boolean removePermanentLinkTo(java.lang.String serviceTo,
                                               java.lang.String servicePassword,
                                               org.licas_xml.abs.Element servicePath)
                                        throws java.lang.Exception

      Remove a permanent link from this service to another service. This method also calls the other service remotely to ask it to remove the same link from reference to this service.
      Parameters:
        `serviceTo` - the unique ID of the service to remove a link to.
        `servicePassword` - the password to call the other service.
        `servicePath` - the path to the other service.
      Returns:
        true if the link is successfully removed.
      Throws:
        `java.lang.Exception` - any error.

    - #### addLinkToService

          protected boolean addLinkToService(java.lang.String serviceID,
                                             java.lang.Object theReference)

      Add a link reference to another service locally in this service.
      Parameters:
        `serviceID` - a unique id to identify the service.
        `theReference` - the source reference (Object or XML URI).
      Returns:
        true if the link is added or false if the id already exists.

    - #### removeLinkToService

          protected void removeLinkToService(java.lang.String serviceID)

      Remove the local link to the specified service if it exists. This should not be called directly, but is called through the `removePermanentLinkTo` method.
      Parameters:
        `serviceID` - the id of the service being linked to.

    - #### getAllLinkToService

          protected java.util.ArrayList<java.lang.Object> getAllLinkToService()

      Get all source references for a links to another service.
      Returns:
        a list of all source references, or null if no links exist.

    - #### getLinkToService

          public java.lang.Object getLinkToService(java.lang.String serviceID)

      Get the source reference for a link to another service.
      Parameters:
        `serviceID` - the id of the service linked to.
      Returns:
        the value of source or null if no link exists.

    - #### addLinkFromService

          public boolean addLinkFromService(java.lang.String serviceID,
                                            java.lang.Object theReference)

      Add a link from another service locally in this service. This method should not be called directly, but is done through the `createPermanentLinkTo` method on the remote service creating the link.
      Parameters:
        `serviceID` - a unique id to identify the service.
        `theReference` - the source reference (Object or XML URI).
      Returns:
        true if the link is added or false if the id already exists.

    - #### removeLinkFromService

          public void removeLinkFromService(java.lang.String serviceID)

      Remove the local link from the specified service if it exists. This method should not be called directly, but is done through the `removePermanentLinkTo` method on the remote service removing the link.
      Parameters:
        `serviceID` - the id of the service being linked to.

    - #### getLinkFromService

          public java.lang.Object getLinkFromService(java.lang.String serviceID)

      Get the source reference for a link from another service.
      Parameters:
        `serviceID` - the id of the service linked to.
      Returns:
        the value of source or null if no link exists.

    - #### getPermanentLinks

          public PermanentLink getPermanentLinks()

      Get the list of permanent links.
      Returns:
        the value of permanentLinks.

    - #### addChildService

          public boolean addChildService(java.lang.String serviceID)

      Add the service id as a nested child service.
      Parameters:
        `serviceID` - the service id for a nested child service.
      Returns:
        true if added or false if the meta uuid already exists.

    - #### removeChildService

          public void removeChildService(java.lang.String serviceID)

      Remove the child service id from the metadata.
      Parameters:
        `serviceID` - the service id to remove.