You are viewing a plain text version of this content. The canonical link for it is here.
Posted to kato-commits@incubator.apache.org by mo...@apache.org on 2009/07/23 13:18:01 UTC
svn commit: r797061 -
/incubator/kato/trunk/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaObject.java
Author: monteith
Date: Thu Jul 23 13:18:01 2009
New Revision: 797061
URL: http://svn.apache.org/viewvc?rev=797061&view=rev
Log:
Updates comments to the JavaObject javadoc with some clarification.
Modified:
incubator/kato/trunk/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaObject.java
Modified: incubator/kato/trunk/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaObject.java
URL: http://svn.apache.org/viewvc/incubator/kato/trunk/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaObject.java?rev=797061&r1=797060&r2=797061&view=diff
==============================================================================
--- incubator/kato/trunk/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaObject.java (original)
+++ incubator/kato/trunk/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaObject.java Thu Jul 23 13:18:01 2009
@@ -25,74 +25,87 @@
/**
- * Represents a Java object
+ * <p>Represents a Java object or array.</p>
+ * <p>Array elements can be retrieved using the {@link #arraycopy()} method. Object instance fields
+ * can be retrieved using the <code>get*()</code> methods in {@link JavaField} such as
+ * {@link JavaField#get(JavaObject)}. The {@link JavaField} objects can be retrieved from an
+ * object's {@link JavaClass} using {@link JavaClass#getDeclaredFields()}.
+ * </p>
+ *
+ *
*/
public interface JavaObject {
/**
- * Get the JavaClass instance which represents the class of this object.
- * @return the JavaClass instance which represents the class of this object
+ * <p>Get the JavaClass instance which represents the class of this object.</p>
+ * <p>This method never returns null, all objects have a class. The JavaClass returned
+ * might be synthetic for array types.</p>
+ *
+ * @return the JavaClass instance which represents the class of this object.
* @throws CorruptDataException
*/
JavaClass getJavaClass() throws CorruptDataException;
/**
- * Is this object an array ?
- * @return true if the receiver represents an instance of an array, or
- * false otherwise
+ * <p>Returns true if this JavaObject represents an array.</p>
+ *
+ * @return true if this JavaObject represents an array.
* @throws CorruptDataException
*/
boolean isArray() throws CorruptDataException;
/**
- * Get the number of elements in this array.
- * @return the number of elements in this array
- * <p>
+ * <p>Get the number of elements in this array.</p>
+ * <p>This is equivalent to calling <code>array.length</code> in Java, where <code>array</code> is an
+ * array reference.</p>
+ *
+ * @return the number of elements in this array.
* @throws CorruptDataException
- * @exception IllegalArgumentException if the receiver is not an array
+ * @exception IllegalArgumentException if the object is not an array.
*/
int getArraySize() throws CorruptDataException;
/**
- * Copies data from the image array into a local Java array.
- * The dst object must be an array of the appropriate type --
- * a base type array for base types, or a JavaObject array
- * for reference arrays.
+ * <p>Copies data from the array this JavaObject represents into an array.</p>
+ * <p>The dst object must be an array of the appropriate type --
+ * a primitive type array for base types, or a JavaObject array
+ * for reference arrays.</p>
*
- * @param srcStart index in the receiver to start copying from
- * @param dst the destination array
- * @param dstStart index in the destination array to start copying into
- * @param length the number of elements to be copied
+ * @param srcStart index in the receiver to start copying from.
+ * @param dst the destination array.
+ * @param dstStart index in the destination array to start copying into.
+ * @param length the number of elements to be copied.
* @throws CorruptDataException
* @throws MemoryAccessException
*
- * @exception NullPointerException if dst is null
- * @exception IllegalArgumentException if the receiver is not an array,
- * or if dst is not an array of the appropriate type
+ * @exception NullPointerException if dst is null.
+ * @exception IllegalArgumentException if the object is not an array,
+ * or if dst is not an array of the appropriate type.
* @exception IndexOutOfBoundsException if srcStart, dstStart, or length
- * are out of bounds in either the receiver or the destination array
+ * are out of bounds in either the JavaObject or the destination array.
*/
void arraycopy(int srcStart, Object dst, int dstStart, int length) throws CorruptDataException, MemoryAccessException;
/**
- * Get the number of bytes of memory occupied by this object.
+ * <p>Get the number of bytes of memory occupied by this object.</p>
+ *
* @return the number of bytes of memory occupied by this object. The
- * memory may not necessarily be contiguous
+ * memory may not necessarily be contiguous.
* @throws CorruptDataException
*/
long getSize() throws CorruptDataException;
/**
- * Fetch the basic hash code for the object. This is the hash code which
- * would be returned if a Java thread had requested it. Typically the hash
- * code is based on the address of an object, and may change if the object
- * is moved by a garbage collect cycle.
+ * <p>Fetch the basic hash code for the object.</p>
+ * <p> This is the hash code which would be returned if a Java thread had
+ * requested it. Typically the hash code is based on the address of an
+ * object, and may change if the object is moved by a garbage collect cycle.
*
* @return the basic hash code of the object in the image.
*
* @see #getPersistentHashcode()
*
- * @exception DataUnavailable if the hash code cannot be determined
+ * @exception DataUnavailable if the hash code cannot be determined.
* @throws CorruptDataException
*/
long getHashcode() throws DataUnavailable, CorruptDataException;
@@ -119,52 +132,66 @@
long getPersistentHashcode() throws DataUnavailable, CorruptDataException;
/**
- * The ID of an object is a unique address is memory which identifies the object.
+ * <p>The ID of an object is a unique address is memory which identifies the object.
+ * </p>
+ * <p>It is probable that an object's address will change during the lifetime of a Java Virtual
+ * Machine because of the operations of the garbage collector. Other mechanisms for uniquely identifying
+ * objects should be used when comparing dumps.
+ * </p>
+ * <p>
* The data at this memory is implementation defined. The object may be
- * non-contiguous. Portions of the object may appear below or above this address.
+ * non-contiguous. Portions of the object may appear below or above this address.</p>
+ * </p>
+ *
+ * @return the runtime-wide unique identifier for the object.
*
- * @return the runtime-wide unique identifier for the object
*/
ImagePointer getID();
/**
- * An object is represented in the Java runtime by one or more regions of memory.
- * These include the object's header and the data in the object.
+ * <p>Returns the sections that this object occupies in memory.</p>
+ * <p>These sections include the object's header and the data in the object.</p>
*
- * In certain allocation strategies, an object's header and data may be allocated
+ * <p>In certain allocation strategies, an object's header and data may be allocated
* contiguously. In this case, this method may return an iterator for a single
- * section.
+ * section.</p>
*
- * In other schemes, the header may be separate from the data or the data may be
+ * <p>In other schemes, the header may be separate from the data or the data may be
* broken up into multiple regions. Additionally, this function does not guarantee
* that the memory used by this object is not also shared by one or more other
- * objects.
+ * objects.</p>
*
- * Callers should not make any assumptions about the contents of the memory.
+ * <p>The contents of the image sections are implementation specific, as so are
+ * undefined here.</p>
*
- * @return a collection of sections that make up this object
+ * @return a collection of sections that make up this object.
*
* @see ImageSection
- * @see javax.tools.diagnostics.image.CorruptData
*/
- List getSections();
+ List<ImageSection> getSections();
/**
- * Get the set of references from this object.
+ * <p>Get the set of references from this object.</p>
+ * <p>These references will include at least the object's references to its class,
+ * and any references from instance fields to other objects and classes, or array elements
+ * references to other objects.</p>
*
- * @return an iterator of JavaReferences
+ * @return an List of JavaReferences.
* @see javax.tools.diagnostics.java.JavaReference
*
- * @see javax.tools.diagnostics.image.CorruptData
*/
- List getReferences();
+ List<JavaReference> getReferences();
/**
- * Gets the heap where this object is located.
- * @return the <code>JavaHeap</code> instance representing the heap where this object is stored in memory.
+ * <p>Gets the heap where this object is located.</p>
+ * <p>A JavaHeap will always be returned if this object could be retrieved by
+ * {@link JavaHeap#getObject()}, otherwise {@link DataUnavailable} is thrown.
+ * </p>
+ *
+ * @return the {@link JavaHeap} instance representing the heap where this object is stored in memory.
* @throws CorruptDataException if the heap information for this object is corrupt.
* @throws DataUnavailable if the heap information for this object is not available.
- * @see javax.tools.diagnostics.java.JavaHeap
+ * @see JavaHeap
*/
JavaHeap getHeap() throws CorruptDataException, DataUnavailable;