samer@0: /*
samer@0:  *	Agent.java	
samer@0:  *
samer@0:  *	Copyright (c) 2000, Samer Abdallah, King's College London.
samer@0:  *	All rights reserved.
samer@0:  *
samer@0:  *	This software is provided AS iS and WITHOUT ANY WARRANTY; 
samer@0:  *	without even the implied warranty of MERCHANTABILITY or 
samer@0:  *	FITNESS FOR A PARTICULAR PURPOSE.
samer@0:  */
samer@0: 
samer@0: package samer.core;
samer@0: 
samer@0: /**
samer@0: 	An Agent is something that can handle commands.
samer@0: 	It can also optionally report which commands it
samer@0: 	can handle so that they can be exposed in some
samer@0: 	way, eg buttons or a menu.
samer@0:  */
samer@0: 
samer@0: public interface Agent
samer@0: {
samer@0: 	/**
samer@0: 		Bad interface name, I know, but a Registry is
samer@0: 		supplied to an agent so that it can report
samer@0: 		which commands it handles. The implementation
samer@0: 		of the Registry can do whatever it likes with
samer@0: 		the names: compile a list, create buttons or a
samer@0: 		menu, or just ignore them.
samer@0: 
samer@0: 		<p>May eventually want to be able to supply
samer@0: 		more information abdut a command, so that we
samer@0: 		can, eg, put an icon on a toolbar or have a
samer@0: 		tool tip
samer@0: 	 */
samer@0: 
samer@0: 	public interface Registry {
samer@0: 		Registry add( String name);
samer@0: 
samer@0: 		/**
samer@0: 			The second form of add, with a boolean
samer@0: 			second argument suggests that the command expects
samer@0: 			a boolean argument and can thus be associated
samer@0: 			with a checkbox or check menu item.
samer@0: 		 */
samer@0: 
samer@0: 		Registry add( String name, boolean initialValue);
samer@0: 
samer@0: 		/** 
samer@0: 			This means that the following commands reported
samer@0: 			to add() are to be directed to a different Agent
samer@0: 		 */
samer@0: 
samer@0: 		void     setTarget(Agent a);
samer@0: 
samer@0: 		/** this means start a new group */
samer@0: 		void group(); 
samer@0: 	}
samer@0: 
samer@0: 	/** Implementations can use the Registry to report which
samer@0: 		commands they respond to */
samer@0: 	void getCommands(Registry r);
samer@0: 
samer@0: 	/** This must do what the named command says using the given Environment
samer@0: 		for parameters or supplimentary data. */
samer@0: 	void execute( String name, Environment env) throws Exception;
samer@0: }