ontology.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.content.onto;

import java.util.Hashtable;
import java.util.Enumeration;
//#J2ME_EXCLUDE_BEGIN
import java.util.List;
import java.util.ArrayList;
//#J2ME_EXCLUDE_END

import jade.content.abs.AbsObject;
import jade.content.schema.ObjectSchema;
import jade.content.schema.AgentActionSchema;
import jade.content.schema.ConceptSchema;
import jade.content.schema.PredicateSchema;

import jade.util.leap.Serializable;
import jade.util.Logger;

/**
 *  An application-specific ontology describes the elements that agents
 * can use within content of messages. It defines a vocabulary and
 * relationships between the elements in such a vocabulary.
 * The relationships can be:
 * <ul>
 * <li>structural, e.g., the predicate <code>fatherOf</code> accepts two
 *     parameters, a father and a set of children;
 * <li>semantic, e.g., a concept of class <code>Man</code> is also of class
 *     <code>Person</code>.
 * </ul>
 * Application-specific ontologies are implemented through objects
 * of class <code>Ontology</code>.<br>
 * An ontology is characterized by:
 * <ul>
 * <li>one name;
 * <li>one (or more) base ontology that it extends;
 * <li>a set of <i>element schemas</i>.
 * </ul>
 * Element schemas are objects describing the structure of concepts, actions,
 * and predicates. that are allowed in messages. For example,
 * <code>People</code> ontology contains an element schema called
 * <code>Person</code>. This schema states that a <code>Person</code> is
 * characterized by a <code>name</code> and by an <code>address</code>:
 * <code>
 * ConceptSchema personSchema = new ConceptSchema(PERSON);
 * personSchema.addSlot(NAME,    stringSchema);
 * personSchema.addSlot(ADDRESS, addressSchema, ObjectSchema.OPTIONAL);
 * </code>
 * where <code>PERSON<code>, <code>NAME</code> and <code>ADDRESS</code> are
 * string constants. When you register your schema with the ontology, such
 * constants become part of the vocabulary of the ontology.<br>
 * Schemas that describe concepts support inheritance. You can define the
 * concept <code>Man</code> as a refinement of the concept <code>Person</code>:
 * <code>
 * ConceptSchema manSchema = new ConceptSchema(MAN);
 * manSchema.addSuperSchema(personSchema);
 * </code>
 * Each element schema can be associated with a Java class to map elements of
 * the ontology that comply with a schema with Java objects of that class. The
 * following is a class that might be associated with the <code>Person</code>
 * schema:
 * <code>
 * public class Person extends Concept {
 *       private String  name    = null;
 *       private Address address =  null;
 *
 *       public void setName(String name) {
 *               this.name = name;
 *       }
 *
 *       public void setAddress(Address address) {
 *               this.address = address;
 *       }
 *
 *       public String getName() {
 *               return name;
 *       }
 *
 *       public Address getAddress() {
 *               return address;
 *       }
 * }
 * </code>
 * When sending/receiving messages you can represent your content in terms of
 * objects belonging to classes that the ontology associates with schemas.<br>
 * As the previous example suggests, you cannot use objects of class
 * <code>Person</code> when asking for the value of some attribute, e.g., when
 * asking for the value of <code>address</code>. Basically, the problem is that
 * you cannot 'assign' a variable to an attribute of an object, i.e.
 * you cannot write something like:
 * <code>person.setName(new Variable("X"))</code>.<br>
 * In order to solve this problem, you can describe your content in terms of
 * <i>abstract descriptors</i>. An abstract descriptor is an
 * object that reifies an element of the ontology.
 * The following is the creation of an abstract
 * descriptor for a concept of type <code>Man</code>:
 * <code>
 * AbsConcept absMan = new AbsConcept(MAN);
 * absMan.setSlot(NAME,    "John");
 * absMan.setSlot(ADDRESS, absAddress);
 * </code>
 * where <code>absAddress</code> is the abstract descriptor for John's
 * address:
 * <code>
 * AbsConcept absAddress = new AbsConcept(ADDRESS);
 * absAddress.setSlot(CITY, "London");
 * </code>
 * Objects of class <code>Ontology</code> allows you to:
 * <ul>
 * <li>register schemas with associated (i) a mandatory term of the
 *     vocabulary e.g. <code>NAME</code> and (ii) an optional Java class,
 *     e.g. <code>Person</code>;
 * <li>retrieve the registered information through various keys.
 * </ul>
 * The framework already provides the <code>BasicOntology</code> ontology
 * that provides all basic elements, i.e. primitive data types, aggregate
 * types, etc.
 * Application-specific ontologies should be implemented extending it.

 * @see jade.content.Concept
 * @see jade.content.abs.AbsConcept
 * @see jade.content.schema.ConceptSchema
 * @see jade.content.onto.BasicOntology
 * @author Federico Bergenti - Universita` di Parma
 * @author Giovanni Caire - TILAB
 */
