org.licas.service.link

## Class Link

- java.lang.Object
- - java.lang.Thread
  - - org.licas.module.LicasModule
    - - org.licas.module.FrameworkModule
      - - org.licas.module.ServiceModule
        - - org.licas.service.link.Link

- All Implemented Interfaces:
    java.lang.Runnable, ServiceDef
  Direct Known Subclasses:
    Link_B, Link_M, Link_NM

      public abstract class Link
      extends ServiceModule

  This is an abstract base class for a set of linking methods to dynamically link components. The derived class should be added as a utility service, to any service requiring the dynamic linking mechanism. A `Tree` structure is used to store any related path information to a set of sources, that are themselves stored in a `Thresholds` structure at the end of each path, inside a `TreeNode`. There are three default derived versions:

  `Link_B` does not have any memory restrictions. It will also only increment weight values and not decrement them.

  `Link_NM` does not have any memory restrictions, but will decrement weight values as well as increment them.

  `Link_M` restricts the linking structure based on the memory (allowed numbers of entries) and some other options. It also increments and decrements weight values.

  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
    Modifier and Type | Field and Description
    --- | ---
    `protected int` | `linkCount` Total number of sources at the link level
    `protected LinkSpec` | `linkSpec` This stores the original linking configuration, which is used to initialise the thresholds structures.
    `protected org.ai_heuristic.tree.Tree` | `linkTree` The dynamic links structure that lists source references.
    `protected int` | `maxNegative` The maximum number of allowed negative entries for each link
    `protected int` | `monitorCount` Total number of sources at the monitor level
    `protected int` | `possibleCount` Total number of sources at the possible level
    `protected long` | `timeStamp` A time stamp indicating the time that a particular source reference is added.

    - ### 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
    `Link()` Creates a new instance of Link.
    `Link(Service service, PasswordHandler pHandler)` Creates a new instance of Link.
    `Link(Service service, PasswordHandler pHandler, LinkSpec thisLinkSpec)` Creates a new instance of Link.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.util.ArrayList<?>` | `addDynamicLinks(java.util.ArrayList sourceList)` Add sources related by some event to the component.
    `java.util.ArrayList<?>` | `addDynamicLinks(java.util.ArrayList sourceList, java.util.ArrayList<java.lang.String> conceptList)` Add sources related by some event to the component.
    `java.util.ArrayList<?>` | `addDynamicLinks(java.util.ArrayList sourceList, java.util.ArrayList<java.lang.String> conceptList, java.util.ArrayList negative)` Add sources related by some event to the component.
    `java.lang.String` | `dynamicLinksToString(boolean allLevels, java.lang.String indent)` Return all linked sources as a string-based description.
    `org.licas_xml.abs.Element` | `dynamicLinksToXml(boolean allLevels, boolean configValues)` Return all linked sources as a list of XML elements.
    `int` | `getCurrentCount(int thresholdType)` Get the current number of entries for the threshold level.
    `java.util.ArrayList<org.licas_xml.abs.Element>` | `getLinkElements(org.licas_xml.abs.Element rootElem)` Parse the XML description to retrieve a list of linked sources from it.
    `java.util.ArrayList<java.lang.Object>` | `getLinkSources(java.util.ArrayList<java.lang.String> concepts, java.util.ArrayList<java.lang.Object> negativeConcepts)` Return a list of sources linked to the current source, using the specified concept path.
    `org.ai_heuristic.tree.Tree` | `getLinkTree()` Get the list of related sources
    `long` | `getThresholdCount(int thresholdLevel)` Get the total number of sources stored as links in all threshold structures.
    `long` | `getThresholdCount(org.ai_heuristic.tree.TreeNode treeNode, int thresholdLevel)` Get the total number of sources stored as links in all threshold structures.
    `java.util.HashMap<java.lang.String,java.lang.Long>` | `getTotalInstancesCount()` Count the number of instances of each source type in the different threshold structures.
    `protected void` | `getTotalInstancesCount(org.ai_heuristic.tree.TreeNode treeNode, java.util.HashMap<java.lang.String,java.lang.Long> totalInstances)` Count the number of instances of each source type in the different threshold structures.
    `protected java.lang.String` | `getUuid(java.lang.Object componentObj)` Return the id of the component.
    `org.licas_xml.abs.Element` | `linkQuery(LinkQueryConfig queryConfig)` Perform a query over the link paths to return matching sources.
    `protected void` | `resetRelatedThresholds()` Reset all end linking threshold structures to the original specification.
    `protected void` | `resetRelatedThresholds(org.ai_heuristic.tree.TreeNode nextSources)` Reset the next end linking threshold structure to the original specification.
    `protected void` | `resetUpdatedThresholds()` Reset all end linking threshold structure updates to zero, for a new update batch.
    `protected void` | `resetUpdatedThresholds(org.ai_heuristic.tree.TreeNode nextSources)` Reset the next end linking threshold structure updates to zero, for a new update batch.
    `void` | `resetValues()` Reset the values
    `void` | `setThresholds(org.licas_xml.abs.Element thresholdsXml)` Set the initial threshold values for this component.
    `void` | `setThresholds(LinkSpec copyLinkSpec)` Set the initial threshold values for this component.
    `void` | `setThresholds(Thresholds copyTo)` Set the threshold values for the `Thresholds` parameter.
    `protected abstract void` | `updateThresholds(Thresholds theThresholds, java.util.ArrayList<java.lang.String> conceptPath, java.util.ArrayList newSources, long timeStamp, java.util.ArrayList sourcesAdded, java.util.ArrayList negative)` Update the linkSpec structure.
    `void` | `xmlToDynamicLinks(org.licas_xml.abs.Element linksElem)` Parse the xml description and fill the link spec and structure with the dynamic links.

    - ### Methods inherited from class org.licas.module.ServiceModule

      `getShutDown, interrupt, setShutDown, setShutDown`

    - ### Methods inherited from class org.licas.module.FrameworkModule

      `canAccess, canAccessTemp, getPasswordHandler, getPasswordHandler, getServerPassword, 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, run, 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.ServiceDef

      `getUUID, setJarFile, setUUID`

