amsservice.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.domain;

import jade.util.leap.*;

import jade.domain.FIPAAgentManagement.*;
import jade.core.Agent;
import jade.core.AID;
import jade.lang.acl.ACLMessage;

//import jade.content.lang.sl.SimpleSLTokenizer;
//import jade.content.lang.sl.SL0Vocabulary;

import jade.content.*;
import jade.content.lang.*;
import jade.content.lang.sl.*;
import jade.content.lang.Codec.*;
import jade.content.onto.Ontology;
import jade.content.onto.basic.Action;
import jade.content.onto.basic.Result;
import jade.content.onto.OntologyException;

/**
 * This class provides a set of static methods to communicate with
 * a AMS Service that complies with FIPA specifications.
 * Notice that JADE calls automatically the register and deregister methods 
 * with the default AMS respectively before calling <code>Agent.setup()</code> 
 * method and just 
 * after <code>Agent.takeDown()</code> method returns; so there is no need for a normal 
 * programmer to call them. 
 * However, under certain circumstances, a programmer might need to call its 
 * methods. To give some examples: when an agent wishes to register with the 
 * AMS of a remote agent platform, or when an agent wishes to modify its 
 * description by adding a private address to the set of its addresses, ...
 * <p>
 * It includes methods to register, deregister, modify and search with an AMS. 
 * Each of this method has version with all the needed parameters, or with a 
 * subset of them where, those parameters that can be omitted have been 
 * defaulted to the default AMS of the platform, the AID of the sending agent,
 *  the default Search Constraints.
 * Notice that all these methods blocks every activity of the agent until the
 * action (i.e. register/deregister/modify/search) has been successfully 
 * executed or a jade.domain.FIPAException exception has been thrown 
 * (e.g. because a FAILURE message has been received by the AMS). 
 * In some cases, instead, it is more convenient to execute this task in a 
 * non-blocking way. The method getNonBlockingBehaviour() returns a 
 * non-blocking behaviour of type RequestFIPAServiceBehaviour that can be 
 * added to the queue of the agent behaviours, as usual, by using 
 * <code>Agent.addBehaviour()</code>. 
 * <br>
 * <b>The MIDP version of this class only includes the 
 * <code>getFailedReceiver()</code> method.</b>
 * <br>
 *
 * @author Fabio Bellifemine - CSELT S.p.A.
 @version $Date: 2007-10-05 17:00:50 +0200 (ven, 05 ott 2007) $ $Revision: 5999 $ 
 **/
public class AMSService extends FIPAService {
	
	//#MIDP_EXCLUDE_BEGIN
	private static Codec c = new SLCodec();
	private static Ontology o = FIPAManagementOntology.getInstance();
	private static ContentManager cm = new ContentManager();
	static {
		cm.registerLanguage(c, FIPANames.ContentLanguage.FIPA_SL0);
		cm.registerOntology(o);
	}
	
	/**
	 * check that the <code>AMSAgentDescription</code> contains the mandatory
	 * slots, i.e. the agent name and the agent state. 
	 * @throw a MissingParameter exception is it is not valid
	 */
	static void checkIsValid(AMSAgentDescription amsd) throws MissingParameter {
		// FIXME: use FIPAManagementOntology constants instead of Strings  
		if (amsd.getName()==null) 
			throw new MissingParameter(FIPAManagementOntology.AMSAGENTDESCRIPTION, "name");
		if (amsd.getState()==null) 
			throw new MissingParameter(FIPAManagementOntology.AMSAGENTDESCRIPTION, "state");
	}
	
	/**
	 Register a AMSAgentDescription with a <b>AMS</b> agent. 
	 However, 
	 since <b>AMS</b> registration and
	 deregistration are automatic in JADE, this method should not be
	 used by application programmers to register with the default AMS.
	 @param a is the Agent performing the registration 
	 @param AMSName The AID of the <b>AMS</b> agent to register with.
	 @param amsd A <code>AMSAgentDescriptor</code> object containing all
	 data necessary to the registration. If the Agent name is empty, than
	 it is set according to the <code>a</code> parameter. If the Agent state is
	 empty, than it is set to ACTIVE.
	 @exception FIPAException A suitable exception can be thrown when
	 a <code>refuse</code> or <code>failure</code> messages are
	 received from the AMS to indicate some error condition or when
	 the method locally discovers that the amsdescription is not valid.
	 */
	public static void register(Agent a, AID AMSName, AMSAgentDescription amsd) throws FIPAException {
		ACLMessage request = createRequestMessage(a, AMSName);
		
		if (amsd.getName() == null)
			amsd.setName(a.getAID());
		if (amsd.getState() == null)
			amsd.setState(AMSAgentDescription.ACTIVE);
		checkIsValid(amsd);
		
		// Build a AMS action object for the request
		Register r = new Register();
		r.setDescription(amsd);
		
		Action act = new Action();
		
		act.setActor(AMSName);
		act.setAction(r);
		
		synchronized (cm) {
			try{    
				cm.fillContent(request, act);
			}
			catch(Exception e){
				throw new FIPAException("Error encoding REQUEST content. "+e);
			}
		}
		
		// Send message and collect reply
		doFipaRequestClient(a,request);
	}
	
	
	/**
	 * registers a <code>AMSAgentDescription</code> with the default AMS
	 * @see #register(Agent,AID,AMSAgentDescription)
	 **/
	public static void register(Agent a, AMSAgentDescription amsd) throws FIPAException {
		register(a,a.getAMS(),amsd);
	}
	
	/**
	 Deregister a AMSAgentDescription from a <b>AMS</b> agent. However, since <b>AMS</b> registration and
	 deregistration are automatic in JADE, this method should not be
	 used by application programmers to deregister with the default AMS.
	 @param AMSName The AID of the <b>AMS</b> agent to deregister from.
	 @param amsd A <code>AMSAgentDescription</code> object containing all
	 data necessary to the deregistration.
	 @exception FIPAException A suitable exception can be thrown when
	 a <code>refuse</code> or <code>failure</code> messages are
	 received from the AMS to indicate some error condition or when
	 the method locally discovers that the amsdescription is not valid.
	 */
	public static void deregister(Agent a, AID AMSName, AMSAgentDescription amsd) throws FIPAException {
		
		ACLMessage request = createRequestMessage(a, AMSName);
		
		if (amsd.getName() == null)
			amsd.setName(a.getAID());
		if (amsd.getState() == null)
			amsd.setState(AMSAgentDescription.ACTIVE);
		// Build a AMS action object for the request
		Deregister d = new Deregister();
		d.setDescription(amsd);
		
		Action act = new Action();
		act.setActor(AMSName);
		act.setAction(d);
		
		synchronized (cm) {
			try{    
				cm.fillContent(request, act);
			}
			catch(Exception e){
				throw new FIPAException("Error encoding REQUEST content. "+e);
			}
		}
		
		// Send message and collect reply
		doFipaRequestClient(a,request);
	}
	
	/**
	 The AID of the AMS is defaulted to the AMS of this platform.
	 @see #deregister(Agent a, AID AMSName, AMSAgentDescription amsd)
	 **/
	public static void deregister(Agent a, AMSAgentDescription amsd) throws FIPAException {
		deregister(a,a.getAMS(),amsd);
	}
	
	/**
	 A default AMSAgentDescription is used for this agent, where only AID and state
	 are set (state is set to ACTIVE).
	 @see #deregister(Agent a, AID AMSName, AMSAgentDescription amsd)
	 **/
	public static void deregister(Agent a, AID AMSName) throws FIPAException {
		AMSAgentDescription amsd = new AMSAgentDescription();
		amsd.setName(a.getAID());
		deregister(a,AMSName,amsd);
	}
	
	/**
	 A default AMSAgentDescription is used for this agent, where only AID and state
	 are set.
	 The AID of the AMS is defaulted to the AMS of this platform.
	 @see #deregister(Agent a, AID AMSName, AMSAgentDescription amsd)
	 **/
	public static void deregister(Agent a) throws FIPAException {
		AMSAgentDescription amsd = new AMSAgentDescription();
		amsd.setName(a.getAID());
		deregister(a,amsd);
	}
	
	
	/**
	 Modifies data contained within a <b>AMS</b>
	 agent. 
	 @param AMSName The GUID of the <b>AMS</b> agent holding the data
	 to be changed.
	 @param amsd The new <code>AMSAgentDescriptor</code> object 
	 that should modify the existing one. 
	 @exception FIPAException A suitable exception can be thrown when
	 a <code>refuse</code> or <code>failure</code> messages are
	 received from the AMS to indicate some error condition or when
	 the method locally discovers that the amsdescription is not valid.
	 */
	public static void modify(Agent a, AID AMSName, AMSAgentDescription amsd) throws FIPAException {
		ACLMessage request = createRequestMessage(a, AMSName);
		
		if (amsd.getName() == null)