jade.onto
Interface Ontology

All Known Implementing Classes:
DefaultOntology

public abstract interface Ontology

An application specific ontology is represented by a properly initialized instance of a class implementing the Ontologyinterface. It should be noticed in fact that two instances of the same class implementing the Ontology interface can represent two different ontologies, provided that they have been initialized differently.

In the adopted approach, a generic item included in an ontology is called a role. For example the concepts Company and Person, the predicate WorfsFor and the action Engage can be roles in an ontology dealing with employees.
Each ontological role is characterised by a name and a structure defined in terms of a number of slots. For instance the Person role will have the name "person" and some slots describing the person's first-name, family-name and age. In case of an ontological role that is an action the slots describes the arguments of the action
A slot on its turn is characterised by


Entities in a specific domain, i.e. instances of the ontological roles, can be conveniently represented inside an agent as instances of application-specific Java classes each one representing a role.
For example the class public class Person { String name; int age; void setName(String n) { name = n; } String getName() { return name; } void setAge(int a) { age = a; } int getAge() { return age; } } can represent the Person role and instances of this role can be represented as Person objects.

An alternative, yet less convenient, way of representing a domain entity is as an instance of the Frame class that is designed so that each entity (regardless of the role it is an instance of) can be represented as a Frame object. This class is however mostly used in JADE internal conversions.

The methods in the Ontology interface allows to
  • Initialize an object representing an ontology (i.e. an instance of a class implementing the Ontology interface) by adding to it all the ontological roles included in the ontology and specifying for each role the application specific class representing that role
  • Convert a Frame representing an entity into/from an instance of the application specific class representing the role this entity is an instance of
  • In the above conversion perform all the necessary ontological checks e.g. that the age of a person is an integer value

In order to represent an ontological role, a Java class must obey to some rules:
  1. Primitive types such as int and boolean cannot be used. Use Integer and Boolean classes instead.
  2. For every slot in the role named XXX, of category PRIMITIVE_SLOT or FRAME_SLOT and of type T the class must have two accessible methods, with the following signature:
    • T getXXX()
    • void setXXX(T t)
  3. For every slot in the role named XXX, of category SET_TERM or SEQUENCE_TERM and with elements of type T, the class must have two accessible methods, with the following signature:
    • Iterator getAllXXX()
    • void addXXX(T t)
As long as the above rules are followed, any user-defined class can be added to the Ontology object. As a useful technique, one can define compliant Java interfaces and add them to the Ontology; this way useful OO idioms such as polymorphism and mix-in inheritance can be exploited for the Java representations of ontological objects. Due to different lexical conventions between the Java language and FIPA ACL and content languages, some name translation must be performed to map the name of a slot into the name of the corresponding get and set methods. Name translation works as follows:
  1. Any ':' character must be removed.
  2. Any '-' character must be removed.
Moreover, a case insensitive match is followed. As an example, a role with an integer slot named :user-age, will require the following methods (case is not important, but according to a popular Java coding convention, the two methods have capital letters whenever a '-' is present in the slot name):
  • int getUserAge()
  • void setUserAge(int age)

