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 sp...@apache.org on 2009/07/22 15:29:13 UTC
svn commit: r796766 - in
/incubator/kato/trunk/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java:
JavaClass.java JavaMonitor.java
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