story.dbcore.links
Class RelatedNodes

java.lang.Object
  extended by story.dbcore.links.RelatedNodes
Direct Known Subclasses:
WritableRelatedNodes

public class RelatedNodes
extends java.lang.Object

A class representing one node's relationships with other nodes under a certain link type. Contains both data for one node's immediate links of some type to other nodes, as well as logic for traversing graphs and compiling LinkSets, which are essentially query results. Instances of this class may be passed around as results to searches or whenever a node's related nodes must be communicated. Thus it is read-only. High-level classes shouldn't try to construct instances of this class. Ask your DBCoreInterface for one instead.

The difference between RelatedNodes and LinkSet is that RelatedNodes always reflects the underlying data while LinkSet is a snapshot. (Also see numberOfLinks and numRelatedNodes functions). The difference between RelatedNodes and LinkTable/LinkTableSet is that the latter two provide a data structure for RelatedNodes to store the link data, and RelatedNodes then applies logic.


Method Summary
 LinkLabelAddress findLinkLabelAddress(GenericNode relatedNode, LinkLabel label)
          Searches to see if the node is related to some particular node by a particular label, and if so, returns the LinkLabelAddress of that label.
 LinkSet getLinkSet(boolean overrideInference)
          Compile and reveal a LinkSet of nodes related to this node.
 boolean isDirectlyRelatedTo(GenericNode relatedNode)
          Determines whether or not the related nodes include a particular node, regardless of particular labeling.
 boolean isDirectlyRelatedTo(GenericNode relatedNode, LinkLabelAddress labelAddress)
          Determines whether or not the related nodes includes a particular node and a particular label.
 boolean isIndirectlyRelatedTo(GenericNode relatedNode)
          Determines whether or not the related nodes include a particular node, regardless of particular labeling.
 int numberOfLinks()
          Return the number of total links associated with this node, including multiple links for the same related node.
 int numRelatedNodes()
          Return the number nodes directly related to this node, matter how many labels are associated with each node.
 java.lang.StringBuffer render()
          Version of render whose overrideInference parameter defaults to false.
 java.lang.StringBuffer render(boolean overrideInference)
          Render the data structure as a text table.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

isDirectlyRelatedTo

public boolean isDirectlyRelatedTo(GenericNode relatedNode,
                                   LinkLabelAddress labelAddress)
                            throws Scheherexception
Determines whether or not the related nodes includes a particular node and a particular label.

If a node is indeed related, but of one or more distinct labels, this will still return false.

Note that this function only matches to direct node-to-node links. It will never return true for nodes separated by 2 or more degrees, since such nodes are never linked by a single LinkLabel.

This version takes a LinkLabelAddress, and searches for that exact label (i.e., so addressed) among the links between the two nodes. See other version that takes LinkLabel.

Parameters:
relatedNode - The possibly related node you're curious about.
label - The exact label that the related node would have.
Throws:
Scheherexception

findLinkLabelAddress

public LinkLabelAddress findLinkLabelAddress(GenericNode relatedNode,
                                             LinkLabel label)
                                      throws Scheherexception
Searches to see if the node is related to some particular node by a particular label, and if so, returns the LinkLabelAddress of that label. Returns null if there is no such label linking the two nodes.

Parameters:
relatedNode - The possibly related node you're curious about.
label - The exact label that the related node would have.
Throws:
Scheherexception

isDirectlyRelatedTo

public boolean isDirectlyRelatedTo(GenericNode relatedNode)
                            throws Scheherexception
Determines whether or not the related nodes include a particular node, regardless of particular labeling. In other words, determines whether there is at least one labeled relation to some node.

Note that this function only matches to direct node-to-node links. It will never return true for nodes separated by 2 or more degrees, by design.

Parameters:
relatedNode - The possibly related node you're curious about.
Throws:
Scheherexception

isIndirectlyRelatedTo

public boolean isIndirectlyRelatedTo(GenericNode relatedNode)
                              throws Scheherexception
Determines whether or not the related nodes include a particular node, regardless of particular labeling. In other words, determines whether there is at least one labeled relation to some node.

Note that this function uses inference to match disparately related nodes. It will return true if the rules of inference set for the particular link type somehow allow a connection between the two nodes.

Parameters:
relatedNode - The possibly related node you're curious about.
Throws:
Scheherexception

numRelatedNodes

public int numRelatedNodes()
Return the number nodes directly related to this node, matter how many labels are associated with each node.

Note that this function only counts direct node-to-node links. It will never count nodes separated by 2 or more degrees. For the number of inferred related nodes, first ask the RelatedNodes for a LinkSet with inference, then run the LinkSet's numLinkedNodes(). However, the LinkSet will be a static snapshot that will not update with the underlying data.


numberOfLinks

public int numberOfLinks()
Return the number of total links associated with this node, including multiple links for the same related node. In other words, count the total number of labels associated with this node.

Note that this function only counts direct node-to-node links. It does not do any graph traversal with inference. For the number of inferred links, first ask the RelatedNodes for a LinkSet with inference, then run the LinkSet's numberOfLinks(). However, the LinkSet will be a static snapshot that will not update with the underlying data.


render

public java.lang.StringBuffer render(boolean overrideInference)
                              throws Scheherexception
Render the data structure as a text table.

Parameters:
overrideInference - Set to true if you want to override the rules of inference associated with the link type and only render the nodes which are directly related (i.e., not by 2 or more degrees).
Throws:
Scheherexception

render

public java.lang.StringBuffer render()
                              throws Scheherexception
Version of render whose overrideInference parameter defaults to false.

Throws:
Scheherexception

getLinkSet

public LinkSet getLinkSet(boolean overrideInference)
                   throws Scheherexception
Compile and reveal a LinkSet of nodes related to this node. (Most other methods in this class do this first, then perform some operation on the result, for your convenience.)

Not that, while RelatedNodes objects may be kept around and will always reflect the most recent version of the data, LinkSets are static "snapshots" that are never updated. Hence, always ask RelatedNodes to give a fresh LinkSet whenever you need updated query results.

Parameters:
overrideInference - Set to true if you want to override the rules of inference associated with the link type and only compile the nodes which are directly related (i.e., not by 2 or more degrees).
Returns:
LinkSet of "query" results: the nodes related to the origin node by the link type with which this RelatedNodes was constructed.
Throws:
Scheherexception


Copyright © 2011 David K. Elson. All Rights Reserved.