package edu.vt.marian.search;

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

import edu.vt.marian.common.*;


/**
 * Class Manager for searchable Strings.  Controlled strings are those that can
	be recognized, compared, and searched, as opposed to the long uncontrolled
	strings that serve as underlayment for raw documents.  Examples of
	controlled string classes are persons' names, subject descriptors, and
	English words.  Since the criteria for identity is determined by the
	raw objects (in Java, it is just String.equals()) the class manager
	can enforce instance identity, and can and does generate its own instance
	IDs.  Thus, when a client adds a string to the class, it is the class
	manager, not the client, that generates the instance ID.  In fact, adding
	a string and generating an ID is not semantically separable from recognizing
	a string already in the class and returning its previously generated ID.
 *
 * @author Robert France
 * @see ClassManager
 * @see NodeClassManager
 * @see UncontrolledStringClassManager
 */

public class ControlledStringClassManager implements NodeClassManager
{
	/**
	   Create (or find in the local cache) a set of matches to description.
	*/
	public WtdObjSet match(InfoDesc description)
	{
		return( null );
	}


	/**
	 * Is this the ID of an instance currently in this class?
	 */
	public boolean isInClass(FullID id)
	{
		return( false );
	}

	/**
	 * Is this String an instance currently in this class?
	 */
	public boolean isInClass(String str)
	{
		return( false );
	}


	/**
	 * Map this ID to the String form of class instance.
	   @param	id	The FullID of an instance of this class.
	   @return	The String form of that instance, or
	   <BR>		'null' if id does not pick out any current class instance.
	 */
	public String idToString(FullID id)
	{
		return( null );
	}


	/**
	   Return the Java Object that implements the instance of this class
		picked out by id.
	   @param	id	The FullID for an object of this class.
	   @return	the (Java form of the) real object, or 'null' if id
			does not describe an instance currently in this class.
	 */
	public Object idToObject(FullID id)
	{
		return( idToString(id) );
	}


	/**
	   Do idToObject() for a bunch of FullIDs.
	   @param	ids	A Vector of FullIDs for objects of this class.
	   @return	A Vector of real (Java) objects, in one-to-one
			correspondence with their FullIDs in ids.
	   <B>NOTE:</B> Should a FullID in ids not pick out a valid instance
			of this class, the corresponding element of the return
			vector is set to 'null'.
	 */
	public Vector idsToObjects(Vector ids)
	{
		return( null );
	}


	/**
	 * Map this String to a FullID of this class.
	   @param	str	The String form of an instance of this class.
	   @return	The ID of that instance.
	<P><B>NOTE:</B>  This is a "find-or-add" operation.  If str is already
		known as a member of this class, then an ID has already been
		assigned to it in an earlier invocation of this method of add().
		The same ID will be returned this time.  If str has not previsously
		been seen, it will be added to the known instances of the class.
		A previously unused instanceID will be generated for it and used to
		construct the FullID that is returned.
	   @see	#add(String)
	 */
	public FullID stringToID(String str)
	{
		return( null );
	}


	/**
	    Add a new String and a new FullID for it to this class <I>(See note)</I>.
	    @param	id	An unused FullID of this class.
	    @param	str	A previously unseen String of this class.
	    @return	OK -- Both id and str are unknown, and have been added,
			<I>or</I>both were known, and id is already the FullID of str;
	    <BR>	ClassManager.ALREADY_EXISTS -- either id or str is already used;
	    <BR>	NO_CAN_DO -- something else went wrong.
	<P><B>NOTE:</B>  This method should not be used under normal circumstances.
		Normally all FullIDs of a controlled string class are generated by
		the class manager.  Overriding that responsibility and adding one
		created "on the outside" introduces inefficiencies and the potential
		for confusion.  Insead, add(Sting str) and stringToID() are preferred.
	 */
	public int add(FullID id, String str)
	{
		return( ReturnCodes.NOT_YET_IMPLEMENTED );
	}

	/**
	 * Add a new String to this class, and generate its new FullID.
	   @param	str	The String form of an instance of this class.
	   @return	The ID of that instance, or
	   <BR>		'null' if str is already a known instance of this class.
	<P><B>NOTE:</B>  This method is identical to stringToID() except that str
		is presumed to not already be a known instance of this class.  If
		it <I>is</I> an instance already managed by this, add() will fail.
	   @see	#stringToID
	 */
	public FullID add(String str)
	{
		return( null );
	}


	/**
	    Forget about the object referred to by id.
	    @return	OK -- There was such a string in the class, and now there isn't;
	    <BR>	ClassManager.NO_SUCH_OBJECT -- There never was such an instance.
	    <BR>	NO_CAN_DO -- The object was there, but could not be deleted.
	 */
	public int delete(FullID id)
	{
		return( ReturnCodes.NOT_YET_IMPLEMENTED );
	}


	/**
	    Forget about a String currently among the class instances.
	    @return	OK -- There was such a string in the class, and now there isn't;
	    <BR>	ClassManager.NO_SUCH_OBJECT -- There never was such an instance.
	    <BR>	NO_CAN_DO -- The object was there, but could not be deleted.
	 */
	public int delete(String str)
	{
		return( ReturnCodes.NOT_YET_IMPLEMENTED );
	}


	/**
	 * Return the number of class instances currently in the factory.
	 */
	public long classSize()
	{
		return( ReturnCodes.NOT_YET_IMPLEMENTED );
	}
}