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 }