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

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.