behaviour.java

java实现的P2P多agent中间件

/*****************************************************************
 JADE - Java Agent DEvelopment Framework is a framework to develop
 multi-agent systems in compliance with the FIPA specifications.
 Copyright (C) 2000 CSELT S.p.A.
 
 GNU Lesser General Public License
 
 This library is free software; you can redistribute it and/or
 modify it under the terms of the GNU Lesser General Public
 License as published by the Free Software Foundation, 
 version 2.1 of the License. 
 
 This library is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 Lesser General Public License for more details.
 
 You should have received a copy of the GNU Lesser General Public
 License along with this library; if not, write to the
 Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 Boston, MA  02111-1307, USA.
 *****************************************************************/

package jade.core.behaviours;

import jade.util.leap.Serializable;

import jade.core.Agent;

/**
 Abstract base class for <b><em>JADE</em></b> behaviours.  Extending
 this class directly should only be needed for particular behaviours
 with special synchronization needs; this is because event based
 notification used for blocking and restarting behaviours is
 directly accessible at this level.
 
 
 @author Giovanni Rimassa - Universita' di Parma
 @version $Date: 2007-06-14 11:02:43 +0200 (gio, 14 giu 2007) $ $Revision: 5969 $
 
 */
public abstract class Behaviour implements Serializable {
	private static final long     serialVersionUID = 3487495895819001L;
	
	//#APIDOC_EXCLUDE_BEGIN
	
	/**
	 A constant for child-to-parent notifications.
	 @serial
	 */
	protected static final int NOTIFY_UP = -1;
	
	/**
	 A constant for parent-to-child notifications.
	 @serial
	 */
	protected static final int NOTIFY_DOWN = 1;
	
	/**
	 A constant identifying the runnable state.
	 @serial
	 */
	public static final String STATE_READY = "READY";
	
	/**
	 A constant identifying the blocked state.
	 @serial
	 */
	public static final String STATE_BLOCKED = "BLOCKED";
	
	/**
	 A constant identifying the running state.
	 @serial
	 */
	public static final String STATE_RUNNING = "RUNNING";
	
	
	/**
	 Event class for notifying blocked and restarted behaviours.
	 This class is used to notify interested behaviours when a
	 Behaviour changes its runnable state. It may be sent to
	 behaviour's parent (<em>upward notification</em> or to behaviour's
	 children (<em>downward notification</em>).
	 */
	protected class RunnableChangedEvent implements Serializable {
		private static final long     serialVersionUID = 3487495895819002L;
		/**
		 @serial
		 */
		private boolean runnable;
		
		/**
		 @serial
		 */
		private int direction;
		
		/**
		 Re-init event content. This method can be used to rewrite an
		 existing event with new data (much cheaper than making a new
		 object).
		 @param b A <code>boolean</code> flag; when <code>false</code>
		 it means that a behaviour passed from <em>Ready</em> to
		 <em>Blocked</em> state. When <code>true</code> it means that a
		 behaviour passed from <em>Blocked</em> to <em>Ready</em> (this
		 flag is the truth value of the predicate <em><b>'The behaviour
		 has now become runnable'</b></em>.
		 @param d A notification direction: when direction is
		 <code>NOTIFY_UP</code>, the event travels upwards the behaviour
		 containment hierarchy; when it is <code>NOTIFY_DOWN</code>, the
		 event travels downwards.
		 */
		public void init(boolean b, int d) {
			runnable = b;
			direction = d;
		}
		
		
		/**
		 Read event source.
		 @return The <code>Behaviour</code> object which generated this event.
		 */
		public Behaviour getSource() {
			return Behaviour.this;
		}
		
		/**
		 Check whether the event is runnable.
		 @return <code>true</code> when the behaviour generating this
		 event has become <em>Ready</em>, <code>false</code> when it has
		 become <em>Blocked</em>.  */
		public boolean isRunnable() {
			return runnable;
		}
		
		/**
		 Check which direction this event is travelling.
		 @return <code>true</code> when the event is a notification
		 going from a child behaviour to its parent; <code>false</code>
		 otherwise.
		 */
		public boolean isUpwards() {
			return direction == NOTIFY_UP;
		}
		
	} // End of RunnableChangedEvent class
	
	
	//#APIDOC_EXCLUDE_END
	
	
	private String myName;	
	private boolean startFlag = true;
	
	/**
	 The agent this behaviour belongs to.
	 
	 This is an instance variable that holds a reference to the Agent
	 object and allows the usage of its methods within the body of the
	 behaviour. As the class <code>Behaviour</code> is the superclass
	 of all the other behaviour classes, this variable is always
	 available. Of course, remind to use the appropriate constructor,
	 i.e. the one that accepts an agent object as argument; otherwise,
	 this variable is set to <code>null</code>.
	 */
	protected Agent myAgent;
	
	/**
	 Flag indicating whether this Behaviour is runnable or not
	 */
	private volatile boolean runnableState = true;
	private volatile String executionState = STATE_READY;
	
	//#APIDOC_EXCLUDE_BEGIN
	
	/**
	 This event object will be re-used for every state change
	 notification.
	 */
	protected RunnableChangedEvent myEvent = new RunnableChangedEvent();
	
	//#APIDOC_EXCLUDE_END
	
	//#CUSTOM_EXCLUDE_BEGIN
	/** 
	 The private data store of this Behaviour
	 */
	private DataStore myStore;
	
	void setParent(CompositeBehaviour cb) {
		parent = cb;
		if (parent != null) {
			myAgent = parent.myAgent;
		}
		threadedParent = null;
	}
	
	void setThreadedParent(CompositeBehaviour cb) {
		threadedParent = cb;
	}
	
	private CompositeBehaviour threadedParent;
	//#APIDOC_EXCLUDE_BEGIN
	protected CompositeBehaviour parent;
	//#APIDOC_EXCLUDE_END
	
	/**
	 @return The enclosing Behaviour (if present).
	 @see jade.core.behaviours.CompositeBehaviour
	 */
	protected CompositeBehaviour getParent() {
		if (threadedParent != null) {
			return threadedParent;
		}
		else {
			return parent;
		}
	}
	//#CUSTOM_EXCLUDE_END
	
	
	/**
	 Default constructor. It does not set the agent owning this
	 behaviour object.
	 */
	public Behaviour() {
		// Construct a default name
		myName = getClass().getName();
		// Remove the class name and the '$' characters from
		// the class name for readability.
		int dotIndex = myName.lastIndexOf('.');
		int dollarIndex = myName.lastIndexOf('$');
		int lastIndex = (dotIndex > dollarIndex ? dotIndex : dollarIndex);
		
		if (lastIndex != -1) {
			myName = myName.substring(lastIndex+1);
		}
	}
	
	/**
	 Constructor with owner agent.
	 @param a The agent owning this behaviour.
	 */
	public Behaviour(Agent a) {
		this();
		myAgent = a;
	}
	
	/**
	 Give a name to this behaviour object.
	 @param name The name to give to this behaviour.
	 */
	public final void setBehaviourName(String name) {
		myName = name;
	}
	
	/**
	 Retrieve the name of this behaviour object. If no explicit name
	 was set, a default one is given, based on the behaviour class
	 name.
	 @return The name of this behaviour.
	 */
	public final String getBehaviourName() {
		return myName;
	}
	
	/**
	 Runs the behaviour. This abstract method must be implemented by
	 <code>Behaviour</code>subclasses to perform ordinary behaviour
	 duty. An agent schedules its behaviours calling their
	 <code>action()</code> method; since all the behaviours belonging
	 to the same agent are scheduled cooperatively, this method