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  [] 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  [] 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   fieldName,
98                                  String   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   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   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   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   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   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   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   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   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   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  [] 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   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   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   className, String  [] 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   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   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  [] 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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags