My first initial commit with all of mine experimental changes.

Dmitry Kabak (userdima committed 13 years ago

Commit d37b88d1 parent 3f5b46618352 files · +2598093 −-8690Browse files

Showing the changes to java/pkg/com/sun/jdi/ReferenceType.java (1 of 18352 files). Show all

Unified · Split

java/pkg/com/sun/jdi/ReferenceType.java+830−0

@@ -0,0 +1,830 @@
	1	+/*
	2	+ * Copyright (c) 1998, 2006, 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	+import java.util.Map;
	30	+
	31	+/**
	32	+ * The type of an object in a target VM. ReferenceType encompasses
	33	+ * classes, interfaces, and array types as defined in
	34	+ * <cite>The Java™ Language Specification</cite>.
	35	+ * All ReferenceType objects belong to one of the following
	36	+ * subinterfaces:
	37	+ * {@link ClassType} for classes,
	38	+ * {@link InterfaceType} for interfaces, and
	39	+ * {@link ArrayType} for arrays.
	40	+ * Note that primitive classes (for example, the
	41	+ * {@link ClassObjectReference#reflectedType() reflected type} of
	42	+ * {@link java.lang.Integer#TYPE Integer.TYPE})
	43	+ * are represented as ClassType.
	44	+ * The VM creates Class objects for all three, so from the VM perspective,
	45	+ * each ReferenceType maps to a distinct Class object.
	46	+ * <p>
	47	+ * ReferenceTypes can
	48	+ * be obtained by querying a particular {@link ObjectReference} for its
	49	+ * type or by getting a list of all reference types from the
	50	+ * {@link VirtualMachine}.
	51	+ * <p>
	52	+ * ReferenceType provides access to static type information such as
	53	+ * methods and fields and provides access to dynamic type
	54	+ * information such as the corresponding Class object and the classloader.
	55	+ * <p>
	56	+ * Any method on <code>ReferenceType</code> which directly or
	57	+ * indirectly takes <code>ReferenceType</code> as an parameter may throw
	58	+ * {@link com.sun.jdi.VMDisconnectedException} if the target VM is
	59	+ * disconnected and the {@link com.sun.jdi.event.VMDisconnectEvent} has been or is
	60	+ * available to be read from the {@link com.sun.jdi.event.EventQueue}.
	61	+ * <p>
	62	+ * Any method on <code>ReferenceType</code> which directly or
	63	+ * indirectly takes <code>ReferenceType</code> as an parameter may throw
	64	+ * {@link com.sun.jdi.VMOutOfMemoryException} if the target VM has run out of memory.
	65	+ * <p>
	66	+ * Any method on <code>ReferenceType</code> or which directly or indirectly takes
	67	+ * <code>ReferenceType</code> as parameter may throw
	68	+ * {@link com.sun.jdi.ObjectCollectedException} if the mirrored type has been unloaded.
	69	+ *
	70	+ * @see ObjectReference
	71	+ * @see ObjectReference#referenceType
	72	+ * @see VirtualMachine
	73	+ * @see VirtualMachine#allClasses
	74	+ *
	75	+ * @author Robert Field
	76	+ * @author Gordon Hirsch
	77	+ * @author James McIlree
	78	+ * @since 1.3
	79	+ */
	80	+public interface ReferenceType
	81	+ extends Type, Comparable<ReferenceType>, Accessible
	82	+{
	83	+
	84	+ /**
	85	+ * Gets the fully qualified name of this type. The returned name
	86	+ * is formatted as it might appear in a Java programming langauge
	87	+ * declaration for objects of this type.
	88	+ * <p>
	89	+ * For primitive classes
	90	+ * the returned name is the name of the corresponding primitive
	91	+ * type; for example, "int" is returned as the name of the class
	92	+ * represented by {@link java.lang.Integer#TYPE Integer.TYPE}.
	93	+ * @return a string containing the type name.
	94	+ */
	95	+ String name();
	96	+
	97	+ /**
	98	+ * Gets the generic signature for this type if there is one.
	99	+ * Generic signatures are described in the
	100	+ * <cite>The Java™ Virtual Machine Specification</cite>.
	101	+ *
	102	+ * @return a string containing the generic signature, or <code>null</code>
	103	+ * if there is no generic signature.
	104	+ *
	105	+ * @since 1.5
	106	+ */
	107	+ String genericSignature();
	108	+
	109	+ /**
	110	+ * Gets the classloader object which loaded the class corresponding
	111	+ * to this type.
	112	+ *
	113	+ * @return a {@link ClassLoaderReference} which mirrors the classloader,
	114	+ * or <code>null</code> if the class was loaded through the bootstrap class
	115	+ * loader.
	116	+ */
	117	+ ClassLoaderReference classLoader();
	118	+
	119	+ /**
	120	+ * Gets an identifying name for the source corresponding to the
	121	+ * declaration of this type. Interpretation of this string is
	122	+ * the responsibility of the source repository mechanism.
	123	+ * <P>
	124	+ * The returned name is dependent on VM's default stratum
	125	+ * ({@link VirtualMachine#getDefaultStratum()}).
	126	+ * In the reference implementation, when using the base stratum,
	127	+ * the returned string is the
	128	+ * unqualified name of the source file containing the declaration
	129	+ * of this type. In other strata the returned source name is
	130	+ * the first source name for that stratum. Since other languages
	131	+ * may have more than one source name for a reference type,
	132	+ * the use of {@link Location#sourceName()} or
	133	+ * {@link #sourceNames(String)} is preferred.
	134	+ * <p>
	135	+ * For arrays ({@link ArrayType}) and primitive classes,
	136	+ * AbsentInformationException is always thrown.
	137	+ *
	138	+ * @return the string source file name
	139	+ * @throws AbsentInformationException if the source name is not
	140	+ * known
	141	+ */
	142	+ String sourceName() throws AbsentInformationException;
	143	+
	144	+ /**
	145	+ * Gets the identifying names for all the source corresponding to the
	146	+ * declaration of this type. Interpretation of these names is
	147	+ * the responsibility of the source repository mechanism.
	148	+ * <P>
	149	+ * The returned names are for the specified stratum
	150	+ * (see {@link Location} for a description of strata).
	151	+ * In the reference implementation, when using the Java
	152	+ * programming language stratum,
	153	+ * the returned List contains one element: a String which is the
	154	+ * unqualified name of the source file containing the declaration
	155	+ * of this type. In other strata the returned source names are
	156	+ * all the source names defined for that stratum.
	157	+ *
	158	+ * @param stratum The stratum to retrieve information from
	159	+ * or <code>null</code> for the declaring type's
	160	+ * default stratum.
	161	+ *
	162	+ * @return a List of String objects each representing a source name
	163	+ *
	164	+ * @throws AbsentInformationException if the source names are not
	165	+ * known.
	166	+ * <p>
	167	+ * For arrays ({@link ArrayType}) and primitive classes,
	168	+ * AbsentInformationException is always thrown.
	169	+ *
	170	+ * @since 1.4
	171	+ */
	172	+ List<String> sourceNames(String stratum) throws AbsentInformationException;
	173	+
	174	+ /**
	175	+ * Gets the paths to the source corresponding to the
	176	+ * declaration of this type. Interpretation of these paths is
	177	+ * the responsibility of the source repository mechanism.
	178	+ * <P>
	179	+ * The returned paths are for the specified stratum
	180	+ * (see {@link Location} for a description of strata).
	181	+ * In the reference implementation, for strata which
	182	+ * do not explicitly specify source path (the Java
	183	+ * programming language stratum never does), the returned
	184	+ * strings are the {@link #sourceNames(String)} prefixed by
	185	+ * the package name of this ReferenceType
	186	+ * converted to a platform dependent path.
	187	+ * For example, on a Windows platform,
	188	+ * <CODE>java.lang.Thread</CODE>
	189	+ * would return a List containing one element:
	190	+ * <CODE>"java\lang\Thread.java"</CODE>.
	191	+ *
	192	+ * @param stratum The stratum to retrieve information from
	193	+ * or <code>null</code> for the declaring type's
	194	+ * default stratum.
	195	+ *
	196	+ * @return a List of String objects each representing a source path
	197	+ *
	198	+ * @throws AbsentInformationException if the source names are not
	199	+ * known.
	200	+ * <p>
	201	+ * For arrays ({@link ArrayType}) and primitive classes,
	202	+ * AbsentInformationException is always thrown.
	203	+ *
	204	+ * @since 1.4
	205	+ */
	206	+ List<String> sourcePaths(String stratum) throws AbsentInformationException;
	207	+
	208	+ /**
	209	+ * Get the source debug extension of this type.
	210	+ * <p>
	211	+ * Not all target virtual machines support this operation.
	212	+ * Use
	213	+ * {@link VirtualMachine#canGetSourceDebugExtension() canGetSourceDebugExtension()}
	214	+ * to determine if the operation is supported.
	215	+ * @return as a string the source debug extension attribute
	216	+ * @throws AbsentInformationException if the extension is not
	217	+ * specified
	218	+ * @throws java.lang.UnsupportedOperationException if
	219	+ * the target virtual machine does not support this
	220	+ * operation - see
	221	+ * {@link VirtualMachine#canGetSourceDebugExtension() canGetSourceDebugExtension()},
	222	+ */
	223	+ String sourceDebugExtension() throws AbsentInformationException;
	224	+
	225	+ /**
	226	+ * Determines if this type was declared static. Only nested types,
	227	+ * can be declared static, so <code>false</code> is returned
	228	+ * for any package-level type, array type, or primitive class.
	229	+ *
	230	+ * @return <code>true</code> if this type is static; false otherwise.
	231	+ */
	232	+ boolean isStatic();
	233	+
	234	+ /**
	235	+ * Determines if this type was declared abstract.
	236	+ * <p>
	237	+ * For arrays ({@link ArrayType}) and primitive classes,
	238	+ * the return value is undefined.
	239	+ *
	240	+ * @return <code>true</code> if this type is abstract; false otherwise.
	241	+ */
	242	+ boolean isAbstract();
	243	+
	244	+ /**
	245	+ * Determines if this type was declared final.
	246	+ * <p>
	247	+ * For arrays ({@link ArrayType}) and primitive classes,
	248	+ * the return value is always true.
	249	+ *
	250	+ * @return <code>true</code> if this type is final; false otherwise.
	251	+ */
	252	+ boolean isFinal();
	253	+
	254	+ /**
	255	+ * Determines if this type has been prepared. See the JVM
	256	+ * specification for a definition of class preparation.
	257	+ * <p>
	258	+ * For arrays ({@link ArrayType}) and primitive classes,
	259	+ * the return value is undefined.
	260	+ *
	261	+ * @return <code>true</code> if this type is prepared; false otherwise.
	262	+ */
	263	+ boolean isPrepared();
	264	+
	265	+ /**
	266	+ * Determines if this type has been verified. See the JVM
	267	+ * specification for a definition of class verification.
	268	+ * <p>
	269	+ * For arrays ({@link ArrayType}) and primitive classes,
	270	+ * the return value is undefined.
	271	+ *
	272	+ * @return <code>true</code> if this type is verified; false otherwise.
	273	+ */
	274	+ boolean isVerified();
	275	+
	276	+ /**
	277	+ * Determines if this type has been initialized. See the JVM
	278	+ * specification for a definition of class verification.
	279	+ * For {@link InterfaceType}, this method always returns the
	280	+ * same value as {@link #isPrepared()}.
	281	+ * <p>
	282	+ * For arrays ({@link ArrayType}) and primitive classes,
	283	+ * the return value is undefined.
	284	+ *
	285	+ * @return <code>true</code> if this type is initialized; false otherwise.
	286	+ */
	287	+ boolean isInitialized();
	288	+
	289	+ /**
	290	+ * Determines if initialization failed for this class. See the JVM
	291	+ * specification for details on class initialization.
	292	+ * <p>
	293	+ * For arrays ({@link ArrayType}) and primitive classes,
	294	+ * the return value is undefined.
	295	+ *
	296	+ * @return <code>true</code> if initialization was attempted and
	297	+ * failed; false otherwise.
	298	+ */
	299	+ boolean failedToInitialize();
	300	+
	301	+ /**
	302	+ * Returns a list containing each {@link Field} declared in this type.
	303	+ * Inherited fields are not included. Any synthetic fields created
	304	+ * by the compiler are included in the list.
	305	+ * <p>
	306	+ * For arrays ({@link ArrayType}) and primitive classes, the returned
	307	+ * list is always empty.
	308	+ *
	309	+ * @return a list {@link Field} objects; the list has length 0
	310	+ * if no fields exist.
	311	+ * @throws ClassNotPreparedException if this class not yet been
	312	+ * prepared.
	313	+ */
	314	+ List<Field> fields();
	315	+
	316	+ /**
	317	+ * Returns a list containing each unhidden and unambiguous {@link Field}
	318	+ * in this type.
	319	+ * Each field that can be accessed from the class
	320	+ * or its instances with its simple name is included. Fields that
	321	+ * are ambiguously multiply inherited or fields that are hidden by
	322	+ * fields with the same name in a more recently inherited class
	323	+ * cannot be accessed
	324	+ * by their simple names and are not included in the returned
	325	+ * list. All other inherited fields are included.
	326	+ * See JLS section 8.3 for details.
	327	+ * <p>
	328	+ * For arrays ({@link ArrayType}) and primitive classes, the returned
	329	+ * list is always empty.
	330	+ *
	331	+ * @return a List of {@link Field} objects; the list has length
	332	+ * 0 if no visible fields exist.
	333	+ * @throws ClassNotPreparedException if this class not yet been
	334	+ * prepared.
	335	+ */
	336	+ List<Field> visibleFields();
	337	+
	338	+ /**
	339	+ * Returns a list containing each {@link Field} declared in this type,
	340	+ * and its superclasses, implemented interfaces, and/or superinterfaces.
	341	+ * All declared and inherited
	342	+ * fields are included, regardless of whether they are hidden or
	343	+ * multiply inherited.
	344	+ * <p>
	345	+ * For arrays ({@link ArrayType}) and primitive classes, the returned
	346	+ * list is always empty.
	347	+ *
	348	+ * @return a List of {@link Field} objects; the list has length
	349	+ * 0 if no fields exist.
	350	+ * @throws ClassNotPreparedException if this class not yet been
	351	+ * prepared.
	352	+ */
	353	+ List<Field> allFields();
	354	+
	355	+ /**
	356	+ * Finds the visible {@link Field} with the given
	357	+ * non-ambiguous name. This method follows the
	358	+ * inheritance rules specified in the JLS (8.3.3) to determine
	359	+ * visibility.
	360	+ * <p>
	361	+ * For arrays ({@link ArrayType}) and primitive classes, the returned
	362	+ * value is always null.
	363	+ *
	364	+ * @param fieldName a String containing the name of desired field.
	365	+ * @return a {@link Field} object which mirrors the found field, or
	366	+ * null if there is no field with the given name or if the given
	367	+ * name is ambiguous.
	368	+ * @throws ClassNotPreparedException if this class not yet been
	369	+ * prepared.
	370	+ */
	371	+ Field fieldByName(String fieldName);
	372	+
	373	+ /**
	374	+ * Returns a list containing each {@link Method} declared
	375	+ * directly in this type.
	376	+ * Inherited methods are not included. Constructors,
	377	+ * the initialization method if any, and any synthetic methods created
	378	+ * by the compiler are included in the list.
	379	+ * <p>
	380	+ * For arrays ({@link ArrayType}) and primitive classes, the returned
	381	+ * list is always empty.
	382	+ *
	383	+ * @return a list {@link Method} objects; the list has length 0
	384	+ * if no methods exist.
	385	+ * @throws ClassNotPreparedException if this class not yet been
	386	+ * prepared.
	387	+ */
	388	+ List<Method> methods();
	389	+
	390	+ /**
	391	+ * Returns a list containing each {@link Method}
	392	+ * declared or inherited by this type. Methods from superclasses
	393	+ * or superinterfaces that that have been hidden or overridden
	394	+ * are not included.
	395	+ * <p>
	396	+ * Note that despite this exclusion, multiple inherited methods
	397	+ * with the same signature can be present in the returned list, but
	398	+ * at most one can be a member of a {@link ClassType}.
	399	+ * See JLS section 8.4.6 for details.
	400	+ * <p>
	401	+ * For arrays ({@link ArrayType}) and primitive classes, the returned
	402	+ * list is always empty.
	403	+ *
	404	+ * @return a List of {@link Method} objects; the list has length
	405	+ * 0 if no visible methods exist.
	406	+ * @throws ClassNotPreparedException if this class not yet been
	407	+ * prepared.
	408	+ */
	409	+ List<Method> visibleMethods();
	410	+
	411	+ /**
	412	+ * Returns a list containing each {@link Method} declared in this type,
	413	+ * and its superclasses, implemented interfaces, and/or superinterfaces.
	414	+ * All declared and inherited
	415	+ * methods are included, regardless of whether they are hidden or
	416	+ * overridden.
	417	+ * <p>
	418	+ * For arrays ({@link ArrayType}) and primitive classes, the returned
	419	+ * list is always empty.
	420	+ *
	421	+ * @return a List of {@link Method} objects; the list has length
	422	+ * 0 if no methods exist.
	423	+ * @throws ClassNotPreparedException if this class not yet been
	424	+ * prepared.
	425	+ */
	426	+ List<Method> allMethods();
	427	+
	428	+ /**
	429	+ * Returns a List containing each visible {@link Method} that
	430	+ * has the given name. This is most commonly used to
	431	+ * find overloaded methods.
	432	+ * <p>
	433	+ * Overridden and hidden methods are not included.
	434	+ * See JLS (8.4.6) for details.
	435	+ * <p>
	436	+ * For arrays ({@link ArrayType}) and primitive classes, the returned
	437	+ * list is always empty.
	438	+ *
	439	+ * @param name the name of the method to find.
	440	+ * @return a List of {@link Method} objects that match the given
	441	+ * name; the list has length 0 if no matching methods are found.
	442	+ * @throws ClassNotPreparedException if this class not yet been
	443	+ * prepared.
	444	+ */
	445	+ List<Method> methodsByName(String name);
	446	+
	447	+ /**
	448	+ * Returns a List containing each visible {@link Method} that
	449	+ * has the given name and signature.
	450	+ * The signature string is the
	451	+ * JNI signature for the target method:
	452	+ * <ul>
	453	+ * <li><code>()V</code>
	454	+ * <li><code>([Ljava/lang/String;)V</code>
	455	+ * <li><code>(IIII)Z</code>
	456	+ * </ul>
	457	+ * This method follows the inheritance rules specified
	458	+ * in the JLS (8.4.6) to determine visibility.
	459	+ * <p>
	460	+ * At most one method in the list is a concrete method and a
	461	+ * component of {@link ClassType}; any other methods in the list
	462	+ * are abstract. Use {@link ClassType#concreteMethodByName} to
	463	+ * retrieve only the matching concrete method.
	464	+ * <p>
	465	+ * For arrays ({@link ArrayType}) and primitive classes, the returned
	466	+ * list is always empty.
	467	+ *
	468	+ * @param name the name of the method to find.
	469	+ * @param signature the signature of the method to find
	470	+ * @return a List of {@link Method} objects that match the given
	471	+ * name and signature; the list has length 0 if no matching methods
	472	+ * are found.
	473	+ * @throws ClassNotPreparedException if this class not yet been
	474	+ * prepared.
	475	+ */
	476	+ List<Method> methodsByName(String name, String signature);
	477	+
	478	+ /**
	479	+ * Returns a List containing {@link ReferenceType} objects that are
	480	+ * declared within this type and are currently loaded into the Virtual
	481	+ * Machine. Both static nested types and non-static nested
	482	+ * types (that is, inner types) are included. Local inner types
	483	+ * (declared within a code block somewhere in this reference type) are
	484	+ * also included in the returned list.
	485	+ * <p>
	486	+ * For arrays ({@link ArrayType}) and primitive classes, the returned
	487	+ * list is always empty.
	488	+ *
	489	+ * @return a List of nested {@link ReferenceType} objects; the list
	490	+ * has 0 length if there are no nested types.
	491	+ */
	492	+ List<ReferenceType> nestedTypes();
	493	+
	494	+ /**
	495	+ * Gets the {@link Value} of a given static {@link Field} in this type.
	496	+ * The Field must be valid for this type;
	497	+ * that is, it must be declared in this type, a superclass, a
	498	+ * superinterface, or an implemented interface.
	499	+ *
	500	+ * @param field the field containing the requested value
	501	+ * @return the {@link Value} of the instance field.
	502	+ * @throws java.lang.IllegalArgumentException if the field is not valid for
	503	+ * this object's class.
	504	+ */
	505	+ Value getValue(Field field);
	506	+
	507	+ /**
	508	+ * Returns a map containing the {@link Value} of each
	509	+ * static {@link Field} in the given list.
	510	+ * The Fields must be valid for this type;
	511	+ * that is, they must be declared in this type, a superclass, a
	512	+ * superinterface, or an implemented interface.
	513	+ *
	514	+ * @param fields a list of {@link Field} objects containing the
	515	+ * requested values.
	516	+ * @return a Map of the requested {@link Field} objects with
	517	+ * their {@link Value}.
	518	+ * @throws java.lang.IllegalArgumentException if any field is not valid for
	519	+ * this object's class.
	520	+ * @throws VMMismatchException if a {@link Mirror} argument and this mirror
	521	+ * do not belong to the same {@link VirtualMachine}.
	522	+ */
	523	+ Map<Field,Value> getValues(List<? extends Field> fields);
	524	+
	525	+ /**
	526	+ * Returns the class object that corresponds to this type in the
	527	+ * target VM. The VM creates class objects for every kind of
	528	+ * ReferenceType: classes, interfaces, and array types.
	529	+ * @return the {@link ClassObjectReference} for this reference type
	530	+ * in the target VM.
	531	+ */
	532	+ ClassObjectReference classObject();
	533	+
	534	+ /**
	535	+ * Returns a list containing a {@link Location} object
	536	+ * for each executable source line in this reference type.
	537	+ * <P>
	538	+ * This method is equivalent to
	539	+ * <code>allLineLocations(vm.getDefaultStratum(),null)</code> -
	540	+ * see {@link #allLineLocations(String,String)}
	541	+ * for more information.
	542	+ *
	543	+ * @throws AbsentInformationException if there is no line
	544	+ * number information for this class and there are non-native,
	545	+ * non-abstract executable members of this class.
	546	+ *
	547	+ * @throws ClassNotPreparedException if this class not yet
	548	+ * been prepared.
	549	+ */
	550	+ List<Location> allLineLocations() throws AbsentInformationException;
	551	+
	552	+ /**
	553	+ * Returns a list containing a {@link Location} object
	554	+ * for each executable source line in this reference type.
	555	+ * Each location maps a source line to a range of code
	556	+ * indices.
	557	+ * The beginning of the range can be determined through
	558	+ * {@link Location#codeIndex}. The returned list may contain
	559	+ * multiple locations for a particular line number, if the
	560	+ * compiler and/or VM has mapped that line to two or more
	561	+ * disjoint code index ranges. Note that it is possible for
	562	+ * the same source line to represent different code index
	563	+ * ranges in <i>different</i> methods.
	564	+ * <P>
	565	+ * For arrays ({@link ArrayType}) and primitive classes, the
	566	+ * returned list is always empty. For interfaces ({@link
	567	+ * InterfaceType}), the returned list will be non-empty only
	568	+ * if the interface has executable code in its class
	569	+ * initialization.
	570	+ * <P>
	571	+ * Returned list is for the specified <i>stratum</i>
	572	+ * (see {@link Location} for a description of strata).
	573	+ *
	574	+ * @param stratum The stratum to retrieve information from
	575	+ * or <code>null</code> for the {@link #defaultStratum()}.
	576	+ *
	577	+ * @param sourceName Return locations only within this
	578	+ * source file or <code>null</code> to return locations.
	579	+ *
	580	+ * @return a List of all source line {@link Location} objects.
	581	+ *
	582	+ * @throws AbsentInformationException if there is no line
	583	+ * number information for this class and there are non-native,
	584	+ * non-abstract executable members of this class.
	585	+ * Or if <i>sourceName</i> is non-<code>null</code>
	586	+ * and source name information is not present.
	587	+ *
	588	+ * @throws ClassNotPreparedException if this class not yet
	589	+ * been prepared.
	590	+ *
	591	+ * @since 1.4
	592	+ */
	593	+ List<Location> allLineLocations(String stratum, String sourceName)
	594	+ throws AbsentInformationException;
	595	+
	596	+ /**
	597	+ * Returns a List containing all {@link Location} objects
	598	+ * that map to the given line number.
	599	+ * <P>
	600	+ * This method is equivalent to
	601	+ * <code>locationsOfLine(vm.getDefaultStratum(), null,
	602	+ * lineNumber)</code> -
	603	+ * see {@link
	604	+ * #locationsOfLine(java.lang.String,java.lang.String,int)}
	605	+ * for more information.
	606	+ *
	607	+ * @param lineNumber the line number
	608	+ *
	609	+ * @return a List of all {@link Location} objects that map to
	610	+ * the given line.
	611	+ *
	612	+ * @throws AbsentInformationException if there is no line
	613	+ * number information for this class.
	614	+ *
	615	+ * @throws ClassNotPreparedException if this class not yet
	616	+ * been prepared.
	617	+ *
	618	+ * @see VirtualMachine#getDefaultStratum()
	619	+ */
	620	+ List<Location> locationsOfLine(int lineNumber)
	621	+ throws AbsentInformationException;
	622	+
	623	+ /**
	624	+ * Returns a List containing all {@link Location} objects
	625	+ * that map to the given line number.
	626	+ * <P>
	627	+ * For arrays ({@link ArrayType}) and primitive classes, the
	628	+ * returned list is always empty.
	629	+ * For interfaces ({@link InterfaceType}), the returned list
	630	+ * will be non-empty only if the interface has executable code
	631	+ * in its class initialization at the specified line number.
	632	+ * An empty list will be returned if there is no executable
	633	+ * code at the specified line number.
	634	+ * <p>
	635	+ * Returned list is for the specified <i>stratum</i>
	636	+ * (see {@link Location} for a description of strata).
	637	+ *
	638	+ * @param stratum the stratum to use for comparing line number
	639	+ * and source name, or <code>null</code> to
	640	+ * use the {@link #defaultStratum()}.
	641	+ *
	642	+ * @param sourceName the source name containing the line
	643	+ * number, or <code>null</code> to match
	644	+ * all source names
	645	+ *
	646	+ * @param lineNumber the line number
	647	+ *
	648	+ * @return a List of all {@link Location} objects that map
	649	+ * to the given line.
	650	+ *
	651	+ * @throws AbsentInformationException if there is no line
	652	+ * number information for this class.
	653	+ * Or if <i>sourceName</i> is non-<code>null</code>
	654	+ * and source name information is not present.
	655	+ *
	656	+ * @throws ClassNotPreparedException if this class not yet
	657	+ * been prepared.
	658	+ *
	659	+ * @since 1.4
	660	+ */
	661	+ List<Location> locationsOfLine(String stratum,
	662	+ String sourceName,
	663	+ int lineNumber)
	664	+ throws AbsentInformationException;
	665	+
	666	+ /**
	667	+ * Return the available strata for this reference type.
	668	+ * <P>
	669	+ * See the {@link Location} for a description of strata.
	670	+ *
	671	+ * @return List of <CODE>java.lang.String</CODE>, each
	672	+ * representing a stratum
	673	+ *
	674	+ * @since 1.4
	675	+ */
	676	+ List<String> availableStrata();
	677	+
	678	+ /**
	679	+ * Returns the default stratum for this reference type.
	680	+ * This value is specified in the class file and cannot
	681	+ * be set by the user. If the class file does not
	682	+ * specify a default stratum the base stratum
	683	+ * (<code>"Java"</code>) will be returned.
	684	+ * <P>
	685	+ * See the {@link Location} for a description of strata.
	686	+ *
	687	+ * @since 1.4
	688	+ */
	689	+ String defaultStratum();
	690	+
	691	+ /**
	692	+ * Returns instances of this ReferenceType.
	693	+ * Only instances that are reachable for the purposes of garbage collection
	694	+ * are returned.
	695	+ * <p>
	696	+ * Not all target virtual machines support this operation.
	697	+ * Use {@link VirtualMachine#canGetInstanceInfo()}
	698	+ * to determine if the operation is supported.
	699	+ *
	700	+ * @see VirtualMachine#instanceCounts(List)
	701	+ * @see ObjectReference#referringObjects(long)
	702	+ *
	703	+ * @param maxInstances the maximum number of instances to return.
	704	+ * Must be non-negative. If zero, all instances are returned.
	705	+ * @return a List of {@link ObjectReference} objects. If there are
	706	+ * no instances of this ReferenceType, a zero-length list is returned.
	707	+ *
	708	+ * @throws java.lang.UnsupportedOperationException if
	709	+ * the target virtual machine does not support this
	710	+ * operation - see
	711	+ * {@link VirtualMachine#canGetInstanceInfo() canGetInstanceInfo()}
	712	+ * @throws java.lang.IllegalArgumentException if maxInstances is less
	713	+ * than zero.
	714	+ * @since 1.6
	715	+ */
	716	+ List<ObjectReference> instances(long maxInstances);
	717	+
	718	+ /**
	719	+ * Compares the specified Object with this ReferenceType for equality.
	720	+ *
	721	+ * @return true if the Object is a {@link ReferenceType}, if the
	722	+ * ReferenceTypes belong to the same VM, and if they mirror classes
	723	+ * which correspond to the same instance of java.lang.Class in that VM.
	724	+ */
	725	+ boolean equals(Object obj);
	726	+
	727	+ /**
	728	+ * Returns the hash code value for this ObjectReference.
	729	+ *
	730	+ * @return the integer hash code
	731	+ */
	732	+ int hashCode();
	733	+
	734	+ /**
	735	+ * Returns the class major version number, as defined in the class file format
	736	+ * of the Java Virtual Machine Specification.
	737	+ *
	738	+ * For arrays ({@link ArrayType}) and primitive classes,
	739	+ * the returned major version number value is zero.
	740	+ *
	741	+ * Not all target virtual machines support this operation.
	742	+ * Use {@link VirtualMachine#canGetClassFileVersion()}
	743	+ * to determine if the operation is supported.
	744	+ *
	745	+ * @return the major version number of the class.
	746	+ *
	747	+ * @throws java.lang.UnsupportedOperationException if
	748	+ * the target virtual machine does not support this
	749	+ * operation - see
	750	+ * {@link VirtualMachine#canGetClassFileVersion() canGetClassFileVersion()}
	751	+ *
	752	+ * @since 1.6
	753	+ */
	754	+ int majorVersion();
	755	+
	756	+
	757	+ /**
	758	+ * Returns the class minor version number, as defined in the class file format
	759	+ * of the Java Virtual Machine Specification.
	760	+ *
	761	+ * For arrays ({@link ArrayType}) and primitive classes,
	762	+ * the returned minor version number value is zero.
	763	+ *
	764	+ * Not all target virtual machines support this operation.
	765	+ * Use {@link VirtualMachine#canGetClassFileVersion()}
	766	+ * to determine if the operation is supported.
	767	+ *
	768	+ * @return the minor version number of the class.
	769	+ *
	770	+ * @throws java.lang.UnsupportedOperationException if
	771	+ * the target virtual machine does not support this
	772	+ * operation - see
	773	+ * {@link VirtualMachine#canGetClassFileVersion() canGetClassFileVersion()}
	774	+ *
	775	+ * @since 1.6
	776	+ */
	777	+ int minorVersion();
	778	+
	779	+ /**
	780	+ * Returns the number of entries in the constant pool plus one.
	781	+ * This corresponds to the constant_pool_count item of the Class File Format
	782	+ * in the Java Virtual Machine Specification.
	783	+ *
	784	+ * For arrays ({@link ArrayType}) and primitive classes,
	785	+ * the returned constant pool count value is zero.
	786	+ *
	787	+ * Not all target virtual machines support this operation.
	788	+ * Use {@link VirtualMachine#canGetConstantPool()}
	789	+ * to determine if the operation is supported.
	790	+ *
	791	+ * @return total number of constant pool entries for a class plus one.
	792	+ *
	793	+ * @throws java.lang.UnsupportedOperationException if
	794	+ * the target virtual machine does not support this
	795	+ * operation - see
	796	+ * {@link VirtualMachine#canGetConstantPool() canGetConstantPool()}
	797	+ *
	798	+ * @see #constantPool()
	799	+ * @since 1.6
	800	+ */
	801	+ int constantPoolCount();
	802	+
	803	+ /**
	804	+ * Returns the raw bytes of the constant pool in the format of the
	805	+ * constant_pool item of the Class File Format in the Java Virtual
	806	+ * Machine Specification. The format of the constant pool may
	807	+ * differ between versions of the Class File Format, so, the
	808	+ * minor and major class version numbers should be checked for
	809	+ * compatibility.
	810	+ *
	811	+ * For arrays ({@link ArrayType}) and primitive classes,
	812	+ * a zero length byte array is returned.
	813	+ *
	814	+ * Not all target virtual machines support this operation.
	815	+ * Use {@link VirtualMachine#canGetConstantPool()}
	816	+ * to determine if the operation is supported.
	817	+ *
	818	+ * @return the raw bytes of constant pool.
	819	+ *
	820	+ * @throws java.lang.UnsupportedOperationException if
	821	+ * the target virtual machine does not support this
	822	+ * operation - see
	823	+ * {@link VirtualMachine#canGetConstantPool() canGetConstantPool()}
	824	+ *
	825	+ * @see #constantPoolCount()
	826	+ * @since 1.6
	827	+ */
	828	+ byte[] constantPool();
	829	+
	830	+}