Author:
Giovanni Rimassa - Universita` di Parma
See Also:
Codec, Frame, SlotDescriptor

Field Summary
static short ANY_SLOT
          Constant for slots whose category is not specified
static java.lang.String ANY_TYPE
          Constant for any type in a SlotDescriptor.
static java.lang.String BINARY_TYPE
          Constant for byte[] type in a SlotDescriptor.
static java.lang.String BOOLEAN_TYPE
          Constant for boolean type in a SlotDescriptor.
static java.lang.String BYTE_TYPE
          Constant for byte type in a SlotDescriptor.
static java.lang.String CHARACTER_TYPE
          Constant for char type in a SlotDescriptor.
static java.lang.String DATE_TYPE
          Constant for java.util.Date type in a SlotDescriptor.
static java.lang.String DOUBLE_TYPE
          Constant for double type in a SlotDescriptor.
static java.lang.String FLOAT_TYPE
          Constant for float type in a SlotDescriptor.
static short FRAME_SLOT
          Constant for category of slots whose value is an instance of a given ontological role (and can therefore be represented as a frame).
static java.lang.String INTEGER_TYPE
          Constant for int type in a SlotDescriptor.
static java.lang.String LONG_TYPE
          Constant for long type in a SlotDescriptor.
static boolean M
          Boolean constant for Mandatory slots.
static java.lang.String NAME_OF_ACTION_SLOT
          Symbolic constant identifying a slot representing an action
static java.lang.String NAME_OF_ACTOR_SLOT
          Symbolic constant identifying a slot representing an actor
static java.lang.String NAME_OF_SEQUENCE_FRAME
          Symbolic constant identifying a frame representing a sequence
static java.lang.String NAME_OF_SET_FRAME
          Symbolic constant identifying a frame representing a set
static boolean O
          Boolean constant for Optional slots.
static short PRIMITIVE_SLOT
          Constant for category of slots whose value is a primitive entity
static short SEQUENCE_SLOT
          Constant for category of slots whose value is a sequence of entities
static short SET_SLOT
          Constant for category of slots whose value is a set of entities
static java.lang.String SHORT_TYPE
          Constant for short type in a SlotDescriptor.
static java.lang.String STRING_TYPE
          Constant for String type in a SlotDescriptor.
 
Method Summary
 void addRole(java.lang.String roleName, SlotDescriptor[] slots)
          Adds to the ontology a role without any application-specific class representing it.
 void addRole(java.lang.String roleName, SlotDescriptor[] slots, RoleEntityFactory ref)
          Adds to the ontology a role with an application-specific class representing it.
 void check(Frame f)
          Checks whether the given Frame object represents a valid instance of some role, making sure that every slot has the correct category and type and that no mandatory slot has a null value.
 void check(java.lang.Object o, java.lang.String roleName)
          Checks whether the given Java object represents a valid instance of some role, making sure that every slot has the correct category and type and that no mandatory slot has a null value.
 Frame createFrame(java.lang.Object o, java.lang.String roleName)
          Creates a Frame object from a given Java object.
 java.util.List createObject(java.util.List v)
          Creates a list of Java objects representing each one an instance of a given role, getting the information from a given List of Frame objects.
 RoleEntityFactory getFactory(java.lang.String roleName)
          Returns the factory for instances of the user defined class representing a given role
 java.lang.String getRoleName(java.lang.Class c)
           
 SlotDescriptor[] getSlots(java.lang.String roleName)
          Returns the array of SlotDescriptor objects that represent the structure of the given ontological role.
 java.util.List getVocabulary()
           
 boolean isRole(java.lang.String roleName)
          Tells whether a given string is the name of a role in the current ontology.
 void joinOntology(Ontology o)
          Adds to this ontology all roles included into another ontology
 

Field Detail

O

public static final boolean O
Boolean constant for Optional slots.

M

public static final boolean M
Boolean constant for Mandatory slots.

BOOLEAN_TYPE

public static final java.lang.String BOOLEAN_TYPE
Constant for boolean type in a SlotDescriptor.
See Also:
SlotDescriptor

BYTE_TYPE

public static final java.lang.String BYTE_TYPE
Constant for byte type in a SlotDescriptor.
See Also:
SlotDescriptor

CHARACTER_TYPE

public static final java.lang.String CHARACTER_TYPE
Constant for char type in a SlotDescriptor.
See Also:
SlotDescriptor

DOUBLE_TYPE

public static final java.lang.String DOUBLE_TYPE
Constant for double type in a SlotDescriptor.
See Also:
SlotDescriptor

FLOAT_TYPE

public static final java.lang.String FLOAT_TYPE
Constant for float type in a SlotDescriptor.
See Also:
SlotDescriptor

INTEGER_TYPE

public static final java.lang.String INTEGER_TYPE
Constant for int type in a SlotDescriptor.
See Also:
SlotDescriptor

LONG_TYPE

public static final java.lang.String LONG_TYPE
Constant for long type in a SlotDescriptor.
See Also:
SlotDescriptor

SHORT_TYPE

public static final java.lang.String SHORT_TYPE
Constant for short type in a SlotDescriptor.
See Also:
SlotDescriptor

STRING_TYPE

public static final java.lang.String STRING_TYPE
Constant for String type in a SlotDescriptor.
See Also:
SlotDescriptor

BINARY_TYPE

public static final java.lang.String BINARY_TYPE
Constant for byte[] type in a SlotDescriptor.
See Also:
SlotDescriptor

DATE_TYPE

public static final java.lang.String DATE_TYPE
Constant for java.util.Date type in a SlotDescriptor.
See Also:
SlotDescriptor

ANY_TYPE

public static final java.lang.String ANY_TYPE
Constant for any type in a SlotDescriptor.
See Also:
SlotDescriptor

NAME_OF_ACTOR_SLOT

public static final java.lang.String NAME_OF_ACTOR_SLOT
Symbolic constant identifying a slot representing an actor

NAME_OF_ACTION_SLOT

public static final java.lang.String NAME_OF_ACTION_SLOT
Symbolic constant identifying a slot representing an action

NAME_OF_SET_FRAME

public static final java.lang.String NAME_OF_SET_FRAME
Symbolic constant identifying a frame representing a set

NAME_OF_SEQUENCE_FRAME

public static final java.lang.String NAME_OF_SEQUENCE_FRAME
Symbolic constant identifying a frame representing a sequence

FRAME_SLOT

public static final short FRAME_SLOT
Constant for category of slots whose value is an instance of a given ontological role (and can therefore be represented as a frame).
See Also:
SlotDescriptor, Frame

SET_SLOT

public static final short SET_SLOT
Constant for category of slots whose value is a set of entities
See Also:
SlotDescriptor, Frame

SEQUENCE_SLOT

public static final short SEQUENCE_SLOT
Constant for category of slots whose value is a sequence of entities
See Also:
SlotDescriptor, Frame

PRIMITIVE_SLOT

public static final short PRIMITIVE_SLOT
Constant for category of slots whose value is a primitive entity
See Also:
SlotDescriptor, Frame

ANY_SLOT

public static final short ANY_SLOT
Constant for slots whose category is not specified
See Also:
SlotDescriptor, Frame
Method Detail

addRole

public void addRole(java.lang.String roleName,
                    SlotDescriptor[] slots)
             throws OntologyException
Adds to the ontology a role without any application-specific class representing it.
Parameters:
roleName - The name of this role (names are case preserving but the match is case insensitive).
slots - An array of descriptors; each one of them describes a slot of the role, providing:
  • The name of the slot.
  • The category of the slot
  • The type of the slot.
  • The optionality of the slot (i.e. whether a value is required or not).
  • The position of the slot (implicitly defined by the position in the array).

addRole

public void addRole(java.lang.String roleName,
                    SlotDescriptor[] slots,
                    RoleEntityFactory ref)
             throws OntologyException
Adds to the ontology a role with an application-specific class representing it.
Parameters:
roleName - The name of this role (names are case preserving but the match is case insensitive).
slots - An array of descriptors; each one of them describes a slot of the role, providing:
  • The name of the slot.
  • The category of the slot
  • The type of the slot.
  • The optionality of the slot (i.e. whether a value is required or not).
  • The position of the slot (implicitly defined by the position in the array).
ref - A Factory object, which will be used to create application specific Java objects representing instances of the role that is being added.

joinOntology

public void joinOntology(Ontology o)
                  throws OntologyException
Adds to this ontology all roles included into another ontology
Parameters:
o - The Ontology object whose roles will be added

createObject

public java.util.List createObject(java.util.List v)
                            throws OntologyException
Creates a list of Java objects representing each one an instance of a given role, getting the information from a given List of Frame objects. This method requires that a factory for the given role is registered in this ontology, because it creates internally the returned object.
Parameters:
v - A List of Frame objects, from which a List of Java objects is built.
Returns:
A newly created List of Java objects, each Java object corresponding to a Frame and representing an entity in the domain.
Throws:
OntologyException - If a Frame does not represent an instance of any role in the current ontology, or if the registered class does not follow the rules for representing a role.
See Also:
addRole(String roleName, SlotDescriptor[] slots, RoleEntityFactory ref)

createFrame

public Frame createFrame(java.lang.Object o,
                         java.lang.String roleName)
                  throws OntologyException
Creates a Frame object from a given Java object. A suitable factory must be registered in the ontology to represent the given role, and the given object must be an instance of the class returned by the getClassForRole() method of the RoleEntityFactory (an indirect instance, i.e. an instance of the class itself or of a subclass).
Parameters:
o - The Java object, from which the Frame will be built.
roleName - The name of the role represented in this ontology by the class of the given object. Note that the role name does not necessarily coincide with the name of the class representing the role. For this reason the role name must be explicitly indicated.
Returns:
A Frame object representing an instance of the given role, built from the given Object.
Throws:
OntologyException - If the given role does not exist, or the given object is not of the correct class.

check

public void check(Frame f)
           throws OntologyException
Checks whether the given Frame object represents a valid instance of some role, making sure that every slot has the correct category and type and that no mandatory slot has a null value.
Parameters:
f - The Frame object to check.
Throws:
OntologyException - If the check fails.

check

public void check(java.lang.Object o,
                  java.lang.String roleName)
           throws OntologyException
Checks whether the given Java object represents a valid instance of some role, making sure that every slot has the correct category and type and that no mandatory slot has a null value.
Parameters:
o - The Java object to check.
roleName - The role against which to check the given object.
Throws:
OntologyException - If the check fails.

isRole

public boolean isRole(java.lang.String roleName)
               throws OntologyException
Tells whether a given string is the name of a role in the current ontology.
Parameters:
roleName - The name of the role to check.
Returns:
true if a role with the given name exists, false otherwise.

getSlots

public SlotDescriptor[] getSlots(java.lang.String roleName)
                          throws OntologyException
Returns the array of SlotDescriptor objects that represent the structure of the given ontological role.
Parameters:
roleName - The name of the ontological role to examine.
Returns:
The descriptors for the selected ontology role.
See Also:
SlotDescriptor

getRoleName

public java.lang.String getRoleName(java.lang.Class c)
                             throws OntologyException
Returns:
the name of the role represented by the passed class as registered in this ontology
Throws:
OntologyException - if no role is found for this class

getVocabulary

public java.util.List getVocabulary()
Returns:
a List including the names of all the roles in the ontology, i.e. the Vocabulary used by the ontology

getFactory

public RoleEntityFactory getFactory(java.lang.String roleName)
                             throws OntologyException
Returns the factory for instances of the user defined class representing a given role
Parameters:
roleName - The name of the ontological role.
Returns:
the factory for instances of the user defined class representing a given role
Throws:
OntologyException - if no role is found with the specified name or if a factory is not registered for the role