incubator-kato-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From monte...@apache.org
Subject svn commit: r797083 - /incubator/kato/trunk/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaThread.java
Date Thu, 23 Jul 2009 14:29:54 GMT
Author: monteith
Date: Thu Jul 23 14:29:54 2009
New Revision: 797083

URL: http://svn.apache.org/viewvc?rev=797083&view=rev
Log:
Update JavaThread javadoc.

Modified:
    incubator/kato/trunk/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaThread.java

Modified: incubator/kato/trunk/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaThread.java
URL: http://svn.apache.org/viewvc/incubator/kato/trunk/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaThread.java?rev=797083&r1=797082&r2=797083&view=diff
==============================================================================
--- incubator/kato/trunk/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaThread.java
(original)
+++ incubator/kato/trunk/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaThread.java
Thu Jul 23 14:29:54 2009
@@ -25,9 +25,14 @@
 
 
 /**
- * Represents a Java thread
- * 
- * @see javax.tools.diagnostics.java.JavaRuntime#getThreads()
+ * <p>Represents a Java thread.</p>
+ * <p><code>JavaThread</code> instances correspond with executing threads
in the Java Virtual Machine,
+ * not {@link java.lang.Thread} instances on the heap.
+ * <code>JavaThread</code> provide information on what was running including
the locations
+ * of all of the threads within the Java program when the dump was taken.
+ * </p> 
+ *  
+ * @see JavaRuntime#getThreads()
  */
 public interface JavaThread  {
 
@@ -65,92 +70,124 @@
 	int STATE_VENDOR_3					= 0x40000000;
 	
     /**
-     * Get the address of the JNIEnv structure which represents this thread instance in JNI.
-     * @return the address of the JNIEnv structure which represents this thread instance
in JNI
+     * <p>Get the address of the JNIEnv structure which represents this thread instance
in JNI.</p>
+     * 
+     * @return the address of the JNIEnv structure which represents this thread instance
in JNI.
      * @throws CorruptDataException 
      */
     ImagePointer getJNIEnv() throws CorruptDataException;
     
     /**
-     * Get the Java priority of the thread.
+     * <p>Get the Java priority of the thread.</p>
+     * <p>The value returned will be the same as what would have been returned by a
call
+     * to {@link java.lang.Thread#getPriority()} within the Java Virtual Machine.
+     * 
      * @return the Java priority of the thread (a number between 1 and 10 inclusive)
      * @throws CorruptDataException 
      * 
-     * @see Thread#getPriority()
+     * @see java.lang.Thread#getPriority()
      */
     int getPriority() throws CorruptDataException;
     
 
     /**
-     * Fetch the java.lang.Thread associated with this thread. If the thread is in the process
-     * of being attached, this may return null.
+     * <p>Returns the {@link JavaObject} representing the instance of the class or
subclass of {@link java.lang.Thread}
+     * that represents this thread in the Java Virtual Machine.</p>
      * 
-     * @return the a JavaObject representing the java.lang.Thread associated with this thread
-     * @throws CorruptDataException 
+     * <p>The object returned is the {@link java.lang.Thread} instance the method 
+     * {@link java.lang.Thread#start() start()} was executed against in order to create this

+     * Java thread.
+     * </p>
+     * 
+     * <p>This method may return <code>null</code> when there is no {@link
java.lang.Thread} instance associated with this
+     * Java thread. Some Java threads may be created for purposes other than for executing
Java code
+     * (for example, for garbage collection).    
+     * </p>
+     * 
+     * 
+     * @return a JavaObject representing the {@link java.lang.Thread} associated with this
thread, or <code>null</code>.
+     * @throws CorruptDataException if the reference to <code>java.lang.Thread</code>
is not <code>null</code> and cannot be retrieved.
      * 
      * @see JavaObject
-     * @see Thread
+     * @see java.lang.Thread
      */
     JavaObject getObject() throws CorruptDataException;
     
     /**
-     * Get the state of the thread when the image was created.
+     * <p>Get the state of the thread when the dump was generated.</p>
+     * <p>The result is a bit vector, and uses the states defined by
+     * the function 
+     * <a href="http://java.sun.com/j2se/1.5.0/docs/guide/jvmti/jvmti.html#GetThreadState">GetThreadState</a>
+     *  in the JVMTI specification.
+     * </p> 
+     * 
      * @return the state of the thread when the image was created.
-     * The result is a bit vector, and uses the states defined by
-     * the JVMTI specification.
-     * @throws CorruptDataException 
+     * 
+     * @throws CorruptDataException If the thread state could not be successfully retrieved.
 
      */
     int getState() throws CorruptDataException;
     
     /**
-     * Represents the joining point between the Java view of execution and the corresponding
native view.
-     * This method is where the mapping from Java into native threading resources is provided.
+     * <p>Returns the operating system level thread that executes the Java thread.</p>
+     * <p>This will return an {@link ImageThread} if an operating system level thread
can be
+     * returned, otherwise the <code>DataUnavailable</code> exception is thrown.
+     * There is no guarantee that there is a 1:1 relationship between <code>JavaThreads</code>
+     * and {@link ImageThread ImageThreads}.
+     * </p>
      * 
-     * @return the ImageThread which this ManagedThread is currently bound to.
+     * @return the ImageThread which this thread is currently bound to.
      * @throws CorruptDataException If the underlying resource describing the native representation
of the thread
-     * is damaged
-     * @throws DataUnavailable If no mapping is provided due to missing or limited underlying
resources (this 
-     * exception added in DTFJ 1.1)
+     * is damaged.
+     * @throws DataUnavailable If no mapping is provided due to missing or limited underlying
resources.
      * 
      * @see ImageThread
      */
     ImageThread getImageThread() throws CorruptDataException, DataUnavailable;
 
     /**
-     * Get the set of ImageSections which make up the managed stack.
-     * <br>
-     * Some Runtime implementations may also use parts of the ImageThread's stack
+     * <p>Get the set of {@link ImageSection ImageSections} which make up the Java
Virtual Machine stack.
+     * </p>
+     * <p> 
+     * Some Java Virtual Machine implementations may use parts of the ImageThread's stack
      * for JavaStackFrames.
+     * </p>
      * 
-     * @return a collection of ImageSections which make up the managed stack.
+     * @return a collection of <code>ImageSections</code> which make up the Java
stack.
      * 
-     * @see ImageSection
-     * @see ImageThread#getStackSections()
+     * @see javax.tools.diagnostics.image.ImageSection
+     * @see javax.tools.diagnostics.image.ImageThread#getStackSections()
      * @see javax.tools.diagnostics.image.CorruptData
      */
-    List getStackSections();
+    List<ImageSection> getStackSections();
     
     /**
-     * Get the set of stack frames.
-     * 
-     * @return an iterator to walk the managed stack frames in order from 
-     * top-of-stack (that is, the most recent frame) to bottom-of-stack
+     * <p>Get the set of stack frames.</p>
+     * <p>The start of the list will contain the top most stack frame, the last entry
+     * will contain the bottom most stack frame. The top contains the most recently executing
+     * stack frame.  
+     * </p>
+     * <p>
+     * This method may return an empty list when there are no Java stack frames associated
with
+     * this Java thread. <code>null</code> must never be returned.
+     * </p>
      * 
+     * @return a list of Java stack frames in order from top to bottom.
+     *  
      * @see JavaStackFrame
-     * @see javax.tools.diagnostics.image.CorruptData
      * 
      */
     List<JavaStackFrame> getStackFrames();
     
     /**
-     * Return the name of the thread.
+     * <p>Return the name of the thread.</p>
      * 
-     * Usually this is derived from the object associated with the thread, but if the
+     * <p>Usually this is derived from the object associated with the thread, but if
the
      * name cannot be derived this way (e.g. there is no object associated with the thread)
-     * DTFJ will synthesise a name for the thread.
+     * Kato will create a name for the thread.
+     * </p>
      * 
      * @return the name of the thread
-     * @throws CorruptDataException 
+     * @throws CorruptDataException If a name exists but cannot be retrieved. 
      */
     String getName() throws CorruptDataException;
     



Mime
View raw message