1 /******************************************************************
2 JADE - Java Agent DEvelopment Framework is a framework to develop
3 multi-agent systems in compliance with the FIPA specifications.
4 Copyright (C) 2000 CSELT S.p.A.
5
6 The updating of this file to JADE 2.0 has been partially supported by the IST-1999-10211 LEAP Project
7
8 GNU Lesser General Public License
9
10 This library is free software; you can redistribute it and/or
11 modify it under the terms of the GNU Lesser General Public
12 License as published by the Free Software Foundation,
13 version 2.1 of the License.
14
15 This library is distributed in the hope that it will be useful,
16 but WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 Lesser General Public License for more details.
19
20 You should have received a copy of the GNU Lesser General Public
21 License along with this library; if not, write to the
22 Free Software Foundation, Inc., 59 Temple Place - Suite 330,
23 Boston, MA 02111-1307, USA.
24 *****************************************************************/
25
26 package sl;
27 import java.util.List;
28
29
30 /***
31 An application specific ontology is represented by a properly initialized
32 instance of
33 a class implementing the <code>Ontology</code>interface. It should be noticed
34 in fact that two instances of the same class implementing the
35 <code>Ontology</code> interface can represent two different ontologies,
36 provided that they have been initialized differently.<br>
37 <br>
38 In the adopted approach, a generic item included in an ontology is called
39 a <b>role</b>. For example the concepts <i>Company<i> and <i>Person</i>, the
40 predicate <i>WorfsFor</i> and the action <i>Engage</i> can be <b>roles</b>
41 in an ontology dealing with employees.<br>
42 Each ontological role is characterised by a <b>name</b> and a structure
43 defined in terms of a number of <b>slots</b>. For instance the <i>Person</i> role
44 will have the name "person" and some slots describing the person's first-name,
45 family-name and age. In case of an ontological role that is an action the
46 slots describes the arguments of the action<br>
47 A slot on its turn is characterised by
48 <ul>
49 <li> a <b>name</b> identifying the slot </li>
50 <li> a <b>category</b> stating that the value of the slot can be a primitive
51 entity such as a string or an integer (<code>PRIMITIVE_SLOT<code>), an
52 instance of another ontologycal role (<code>FRAME_SLOT<code>) or a set
53 (<code>SET_SLOT<code>) or sequence (<code>SEQUENCE_SLOT<code>)
54 of entities.</li>
55 <li> a <b>type</b> defining the primitive type (for <code>PRIMITIVE_SLOT<code>)
56 or role (for <code>FRAME_SLOT<code>) of the value of the
57 slot or of the elements in the set/sequence in case of <code>SET_SLOT<code>
58 or <code>SEQUENCE_SLOT<code>. </li>
59 <li> a <b>presence<b> flag defining whether the slot is mandatory or
60 optional.</li>
61 </ul>
62 <br>
63 Entities in a specific domain, i.e. instances of the ontological roles,
64 can be conveniently represented inside an agent as instances of
65 application-specific Java classes each one representing a role.<br>
66 For example the class
67 <code>
68 public class Person {
69 String name;
70 int age;
71
72 void setName(String n) { name = n; }
73 String getName() { return name; }
74 void setAge(int a) { age = a; }
75 int getAge() { return age; }
76 }
77 </code>
78 can represent the <i>Person</i> role and instances of this role
79 can be represented as <code>Person</code> objects.<br>
80 <br>
81 An alternative, yet less convenient, way of representing a domain
82 entity is as an instance of the <code>Frame</code> class that is designed
83 so that each entity (regardless of the role it is an instance of)
84 can be represented
85 as a <code>Frame</code> object. This class is however mostly used
86 in JADE internal conversions.<br>
87 <br>
88 The methods in the <code>Ontology</code> interface allows to
89 <ul>
90 <li> Initialize an object representing an ontology (i.e. an
91 instance of a class implementing the <code>Ontology</code> interface)
92 by adding to it all the ontological roles included in the ontology
93 and specifying for each role the application specific class
94 representing that role</li>
95
96 <li> Convert a <code>Frame</code> representing an entity
97 into/from an instance of the application specific class
98 representing the role this entity is an instance of</li>
99
100 <li> In the above conversion perform all the necessary ontological
101 checks e.g. that the age of a person is an integer value</li>
102 </ul>
103 <br>
104 In order to represent an ontological role, a Java class must
105 obey to some rules:
106
107 <ol>
108
109 <li><i> Primitive types such as <code>int</code> and <code>boolean</code>
110 cannot be used. Use <code>Integer</code> and <code>Boolean</code> classes
111 instead.</i>
112 </li>
113
114 <li><i> For every <code>slot</code> in the role named <code>XXX</code>,
115 of category <code>PRIMITIVE_SLOT</code> or <code>FRAME_SLOT</code> and
116 of type <code>T</code> the class must have two accessible methods,
117 with the following signature:</i>
118 <ul>
119 <li> <code>T getXXX()</code>
120 <li> <code>void setXXX(T t)</code>
121 </ul>
122 </li>
123
124 <li><i> For every <b>slot</b> in the role named <code>XXX</code>,
125 of category <code>SET_TERM</code> or <code>SEQUENCE_TERM</code> and
126 with elements of type <code>T</code>, the class must have two accessible
127 methods, with the following signature:</i>
128 <ul>
129 <li> <code>Iterator getAllXXX()</code>
130 <li> <code>void addXXX(T t)</code>
131 </ul>
132 </li>
133
134 </ol>
135
136 As long as the above rules are followed, any user-defined class
137 can be added to the Ontology object. As a useful technique, one
138 can define compliant Java interfaces and add them to the
139 Ontology; this way useful OO idioms such as polymorphism and
140 mix-in inheritance can be exploited for the Java representations
141 of ontological objects.
142
143 Due to different lexical conventions between the Java language
144 and FIPA ACL and content languages, some name translation must be
145 performed to map the name of a slot into the name of the
146 corresponding get and set methods.
147 Name translation works as follows:
148 <ol>
149 <li> Any <code>':'</code> character must be removed.
150 <li> Any <code>'-'</code> character must be removed.
151 </ol>
152 Moreover, a case insensitive match is followed.
153
154 As an example, a role with an integer slot named
155 <code>:user-age</code>, will require the following methods (case
156 is not important, but according to a popular Java coding
157 convention, the two methods have capital letters whenever a
158 <code>'-'</code> is present in the slot name):
159
160 <ul>
161 <li><code>int getUserAge()</code>
162 <li><code>void setUserAge(int age)</code>
163 </ul>
164
165 @author Giovanni Rimassa - Universita` di Parma
166 @version $Date: 2003/10/09 13:00:37 $ $Revision: 1.1.1.1 $
167 @see jade.lang.Codec
168 @see jade.onto.Frame
169 @see jade.onto.SlotDescriptor
170 */
171
172 public interface Ontology {
173
174 /***
175 Boolean constant for <i>Optional</i> slots.
176 */
177 static final boolean O = true;
178
179 /***
180 Boolean constant for <i>Mandatory</i> slots.
181 */
182 static final boolean M = false;
183
184
185
186
187
188 /***
189 Constant for <code>boolean</code> type in a <code>SlotDescriptor</code>.
190 @see jade.onto.SlotDescriptor
191 */
192 static final String BOOLEAN_TYPE = "java.lang.Boolean";
193
194 /***
195 Constant for <code>byte</code> type in a <code>SlotDescriptor</code>.
196 @see jade.onto.SlotDescriptor
197 */
198 static final String BYTE_TYPE = "java.lang.Byte";
199
200 /***
201 Constant for <code>char</code> type in a <code>SlotDescriptor</code>.
202 @see jade.onto.SlotDescriptor
203 */
204 static final String CHARACTER_TYPE = "java.lang.Character";
205
206 /***
207 Constant for <code>double</code> type in a <code>SlotDescriptor</code>.
208 @see jade.onto.SlotDescriptor
209 */
210 static final String DOUBLE_TYPE = "java.lang.Double";
211
212 /***
213 Constant for <code>float</code> type in a <code>SlotDescriptor</code>.
214 @see jade.onto.SlotDescriptor
215 */
216 static final String FLOAT_TYPE = "java.lang.Float";
217
218 /***
219 Constant for <code>int</code> type in a <code>SlotDescriptor</code>.
220 @see jade.onto.SlotDescriptor
221 */
222 static final String INTEGER_TYPE = "java.lang.Integer";
223
224 /***
225 Constant for <code>long</code> type in a <code>SlotDescriptor</code>.
226 @see jade.onto.SlotDescriptor
227 */
228 static final String LONG_TYPE = "java.lang.Long";
229
230 /***
231 Constant for <code>short</code> type in a <code>SlotDescriptor</code>.
232 @see jade.onto.SlotDescriptor
233 */
234 static final String SHORT_TYPE = "java.lang.Short";
235
236 /***
237 Constant for <code>String</code> type in a <code>SlotDescriptor</code>.
238 @see jade.onto.SlotDescriptor
239 */
240 static final String STRING_TYPE = "java.lang.String";
241
242 /***
243 Constant for <code>byte[]</code> type in a <code>SlotDescriptor</code>.
244 @see jade.onto.SlotDescriptor
245 */
246 static final String BINARY_TYPE = "java.lang.Byte[]";
247
248 /***
249 Constant for <code>java.util.Date</code> type in a
250 <code>SlotDescriptor</code>.
251 @see jade.onto.SlotDescriptor
252 */
253 static final String DATE_TYPE = "java.util.Date";
254
255 /***
256 Constant for any type in a <code>SlotDescriptor</code>.
257 @see jade.onto.SlotDescriptor
258 */
259 static final String ANY_TYPE = "java.lang.Object";
260
261
262 /*** Symbolic constant identifying a frame representing a set **/
263 public static String NAME_OF_SET_FRAME = "set";
264 /*** Symbolic constant identifying a frame representing a sequence **/
265 public static String NAME_OF_SEQUENCE_FRAME = "sequence";
266
267
268 /***
269 Constant for category of slots whose value is an instance of a given
270 ontological role (and can therefore be represented as a frame).
271 @see jade.onto.SlotDescriptor
272 @see jade.onto.Frame
273 */
274 static final short FRAME_SLOT = 12;
275
276 /***
277 Constant for category of slots whose value is a <code>set</code> of entities
278 @see jade.onto.SlotDescriptor
279 @see jade.onto.Frame
280 */
281 static final short SET_SLOT = 13;
282
283 /***
284 Constant for category of slots whose value is a <code>sequence</code> of entities
285 @see jade.onto.SlotDescriptor
286 @see jade.onto.Frame
287 */
288 static final short SEQUENCE_SLOT = 14;
289
290 /***
291 Constant for category of slots whose value is a primitive entity
292 @see jade.onto.SlotDescriptor
293 @see jade.onto.Frame
294 */
295 static final short PRIMITIVE_SLOT = 15;
296
297 /***
298 Constant for slots whose category is not specified
299 @see jade.onto.SlotDescriptor
300 @see jade.onto.Frame
301 */
302 static final short ANY_SLOT = 16;
303
304
305
306
307 /***
308 Adds to the ontology a role without any application-specific class
309 representing it.
310 @param roleName The name of this role (names are case
311 preserving but the match is case insensitive).
312 @param slots An array of descriptors; each one of them describes a
313 slot of the role, providing:
314 <ul>
315 <li> The name of the slot.
316 <li> The category of the slot
317 <li> The type of the slot.
318 <li> The optionality of the slot (i.e. whether a value is required or not).
319 <li> The position of the slot (implicitly defined by the position in the array).
320 </ul>
321 */
322 void addRole(String roleName, SlotDescriptor[] slots) throws OntologyException;
323
324 /***
325 Adds to the ontology a role with an application-specific class
326 representing it.
327 @param roleName The name of this role (names are case
328 preserving but the match is case insensitive).
329 @param slots An array of descriptors; each one of them describes a
330 slot of the role, providing:
331 <ul>
332 <li> The name of the slot.
333 <li> The category of the slot
334 <li> The type of the slot.
335 <li> The optionality of the slot (i.e. whether a value is required or not).
336 <li> The position of the slot (implicitly defined by the position in the array).
337 </ul>
338 @param ref the <code>Class</code> which will be used to create
339 application specific Java objects representing instances of the role that
340 is being added.
341 */
342 void addRole(String roleName, SlotDescriptor[] slots, Class c) throws OntologyException;
343
344 /***
345 Adds to this ontology all roles included into another ontology
346 @param o The <code>Ontology</code> object whose roles will
347 be added
348 */
349 void joinOntology(Ontology o) throws OntologyException;
350
351 /***
352 Creates a list of Java objects representing each one an instance of
353 a given role, getting the
354 information from a given <code>List</code> of <code>Frame</code>
355 objects. This method
356 requires that a factory for the given role is registered in this ontology,
357 because it creates internally the returned object.
358 @param v A <code>List</code> of <code>Frame</code> objects,
359 from which a <code>List</code> of Java objects is built.
360 @return A newly created <code>List</code> of Java objects,
361 each Java object corresponding to a <code>Frame</code> and representing an
362 entity in the domain.
363 @exception OntologyException If a <code>Frame</code> does
364 not represent an instance of any role in the current ontology,
365 or if the registered class does not follow the rules for representing a role.
366 @see jade.onto.Ontology#addRole(String roleName, SlotDescriptor[] slots, RoleEntityFactory ref)
367 */
368 List createObject(List v) throws OntologyException;
369
370 /***
371 Creates a <code>Frame</code> object from a given Java object. A
372 suitable factory must be registered in the ontology to represent the
373 given role, and the given object must be an instance of the class returned
374 by the <code>getClassForRole()</code> method of the <code>RoleEntityFactory</code>
375 (an indirect instance, i.e. an instance of the class itself or of a subclass).
376 @param o The Java object, from which the <code>Frame</code> will
377 be built.
378 @param roleName The name of the role represented in this ontology by
379 the class of the given object. Note that the role name does not
380 necessarily coincide with the name of the class representing the role.
381 For this reason the role name must be explicitly indicated.
382 @return A <code>Frame</code> object representing an instance of
383 the given role, built from the given <code>Object</code>.
384 @exception OntologyException If the given role does not exist, or
385 the given object is not of the correct class.
386 */
387 Frame createFrame(Object o, String roleName) throws OntologyException;
388
389 /***
390 Checks whether the given <code>Frame</code> object represents a valid
391 instance of some role, making sure that every slot has the correct
392 category and type and that no mandatory slot has a <code>null</code> value.
393 @param f The <code>Frame</code> object to check.
394 @exception OntologyException If the check fails.
395 */
396 void check(Frame f) throws OntologyException;
397
398 /***
399 Checks whether the given Java object represents a valid instance of some
400 role, making sure that every slot has the correct category and type and
401 that no mandatory slot has a <code>null</code> value.
402 @param o The Java object to check.
403 @param roleName The role against which to check the given object.
404 @exception OntologyException If the check fails.
405 */
406 void check(Object o, String roleName) throws OntologyException;
407
408 /***
409 Tells whether a given string is the name of a role in the current
410 ontology.
411 @param roleName The name of the role to check.
412 @return <code>true</code> if a role with the given name exists,
413 <code>false</code> otherwise.
414 */
415 boolean isRole(String roleName) throws OntologyException;
416
417 /***
418 Returns the array of <code>SlotDescriptor</code> objects that
419 represent the structure of the given ontological role.
420 @param roleName The name of the ontological role to examine.
421 @return The descriptors for the selected ontology role.
422 @see jade.onto.SlotDescriptor
423 */
424 SlotDescriptor[] getSlots(String roleName) throws OntologyException;
425
426 /***
427 @return the name of the role represented by the passed class as
428 registered in this ontology
429 @throws OntologyException if no role is found for this class
430 */
431 String getRoleName(Class c) throws OntologyException;
432
433 /***
434 @return a <code>List</code> including the names of all the roles
435 in the ontology, i.e. the Vocabulary used by the ontology
436 */
437 List getVocabulary();
438
439 /***
440 Creates an object, starting from a given frame. This method can just create
441 the object ignoring its argument, or it can use the frame to select the
442 concrete class to instantiate.
443 @param f A frame containing initialization data for the object.
444 @return A Java object, instance of the proper class (either the class
445 returned by <code>getClassForRole()</code>, or one of its subclasses).
446 */
447 Object create(Frame f) throws OntologyException;
448
449 /***
450 Provides the Java class associated with this ontological role. This class is
451 usually the class used by the <code>create()</code> method to instantiate
452 objects. A useful technique is returning an interface or an abstract class,
453 while using concrete subclasses to create objects.
454 @param a string representing the name of the ontological role
455 @return the Java class that plays this ontological role (e.g. <code>DFAgentDescription.class</code>, null if no class has been registered for this role.
456 */
457 Class getClassForRole(String roleName);
458
459 /***
460 * This method initialized this ontology object on the basis of its
461 * representation as an SL-0 expression.
462 * This expression is based on the JADE-Meta-Ontology encoded in the
463 * package <code>jade.onto.JadeMetaOntology</code
464 * @param str is the SL-0 expression representing this ontology
465 * @return the name of the ontology
466 * @see toSL0String()
467 * @see jade.lang.sl.SL0Codec
468 * @see jade.onto.JadeMetaOntology.JADEMetaOntology
469 **/
470 String fromSL0String(String str) throws CodecException, OntologyException;
471
472 /***
473 * This method encodes the current ontology according to the SL-0 syntax
474 * and the JADE-meta-ontology ontology.
475 * @param ontologyName the name of this ontology
476 * @return a String that is an SL-0 expression representing this ontology
477 * @see fromSL0String(String)
478 * @see jade.lang.sl.SL0Codec
479 * @see jade.onto.JadeMetaOntology.JADEMetaOntology
480 **/
481 public String toSL0String(String ontologyName) throws OntologyException;
482
483 /***
484 * Return an object representing this ontology in terms of the
485 * JADE-Meta-Ontology and that is suitable to be encoded as a String and,
486 * for instance, become the content of an ACLMessage.
487 * @param ontologyName is the name of this ontology. It cannot be either
488 * null or an empty String.
489 * @return a JADE-Meta-Ontology
490 **/
491 public AnOntology toMetaOntologyRepresentation(String ontologyName);
492
493 /***
494 * Initialize this ontology based on the passed meta-ontology
495 * @param o is a JADE-Meta-Ontology
496 **/
497 public void fromMetaOntologyRepresentation(AnOntology o) throws OntologyException;
498 }