001    /*
002      Copyright (C) 2001-2002 Renaud Pawlak. <renaud@aopsys.com>
003    
004      This program is free software; you can redistribute it and/or modify
005      it under the terms of the GNU Lesser General Public License as published by
006      the Free Software Foundation; either version 2 of the License, or
007      (at your option) any later version.
008    
009      This program is distributed in the hope that it will be useful,
010      but WITHOUT ANY WARRANTY; without even the implied warranty of
011      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
012      GNU Lesser General Public License for more details.
013    
014      You should have received a copy of the GNU Lesser General Public
015      License along with this program; if not, write to the Free Software
016      Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
017      USA */
018    
019    package org.objectweb.jac.core;
020    
021    import java.util.*;
022    
023    import org.objectweb.jac.core.rtti.*;
024    
025    /**
026     * This interface specify the prototypes of the methods that can be
027     * notified when an event occurs within the base program.
028     * 
029     * <p>This can be regarded as the JAC Meta-Object Protocol (MOP).
030     *
031     * @author Renaud Pawlak
032     */
033    
034    public interface BaseProgramListener {
035    
036       /**
037        * This method is upcalled by JAC when a given instance is used for
038        * the first time at construction-time.
039        * 
040        * <p>Informations about the called method can be retrieved by
041        * using the <code>CollaborationParticipant</code> methods.<br>
042        *
043        * @param interaction the interaction that triggered the
044        * whenUsingNewInstance event (usually a constructor invocation)
045        *
046        * @see CollaborationParticipant 
047        * @see #whenUsingNewClass(ClassItem) */
048       void whenUsingNewInstance(Interaction interaction);
049    
050       /**
051        * This method is upcalled by JAC when a static method is called
052        * for the first time.
053        *
054        * @param cl the class that is used for the first time.
055        *
056        * @see CollaborationParticipant 
057        * @see #whenUsingNewInstance(Interaction) */
058       void whenUsingNewClass(ClassItem cl);
059    
060       /**
061        * This method is upcalled by JAC when a new object is instantiated
062        * from a remote site.
063        *
064        * <p>The name that is passed is the name of the remote
065        * reference that has been used to create the object.
066        * 
067        * @param newInstance the instance that have been created by a
068        * remote host
069        * @param name the name of the new instance 
070        */
071       void whenRemoteInstantiation(Wrappee newInstance, String name);
072    
073       /**
074        * This method is upcalled by JAC when a JAC object is cloned.
075        * 
076        * @param cloned the object that is being cloned
077        * @param clone the new object (the clone of cloned) 
078        */
079       void whenClone(Wrappee cloned, Wrappee clone);
080    
081    
082       /**
083        * This method is called when a JAC object is serialized and can
084        * parametrize the serialization by filling the <code>finalObject</code>
085        * parameter.
086        *
087        * <p><b>IMPORTANT</b>: this method is upcalled only if the
088        * serialization is done with a
089        * <code>JacObjectOutputStream</code>. To ensure the correct use of
090        * this class, only use <code>JacObject.serialize()</code> to
091        * serialize an object.</p>
092        *
093        * @param orgObject the object being serialized
094        * @param finalObject the corresponding serialized structure
095        * @return the object being serialized (usually orgObject, but not
096        * necessarily).
097        * @see SerializedJacObject
098        * @see JacObjectOutputStream 
099        */
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    }