KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > objectweb > jac > core > rtti > RttiConf


1 /*
2   Copyright (C) 2001-2003 Renaud Pawlak <renaud@aopsys.com>,
3                           Laurent Martelli <laurent@aopsys.com>
4   
5   This program is free software; you can redistribute it and/or modify
6   it under the terms of the GNU Lesser General Public License as
7   published by the Free Software Foundation; either version 2 of the
8   License, or (at your option) any later version.
9
10   This program is distributed in the hope that it will be useful,
11   but WITHOUT ANY WARRANTY; without even the implied warranty of
12   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13   GNU Lesser General Public License for more details.
14
15   You should have received a copy of the GNU Lesser General Public License
16   along with this program; if not, write to the Free Software
17   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */

18
19 package org.objectweb.jac.core.rtti;
20
21 /**
22  * This class defines the rtti aspect.
23  *
24  * <p>It allows the programmer to add some runtime type information on
25  * the classes of its applications.
26  *
27  * <p>Some configuration methods are useless since the type
28  * information is retrieved through bytecode analysis. They are kept
29  * in the interface in case of.
30  *
31  * @see ClassItem
32  * @see MethodItem
33  * @see FieldItem
34  * @see CollectionItem
35  *
36  * @author Renaud Pawlak
37  * @author Laurent Martelli
38  */

39
40 public interface RttiConf {
41
42     /**
43      * Introduces a new member (field or method) into a given
44      * class. <b>Does not work yet.</b>
45      *
46      * <p>The target class does not declare the member but is wrapped by
47      * a wrapper that contains a member that should be considered as a
48      * base-object member.
49      *
50      * <p>Once introduced, the member will behave like a regular member
51      * if accessed or setted through the RTTI.
52      *
53      * @param target the target class where to add the memeber
54      * @param roleType the type of the role wrapper that actually
55      * contains the member
56      * @param memberType the member's type
57      * @param memberName the member's name
58      */

59     /*
60     void introduce(ClassItem target,ClassItem roleType,
61                    String memberType,String memberName);
62     */

63
64     /**
65      * Adds some written fields to a given method.
66      *
67      * <p>This configuration method must be used when a method changes
68      * some field values and does not follow the naming conventions (it
69      * is not a setter or an adder for instance).
70      *
71      * @param method the method
72      * @param writtenFields some new fields the method writes
73      */

74     void addWrittenFields(AbstractMethodItem method, String JavaDoc[] writtenFields);
75
76     /**
77      * Adds some accessed fields to a given method.
78      *
79      * <p>This configuration method must be used when a method reads
80      * some field values and does not follow the naming conventions (it
81      * is not a getter for instance).
82      *
83      * @param method the method
84      * @param accessedFields some new fields the method reads
85      */

86     void addAccessedFields(MethodItem method, String JavaDoc[] accessedFields);
87
88     /**
89      * Declare a calculated field, which is a field with only a getter
90      * and no actual field.
91      *
92      * @param cl the class item of te calculated field
93      * @param fieldName the name of the calculated field
94      * @param getterName the name of the getter method
95      * @see #addDependentField(FieldItem,String)
96      */

97     void declareCalculatedField(ClassItem cl, String JavaDoc fieldName,
98                                 String JavaDoc getterName);
99
100     /**
101      * Sets the setter of a field
102      * @param field the field
103      * @param setterName name of the setter method
104      */

105     void setSetter(FieldItem field, String JavaDoc setterName);
106
107     /**
108      * Sets the getter of a field
109      * @param field the field
110      * @param getterName name of the getter method
111      */

112     void setGetter(FieldItem field, String JavaDoc getterName);
113
114     /**
115      * Declares a field dependency. It will cause the field to be
116      * refreshed when the dependent field's value changes.
117      *
118      * @param field the field to refresh
119      * @param dependentField the name of the field it depends on. It
120      * must be in the same class as field.
121      * @see #declareCalculatedField(ClassItem,String,String)
122      */

123     void addDependentField(FieldItem field, String JavaDoc dependentField);
124
125     /**
126      * Tells that when field changes, dependentField changes too.
127      */

128     void addFieldDependency(FieldItem field, FieldItem dependentField);
129
130     /**
131      * Adds an adding method for a collection
132      *
133      * @param collection the collection's name
134      * @param method the name of the adding method
135      */

136     void addAdder(CollectionItem collection,String JavaDoc method);
137
138     /**
139      * Sets <em>the</em> adder of a collection.
140      * @param collection the collection
141      * @param method the name of the adder method
142      */

143     void setAdder(CollectionItem collection, String JavaDoc method);
144
145     /**
146      * Adds a removing method for a collection
147      * @param collection the collection
148      * @param method the name of the removing method
149      */

150     void addRemover(CollectionItem collection, String JavaDoc method);
151
152     /**
153      * Sets <em>the</em> remover of a collection.
154      *
155      * @param collection the collection
156      * @param method the name of the remover method
157      */

158     void setRemover(CollectionItem collection, String JavaDoc method);
159
160     /**
161      * Declares a field to be of a given type
162      *
163      * @param field the field
164      * @param type the type
165      *
166      * @see #setDynamicFieldType(FieldItem,MethodItem)
167      */

168     void setFieldType(FieldItem field, String JavaDoc type);
169
170     /**
171      * Use a method to dynamically determine the type of a field
172      *
173      * @param field the field
174      * @param method a static method taking as arguments a FieldItem
175      * and an Object (holder of the field), and return a ClassItem or
176      * a VirtualClassItem or a String.
177      *
178      * @see #setFieldType(FieldItem,String)
179      */

180     void setDynamicFieldType(FieldItem field, MethodItem method);
181
182     /**
183      * Sets the component type of a collection, i.e. the type of
184      * objects it contains.
185      *
186      * @param collection the collection
187      * @param type the component type of the collection
188      */

189     void setComponentType(CollectionItem collection, String JavaDoc type);
190
191     /**
192      * Declare a method's parameters to be of a given type
193      *
194      * @param method the method
195      * @param types the types of each parameteropf the method
196      */

197     void setParametersType(AbstractMethodItem method, String JavaDoc[] types) ;
198
199     /**
200      * Create a new virtual class. Virtual classes allow you extend and
201      * refine the types used by the application, so that aspects can
202      * behave differently.
203      *
204      * @param className name of the new class
205      * @param actualType the actual primitive type that is extended
206      */

207     void newVirtualClass(String JavaDoc className, ClassItem actualType);
208
209     /**
210      * Declare a repository to get instances of a class from, instead
211      * of fetching all instances of the class, when
212      * ObjectRepository.getObjects(ClassItem) is called.
213      *
214      * @param type the type of objects to add in the repository
215      * @param repositoryName the name of the object holding the repository
216      * @param repositoryCollection the collection to get the objects
217      * from. Any expression field can be used.
218      *
219      * @see org.objectweb.jac.core.ObjectRepository#getObjects(ClassItem)
220      */

221     void defineRepository(ClassItem type,
222                           String JavaDoc repositoryName,
223                           CollectionItem repositoryCollection);
224
225     /**
226      * This configuration method tells that the fields (references or
227      * collections) must be cloned when the class is cloned.
228      *
229      * @param className the class name
230      * @param fields the names of the fields that are cloned
231      */

232     void setClonedFields(String JavaDoc className, String JavaDoc[] fields);
233
234     /**
235      * Sets a user defined class on a class. This can be used by
236      * aspects user-defined configuration.
237      *
238      * @param cli the class to redefine
239      * @param className the new class name
240      */

241     void setClass(ClassItem cli, String JavaDoc className);
242
243     /**
244      * Sets a user defined class on a class' member. This can be used by
245      * aspects user-defined configuration.
246      *
247      * @param member the member whose type to redefine
248      * @param className the new class name
249      */

250     void setClass(MemberItem member, String JavaDoc className);
251
252     /**
253      * Specifies that the parameters of a method will be assigned to a
254      * given field.
255      *
256      * <p>Other aspects (such as the GUI aspect) may use this
257      * information to provide better default behaviour for the
258      * paramters.</p>
259      *
260      * @param method the of the method
261      * @param fields an array of field items, one per parameter of the
262      * method. Elements of this array may be null if some parameters
263      * are not assigned to any field.
264      */

265     void setParametersFields(AbstractMethodItem method, FieldItem[] fields);
266
267     /**
268      * This configuration method tells that the field can be set to null
269      * (forbidden by default)
270      *
271      * @param field the field
272      *
273      * @see #setNullAllowed(FieldItem,boolean)
274      */

275     void setNullAllowed(FieldItem field);
276
277     /**
278      * This configuration method tells wether the field can be set to
279      * null or not. (forbidden by default)
280      *
281      * @param field the field
282      * @param allowed wether to allow null values
283      *
284      * @see #setNullAllowed(FieldItem)
285      */

286     void setNullAllowed(FieldItem field, boolean allowed);
287
288     /**
289      * Tells if JAC object-typed (references) arguments of a method can take
290      * null value while the method's invocation or if they should be
291      * choosen in existing instances list.
292      *
293      * @param method the method
294      * @param nulls a flags array that tells for each parameter whether
295      * it can be null (true) or not (false). It has no effect if the
296      * parameter is not a JAC object (a reference)
297      */

298     void setNullAllowedParameters(AbstractMethodItem method,
299                                   boolean[] nulls);
300
301     /**
302      * Specify wether a Map implementing a collection is a mere index
303      * for the collection (this is not the default). In this case,
304      * CollectionItem.getActualCollection() returns the values
305      * contained in the hashtable, otherwise the (key,values) entries
306      * are returned.
307      *
308      * @param collection the collection
309      * @param isIndex wether the map is an index
310      *
311      * @see #setIndexedField(CollectionItem,FieldItem)
312      * @see CollectionItem#getActualCollection(Object)
313      * @see CollectionItem#getActualCollectionThroughAccessor(Object)
314      */

315     void setIsIndex(CollectionItem collection, boolean isIndex);
316
317     /**
318      * Tells that a Map implementing a collection indexes a field of
319      * the contained objects.
320      *
321      * @param collection the collection
322      * @param indexedField the field which is indexed by the map
323      *
324      * @see #setIsIndex(CollectionItem,boolean)
325      * @see CollectionItem#getActualCollection(Object)
326      * @see CollectionItem#getActualCollectionThroughAccessor(Object)
327      */

328     void setIndexedField(CollectionItem collection, FieldItem indexedField);
329
330     /**
331      * Defines primary keys for a collection.
332      *
333      * <p>It is used to check for double entries in the collection by
334      * checking the precised fields (it is the same as primary keys in
335      * a database).</p>
336      */

337     void definePrimaryKey(CollectionItem collection, String JavaDoc[] fields);
338
339     /**
340      * Tells wether a relation is an aggregation or not. By default,
341      * relations are not aggregations.
342      *
343      * @param field the relation
344      * @param isAggregation wether the relation is an aggregations or not.
345      */

346     void setAggregation(FieldItem field, boolean isAggregation);
347
348     /**
349      * <p>Specify that a type can be safely casted into another type.</p>
350      *
351      * <p>It can be useful it you changed the type of a field to a
352      * subclass of the original type that only adds new methods, and a
353      * persistence aspect complains that it cannot load this field
354      * anymore. dest should have constructor which takes a value of
355      * type src as the only argument.</p>
356      *
357      * @param src type of the value to be casted
358      * @param dest type the value should be casted to
359      */

360     void addAllowedCast(ClassItem src, ClassItem dest);
361
362     /**
363      * Sets the opposite role of a reference or collection field
364      *
365      * @param field the field whose opposite role to set
366      * @param oppositeRole the opposite role of the fieldb
367      *
368      * @see #declareAssociation(FieldItem,FieldItem)
369      */

370     void setOppositeRole(FieldItem field, FieldItem oppositeRole);
371
372     /**
373      * Declares an association made of two roles.
374      *
375      * <p>When declared, the relations that constitutes the
376      * association's roles are tagged in the RTTI by the
377      * <code>RttiAC.OPPOSITE_RELATION</code> attribute (then they can
378      * be interpreted by other aspects such as Integrity, GUI or
379      * Persistence).
380      *
381      * <p>For instance, if you have a Customer class and an Order
382      * class:</p>
383      *
384      * <pre>
385      * ,----------. 1 n ,-------.
386      * | Customer |--------| Order |
387      * `----------' `-------'
388      * </pre>
389      *
390      * @param roleA the starting role (e.g. Customer.orders)
391      * @param roleB the ending role (e.g. Order.customer)
392      */

393     void declareAssociation(FieldItem roleA, FieldItem roleB);
394
395     /**
396      * Adds a mixin method to a class.
397      *
398      * <p>A mixin method of class is a method which is not defined in
399      * the code of that class, but which will be made available on
400      * that class's ClassItem.</p>
401      *
402      * @param cli a class
403      * @param method a static method whose 1st argument must be cli.
404      *
405      * @see MixinMethodItem#invoke(Object,Object[])
406      */

407     void addMixinMethod(ClassItem cli, MethodItem method) throws InvalidDelegateException;
408 }
409
Popular Tags