incubator-kato-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From spo...@apache.org
Subject svn commit: r796766 - in /incubator/kato/trunk/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java: JavaClass.java JavaMonitor.java
Date Wed, 22 Jul 2009 15:29:13 GMT
Author: spoole
Date: Wed Jul 22 15:29:12 2009
New Revision: 796766

URL: http://svn.apache.org/viewvc?rev=796766&view=rev
Log:
APi javadoc updates

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

Modified: incubator/kato/trunk/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaClass.java
URL: http://svn.apache.org/viewvc/incubator/kato/trunk/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaClass.java?rev=796766&r1=796765&r2=796766&view=diff
==============================================================================
--- incubator/kato/trunk/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaClass.java
(original)
+++ incubator/kato/trunk/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaClass.java
Wed Jul 22 15:29:12 2009
@@ -30,11 +30,12 @@
 public interface JavaClass {
 
     /**
-     * Fetch the {@link java.lang.Class} object associated with this class.
      * <p>
+     * Fetch the {@link java.lang.Class} object associated with this class.
+     * </p><p>
      * In some implementations this may be null if no object has been
      * created to represent this class, or if the class is synthetic.
-     * 
+     * </p>
      * @return the java.lang.Class object associated with this class 
      * @throws CorruptDataException 
      * 
@@ -47,7 +48,7 @@
      * the bootstrap class loader (including classes representing primitive 
      * types or void) will always return a JavaClassLoader representing the
      * bootstrap class loader. This asymmetry with 
-     * java.lang.Class#getClassLoader() is intentional.
+     * java.lang.Class#getClassLoader() is intentional. 
      * 
      * @throws CorruptDataException if the class loader for this class cannot
      * be found (a class cannot exist without a loader so this implies corruption)
@@ -57,54 +58,64 @@
     JavaClassLoader getClassLoader() throws CorruptDataException;
     
     /**
-     * Get the name of the class.
+     * <p>Get the name of the class in a form that follows the {@link java.lang.Class#getName()}
definition.</p>
+     * <p>This method will always return a valid class name.</p>
+     *   
+     * @return the name of the class
      * 
-     * @return the name of the class in the form: "full/package/class$innerclass"
      * @throws CorruptDataException 
      */
     String getName() throws CorruptDataException;
     
     /**
-     * Get the immediate superclass of this class.
+     * <p>
+     * Get the  super class of this class.
+     * </p><p>
+     * Will return the superclass of this class or null if no superclass exists.
+     *</p><p> 
+     * For JavaClass instances representing interfaces, java.lang.Object, primitive types
( int,boolean,char etc) 
+     * and void, calling this method will return null.
+  	 *</p>
+     * @return the immediate superclass of this class, or null if this class has no superclass.
      * 
-     * @return the immediate superclass of this class, or null if this
-     * class has no superclass. For interfaces, Object, primitive types 
-     * and void null is always returned.
      * @throws CorruptDataException 
      */
     JavaClass getSuperclass() throws CorruptDataException;
     
     
     /**
-     * Get the set of names of interfaces directly implemented by this class.
-     * @return an iterator over the collection of the names of interfaces 
-     * directly implemented by this class. Some JVM implementations may
-     * choose to load interfaces lazily, so only the names are returned.
-     * The JavaClass objects may be found through the defining class loader.
+     * <p>Get the set of names of interfaces directly implemented by the class represented
by this JavaClass.</p>
+     *<p>Some JVM implementations may choose to load interfaces lazily, so only the
names are returned.</p>
+     *<p>The returned list follows the standard semantics for javax.tools.diagnostics
collections.</p>
+     * <p>The returned list is never null but could be empty.</p>
+     * 
+     * @return a list  of the names of interfaces directly implemented by this class. 
      * 
      * @see java.lang.String
      * @see JavaClassLoader#findClass(String)
      * @see javax.tools.diagnostics.image.CorruptData
      */
-    List getInterfaces();
+    List<String> getInterfaces();
     
     /**
-     * Return the Java language modifiers for this class. 
-     * <p>
-     * The modifiers are defined by the JVM Specification.
      * <p>
+     * Return the Java language modifiers for this class. 
+     * </p><p>
+     * The modifiers are defined by the <a href="http://java.sun.com/docs/books/jls/second_edition/html/classes.doc.html#21613">JVM
Specification</a>.
+     * </p><p>
      * Note that, for inner classes, the actual modifiers are returned, not 
      * the synthetic modifiers. For instance, a class will never have its
      * 'protected' modifier set, even if the inner class was a protected
      * member, since 'protected' is not a legal modifier for a class file.
-     * 
+     * </p>
      * @return the modifiers for this class
      * @throws CorruptDataException 
      */
     int getModifiers() throws CorruptDataException;
     
     /**
-     * Is this an array class ?
+     * This method returns true if the class represented by this JavaClass is an array class.
+     * 
      * @return true if this class is an array class
      * @throws CorruptDataException 
      */
@@ -115,15 +126,18 @@
      *
      * @return a JavaClass representing the component type of this array class
      * @throws CorruptDataException 
+     * 
      * @exception java.lang.IllegalArgumentException if this JavaClass does not represent
an array class
      */
     JavaClass getComponentType() throws CorruptDataException;
     
     /**
-     * Get the set of fields declared in this class. 
+     * <p>Get the set of fields declared in this class.</p>
+     * <p>Fields declared in any superclas of this class are not returned.</p>
+     * <p>The returned list follows the standard semantics for javax.tools.diagnostics
collections.</p>
+     * <p>The returned list is never null but could be empty.</p>
      * 
-     * @return an iterator over the collection of fields declared
-     * in this class. 
+     * @return a list of fields declared in this class. 
      * 
      * @see JavaField
      * @see javax.tools.diagnostics.image.CorruptData
@@ -131,9 +145,12 @@
     List<JavaField> getDeclaredFields();
     
     /**
-     * Get the set of methods declared in this class. 
-     * @return an iterator over the collection of methods declared
-     * in this class.
+     * <p>Get the set of methods declared in this class.</p>
+     * <p>Methods declared in any superclas of this class are not returned.</p>
+     * <p>The returned list follows the standard semantics for javax.tools.diagnostics
collections.</p>
+     * <p>The returned list is never null but could be empty.</p>
+ 
+     * @return a list of methods declared in this class.
      * 
      * @see JavaMethod
      * @see javax.tools.diagnostics.image.CorruptData
@@ -141,6 +158,8 @@
     List<JavaMethod> getDeclaredMethods();
     
     /**
+     * Returns the list of constant pool references defined by this class.
+     * 
      * Java classes may refer to other classes and to String objects via 
      * the class's constant pool. These references are followed by the 
      * garbage collector, forming edges on the graph of reachable objects.
@@ -151,7 +170,7 @@
      * objects in the constant pool, some esoteric or future virtual 
      * machines may permit other types of objects to occur in the constant 
      * pool. This API imposes no restrictions on the types of JavaObjects 
-     * which might be included in the Iterator.
+     * which might be included in the list.
      * <p>
      * No assumption should be made about the order in which constant 
      * pool references are returned.
@@ -162,8 +181,10 @@
      * getConstantPoolReferences() unless the object is also referenced
      * by the constant pool.
      * 
-     * @return an iterator over the collection of JavaObjects which
-     * are referred to by the constant pool of this class
+     * <p>The returned list follows the standard semantics for javax.tools.diagnostics
collections.</p>
+     * <p>The returned list is never null but could be empty.</p>
+     * 
+     * @return a list of JavaObjects which are referred to by the constant pool of this class.
      * 
      * @see JavaObject
      * @see javax.tools.diagnostics.image.CorruptData
@@ -171,27 +192,35 @@
     List<JavaObject> getConstantPoolReferences();
     
     /**
+     * <p>
      * The ID of a class is a pointer to a section of memory which identifies
      * the class. The contents of this memory are implementation defined.
      * <p>
      * In some implementations getID() and getObject().getID() may return the
      * same value. This implies that the class object is also the primary
-     * internal representation of the class. Kato users should not rely on this
+     * internal representation of the class. API users should not rely on this
      * behaviour.
      * <p>
      * In some implementations, getID() may return null for some classes.
-     * This indicates that the class is a synthetic class which has been 
-     * constructed for Kato purposes only. The class has no physical 
-     * representation in the VM.
      * 
      * @return a pointer to the class
      */
 	ImagePointer getID();
 	
 	/**
-	 * Get the set of references from this class.
-	 *
-	 * @return an iterator of JavaReferences
+	 * Get the set of references from this class. 
+	 * <p>
+	 * A reference is a object that represents the uni-directional relationship between objects
and classes.
+	 * Objects and classes cannot be reclaimed by the Java Virtual Machine garbage collector
if references exist
+	 * that can ultimately be traced back to root references.  see {@link JavaReference} for
more detailed information.
+	 * <p>
+	 * Since this API can present entities that exist at any point in their lifecycle, it is
possible to encounter an
+	 * JavaClass that is eligible for collection and thus no {@link JavaReference} can be found
that refers to it.
+	 *   
+	 * <p>The returned list follows the standard semantics for javax.tools.diagnostics
collections.</p>
+     * <p>The returned list is never null but could be empty.</p>
+     * 
+     * @return a list of JavaReferences
 	 *
 	 * @see javax.tools.diagnostics.java.JavaReference
 	 * @see javax.tools.diagnostics.image.CorruptData

Modified: incubator/kato/trunk/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaMonitor.java
URL: http://svn.apache.org/viewvc/incubator/kato/trunk/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaMonitor.java?rev=796766&r1=796765&r2=796766&view=diff
==============================================================================
--- incubator/kato/trunk/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaMonitor.java
(original)
+++ incubator/kato/trunk/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaMonitor.java
Wed Jul 22 15:29:12 2009
@@ -23,7 +23,18 @@
 
 
 /**
- * Represents a monitor, either an object monitor or a raw monitor.
+ * Represents the underlying monitor used by a Java Virtual Machine to manage locking and
synchronization of a Java object,
+ * 
+ * <p>The underlying monitor is implementation specific.<p>
+ * 
+ * <p>Java programmers use the synchronized modifier on methods and the synchronized
block within methods to control simultaneous access to Java objects.
+ * The synchronisation mechanism is typically implemented using a variety of techniques.
The JavaMonitor does not distinquish between these types, 
+ * instead it represents a common simple abstraction that allows the caller to determine;
+ * <ul>
+ * <li>which thread currently owns the monitor</li>
+ * <li>which threads are waiting to be informed when the monitor is released</li>
+ * <li>which threads are waiting to be woken after having</li>    
+ * </ul>
  */
 public interface JavaMonitor {
     
@@ -51,8 +62,12 @@
     JavaThread getOwner() throws CorruptDataException;
     
     /**
-     * Get the set of threads waiting to enter the monitor
-     * @return an iterator over the collection of threads waiting to enter this monitor
+     * <p>Get the set of threads waiting to enter the monitor.
+     * 
+     * <p>The returned list follows the standard semantics for javax.tools.diagnostics
collections.</p>
+     * <p>The returned value is never null but can be an empty list.</p>
+    
+     * @return a list of threads waiting to enter this monitor
      * 
      * @see JavaThread
      * @see javax.tools.diagnostics.image.CorruptData
@@ -61,8 +76,9 @@
     
     /**
      * Get the set of threads waiting to be notified on the monitor (in the Object.wait method)
-     * @return an iterator over the collection of threads waiting to be notified on
-     * this monitor
+     * <p>The returned list follows the standard semantics for javax.tools.diagnostics
collections.</p>
+     * <p>The returned value is never null but can be an empty list.</p>
+     * @return a list of threads waiting to be notified on this monitor.
      * 
      * @see JavaThread
      * @see javax.tools.diagnostics.image.CorruptData



Mime
View raw message