incubator-kato-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From spo...@apache.org
Subject svn commit: r794248 - in /incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/src/main: java/javax/tools/diagnostics/java/ java/javax/tools/diagnostics/runtime/ resources/javax/ resources/javax/tools/ resources/javax/tools/d...
Date Wed, 15 Jul 2009 12:29:25 GMT
Author: spoole
Date: Wed Jul 15 12:29:24 2009
New Revision: 794248

URL: http://svn.apache.org/viewvc?rev=794248&view=rev
Log:
small updates to Javadoc for API

Added:
    incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/src/main/resources/javax/
    incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/src/main/resources/javax/tools/
    incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/src/main/resources/javax/tools/diagnostics/
    incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/src/main/resources/javax/tools/diagnostics/runtime/
    incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/src/main/resources/javax/tools/diagnostics/runtime/package.html
  (with props)
Modified:
    incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaRuntime.java
    incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/runtime/ManagedRuntime.java

Modified: incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaRuntime.java
URL: http://svn.apache.org/viewvc/incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaRuntime.java?rev=794248&r1=794247&r2=794248&view=diff
==============================================================================
--- incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaRuntime.java
(original)
+++ incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaRuntime.java
Wed Jul 15 12:29:24 2009
@@ -25,11 +25,21 @@
 
 
 /**
- * Represents an instance of a JavaVM within the ImageProcess
+ * Represents an instance of a Java Virtual Machine
+ * 
+ * This interface defines attributes and features common across real implementation of the
Java Virtual Machine.
+ * Not all of these characteristics are defined by the <a href="http://java.sun.com/docs/books/jvms/second_edition/html/VMSpecTOC.doc.html">Java
Virtual Machine Specification</a>
+ * 
+ * Notable additions beyond the JVM specification include Garbage Collection and access to
the contents of the Heap or Heaps.
+ *  
+ * Since this interface defines a view of the Java Runtime that is beyond that seen by the
Java programmer during program execution it is necessarily more detailed.
+ *    
  */
 public interface JavaRuntime extends ManagedRuntime {
 
     /**
+     * @remove Candidate for removal from specification as not useful
+     * 
      * Get the object that represents the virtual machine
      * @return the address of the JavaVM structure which represents this JVM instance in
JNI
      * @throws CorruptDataException 
@@ -37,42 +47,52 @@
     ImagePointer getJavaVM() throws CorruptDataException;
     
     /**
-     * Fetch the JavaVMInitArgs which were used to create this VM.
-     * See JNI_CreateJavaVM in the JNI Specification for more details.
+     * Fetch the {@link JavaVMInitArgs} which were used to create this VM.
+     * See <a href="http://java.sun.com/javase/6/docs/technotes/guides/jni/spec/invocation.html#wp16334">JNI_CreateJavaVM</a>
in the JNI Specification for more details.
+     * 
+     * A valid object is returned or an exception is thrown.
      * 
      * @return the JavaVMInitArgs which were used to create this VM.
      * @throws DataUnavailable if the arguments are not available 
-     * @throws CorruptDataException
+     * @throws CorruptDataException if the implementation was unexpectedly unable to retrieve
the data
      */
     JavaVMInitArgs getJavaVMInitArgs() throws DataUnavailable, CorruptDataException;
     
     /**
-     * Get the set of class loaders active in this VM
-     * @return an iterator of all of the class loaders within this JavaVM
+     * Get the set of class loaders available in this Java Virtual Machine instance.
+     * 
+     * Available in this context means class loaders that are participating in the class
loader hierarchy.
+     * All class loaders are returned including any defined by the Java Virtual machine instance
ifself.
+     * 
+     * At least one class loader must be returned in the resulting list. 
+     *      
+     * @return a {@link java.util.List} of all of the class loaders within this Java Virtual
Machine instance
      * 
      * @see JavaClassLoader
-     * @see javax.tools.diagnostics.image.CorruptData
      */
     List<JavaClassLoader> getJavaClassLoaders();
     
     /**
-     * Get the set of Java threads known by the VM 
-     * @return an iterator of the JavaThreads in the runtime
+     * Get the set of started Java Threads in this Java Virtual Machine instance.
+     * 
+     * @return a {@link java.util.List} of the JavaThreads in the runtime
      * 
      * @see JavaThread
-     * @see javax.tools.diagnostics.image.CorruptData
      */
+    
     List<JavaThread> getThreads();
     
     /**
-     * This is short cut method. The same result can be found by iterating over all
-     * methods in all class loaders in all classes.
+     * Get the set of JavaMethod objects that have been compiled.  
      * 
-     * @return an iterator over all of the JavaMethods in the JavaRuntime which
-     * have been compiled
+     * Compiled methods are ones that have been converted into native code.
+     * 
+     * There is no expectation that any method has been compiled. The returned list could
be empty.
+     *  
+     * @return a {@link java.util.List} of all of the JavaMethods in the JavaRuntime which
+     * have been compiled.
      * 
      * @see JavaMethod
-     * @see javax.tools.diagnostics.image.CorruptData
      */
     List<JavaMethod> getCompiledMethods();
     

Modified: incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/runtime/ManagedRuntime.java
URL: http://svn.apache.org/viewvc/incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/runtime/ManagedRuntime.java?rev=794248&r1=794247&r2=794248&view=diff
==============================================================================
--- incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/runtime/ManagedRuntime.java
(original)
+++ incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/runtime/ManagedRuntime.java
Wed Jul 15 12:29:24 2009
@@ -18,28 +18,38 @@
 
 /**
  * A generic managed runtime instance.
+ * 
+ * A Managed Runtime as against an "Unmanaged Runtime" is one where the runtime takes an
active role in the program execution.
+ * Common examples of managed runtimes are the Java Virtual Machine or the .NET Common Language
Runtime.
+ *  
  * <br>
- * No class should implement this interface directly. Instead, they should implement
- * another interface which extends this interface and provides APIs for a specific
- * language runtime environment
+ * No class should implement this interface directly. This is an marker interface which is
extended by
+ * specific runtime interfaces. See  {@link javax.tools.diagnostics.java.JavaRuntime} as
an example of such a case.
+ * 
  */
 public interface ManagedRuntime {
     
-    /**
-     * Get the 'full' version information for this runtime.
-     * @return a string representation of the version information for this runtime instance
-     * @throws CorruptDataException 
-     * @see #getVersion()
-     * 
-	 * @deprecated Use "getVersion()" instead
-     */
-	public String getFullVersion() throws CorruptDataException;
+    
     
 	/**
-	 * Get the version data available for this runtime instance.
-	 * @return a string representing all the version data available for this runtime instance.
+	 * Returns version data available for this runtime instance. The version information is
never null.
+	 * The format of the version data is implementation specific. 
+	 * 
+	 * @return a string representing  the available version information specific to the implementation
 	 * 
-	 * @throws CorruptDataException If the runtime presents no understandable version data
+	 * @throws CorruptDataException If the ManagedRuntime implementation is unable to retrieve
version data
+	 */
+	public String getVersion() throws CorruptDataException;
+
+	/**
+	 * @remove as redundant - a carryover from initial contribution
+	 * 
+	 * Get the 'full' version information for this runtime.
+	 * @return a string representation of the version information for this runtime instance
+	 * @throws CorruptDataException 
+	 * @see #getVersion()
+	 * 
+	 * @deprecated Use "getVersion()" instead
 	 */
-	public String getVersion() throws CorruptDataException;    
+	public String getFullVersion() throws CorruptDataException;    
 }

Added: incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/src/main/resources/javax/tools/diagnostics/runtime/package.html
URL: http://svn.apache.org/viewvc/incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/src/main/resources/javax/tools/diagnostics/runtime/package.html?rev=794248&view=auto
==============================================================================
--- incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/src/main/resources/javax/tools/diagnostics/runtime/package.html
(added)
+++ incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/src/main/resources/javax/tools/diagnostics/runtime/package.html
Wed Jul 15 12:29:24 2009
@@ -0,0 +1,8 @@
+<html>
+<body>
+<p>Definition of an abstract view of a managed runtime.</p>
+<p>Runtimes are collections of software services that together, provide a environment
where an application program can be executed. Most computer languages provide some sort of
runtime. 
+This package contains definitions that are common to all runtime environments. 
+</p>
+</body>
+</html>
\ No newline at end of file

Propchange: incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/src/main/resources/javax/tools/diagnostics/runtime/package.html
------------------------------------------------------------------------------
    svn:executable = *



Mime
View raw message