- - ### Field Detail

    - #### timeStamp

          protected long timeStamp

      A time stamp indicating the time that a particular source reference is added. This is then stored in the linking structure itself.

    - #### linkTree

          protected org.ai_heuristic.tree.Tree linkTree

      The dynamic links structure that lists source references. The linking path now uses a Tree structure. Each node name is the path value and the node value can be a linking structure. Each node also stores other child nodes, for the path structure.

    - #### linkSpec

          protected LinkSpec linkSpec

      This stores the original linking configuration, which is used to initialise the thresholds structures.

    - #### linkCount

          protected int linkCount

      Total number of sources at the link level

    - #### monitorCount

          protected int monitorCount

      Total number of sources at the monitor level

    - #### possibleCount

          protected int possibleCount

      Total number of sources at the possible level

    - #### maxNegative

          protected int maxNegative

      The maximum number of allowed negative entries for each link

  - ### Constructor Detail

    - #### Link

          public Link()
               throws java.lang.Exception

      Creates a new instance of Link. Need to call `setServiceDetails` later.
      Throws:
        `java.lang.Exception` - any error.

    - #### Link

          public Link(Service service,
                      PasswordHandler pHandler)
               throws java.lang.Exception

      Creates a new instance of Link.
      Parameters:
        `service` - the parent service.
        `pHandler` - the parent password handler.
      Throws:
        `java.lang.Exception` - any error.

    - #### Link

          public Link(Service service,
                      PasswordHandler pHandler,
                      LinkSpec thisLinkSpec)
               throws java.lang.Exception

      Creates a new instance of Link.
      Parameters:
        `service` - the parent service.
        `pHandler` - the parent password handler.
        `thisLinkSpec` - the config to use for initialising the thresholds structures.
      Throws:
        `java.lang.Exception` - any error.

  - ### Method Detail

    - #### updateThresholds

          protected abstract void updateThresholds(Thresholds theThresholds,
                                                   java.util.ArrayList<java.lang.String> conceptPath,
                                                   java.util.ArrayList newSources,
                                                   long timeStamp,
                                                   java.util.ArrayList sourcesAdded,
                                                   java.util.ArrayList negative)
                                            throws java.lang.Exception

      Update the linkSpec structure. Add or update the new sources references and also add these to the added sources list.
      Parameters:
        `theThresholds` - the linkSpec structure.
        `conceptPath` - a preferred path to find in the tree.
        `newSources` - list of sources to add or update.
        `timeStamp` - time stamp for update.
        `sourcesAdded` - a list of all added sources over all of the update calls.
        `negative` - a list of negative source results.
      Throws:
        `java.lang.Exception` - any error.

    - #### resetValues

          public void resetValues()

      Reset the values

    - #### setThresholds

          public void setThresholds(LinkSpec copyLinkSpec)
                             throws java.lang.Exception

      Set the initial threshold values for this component. This is the method to call to initialise the threshold values. All other linking structures that are created in this service are then initialised with the same values that are set here.
      Parameters:
        `copyLinkSpec` - a full config description for any threshold objects.
      Throws:
        `java.lang.Exception` - any error.

    - #### setThresholds

          public void setThresholds(org.licas_xml.abs.Element thresholdsXml)
                             throws java.lang.Exception

      Set the initial threshold values for this component. This is the method to call to initialise the threshold values. All other linking structures that are created in this service are then initialised the same values that are set here. This method parses an XML-based description of the initial config.
      Parameters:
        `thresholdsXml` - the root config element.
      Throws:
        `java.lang.Exception` - any error.

    - #### setThresholds

          public void setThresholds(Thresholds copyTo)
                             throws java.lang.Exception

      Set the threshold values for the `Thresholds` parameter. The object that is passed in is set with the default values for this service.
      Parameters:
        `copyTo` - the threshold object to set values for.
      Throws:
        `java.lang.Exception` - any error.

    - #### resetRelatedThresholds

          protected void resetRelatedThresholds()
                                         throws java.lang.Exception

      Reset all end linking threshold structures to the original specification.
      Throws:
        `java.lang.Exception` - any error.

    - #### resetRelatedThresholds

          protected void resetRelatedThresholds(org.ai_heuristic.tree.TreeNode nextSources)
                                         throws java.lang.Exception

      Reset the next end linking threshold structure to the original specification.
      Parameters:
        `nextSources` - next sources root node.
      Throws:
        `java.lang.Exception` - any error.

    - #### resetUpdatedThresholds

          protected void resetUpdatedThresholds()
                                         throws java.lang.Exception

      Reset all end linking threshold structure updates to zero, for a new update batch.
      Throws:
        `java.lang.Exception` - any error.

    - #### resetUpdatedThresholds

          protected void resetUpdatedThresholds(org.ai_heuristic.tree.TreeNode nextSources)
                                         throws java.lang.Exception

      Reset the next end linking threshold structure updates to zero, for a new update batch.
      Parameters:
        `nextSources` - next sources root node.
      Throws:
        `java.lang.Exception` - any error.

    - #### addDynamicLinks

          public java.util.ArrayList<?> addDynamicLinks(java.util.ArrayList sourceList)
                                                 throws java.lang.Exception

      Add sources related by some event to the component. A concept list with a single dummy value of `Const`.`LINKS` is added.
      Parameters:
        `sourceList` - the list of source URIs to add, or link URIs to update.
      Returns:
        ArrayList a list of the sources that have been added.
      Throws:
        `java.lang.Exception` - any error.

    - #### addDynamicLinks

          public java.util.ArrayList<?> addDynamicLinks(java.util.ArrayList sourceList,
                                                        java.util.ArrayList<java.lang.String> conceptList)
                                                 throws java.lang.Exception

      Add sources related by some event to the component.
      Parameters:
        `sourceList` - the list of source URIs to add, or link URIs to update.
        `conceptList` - the list of concepts that make up the linking path. This should not be null and include at least 1 value.
      Returns:
        ArrayList a list of the sources that have been added.
      Throws:
        `java.lang.Exception` - any error.

    - #### addDynamicLinks

          public java.util.ArrayList<?> addDynamicLinks(java.util.ArrayList sourceList,
                                                        java.util.ArrayList<java.lang.String> conceptList,
                                                        java.util.ArrayList negative)
                                                 throws java.lang.Exception

      Add sources related by some event to the component.
      Parameters:
        `sourceList` - the list of source URIs to add, or link URIs to update.
        `conceptList` - the list of concepts that make up the linking path. This should not be null and include at least 1 value. If not, then a concept list with a single dummy value of `Const`.`LINKS` is used.
        `negative` - a list of negative comparisons. This can be empty.
      Returns:
        ArrayList a list of the sources that have been added.
      Throws:
        `java.lang.Exception` - any error.

    - #### getTotalInstancesCount

          public java.util.HashMap<java.lang.String,java.lang.Long> getTotalInstancesCount()
                                                                                    throws java.lang.Exception

      Count the number of instances of each source type in the different threshold structures.
      Returns:
        a list of the total counts. Keys are the source types and values are the instance counts.
      Throws:
        `java.lang.Exception` - any error.

    - #### getTotalInstancesCount

          protected void getTotalInstancesCount(org.ai_heuristic.tree.TreeNode treeNode,
                                                java.util.HashMap<java.lang.String,java.lang.Long> totalInstances)
                                         throws java.lang.Exception

      Count the number of instances of each source type in the different threshold structures.
      Parameters:
        `treeNode` - next sources list.
        `totalInstances` - instances count.
      Throws:
        `java.lang.Exception` - any error.

    - #### getThresholdCount

          public long getThresholdCount(int thresholdLevel)

      Get the total number of sources stored as links in all threshold structures.
      Parameters:
        `thresholdLevel` - the threshold level: link, monitor or possible.
      Returns:
        the total number of link sources

    - #### getThresholdCount

          public long getThresholdCount(org.ai_heuristic.tree.TreeNode treeNode,
                                        int thresholdLevel)

      Get the total number of sources stored as links in all threshold structures.
      Parameters:
        `treeNode` - next list of sources.
        `thresholdLevel` - the threshold level: link, monitor or possible.
      Returns:
        the total number of link sources

    - #### dynamicLinksToString

          public java.lang.String dynamicLinksToString(boolean allLevels,
                                                       java.lang.String indent)
                                                throws java.lang.Exception

      Return all linked sources as a string-based description.
      Parameters:
        `allLevels` - if true, return all 3 levels, if false only return the top link level references.
        `indent` - for formatting purposes, can be null.
      Returns:
        an string-based representation of the linked sources.
      Throws:
        `java.lang.Exception` - any error.

    - #### dynamicLinksToXml

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

      Return all linked sources as a list of XML elements.
      Parameters:
        `allLevels` - if true, return all 3 levels, if false only return the top link level references.
        `configValues` - if false, return just the path and source info. If true, include other values, such as config, as well.
      Returns:
        an XML representation of all linked sources.
      Throws:
        `java.lang.Exception` - any error.

    - #### getLinkElements

          public java.util.ArrayList<org.licas_xml.abs.Element> getLinkElements(org.licas_xml.abs.Element rootElem)

      Parse the XML description to retrieve a list of linked sources from it.
      Parameters:
        `rootElem` - the root tree element to parse from.
      Returns:
        a list of all the link elements in the input parameter.

    - #### xmlToDynamicLinks

          public void xmlToDynamicLinks(org.licas_xml.abs.Element linksElem)
                                 throws java.lang.Exception

      Parse the xml description and fill the link spec and structure with the dynamic links.
      Parameters:
        `linksElem` - the dynamic links description.
      Throws:
        `java.lang.Exception` - any error.

    - #### getLinkSources

          public java.util.ArrayList<java.lang.Object> getLinkSources(java.util.ArrayList<java.lang.String> concepts,
                                                                      java.util.ArrayList<java.lang.Object> negativeConcepts)
                                                               throws java.lang.Exception

      Return a list of sources linked to the current source, using the specified concept path.
      Parameters:
        `concepts` - the list of concepts to match the path keys to.
        `negativeConcepts` - a list of concepts that would stop the link being used. This is typically `null`.
      Returns:
        a list of uris to linked sources.
      Throws:
        `java.lang.Exception` - any error.

    - #### linkQuery

          public org.licas_xml.abs.Element linkQuery(LinkQueryConfig queryConfig)
                                              throws java.lang.Exception

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

    - #### getCurrentCount

          public int getCurrentCount(int thresholdType)

      Get the current number of entries for the threshold level.
      Parameters:
        `thresholdType` - the threshold structure type.
      Returns:
        the number of entries.

    - #### getUuid

          protected java.lang.String getUuid(java.lang.Object componentObj)

      Return the id of the component.
      Parameters:
        `componentObj` - the component representation.
      Returns:
        the id of the component, or null if the component is null.

    - #### getLinkTree

          public org.ai_heuristic.tree.Tree getLinkTree()

      Get the list of related sources
      Returns:
        the value of linkTree.