package edu.vt.marian.search;

import java.util.*;
import java.io.*;

import edu.vt.marian.common.*;


/**
 * Class Manager for link objects.  Since links are entirely determined by
	their classID and the nodes at each end, matching and searching
	methods are concerned with moving from a node or WtdObjSet of nodes
	at one end of the link to the WtdObjSet of nodes at the other end.
 *
 * @author Robert France
 * @see ClassManager
 * @see	NodeClassManager
 * @see edu.vt.marian.common.LinkDesc
 * @see	WtdObjSet
 */

public interface LinkClassManager extends ClassManager
{
	/**
	   Create (or find in the local cache) a set of matches to description.
	   @param	description	An abstract description of the links
					we're looking for:  specifically, the
					link class (presumably this.classID),
					the direction, and a description of what
					is on one end.
	   @return	a WtdObjSet of nodes on the other end.
	*/
	public WtdObjSet match(LinkDesc description);


	/**
	 * Take a single node on one end of this link to all the nodes at the other
	 *	end.
	 *
	 * @param	key	The node as a WtdObj.
	 * @param	dir	Whether key functions as source or sink.
	 * @return	The set of all nodes linked to key by instances of this link
	 *		class, weighted by link weights (if any) and key.wt().
	 */
	public WtdObjSet keyNodeToTargetSet(WtdObj key, int dir);

	/**
	 * Take a weighted object set of nodes on one end of the links in this class
	 *	to all the nodes at the other end.
	 * <P>
	 * <B>NOTE:</B>  Where two nodes in keySet are both linked to the same "target"
	 *	node, some function must be applied to compute the node's weight in the
	 *	combined set.  The default for links is max(), but any implementing
	 *	LinkClassManager class may use any function that suits its semantics.
	 *
	 * @param	key	the node as a WtdObj.
	 * @param	dir	Whether key functions as source or sink.
	 * @return	The set of all nodes linked to any node in keySet by instances
	 *		of this link class, weighted by link weights (if any) and key.wt().
	 */
	public WtdObjSet keySetToTargetSet(WtdObjSet keySet, int dir);

	/**
	 * Syntactic sugar on keyNodeToTargetSet().
	 */
	public WtdObjSet sourceToSinks(WtdObj sourceNode);

	/**
	 * Syntactic sugar on keySetToTargetSet().
	 */
	public WtdObjSet sourcesToSinks(WtdObjSet sourceSet);

	/**
	 * Syntactic sugar on keyNodeToTargetSet().
	 */
	public WtdObjSet sinkToSources(WtdObj sinkNode);

	/**
	 * Syntactic sugar on keySetToTargetSet().
	 */
	public WtdObjSet sinksToSources(WtdObjSet sinkSet);


	/**
	 * Return the number of class instances currently in the factory.
	 *	Syntactic sugar on super.classSize().
	 */
	public long numLinks();

	/**
	 * Return the number of unique source nodes currently in the factory.
	 */
	public long numSources();

	/**
	 * Return the number of unique sink nodes currently in the factory.
	 */
	public long numSinks();

	/**
	 * Return the average number of links in this class that impinge on
	 *	a source node currently (== numLinks / numSources).
	 */
	public double avgSourceDegree();

	/**
	 * Return the average number of links in this class that impinge on
	 *	a sinknode currently (== numLinks / numSinks).
	 */
	public double avgSinkDegree();
}