incubator-kato-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From monte...@apache.org
Subject svn commit: r797061 - /incubator/kato/trunk/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaObject.java
Date Thu, 23 Jul 2009 13:18:01 GMT
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;
 	



Mime
View raw message