package configuration;
import java.util.Vector;

/**
 * An interface for objects representing the dependencies among components.
 * For more information on the ComponentConfigurator concept and ideas related to it, 
 * visit <a href="http://choices.cs.uiuc.edu/2k/ComponentConfigurator">the ComponentConfigurator pages</a>.
 * @author  Fabio Kon (f-kon@cs.uiuc.edu)
 * @version 0.2
 * @see     DependencySpecification
*/
public interface ComponentConfigurator {

/////////////////////////////////////////////////////////////////
// METHODS    
/////////////////////////////////////////////////////////////////

/**
 * Deletes the references to all internal data structures.
 */
    public void destroyComponentConfigurator ();
        
/**
 * Adds a hook to the configurator.
 * @param   hookName   the name of the hook to be added.
 * @param   attributes a vector of attributes (may be null).
 * @exception ElementExists if the hook already exists.
 */
    public void addHook (String hookName, DependencyAttributes attributes) throws ElementExists;
    
/**
 * Deletes a hook from the configurator.
 * @param   hookName  the name of the hook to be deleted.
 * @exception NotFound if the hook is not found.
 */
    public void deleteHook (String hookName) throws NotFound;
        
/**
 * Attaches a ComponentConfigurator to the given hook changing the attributes
 * associated with the hook.
 * @param  hookName   the name of the hook.
 * @param  cc         the ComponentConfigurator to be attached to the hook.
 * @param  attributes a vector of attributes (may be null).
 * @exception HookBusy if there is already a component attached to the hook.
 * @exception NotFound if the hook does not exist.
 */
    public void hook (String hookName, ComponentConfigurator cc, DependencyAttributes attributes) 
        throws HookBusy, NotFound;


/**
 * Attaches a ComponentConfigurator to the given hook. It does not change the
 * attributes associated with this hook.
 * @param  hookName  the name of the hook.
 * @param  cc        the ComponentConfigurator to be attached to the hook.
 * @exception HookBusy if there is already a component attached to the hook.
 * @exception NotFound if the hook does not exist.
 */
  public void hook (String hookName, ComponentConfigurator cc) 
       throws HookBusy, NotFound;

/**
 * Detaches a ComponentConfigurator from the given hook.
 * @param hookName  the name of the hook.
 * @param cc        the ComponentConfigurator to be detached.
 * @exception HookVacant if there are no components attached to the hook.
 * @exception NotFound if the hook does not exist.
 */
    public void unhook (String hookName)
        throws HookVacant, NotFound;
    
/**
 * Adds a new component to the list of clients.
 * @param  client  the ComponentConfigurator representing the new client.
 * @param  hookNameInClient the name of the hook to which this component is attached.
 * @param  attributes a vector of attributes (may be null).
 * @exception ElementExists if the given pair (client, hookNameInClient) is 
 *                          already present in the client list.
 * 
 */
    public void registerClient (ComponentConfigurator client, String hookNameInClient,
				DependencyAttributes attributes)
        throws ElementExists;

/**
 * Removes a pair (client, hook) from the list of clients.
 * @param  client  the ComponentConfigurator representing the new client.
 * @param  hookNameInClient the name of the hook to which this component is attached.
 * @exception NotFound if the given pair (client, hookNameInClient) is not 
 *                     present in the client list.
 * 
 */
    public void unregisterClient (ComponentConfigurator client, 
				  String hookNameInClient)
        throws NotFound;

/**
 * This implementation simply prints the event to the standard output.
 * @param  hookedComponent the ComponentConfigurator that generated the event.
 * @param  e               the event that was generated. 
 */
    public void eventOnHookedComponent (ComponentConfigurator hookedComponent,
                                        ComponentEvent e);

    
/**
 * This implementation simply prints the event to the standard output.
 * @param  client  the ComponentConfigurator that generated the event.
 * @param  e       the event that was generated. 
 */
    public void eventOnClient (ComponentConfigurator client,
                               ComponentEvent e);
    
/**
 * Provides a list of the hooks in this component.
 * @return a vector of DependencySpecifications.
 * @see DependencySpecification
 * @see java.util.Vector 
 */
  public Vector listHooks ();

/** 
 * Provides a reference to the component attached to the given hook. 
 * @return a reference to the ComponentConfigurator. 
 * @exception NotFound if the hook does not exist.
 */ 
  ComponentConfigurator getHookedComponent(String hookName) throws NotFound; 

/**
 * @return the number of clients registered with this component.
 */
    public int numberOfClients ();

/**
 * Provides a list of the clients of this component.
 * @return a vector of DependencySpecifications.
 * @see DependencySpecification
 * @see java.util.Vector 
 */
    public Vector listClients ();
    
/**
 * Sets the name of this component.
 */
    public void name (String s);

/**
 * Accessor for the component name.
 * @return a string containing the component name. 
 */
    public String name ();
    
/**
 * Sets the information string for this component.
 */
    public void info (String s);

/**
 * Accessor for the component information string.
 * @return a string containing component information.
 */
    public String info ();    
    
/**
 * Accessor for getting the component implementation.
 * @return the object implementation.
 */
  public Object implementation ();

/**
 * Sets the component implementation.
 */
  public void implementation (Object implementation);


/**
 * Dumps information about the hooks of this Configurator to an output stream.
 * @param   out an output PrintStream in which the information is printed.
 */
  public void printHooks (java.io.PrintStream out);

/**
 * Dumps information about the clients this Component to an output stream.
 * @param   out an output PrintStream in which the information is printed.
 */
  public void printClients (java.io.PrintStream out);


};

