org.licas.service.link

## Class Link_M

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

- All Implemented Interfaces:
    java.lang.Runnable, ServiceDef

      public class Link_M
      extends Link

  This is an implementation of a linking service that also considers memory restrictions. This is a much more complex operation, where the maximum allowed number of entries at each level of the linking structure can be specified. Entries might then need to be removed or re-placed to add a new one.
  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 java.util.HashMap<java.lang.String,java.lang.Integer>` | `linkBorrowed` Link source slots borrowed from another component.
    `protected int` | `linkBorrowedCount` Total number of link sources borrowed
    `protected java.util.HashMap<java.lang.String,java.lang.Integer>` | `linkLent` Link source slots lent to another component.
    `protected Thresholds` | `minThresholds` The threshold values that store the currently selected minimum source.
    `protected java.util.HashMap<java.lang.String,java.lang.Integer>` | `monitorBorrowed` Monitor source slots borrowed from another component.
    `protected int` | `monitorBorrowedCount` Total number of monitor sources borrowed
    `protected java.util.HashMap<java.lang.String,java.lang.Integer>` | `monitorLent` Monitor source slots lent to another component.
    `protected java.util.HashMap<java.lang.String,java.lang.Integer>` | `possibleBorrowed` Possible source slots borrowed from another component.
    `protected int` | `possibleBorrowedCount` Total number of possible sources borrowed
    `protected java.util.HashMap<java.lang.String,java.lang.Integer>` | `possibleLent` Possible source slots lent to another component.

    - ### Fields inherited from class org.licas.service.link.Link

      `linkCount, linkSpec, linkTree, maxNegative, monitorCount, possibleCount, timeStamp`

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

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected boolean` | `addNewSource(java.util.ArrayList<java.lang.String> conceptPath, java.lang.Object source, Thresholds thisThresholds, long timeStamp, boolean updateIndividual)` Add or update the new source swapping other sources if required.
    `int` | `askForMemory(int thresholdType, int slotNumber)` Ask the components stored here for any available memory they are not using.
    `void` | `changeBorrowedMemory(java.lang.String componentID, int thresholdType, int memory)` Update the appropriate memory structure to record the new borrowed amount of memory.
    `void` | `changeCurrentMemory(int thresholdType, int memory)` Update the appropriate memory structure to record the new allowed amount of memory.
    `void` | `changeLentMemory(java.lang.String componentID, int thresholdType, int memory)` Update the appropriate memory structure to record the new lent amount of memory.
    `void` | `checkAllMemory()` Check memory in all structures to make sure it totals to correct amount.
    `void` | `checkCurrentMemory(int thresholdType)` Check that the memory for the threshold level is OK.
    `int` | `getCurrentMemory(int thresholdType)` Get the current working amount of memory for the threshold level.
    `int` | `getMemory(int thresholdType, int slotNumber, java.util.ArrayList<java.lang.String> conceptPath)` Tell a component to give up some memory as the lender wants it back.
    `protected ThresholdSource` | `getMinimumSource(int thresholdType, java.util.ArrayList<java.lang.String> keyValues, java.util.ArrayList<java.lang.String> conceptPath, org.ai_heuristic.tree.TreeNode treeNode, ThresholdSource minTSource)` Get the minimum source details.
    `protected ThresholdSource` | `getMinimumSource(int thresholdType, java.util.ArrayList<java.lang.String> conceptPath, java.lang.String sourceType)` Get the minimum source details in the specified threshold structure.
    `int` | `getOriginalMemory(int thresholdType)` Get the original working amount of memory for the threshold level.
    `int` | `memoryToLend(int thresholdType)` Return the amount of memory that this component can lend.
    `protected void` | `moveSourceDown(Thresholds theThresholds, int thresholdType, java.lang.Object source)` Move the specified source in the linkSpec structure down to the next level.
    `protected void` | `moveSourcesDown(java.util.ArrayList<java.lang.String> conceptPath, java.util.ArrayList<java.lang.Object> sources, Thresholds thisThresholds)` Move any sources not used in the answer down a level if required.
    `protected void` | `moveSourceUp(Thresholds theThresholds, int thresholdType, java.lang.Object source)` Move the specified source in the linkSpec structure up to the next level.
    `void` | `releaseMemory(java.lang.String componentID, int thresholdType, int slotNumber, java.util.ArrayList<java.lang.String> conceptPath)` The component must remove the specified number of slots from its relative structure.
    `void` | `removeSource(Thresholds theThresholds, int thresholdType, java.lang.Object source)` Remove the specified source from the linkSpec structure.
    `void` | `resetValues()` Reset the values
    `int` | `totalBorrowedMemory(int thresholdLevel)` Return the total amount of memory this component has borrowed.
    `int` | `totalLentMemory(int thresholdLevel)` Return the total amount of memory this component has lent.
    `protected 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.

    - ### Methods inherited from class org.licas.service.link.Link

      `addDynamicLinks, addDynamicLinks, addDynamicLinks, dynamicLinksToString, dynamicLinksToXml, getCurrentCount, getLinkElements, getLinkSources, getLinkTree, getThresholdCount, getThresholdCount, getTotalInstancesCount, getTotalInstancesCount, getUuid, linkQuery, resetRelatedThresholds, resetRelatedThresholds, resetUpdatedThresholds, resetUpdatedThresholds, setThresholds, setThresholds, setThresholds, xmlToDynamicLinks`

    - ### 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

    - #### minThresholds

          protected Thresholds minThresholds

      The threshold values that store the currently selected minimum source. Each path in the linking structure stores a linkSpec structure at the end, which then stores the references to the linked sources at the different levels. This field relates to the minimum source at the end of a path, which might then be removed if the linking structure becomes full.

    - #### linkBorrowedCount

          protected int linkBorrowedCount

      Total number of link sources borrowed

    - #### monitorBorrowedCount

          protected int monitorBorrowedCount

      Total number of monitor sources borrowed

    - #### possibleBorrowedCount

          protected int possibleBorrowedCount

      Total number of possible sources borrowed

    - #### linkLent

          protected java.util.HashMap<java.lang.String,java.lang.Integer> linkLent

      Link source slots lent to another component. Keys are the component ids and values are the number of slots.

    - #### linkBorrowed

          protected java.util.HashMap<java.lang.String,java.lang.Integer> linkBorrowed

      Link source slots borrowed from another component. Keys are the component ids and values are the number of slots.

    - #### monitorLent

          protected java.util.HashMap<java.lang.String,java.lang.Integer> monitorLent

      Monitor source slots lent to another component. Keys are the component ids and values are the number of slots.

    - #### monitorBorrowed

          protected java.util.HashMap<java.lang.String,java.lang.Integer> monitorBorrowed

      Monitor source slots borrowed from another component. Keys are the component ids and values are the number of slots.

    - #### possibleLent

          protected java.util.HashMap<java.lang.String,java.lang.Integer> possibleLent

      Possible source slots lent to another component. Keys are the component ids and values are the number of slots.

    - #### possibleBorrowed

          protected java.util.HashMap<java.lang.String,java.lang.Integer> possibleBorrowed

      Possible source slots borrowed from another component. Keys are the component ids and values are the number of slots.

  - ### Constructor Detail

    - #### Link_M

          public Link_M()
                 throws java.lang.Exception

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

    - #### Link_M

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

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

    - #### Link_M

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

      Creates a new instance of Link_M.
      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

    - #### resetValues

          public void resetValues()

      Reset the values
      Overrides:
        `resetValues` in class `Link`

    - #### updateThresholds

          protected 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.
      Specified by:
        `updateThresholds` in class `Link`
      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.

    - #### addNewSource

          protected boolean addNewSource(java.util.ArrayList<java.lang.String> conceptPath,
                                         java.lang.Object source,
                                         Thresholds thisThresholds,
                                         long timeStamp,
                                         boolean updateIndividual)
                                  throws java.lang.Exception

      Add or update the new source swapping other sources if required.
      Parameters:
        `conceptPath` - a preferred path to find in the tree.
        `source` - the representation of the source used.
        `thisThresholds` - the parent thresholds structure.
        `timeStamp` - the current time for adding sources.
        `updateIndividual` - true if update individual links only.
      Returns:
        true if new source is added.
      Throws:
        `java.lang.Exception` - any error.

    - #### moveSourcesDown

          protected void moveSourcesDown(java.util.ArrayList<java.lang.String> conceptPath,
                                         java.util.ArrayList<java.lang.Object> sources,
                                         Thresholds thisThresholds)
                                  throws java.lang.Exception

      Move any sources not used in the answer down a level if required.
      Parameters:
        `conceptPath` - a preferred path to find in the tree.
        `sources` - the representations of the sources used.
        `thisThresholds` - the linkSpec structure.
      Throws:
        `java.lang.Exception` - any error.

    - #### getMinimumSource

          protected ThresholdSource getMinimumSource(int thresholdType,
                                                     java.util.ArrayList<java.lang.String> conceptPath,
                                                     java.lang.String sourceType)
                                              throws java.lang.Exception

      Get the minimum source details in the specified threshold structure. Also store the linkSpec structure reference.
      Parameters:
        `thresholdType` - The threshold structure to query: link, monitor or possible.
        `conceptPath` - a preferred path to find in the tree.
        `sourceType` - the type of source currently being added.
      Returns:
        a full path to the minimum source.
      Throws:
        `java.lang.Exception` - any error.

    - #### getMinimumSource

          protected ThresholdSource getMinimumSource(int thresholdType,
                                                     java.util.ArrayList<java.lang.String> keyValues,
                                                     java.util.ArrayList<java.lang.String> conceptPath,
                                                     org.ai_heuristic.tree.TreeNode treeNode,
                                                     ThresholdSource minTSource)
                                              throws java.lang.Exception

      Get the minimum source details.
      Parameters:
        `thresholdType` - The threshold structure to query: link, monitor or possible.
        `keyValues` - list of actual related sources key values.
        `conceptPath` - a preferred path to find in the tree.
        `treeNode` - next related sources structure.
        `minTSource` - the current minimum threshold source.
      Returns:
        the minimum retrieved threshold source structure.
      Throws:
        `java.lang.Exception` - any error.

    - #### moveSourceDown

          protected void moveSourceDown(Thresholds theThresholds,
                                        int thresholdType,
                                        java.lang.Object source)
                                 throws java.lang.Exception

      Move the specified source in the linkSpec structure down to the next level.
      Parameters:
        `theThresholds` - the linkSpec structure.
        `thresholdType` - the threshold level moving down from.
        `source` - the source representation.
      Throws:
        `java.lang.Exception` - any error.

    - #### moveSourceUp

          protected void moveSourceUp(Thresholds theThresholds,
                                      int thresholdType,
                                      java.lang.Object source)
                               throws java.lang.Exception

      Move the specified source in the linkSpec structure up to the next level.
      Parameters:
        `theThresholds` - the linkSpec structure.
        `thresholdType` - the threshold level moving up from.
        `source` - the source representation.
      Throws:
        `java.lang.Exception` - any error.

    - #### removeSource

          public void removeSource(Thresholds theThresholds,
                                   int thresholdType,
                                   java.lang.Object source)
                            throws java.lang.Exception

      Remove the specified source from the linkSpec structure.
      Parameters:
        `theThresholds` - the linkSpec structure.
        `thresholdType` - the threshold level.
        `source` - the source representation.
      Throws:
        `java.lang.Exception` - any error.

    - #### changeCurrentMemory

          public void changeCurrentMemory(int thresholdType,
                                          int memory)
                                   throws java.lang.Exception

      Update the appropriate memory structure to record the new allowed amount of memory.
      Parameters:
        `thresholdType` - the threshold structure type.
        `memory` - the amount of change. Can be positive or negative.
      Throws:
        `java.lang.Exception` - any error.

    - #### releaseMemory

          public void releaseMemory(java.lang.String componentID,
                                    int thresholdType,
                                    int slotNumber,
                                    java.util.ArrayList<java.lang.String> conceptPath)
                             throws java.lang.Exception

      The component must remove the specified number of slots from its relative structure.
      Parameters:
        `componentID` - the id for the component retrieving its memory.
        `thresholdType` - the threshold structure.
        `slotNumber` - the number of slots to release.
        `conceptPath` - a preferred path to find in the tree.
      Throws:
        `java.lang.Exception` - any error.

    - #### askForMemory

          public int askForMemory(int thresholdType,
                                  int slotNumber)
                           throws java.lang.Exception

      Ask the components stored here for any available memory they are not using.
      Parameters:
        `thresholdType` - the threshold structure type.
        `slotNumber` - number of slots to release.
      Returns:
        the total amount of memory that can be borrowed.
      Throws:
        `java.lang.Exception` - any error.

    - #### getMemory

          public int getMemory(int thresholdType,
                               int slotNumber,
                               java.util.ArrayList<java.lang.String> conceptPath)
                        throws java.lang.Exception

      Tell a component to give up some memory as the lender wants it back.
      Parameters:
        `thresholdType` - the threshold structure type.
        `slotNumber` - number of slots to release.
        `conceptPath` - a preferred path to find in the tree.
      Returns:
        int the amount of memory retrieved.
      Throws:
        `java.lang.Exception` - any error.

    - #### memoryToLend

          public int memoryToLend(int thresholdType)
                           throws java.lang.Exception

      Return the amount of memory that this component can lend.
      Parameters:
        `thresholdType` - the threshold structure type.
      Returns:
        the amount of memory that can be lent.
      Throws:
        `java.lang.Exception` - any error.

    - #### changeLentMemory

          public void changeLentMemory(java.lang.String componentID,
                                       int thresholdType,
                                       int memory)
                                throws java.lang.Exception

      Update the appropriate memory structure to record the new lent amount of memory.
      Parameters:
        `componentID` - the id of the component lending/retrieving its memory.
        `thresholdType` - the threshold structure type.
        `memory` - the amount of change. Can be positive or negative.
      Throws:
        `java.lang.Exception` - any error.

    - #### changeBorrowedMemory

          public void changeBorrowedMemory(java.lang.String componentID,
                                           int thresholdType,
                                           int memory)
                                    throws java.lang.Exception

      Update the appropriate memory structure to record the new borrowed amount of memory.
      Parameters:
        `componentID` - the id of the component lending/retrieving its memory.
        `thresholdType` - the threshold structure type.
        `memory` - the amount of change. Can be positive or negative.
      Throws:
        `java.lang.Exception` - any error.

    - #### totalBorrowedMemory

          public int totalBorrowedMemory(int thresholdLevel)
                                  throws java.lang.Exception

      Return the total amount of memory this component has borrowed.
      Parameters:
        `thresholdLevel` - the threshold structure level.
      Returns:
        the amount of borrowed memory at the specified level.
      Throws:
        `java.lang.Exception` - any error.

    - #### totalLentMemory

          public int totalLentMemory(int thresholdLevel)
                              throws java.lang.Exception

      Return the total amount of memory this component has lent.
      Parameters:
        `thresholdLevel` - the threshold structure level.
      Returns:
        the amount of lent memory at the specified level.
      Throws:
        `java.lang.Exception` - any error.

    - #### checkCurrentMemory

          public void checkCurrentMemory(int thresholdType)
                                  throws java.lang.Exception

      Check that the memory for the threshold level is OK.
      Parameters:
        `thresholdType` - the threshold level.
      Throws:
        `java.lang.Exception` - any error.

    - #### checkAllMemory

          public void checkAllMemory()
                              throws java.lang.Exception

      Check memory in all structures to make sure it totals to correct amount.
      Throws:
        `java.lang.Exception` - any error.

    - #### getCurrentMemory

          public int getCurrentMemory(int thresholdType)

      Get the current working amount of memory for the threshold level.
      Parameters:
        `thresholdType` - the threshold structure type.
      Returns:
        the amount of memory lent.

    - #### getOriginalMemory

          public int getOriginalMemory(int thresholdType)

      Get the original working amount of memory for the threshold level.
      Parameters:
        `thresholdType` - the threshold structure type.
      Returns:
        the amount of memory lent.