public class Ontology implements Serializable {
	private static final String DEFAULT_INTROSPECTOR_CLASS = "jade.content.onto.ReflectiveIntrospector";
	private Ontology[]   base = new Ontology[0];
	private String       name = null;
	private Introspector introspector = null;

	private Hashtable    elements = new Hashtable(); // Maps type-names to schemas
	private Hashtable    classes  = new Hashtable(); // Maps type-names to java classes
	private Hashtable    schemas  = new Hashtable(); // Maps java classes to schemas

	private Logger logger = Logger.getMyLogger(this.getClass().getName());

	// This is required for compatibility with CLDC MIDP where XXX.class
	// is not supported
	private static Class absObjectClass = null;
	static {
		try {
			absObjectClass = Class.forName("jade.content.abs.AbsObject");
		}
		catch (Exception e) {
			// Should never happen
			e.printStackTrace();
		}
	}

	/**
	 * Construct an Ontology object with a given <code>name</code>
	 * that extends a given ontology.
	 * The <code>ReflectiveIntrospector</code> is used by default to
	 * convert between Java objects and abstract descriptors.
	 * @param name The identifier of the ontology.
	 * @param base The base ontology.
	 */
	public Ontology(String name, Ontology base) {
		this(name, base, null);
		try {
			introspector = (Introspector) Class.forName(DEFAULT_INTROSPECTOR_CLASS).newInstance();
		}
		catch (Exception e) {
			throw new RuntimeException("Class "+DEFAULT_INTROSPECTOR_CLASS+"for default Introspector not found");
		}
	}

	/**
	 * Construct an Ontology object with a given <code>name</code>
	 * that uses a given Introspector to
	 * convert between Java objects and abstract descriptors.
	 * @param name The identifier of the ontology.
	 * @param introspector The introspector.
	 */
	public Ontology(String name, Introspector introspector) {
		this(name, new Ontology[0], introspector);
	}

	/**
	 * Construct an Ontology object with a given <code>name</code>
	 * that extends a given ontology and that uses a given Introspector to
	 * convert between Java objects and abstract descriptors.
	 * @param name The identifier of the ontology.
	 * @param base The base ontology.
	 * @param introspector The introspector.
	 */
	public Ontology(String name, Ontology base, Introspector introspector) {
		this(name, (base != null ? new Ontology[]{base} : new Ontology[0]), introspector);
	}

	/**
	 * Construct an Ontology object with a given <code>name</code>
	 * that extends a given set of ontologies and that uses a given Introspector to
	 * convert between Java objects and abstract descriptors.
	 * @param name The identifier of the ontology.
	 * @param base The base ontology.
	 * @param introspector The introspector.
	 */
	public Ontology(String name, Ontology[] base, Introspector introspector) {
		this.name = name;
		this.introspector = introspector;
		this.base = (base != null ? base : new Ontology[0]);
	}

	/**
	 * Retrieves the name of this ontology.
	 * @return the name of this ontology.
	 */
	public String getName() {
		return name;
	}

	/**
	 * Adds a schema to this ontology
	 * @param schema The schema to add
	 * @throws OntologyException
	 */
	public void add(ObjectSchema schema) throws OntologyException {
		add(schema, null);
	}


	/**
	 * Adds a schema to the ontology and associates it to the class
	 * <code>javaClass</code>
	 * @param schema the schema.
	 * @param javaClass the concrete class.
	 * @throws OntologyException
	 */
	public void add(ObjectSchema schema, Class javaClass) throws OntologyException {
		if (schema.getTypeName() == null) {
			throw new OntologyException("Invalid schema identifier");
		}

		String s = schema.getTypeName().toLowerCase();
		elements.put(s, schema);

		if (javaClass != null) {
			classes.put(s, javaClass);
			if (!absObjectClass.isAssignableFrom(javaClass)) {
				if (introspector != null) {
					introspector.checkClass(schema, javaClass, this);
				}
				schemas.put(javaClass, schema);
			}
			else {
				// If the java class is an abstract descriptor check the
				// coherence between the schema and the abstract descriptor
				if (!javaClass.isInstance(schema.newInstance())) {
					throw new OntologyException("Java class "+javaClass.getName()+" can't represent instances of schema "+schema);
				}
			}
		}
	}

	/**
	 * Retrieves the schema of element <code>name</code> in this ontology.
	 * The search is extended to the base ontologies if the schema is not
	 * found.
	 * @param name the name of the schema in the vocabulary.
	 * @return the schema or <code>null</code> if the schema is not found.
	 * @throws OntologyException
	 */
	public ObjectSchema getSchema(String name) throws OntologyException {
		if (name == null) {
			throw new OntologyException("Null schema identifier");
		}

		ObjectSchema ret = (ObjectSchema) elements.get(name.toLowerCase());

		if (ret == null) {
			if(logger.isLoggable(Logger.FINE))
				logger.log(Logger.FINE,"Ontology "+getName()+". Schema for "+name+" not found");
			for (int i = 0; i < base.length; ++i) {
				if (base[i] == null) {