package edu.vt.marian.common;
import java.io.*;
import java.net.*;
import java.util.*;
import edu.vt.marian.uip.rpc_function;
/**
* A Information Description is a description of a digital information object
* in context. In MARIAN representation terms, we will understand this
* as a node within a web of links.
*
* Specifically, an InfoDesc is composed of a node description plus any number
* of link descriptions. For the purposes of Java, we are declaring
* both node and link descriptions to be of class Object, so that
* several disparate types of descriptions can be accomodated. Only
* certain kinds of Objects will actually do in either case, whence the
* if-else if-else statements in setNodeDesc() and addLinkDesc(). These
* statements are deliberately designed to be extensible, so that other
* description types can be added in future.
*
* The function of a node description is to describe a (subset) of nodes within
* some class. Any class of nodes can define one or more matching
* functions. In addition, all node classes support match by classID,
* (including subclass ID) and by exact FullID. Most also support match
* by exact object. Any further match is to be specified by an
* encoded function, which the class manager will apply to its collection
* of instances.
*
* At the moment, we are only allowing a link description to consist of an exact
* description of a single link. Future implementations may allow link
* variables and link operators. A single link is fully described by
* specifying its type and describing the nodes at source end and sink
* end. In the current context, we know the description of the node at
* one end (the "target" end): that is the node described in the node
* portion of this InfoDesc. The node at the other end (the "key" end)
* is described by a further InfoDesc. Thus each member of the linkDesc
* Vector is composed of three elements:
*
- linkClassID -- the class of the link traversed
*
- direction -- whether the target is source or sink
*
- keyDesc -- the description of the key node
*
*
* @author Robert France.
* @see LinkDesc
* @see ClassManager
*/
public class InfoDesc
{
/** Just for debugging */
protected Debug debug;
/* Node description. */
protected Object nodeDesc;
/* Link descriptions. */
protected Vector linkDescs;
/** return values for methods of this class */
public final static int OK = 0;
public final static int BAD_PARAMS = -2;
/**
Create a new null InfoDesc.
@param d the eternal Debug object.
*/
public InfoDesc(Debug d)
{
nodeDesc = null;
linkDescs = new Vector();
debug = d;
}
/**
Create an InfoDesc from a specific nodeDesc.
@param node A node description: either classID, FullID, or Function.
@param d the eternal Debug object.
*/
public InfoDesc(Object node, Debug d)
{
if ( setNodeDesc(node) != OK )
nodeDesc = null;
linkDescs = new Vector();
debug = d;
}
/**
Create an InfoDesc from a specific nodeDesc.
@param node A node description: either ClassID, FullID, or Function.
@param d the eternal Debug object.
*/
public InfoDesc(Object node, Vector links, Debug d)
{
if ( setNodeDesc(node) != OK )
nodeDesc = null;
linkDescs = new Vector();
if ( links == null )
{
debug.dumpTrace("InfoDesc [constructor 3]: null links vector.");
}
else
{
Enumeration e = links.elements();
while ( e.hasMoreElements() )
{
addLinkDesc( e.nextElement() ); // Ignore failures.
}
}
debug = d;
}
/**
Either the nodeDesc or the linkDescs (or both) must be valid,
although either can also be null (but not both!).
*/
public boolean isValid()
{
return( (nodeDesc != null) || (linkDescs.size() > 0) );
}
/**
Set the node description part.
@param node A node description: either ClassID, FullID, or Function.
*/
public int setNodeDesc(Object node)
{
if ( node instanceof ClassID )
{
nodeDesc = node;
return( OK );
}
else if ( node instanceof FullID )
{
nodeDesc = node;
return( OK );
}
else if ( node instanceof String )
{
nodeDesc = node;
return( OK );
}
else if ( node instanceof rpc_function ) //**DEVEL: Someday
{ // consider creating
nodeDesc = node; // a more general function
return( OK ); // type. Also consider
} // using java.lang.Method.
else
{
debug.dumpTrace("InfoDesc.setNodeDesc(): cannot handle object " +
node.toString() + ": only ClassIDs, FullIDs or Functions currently accepted.");
return( BAD_PARAMS );
}
}
/**
Get the node description part.
*/
public Object getNodeDesc()
{
return( nodeDesc );
}
/**
Add another link description to the set of links.
@param link A link description: currently, only LinkDesc allowed.
*/
public int addLinkDesc(Object ld)
{
if ( ld instanceof LinkDesc )
{
linkDescs.addElement(ld);
return( OK );
}
else
{
debug.dumpTrace("InfoDesc.addLinkDesc(): cannot handle object " +
ld.toString() + ": only LinkDescs currently accepted.");
return( BAD_PARAMS );
}
}
public int numLinkDescs()
{
return( linkDescs.size() );
}
/**
Return an enumeration through the link description set.
*/
public Enumeration enumLinkDescs()
{
return( linkDescs.elements() );
}
}