BaseProgramListener


1   /*
2     Copyright (C) 2001-2002 Renaud Pawlak. <renaud@aopsys.com>
3   
4     This program is free software; you can redistribute it and/or modify
5     it under the terms of the GNU Lesser General Public License as published by
6     the Free Software Foundation; either version 2 of the License, or
7     (at your option) any later version.
8   
9     This program is distributed in the hope that it will be useful,
10    but WITHOUT ANY WARRANTY; without even the implied warranty of
11    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12    GNU Lesser General Public License for more details.
13  
14    You should have received a copy of the GNU Lesser General Public
15    License along with this program; if not, write to the Free Software
16    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
17    USA */
18  
19  package org.objectweb.jac.core;
20  
21  import java.util.*;
22  
23  import org.objectweb.jac.core.rtti.*;
24  
25  /**
26   * This interface specify the prototypes of the methods that can be
27   * notified when an event occurs within the base program.
28   * 
29   * <p>This can be regarded as the JAC Meta-Object Protocol (MOP).
30   *
31   * @author Renaud Pawlak
32   */
33  
34  public interface BaseProgramListener {
35  
36     /**
37      * This method is upcalled by JAC when a given instance is used for
38      * the first time at construction-time.
39      * 
40      * <p>Informations about the called method can be retrieved by
41      * using the <code>CollaborationParticipant</code> methods.<br>
42      *
43      * @param interaction the interaction that triggered the
44      * whenUsingNewInstance event (usually a constructor invocation)
45      *
46      * @see CollaborationParticipant 
47      * @see #whenUsingNewClass(ClassItem) */
48     void whenUsingNewInstance(Interaction interaction);
49  
50     /**
51      * This method is upcalled by JAC when a static method is called
52      * for the first time.
53      *
54      * @param cl the class that is used for the first time.
55      *
56      * @see CollaborationParticipant 
57      * @see #whenUsingNewInstance(Interaction) */
58     void whenUsingNewClass(ClassItem cl);
59  
60     /**
61      * This method is upcalled by JAC when a new object is instantiated
62      * from a remote site.
63      *
64      * <p>The name that is passed is the name of the remote
65      * reference that has been used to create the object.
66      * 
67      * @param newInstance the instance that have been created by a
68      * remote host
69      * @param name the name of the new instance 
70      */
71     void whenRemoteInstantiation(Wrappee newInstance, String   name);
72  
73     /**
74      * This method is upcalled by JAC when a JAC object is cloned.
75      * 
76      * @param cloned the object that is being cloned
77      * @param clone the new object (the clone of cloned) 
78      */
79     void whenClone(Wrappee cloned, Wrappee clone);
80  
81  
82     /**
83      * This method is called when a JAC object is serialized and can
84      * parametrize the serialization by filling the <code>finalObject</code>
85      * parameter.
86      *
87      * <p><b>IMPORTANT</b>: this method is upcalled only if the
88      * serialization is done with a
89      * <code>JacObjectOutputStream</code>. To ensure the correct use of
90      * this class, only use <code>JacObject.serialize()</code> to
91      * serialize an object.</p>
92      *
93      * @param orgObject the object being serialized
94      * @param finalObject the corresponding serialized structure
95      * @return the object being serialized (usually orgObject, but not
96      * necessarily).
97      * @see SerializedJacObject
98      * @see JacObjectOutputStream 
99      */
100    Wrappee whenSerialized(Wrappee orgObject,SerializedJacObject finalObject);
101 
102 
103    /**
104     * This method is called when a base object is deserialized and can
105     * parametrize the deserialization by reading the
106     * SerializedJacObject instance to get some extra infos on the
107     * aspects.
108     *
109     * <p><b>IMPORTANT</b>: this method is upcalled only if the
110     * deserialization is done with a
111     * <code>JacObjectInputStream</code>. To ensure the correct use of
112     * this class, only use <code>JacObject.deserialize()</code> to
113     * deserialize an object.
114     *
115     * @param orgObject the corresponding serialized structure
116     * @param finalObject the object being deserialized
117     * @return the object being deserialized (usually finalObject but
118     * not necessarily)
119     * @see SerializedJacObject
120     * @see JacObjectInputStream 
121     */
122    Wrappee whenDeserialized(SerializedJacObject orgObject, Wrappee finalObject);
123 
124    /**
125     * This method is upcalled by JAC when a wrapper is going to be
126     * applied to a wrappee.
127     *
128     * @param wrapper the wrapper that is going to be runned
129     * @param wrappingMethod the name of the may-be runned wrapping
130     * method
131     * @return a boolean that tells if the wrapper has to be runned
132     * (true) or not (false)
133     * @see Wrappee
134     * @see Wrapping#wrap(Wrappee,Wrapper,AbstractMethodItem)
135     * @see Wrapper
136     * @see Wrapper#proceed(Invocation) 
137     */
138    boolean beforeRunningWrapper(Wrapper wrapper, String   wrappingMethod);
139 
140    /**
141     * This method is upcalled by JAC after the application of the
142     * wrapper.
143     * 
144     * @param wrapper the wrapper that has just been runned
145     * @param wrappingMethod the name of the runned wrapping method
146     * @see Wrappee
147     * @see Wrapping#wrap(Wrappee,Wrapper,AbstractMethodItem)
148     * @see Wrapper
149     * @see Wrapper#proceed(Invocation) 
150     */
151    void afterRunningWrapper(Wrapper wrapper, 
152                             String   wrappingMethod);
153 
154    /**
155     * This method is upcalled after the wrappee is wrapped by the
156     * wrapper.
157     *
158     * @see Wrapper
159     * @see Wrappee
160     * @see Wrapping#wrap(Wrappee,Wrapper,AbstractMethodItem) 
161     */
162    void afterWrap(Wrappee wrappee, Wrapper wrapper,
163                   String  [] wrapping_methods,
164                   String  [][] wrapped_methods);
165 
166    /**
167     * Calls whenGetObjects on all aspects.
168     * @param objects list of objects already in memory
169     * @param cl return only instances of this class
170     */
171    void whenGetObjects(Collection objects, ClassItem cl);
172 
173    /**
174     * Upcalled when the naming aspect names an object.
175     *
176     * @param object the object to name
177     * @param name current name of the object or null
178     * @return the proposed name for the object
179     */
180    String   whenNameObject(Object   object, String   name);
181 
182    String   FOUND_OBJECT = "FOUND_OBJECT";
183 
184    /**
185     * Upcalled when an object is been seeked within the name
186     * repository and is not found.
187     *
188     * <p>The finally found object is a contextual attribute called
189     * FOUND_OBJECT.
190     *
191     * @param name the name that has not been found 
192     * @see #FOUND_OBJECT
193     */
194    void whenObjectMiss(String   name);
195 
196    /**
197     * Upcalled when an object is deleted.
198     * @param object the deleted object
199     */
200    void whenDeleted(Wrappee object);
201 
202    /**
203     * Upcalled when an object is freed from the memory.
204     * @param object the deleted object
205     */
206    void whenFree(Wrappee object);
207 
208    /**
209     * Upcalled after a new application is started on the JAC system.  
210     */
211    void afterApplicationStarted(); 
212 
213    /**
214     * Upcalled when a display is closing.
215     *
216     * @param display the closing display 
217     */
218    void whenCloseDisplay(Display display);
219 
220    /**
221     * This method is upcalled when a topological change occurs whithin
222     * the distributed application. */
223    void whenTopologyChanged();
224 
225    /**
226     * This method is upcalled when the system exits.
227     */
228    void onExit();
229 
230     /**
231      * This method should be called by the GUI system before an object
232      * is being created and initialized (but the process is not
233      * finished yet).
234      *
235      * <p>Then, some aspects should deal differently with this object
236      * thant with already created objects (for instance, the GUI
237      * aspect should not show the object to other users, or a remote
238      * access aspect should disable forwarding. */ 
239     
240     void beforeWrappeeInit(Wrappee wrappee);
241 
242     /**
243      * This method should be called by the GUI system after an object
244      * has been created and initialized (tells the other aspects that
245      * the object is now regular). */    
246 
247     void afterWrappeeInit(Wrappee wrappee);
248 
249 }
250
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags