1 /* 2 * Copyright (c) 1998, 2017, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package com.sun.jdi; 27 28 import java.util.List; 29 30 /** 31 * A mirror of a class in the target VM. A ClassType is a refinement 32 * of {@link ReferenceType} that applies to true classes in the JLS 33 * sense of the definition (not an interface, not an array type). Any 34 * {@link ObjectReference} that mirrors an instance of such a class 35 * will have a ClassType as its type. 36 * 37 * @see ObjectReference 38 * 39 * @author Robert Field 40 * @author Gordon Hirsch 41 * @author James McIlree 42 * @since 1.3 43 */ 44 public interface ClassType extends ReferenceType { 45 46 /** 47 * Gets the superclass of this class. 48 * 49 * @return a {@link ClassType} that mirrors the superclass 50 * of this class in the target VM. If no such class exists, 51 * returns null 52 */ 53 ClassType superclass(); 54 55 /** 56 * Gets the interfaces directly implemented by this class. 57 * Only the interfaces that are declared with the "implements" 58 * keyword in this class are included. 59 * 60 * @return a List of {@link InterfaceType} objects each mirroring 61 * a direct interface this ClassType in the target VM. 62 * If none exist, returns a zero length List. 63 * @throws ClassNotPreparedException if this class not yet been 64 * prepared. 65 */ 66 List<InterfaceType> interfaces(); 67 68 /** 69 * Gets the interfaces directly and indirectly implemented 70 * by this class. Interfaces returned by {@link ClassType#interfaces} 71 * are returned as well all superinterfaces. 72 * 73 * @return a List of {@link InterfaceType} objects each mirroring 74 * an interface of this ClassType in the target VM. 75 * If none exist, returns a zero length List. 76 * @throws ClassNotPreparedException if this class not yet been 77 * prepared. 78 */ 79 List<InterfaceType> allInterfaces(); 80 81 /** 82 * Gets the currently loaded, direct subclasses of this class. 83 * No ordering of this list is guaranteed. 84 * 85 * @return a List of {@link ClassType} objects each mirroring a loaded 86 * subclass of this class in the target VM. If no such classes 87 * exist, this method returns a zero-length list. 88 */ 89 List<ClassType> subclasses(); 90 91 /** 92 * Determine if this class was declared as an enum. 93 * @return <code>true</code> if this class was declared as an enum; false 94 * otherwise. 95 */ 96 boolean isEnum(); 97 98 /** 99 * Assigns a value to a static field. 100 * The {@link Field} must be valid for this ClassType; that is, 101 * it must be from the mirrored object's class or a superclass of that class. 102 * The field must not be final. 103 * <p> 104 * Object values must be assignment compatible with the field type 105 * (This implies that the field type must be loaded through the 106 * enclosing class' class loader). Primitive values must be 107 * either assignment compatible with the field type or must be 108 * convertible to the field type without loss of information. 109 * See JLS section 5.2 for more information on assignment 110 * compatibility. 111 * 112 * @param field the field to set. 113 * @param value the value to be assigned. 114 * @throws java.lang.IllegalArgumentException if the field is 115 * not static, the field is final, or the field does not exist 116 * in this class. 117 * @throws ClassNotLoadedException if the field type has not yet been loaded 118 * through the appropriate class loader. 119 * @throws InvalidTypeException if the value's type does not match 120 * the field's declared type. 121 * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}. 122 */ 123 void setValue(Field field, Value value) 124 throws InvalidTypeException, ClassNotLoadedException; 125 126 /** Perform method invocation with only the invoking thread resumed */ 127 static final int INVOKE_SINGLE_THREADED = 0x1; 128 129 /** 130 * Invokes the specified static {@link Method} in the 131 * target VM. The 132 * specified method can be defined in this class, 133 * or in a superclass. 134 * The method must be a static method 135 * but not a static initializer. 136 * Use {@link ClassType#newInstance} to create a new object and 137 * run its constructor. 138 * <p> 139 * The method invocation will occur in the specified thread. 140 * Method invocation can occur only if the specified thread 141 * has been suspended by an event which occurred in that thread. 142 * Method invocation is not supported 143 * when the target VM has been suspended through 144 * {@link VirtualMachine#suspend} or when the specified thread 145 * is suspended through {@link ThreadReference#suspend}. 146 * <p> 147 * The specified method is invoked with the arguments in the specified 148 * argument list. The method invocation is synchronous; this method 149 * does not return until the invoked method returns in the target VM. 150 * If the invoked method throws an exception, this method will throw 151 * an {@link InvocationException} which contains a mirror to the exception 152 * object thrown. 153 * <p> 154 * Object arguments must be assignment compatible with the argument type 155 * (This implies that the argument type must be loaded through the 156 * enclosing class' class loader). Primitive arguments must be 157 * either assignment compatible with the argument type or must be 158 * convertible to the argument type without loss of information. 159 * If the method being called accepts a variable number of arguments, 160 * then the last argument type is an array of some component type. 161 * The argument in the matching position can be omitted, or can be null, 162 * an array of the same component type, or an argument of the 163 * component type followed by any number of other arguments of the same 164 * type. If the argument is omitted, then a 0 length array of the 165 * component type is passed. The component type can be a primitive type. 166 * Autoboxing is not supported. 167 * 168 * See Section 5.2 of 169 * <cite>The Java Language Specification</cite> 170 * for more information on assignment compatibility. 171 * <p> 172 * By default, all threads in the target VM are resumed while 173 * the method is being invoked if they were previously 174 * suspended by an event or by {@link VirtualMachine#suspend} or 175 * {@link ThreadReference#suspend}. This is done to prevent the deadlocks 176 * that will occur if any of the threads own monitors 177 * that will be needed by the invoked method. 178 * Note, however, that this implicit resume acts exactly like 179 * {@link ThreadReference#resume}, so if the thread's suspend 180 * count is greater than 1, it will remain in a suspended state 181 * during the invocation and thus a deadlock could still occur. 182 * By default, when the invocation completes, 183 * all threads in the target VM are suspended, regardless their state 184 * before the invocation. 185 * It is possible that 186 * breakpoints or other events might occur during the invocation. 187 * This can cause deadlocks as described above. It can also cause a deadlock 188 * if invokeMethod is called from the client's event handler thread. In this 189 * case, this thread will be waiting for the invokeMethod to complete and 190 * won't read the EventSet that comes in for the new event. If this 191 * new EventSet is SUSPEND_ALL, then a deadlock will occur because no 192 * one will resume the EventSet. To avoid this, all EventRequests should 193 * be disabled before doing the invokeMethod, or the invokeMethod should 194 * not be done from the client's event handler thread. 195 * <p> 196 * The resumption of other threads during the invocation can be prevented 197 * by specifying the {@link #INVOKE_SINGLE_THREADED} 198 * bit flag in the <code>options</code> argument; however, 199 * there is no protection against or recovery from the deadlocks 200 * described above, so this option should be used with great caution. 201 * Only the specified thread will be resumed (as described for all 202 * threads above). Upon completion of a single threaded invoke, the invoking thread 203 * will be suspended once again. Note that any threads started during 204 * the single threaded invocation will not be suspended when the 205 * invocation completes. 206 * <p> 207 * If the target VM is disconnected during the invoke (for example, through 208 * {@link VirtualMachine#dispose}) the method invocation continues. 209 * 210 * @param thread the thread in which to invoke. 211 * @param method the {@link Method} to invoke. 212 * @param arguments the list of {@link Value} arguments bound to the 213 * invoked method. Values from the list are assigned to arguments 214 * in the order they appear in the method signature. 215 * @param options the integer bit flag options. 216 * @return a {@link Value} mirror of the invoked method's return value. 217 * @throws java.lang.IllegalArgumentException if the method is not 218 * a member of this class or a superclass, if the size of the argument list 219 * does not match the number of declared arguments for the method, or 220 * if the method is an initializer, constructor or static intializer. 221 * @throws ClassNotLoadedException if any argument type has not yet been loaded 222 * through the appropriate class loader. 223 * @throws IncompatibleThreadStateException if the specified thread has not 224 * been suspended by an event. 225 * @throws InvocationException if the method invocation resulted in 226 * an exception in the target VM. 227 * @throws InvalidTypeException If the arguments do not meet this requirement -- 228 * Object arguments must be assignment compatible with the argument 229 * type. This implies that the argument type must be 230 * loaded through the enclosing class' class loader. 231 * Primitive arguments must be either assignment compatible with the 232 * argument type or must be convertible to the argument type without loss 233 * of information. See JLS section 5.2 for more information on assignment 234 * compatibility. 235 * @throws VMCannotBeModifiedException if the VirtualMachine is read-only - see {@link VirtualMachine#canBeModified()}. 236 */ 237 Value invokeMethod(ThreadReference thread, Method method, 238 List<? extends Value> arguments, int options) 239 throws InvalidTypeException, 240 ClassNotLoadedException, 241 IncompatibleThreadStateException, 242 InvocationException; 243 244 /** 245 * Constructs a new instance of this type, using 246 * the given constructor {@link Method} in the 247 * target VM. The 248 * specified constructor must be defined in this class. 249 * <p> 250 * Instance creation will occur in the specified thread. 251 * Instance creation can occur only if the specified thread 252 * has been suspended by an event which occurred in that thread. 253 * Instance creation is not supported 254 * when the target VM has been suspended through 255 * {@link VirtualMachine#suspend} or when the specified thread 256 * is suspended through {@link ThreadReference#suspend}. 257 * <p> 258 * The specified constructor is invoked with the arguments in the specified 259 * argument list. The invocation is synchronous; this method 260 * does not return until the constructor returns in the target VM. 261 * If the invoked method throws an 262 * exception, this method will throw an {@link InvocationException} 263 * which contains a mirror to the exception object thrown. 264 * <p> 265 * Object arguments must be assignment compatible with the argument type 266 * (This implies that the argument type must be loaded through the 267 * enclosing class' class loader). Primitive arguments must be 268 * either assignment compatible with the argument type or must be 269 * convertible to the argument type without loss of information. 270 * If the method being called accepts a variable number of arguments, 271 * then the last argument type is an array of some component type. 272 * The argument in the matching position can be omitted, or can be null, 273 * an array of the same component type, or an argument of the 274 * component type, followed by any number of other arguments of the same 275 * type. If the argument is omitted, then a 0 length array of the 276 * component type is passed. The component type can be a primitive type. 277 * Autoboxing is not supported. 278 * 279 * See section 5.2 of 280 * <cite>The Java Language Specification</cite> 281 * for more information on assignment compatibility. 282 * <p> 283 * By default, all threads in the target VM are resumed while 284 * the method is being invoked if they were previously 285 * suspended by an event or by {@link VirtualMachine#suspend} or 286 * {@link ThreadReference#suspend}. This is done to prevent the deadlocks 287 * that will occur if any of the threads own monitors 288 * that will be needed by the invoked method. It is possible that 289 * breakpoints or other events might occur during the invocation. 290 * Note, however, that this implicit resume acts exactly like 291 * {@link ThreadReference#resume}, so if the thread's suspend 292 * count is greater than 1, it will remain in a suspended state 293 * during the invocation. By default, when the invocation completes, 294 * all threads in the target VM are suspended, regardless their state 295 * before the invocation. 296 * <p> 297 * The resumption of other threads during the invocation can be prevented 298 * by specifying the {@link #INVOKE_SINGLE_THREADED} 299 * bit flag in the <code>options</code> argument; however, 300 * there is no protection against or recovery from the deadlocks 301 * described above, so this option should be used with great caution. 302 * Only the specified thread will be resumed (as described for all 303 * threads above). Upon completion of a single threaded invoke, the invoking thread 304 * will be suspended once again. Note that any threads started during 305 * the single threaded invocation will not be suspended when the 306 * invocation completes. 307 * <p> 308 * If the target VM is disconnected during the invoke (for example, through 309 * {@link VirtualMachine#dispose}) the method invocation continues. 310 * 311 * @param thread the thread in which to invoke. 312 * @param method the constructor {@link Method} to invoke. 313 * @param arguments the list of {@link Value} arguments bound to the 314 * invoked constructor. Values from the list are assigned to arguments 315 * in the order they appear in the constructor signature. 316 * @param options the integer bit flag options. 317 * @return an {@link ObjectReference} mirror of the newly created 318 * object. 319 * @throws java.lang.IllegalArgumentException if the method is not 320 * a member of this class, if the size of the argument list 321 * does not match the number of declared arguments for the constructor, 322 * or if the method is not a constructor. 323 * @throws ClassNotLoadedException if any argument type has not yet been loaded 324 * through the appropriate class loader. 325 * @throws IncompatibleThreadStateException if the specified thread has not 326 * been suspended by an event. 327 * @throws InvocationException if the method invocation resulted in 328 * an exception in the target VM. 329 * @throws InvalidTypeException If the arguments do not meet this requirement -- 330 * Object arguments must be assignment compatible with the argument 331 * type. This implies that the argument type must be 332 * loaded through the enclosing class' class loader. 333 * Primitive arguments must be either assignment compatible with the 334 * argument type or must be convertible to the argument type without loss 335 * of information. See JLS section 5.2 for more information on assignment 336 * compatibility. 337 * @throws VMCannotBeModifiedException if the VirtualMachine is read-only 338 * - see {@link VirtualMachine#canBeModified()}. 339 */ 340 ObjectReference newInstance(ThreadReference thread, Method method, 341 List<? extends Value> arguments, int options) 342 throws InvalidTypeException, 343 ClassNotLoadedException, 344 IncompatibleThreadStateException, 345 InvocationException; 346 347 /** 348 * Returns a the single non-abstract {@link Method} visible from 349 * this class that has the given name and signature. 350 * See {@link ReferenceType#methodsByName(java.lang.String, java.lang.String)} 351 * for information on signature format. 352 * <p> 353 * The returned method (if non-null) is a component of 354 * {@link ClassType}. 355 * 356 * @see ReferenceType#visibleMethods 357 * @see ReferenceType#methodsByName(java.lang.String name) 358 * @see ReferenceType#methodsByName(java.lang.String name, java.lang.String signature) 359 * @param name the name of the method to find. 360 * @param signature the signature of the method to find 361 * @return the {@link Method} that matches the given 362 * name and signature or <code>null</code> if there is no match. 363 * @throws ClassNotPreparedException if methods are not yet available 364 * because the class has not yet been prepared. 365 */ 366 Method concreteMethodByName(String name, String signature); 367 }