From kato-commits-return-472-apmail-incubator-kato-commits-archive=incubator.apache.org@incubator.apache.org Sun Jul 19 09:02:10 2009 Return-Path: Delivered-To: apmail-incubator-kato-commits-archive@minotaur.apache.org Received: (qmail 32604 invoked from network); 19 Jul 2009 09:02:10 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.3) by minotaur.apache.org with SMTP; 19 Jul 2009 09:02:10 -0000 Received: (qmail 8627 invoked by uid 500); 19 Jul 2009 09:03:15 -0000 Delivered-To: apmail-incubator-kato-commits-archive@incubator.apache.org Received: (qmail 8612 invoked by uid 500); 19 Jul 2009 09:03:15 -0000 Mailing-List: contact kato-commits-help@incubator.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: kato-dev@incubator.apache.org Delivered-To: mailing list kato-commits@incubator.apache.org Received: (qmail 8602 invoked by uid 99); 19 Jul 2009 09:03:15 -0000 Received: from athena.apache.org (HELO athena.apache.org) (140.211.11.136) by apache.org (qpsmtpd/0.29) with ESMTP; Sun, 19 Jul 2009 09:03:15 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=10.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Sun, 19 Jul 2009 09:03:04 +0000 Received: by eris.apache.org (Postfix, from userid 65534) id 3C7002388863; Sun, 19 Jul 2009 09:02:44 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r795498 - in /incubator/kato/branches/experimental/maven_restructure/org.apache.kato: ./ kato.anttasks/ kato.anttasks/src/main/java/org/apache/kato/anttasks/xmlgen/ kato.api/ kato.api/src/ant/ kato.api/src/main/java/javax/tools/diagnostics/... Date: Sun, 19 Jul 2009 09:02:43 -0000 To: kato-commits@incubator.apache.org From: spoole@apache.org X-Mailer: svnmailer-1.0.8 Message-Id: <20090719090244.3C7002388863@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Author: spoole Date: Sun Jul 19 09:02:41 2009 New Revision: 795498 URL: http://svn.apache.org/viewvc?rev=795498&view=rev Log: New ant task to spit out javadoc as xml + new docs module to consume xmljavadoc and produce spec. Added: incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/ incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/.classpath incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/.project incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/.settings/ incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/.settings/org.eclipse.jdt.core.prefs incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/.settings/org.maven.ide.eclipse.prefs incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/pom.xml incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/src/ incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/src/ant/ incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/src/ant/buildjavadoc.xml (with props) incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/src/docbkx/ incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/src/docbkx/chapters/ incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/src/docbkx/chapters/API.xml incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/src/docbkx/chapters/Introduction.xml incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/src/docbkx/chapters/sections/ incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/src/docbkx/fo.xsl incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/src/docbkx/spec.xml incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/src/xslt/ incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/src/xslt/packagecontents.xslt incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/src/xslt/packagelist.xslt Removed: incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/package-info.java Modified: incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.anttasks/pom.xml incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.anttasks/src/main/java/org/apache/kato/anttasks/xmlgen/XMLWriter.java incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/pom.xml incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/src/ant/spec.xml incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaClass.java incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaClassLoader.java incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaField.java incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaHeap.java incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaMember.java 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/java/JavaVMInitArgs.java incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaVMOption.java incubator/kato/branches/experimental/maven_restructure/org.apache.kato/pom.xml Modified: incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.anttasks/pom.xml URL: http://svn.apache.org/viewvc/incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.anttasks/pom.xml?rev=795498&r1=795497&r2=795498&view=diff ============================================================================== --- incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.anttasks/pom.xml (original) +++ incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.anttasks/pom.xml Sun Jul 19 09:02:41 2009 @@ -17,19 +17,7 @@ ant 1.7.1 - + com.sun tools @@ -37,20 +25,8 @@ system ${java.home}/../lib/tools.jar - - net.sourceforge.nekohtml nekohtml Modified: incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.anttasks/src/main/java/org/apache/kato/anttasks/xmlgen/XMLWriter.java URL: http://svn.apache.org/viewvc/incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.anttasks/src/main/java/org/apache/kato/anttasks/xmlgen/XMLWriter.java?rev=795498&r1=795497&r2=795498&view=diff ============================================================================== --- incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.anttasks/src/main/java/org/apache/kato/anttasks/xmlgen/XMLWriter.java (original) +++ incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.anttasks/src/main/java/org/apache/kato/anttasks/xmlgen/XMLWriter.java Sun Jul 19 09:02:41 2009 @@ -19,8 +19,10 @@ import com.sun.javadoc.FieldDoc; import com.sun.javadoc.MethodDoc; import com.sun.javadoc.PackageDoc; +import com.sun.javadoc.ParamTag; +import com.sun.javadoc.Parameter; import com.sun.javadoc.Tag; -import com.sun.tools.doclets.internal.toolkit.util.TextTag; +import com.sun.javadoc.Type; public class XMLWriter { @@ -46,8 +48,8 @@ out=new PrintWriter(model); - - write(""); + //write(""); + write(""); @@ -55,7 +57,11 @@ } public void writeClass(ClassDoc c) throws IOException { - write(""); + write(""); + + Tag[] tags=c.firstSentenceTags(); + writeSummary(tags); + writeComment(c.commentText()); for(FieldDoc f:c.fields()) { writeField(f); @@ -77,11 +83,64 @@ } private void writeMethod(MethodDoc m) throws IOException { write(""); + + Parameter[] parameters=m.parameters(); + write(parameters); + + ParamTag[] ptags=m.paramTags(); + write(ptags); + + Type t=m.returnType(); + writeType("returntype",t); + write(""+m.modifiers()+""); + writeComment(m.commentText()); write(""); } + private void write(ParamTag[] parameters) { + if(parameters==null || parameters.length==0) return; + write(""); + for(ParamTag p:parameters) { + write(p); + } + write(""); + + } + private void write(ParamTag p) { + String name=p.parameterName(); + + String comment=p.parameterComment(); + if(comment==null || comment.trim().equals("")) return; + + write(""); + write(p.parameterComment()); + write(""); + } + private void write(Parameter[] parameters) { + if(parameters==null || parameters.length==0) return; + write(""); + for(Parameter p:parameters) { + write(p); + } + write(""); + } + private void write(Parameter p) { + write(""); + Type t=p.type(); + writeType("type",t); + write(""); + + } + private void writeType(String tag,Type t) { + write("<"+tag+">"); + write(""+t.typeName()+""); + write(""+t.simpleTypeName()+""); + write(""+t.qualifiedTypeName()+""); + + write(""); + } private void writeConstructor(ConstructorDoc r) throws IOException { write(""); writeComment(r.commentText()); @@ -138,6 +197,18 @@ break; case Node.ELEMENT_NODE : String name=n.getNodeName(); + if(name.equals("BR")) name="html:br"; + if(name.equals("H1")) name="db:sect2"; + if(name.equals("H2")) name="db:sect3"; + if(name.equals("H3")) name="db:sect4"; + if(name.equals("H4")) name="db:sect5"; + if(name.equals("P")) name="db:para"; + if(name.equals("UL")) name="db:itemizedlist"; + if(name.equals("OL")) name="db:orderedlist"; + if(name.equals("LI")) name="db:listitem"; + if(name.equals("A")) name="db:link"; + if(name.equals("PRE")) name="db:programlisting"; + write("<"+name+">"); if(n.hasChildNodes()) { NodeList kids=n.getChildNodes(); @@ -157,33 +228,22 @@ } public void writeInterface(ClassDoc c) throws IOException { - write(""); + write(""); + Tag[] tags=c.firstSentenceTags(); + writeSummary(tags); writeComment(c.commentText()); for(MethodDoc m:c.methods()) { writeMethod(m); } - write(""); + write(""); } public void addPackageContents(PackageDoc p) throws IOException { write(""); Tag[] tags=p.firstSentenceTags(); - if(tags!=null && tags.length>0) { - StringBuilder sb=new StringBuilder(); - - for(Tag t:tags) { - String kind=t.kind(); - if(kind.equals("Text")) { - sb.append(t.text()+" "); - } - else { - System.out.println("tag="+t.getClass()); - } - } - - writeSummary(sb.toString()); - } + + writeSummary(tags); writeComment(p.commentText()); @@ -198,6 +258,23 @@ write(""); } + private void writeSummary(Tag[] tags) throws IOException { + if(tags!=null && tags.length>0) { + StringBuilder sb=new StringBuilder(); + + for(Tag t:tags) { + String kind=t.kind(); + if(kind.equals("Text")) { + sb.append(t.text()+" "); + } + else { + System.out.println("tag="+t.getClass()); + } + } + + writeSummary(sb.toString()); + } + } private void writeSummary(String text) throws IOException { writeText("summary",text); Modified: incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/pom.xml URL: http://svn.apache.org/viewvc/incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/pom.xml?rev=795498&r1=795497&r2=795498&view=diff ============================================================================== --- incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/pom.xml (original) +++ incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/pom.xml Sun Jul 19 09:02:41 2009 @@ -15,41 +15,48 @@ 3.8.1 test + + org.apache.kato + kato.anttasks + 0.0.1-SNAPSHOT + + 0.0.1-SNAPSHOT JSR 326 API Java classes that define the JSR 326 API - - - - - org.apache.maven.plugins - maven-javadoc-plugin - - org.umlgraph.doclet.UmlGraphDoc - - org.umlgraph - doclet - 5.1 - - -overview ${basedir}/src/javadoc/overview.html - - - - + + + org.apache.maven.plugins + maven-javadoc-plugin + + + compile + + javadoc + + + + + + + org.apache.maven.plugins maven-antrun-plugin + 1.3 compile compile - - + + + + @@ -58,6 +65,45 @@ + + + org.apache.ant + ant-trax + 1.7.1 + + + + + + + + org.apache.maven.doxia + doxia-maven-plugin + 1.1 + + + pre-site + + render-books + + + + + + + target/spec + target/spec/spec.xml + + + + pdf + + + + + + + Modified: incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/src/ant/spec.xml URL: http://svn.apache.org/viewvc/incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/src/ant/spec.xml?rev=795498&r1=795497&r2=795498&view=diff ============================================================================== --- incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/src/ant/spec.xml (original) +++ incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/src/ant/spec.xml Sun Jul 19 09:02:41 2009 @@ -1,46 +1,41 @@ - - - - - - + + + + + - + + + + - - - - - - - - - Building pdf using ${src} - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + - - - - - - Unable to create pdf specification document - Set maven property kato.aurigadoclet.jar in local settings to point to jar containing - required doclet. (Visit http://aurigadoclet.sourceforge.net/) for more information - Current value of property is [${kato.aurigadoclet.jar}] - The containing directory ${doc.dir} ${auriga.doclet.exists} - \ No newline at end of file Modified: incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaClass.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/JavaClass.java?rev=795498&r1=795497&r2=795498&view=diff ============================================================================== --- incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaClass.java (original) +++ incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaClass.java Sun Jul 19 09:02:41 2009 @@ -23,11 +23,14 @@ /** * Represents a Java class. * + * A Java Class can have fields and methods. It is a shallow model of a loaded class file + * or special types such as array types or primitive types in the Java Virtual Machine. + * */ public interface JavaClass { /** - * Fetch the java.lang.Class object associated with this class. + * Fetch the {@link java.lang.Class} object associated with this class. *

* In some implementations this may be null if no object has been * created to represent this class, or if the class is synthetic. Modified: incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaClassLoader.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/JavaClassLoader.java?rev=795498&r1=795497&r2=795498&view=diff ============================================================================== --- incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaClassLoader.java (original) +++ incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaClassLoader.java Sun Jul 19 09:02:41 2009 @@ -21,50 +21,80 @@ /** - * Represents an internal ClassLoader structure within a Java VM instance. - * For most ClassLoaders there is a corresponding java.lang.ClassLoader + *

+ * Represents an internal ClassLoader structure within a Java Virtual Machine instance. + * For most ClassLoaders there is a corresponding {@link java.lang.ClassLoader} * instance within with JavaRuntime. For primordial class loaders such as * the bootstrap class loader, there may or may not be a corresponding - * java.lang.ClassLoader instance. - * + * {@link java.lang.ClassLoader} instance. + *

+ *

* Since Java does not define any strict inheritance structure between * class loaders, there are no APIs for inspecting 'child' or 'parent' * class loaders. This information may be inferred by inspecting the - * corresponding java.lang.ClassLoader instance + * corresponding {@link java.lang.ClassLoader} instance:

+ * pseudo javacode example + * 

+ * 		JavaClassLoader  loader;
+ * 		JavaObject instance=loader.getObject();
+ * 		String classLoaderName=instance.getJavaClass().getName();
+ * 
+ *
* * @see java.lang.ClassLoader */ public interface JavaClassLoader { /** - * Get the set of classes which are defined in this JavaClassLoader. - * @return an iterator over the collection of classes which are defined - * in this JavaClassLoader - * + *

+ * Get the set of classes which are defined in this JavaClassLoader. + * Calling the {@link JavaClass#getClassLoader()} method on objects returned in this list will + * return this JavaClassLoader

+ * + *

The returned list follows the standard semantics for javax.tools.diagnostics collections.

+ *

The returned value is never null but can be an empty list.

+ * + * @return an list of classes which are defined in this JavaClassLoader * @see JavaClass - * @see javax.tools.diagnostics.image.CorruptData */ List getDefinedClasses(); /** + *

* When a ClassLoader successfully delegates a findClass() request to * another ClassLoader, the result of the delegation must be cached within - * the internal structure so that the VM does not make repeated requests + * the internal structure so that the Java Virtual Machine does not make repeated requests * for the same class. + *

+ * The contents of the returned list is a superset of that returned by {@link #getDefinedClasses()} + *

+ * The returned list follows the standard semantics for javax.tools.diagnostics collections.

+ *

The returned value is never null but can be an empty list.

* - * @return an iterator over the collection of classes which are defined - * in this JavaClassLoader or which were found by delegation to - * other JavaClassLoaders + * @return a list of classes which are defined in this JavaClassLoader + * or which were found by delegation to other JavaClassLoaders * * @see JavaClass - * @see javax.tools.diagnostics.image.CorruptData */ List getCachedClasses(); /** - * Find a named class within this class loader. The class may have been + * Find a class by name within this class loader. The class may have been * defined in this class loader, or this class loader may have delegated * the load to another class loader and cached the result. + * + * The form of the name presented to this method should be as follows + * 
+     * [ packagenamepart / ... ] (classname ) [ $innerclassname ...]
+     *
+ *

+ * Examples + *

+ *
    + *
  • To find the JavaClass that represents "java.lang.String" use findClass("java/lang/String")
    • + *
  • To find the JavaClass that represents "Foo.InnerClass.InnerInnerClass" in the default package use findClass("Foo$InnerClass$InnerInnerClass")
    • + *
  • To fine the JavaClass that represents "java.util.Map.Entry usefindClass("java/util/Map$Entry") + *
* * @param name of the class to find. Packages should be separated by * '/' instead of '.' @@ -74,10 +104,14 @@ JavaClass findClass(String name) throws CorruptDataException; /** - * Get the java.lang.ClassLoader instance associated with this class loader. - * @return a JavaObject representing the java.lang.ClassLoader instance - * associated with this class loader, or null if there is no Java class - * loader associated with this low-level class loader. + * Get the {@link java.lang.ClassLoader} instance (represented by a {@link JavaObject} + * associated with this class loader. If there is no associated class loader, for example the + * system class loader , then null will be returned. + * + * Further examination of the returned object is implementation specific. + * + * @return a JavaObject representing the {@link java.lang.ClassLoader} instance + * * @throws CorruptDataException * * @see JavaObject Modified: incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaField.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/JavaField.java?rev=795498&r1=795497&r2=795498&view=diff ============================================================================== --- incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaField.java (original) +++ incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaField.java Sun Jul 19 09:02:41 2009 @@ -18,12 +18,13 @@ /** * Represents a field declaration. - * It is modelled on java.lang.reflect.Field + * It is modelled on {@link java.lang.reflect.Field} */ public interface JavaField extends JavaMember { /** * Get the contents of an Object field + * * @param object to fetch the field from. Ignored for static * fields. * Modified: incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaHeap.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/JavaHeap.java?rev=795498&r1=795497&r2=795498&view=diff ============================================================================== --- incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaHeap.java (original) +++ incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaHeap.java Sun Jul 19 09:02:41 2009 @@ -15,26 +15,43 @@ import java.util.List; +import javax.tools.diagnostics.image.ImageSection; + /** - * Represents a heap of managed objects. There may be multiple heaps - * within a JVM, for instance a generational heap and a class heap. - * Additionally, heaps may consist of non-contiguous memory regions. + * Represents a single heap of managed objects. + * + * The heap can be viewed as an unordered collection of JavaObjects or as a region of storage + * within the Java Virtual Machiine instance. + * + * The heap commonly contains JavaObject instances that are reachable by navigating chains of {@link JavaReference} + * These references can be obtained from the {@link JavaRuntime#getHeapRoots()} method. + * + * A heap can contain instances which cannot be reached by the use of {@link JavaReference} * */ public interface JavaHeap { /** - * Get the set of contiguous memory regions which form this heap. - * @return an iterator over the collection of contiguous memory regions - * which form this heap + * Get the set of memory regions that represent the memory layout of the heap. + * The actual make up of this list is implementation specific. + * + * The returned list follows the standard semantics for javax.tools.diagnostics collections. + * + * The returned value is never null but can be an empty list. + * + * @return a list of {@link ImageSection} instances + * * * @see javax.tools.diagnostics.image.ImageSection - * @see javax.tools.diagnostics.image.CorruptData */ - List getSections(); + List getSections(); /** * Get a brief textual description of this heap. + * The value returned is implementation specific. + * + * The returned value is never null. + * * @return a brief textual description of this heap */ String getName(); @@ -42,11 +59,13 @@ /** * Get the set of objects which are stored in this heap. * - * @return an iterator over the collection of objects which - * are stored in this heap + * @return a list of {@link JavaObject} objects which are stored in this heap + * + * The returned list follows the standard semantics for javax.tools.diagnostics collections. + * + * The returned value is never null but can be an empty list. * * @see JavaObject - * @see javax.tools.diagnostics.image.CorruptData */ List getObjects(); Modified: incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaMember.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/JavaMember.java?rev=795498&r1=795497&r2=795498&view=diff ============================================================================== --- incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaMember.java (original) +++ incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaMember.java Sun Jul 19 09:02:41 2009 @@ -25,9 +25,9 @@ /** * Get the set of modifiers for this field or method - a set of bits - * - * @return the modifiers for this field or method. The values for the constants representing - * the modifiers can be obtained from java.lang.reflect.Modifier. + * The values for the constants representing the modifiers can be obtained from {@link java.lang.reflect.Modifier}. + + * @return the modifiers for this field or method. * @throws CorruptDataException * */ @@ -35,6 +35,7 @@ /** * Get the class which declares this field or method + * * @return the JavaClass which declared this field or method * @throws CorruptDataException * @throws DataUnavailable 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=795498&r1=795497&r2=795498&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 Sun Jul 19 09:02:41 2009 @@ -38,10 +38,9 @@ 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 */ ImagePointer getJavaVM() throws CorruptDataException; @@ -60,12 +59,17 @@ /** * 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. + *

+ * Any structural relationships between class loaders in this list is not exposed. Recreation of the class loader + * graph within a Java Virtual Machine instance is beyond the scope of the API. + *

+ *

At least one class loader must be returned in the resulting list.

+ * + * The returned list follows the standard semantics for javax.tools.diagnostics collections * - * 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 @@ -73,7 +77,13 @@ List getJavaClassLoaders(); /** - * Get the set of started Java Threads in this Java Virtual Machine instance. + * Get the set of Java Threads that have been started {@link java.lang.Thread#start()} in this Java Virtual Machine instance. + * This method does not return all instances of java.lang.Thread contained within the system. Only threads that have been started and have + * not yet stopped or exited are returned. Threads may not be in an active state when returned by this method. + * + * The returned list follows the standard semantics for javax.tools.diagnostics collections + * + * The returned list is never null although it can be empty. * * @return a {@link java.util.List} of the JavaThreads in the runtime * @@ -85,10 +95,14 @@ /** * Get the set of JavaMethod objects that have been compiled. * - * Compiled methods are ones that have been converted into native code. + * Compiled methods are methods that have been converted into native code by the Java Virtual Machine or related Just In Time Compiler * * There is no expectation that any method has been compiled. The returned list could be empty. - * + * However any JavaMethod reachable though the API which would return a non empty list for calls to {@link JavaMethod#getCompiledSections()} must be contained within the list + * returned by this method. + * + * The returned list follows the standard semantics for javax.tools.diagnostics collections + * * @return a {@link java.util.List} of all of the JavaMethods in the JavaRuntime which * have been compiled. * @@ -97,12 +111,17 @@ List getCompiledMethods(); /** - * Provides access to the collection of monitors used in the JavaVM. This - * collection includes both monitors associated with managed objects (e.g. object - * monitors) and monitors associated with internal control structures (e.g. - * raw monitors) + * Provides access to the collection of monitors used in the Java Virtual Machine. This + * collection can include monitors associated with managed objects (e.g. object + * monitors) and monitors associated with Java Virtual Machine internal control structures (e.g. + * raw monitors). Raw monitors are implementation specific. * - * @return an iterator over the collection of monitors + * + * The returned list follows the standard semantics for javax.tools.diagnostics collections. + * + * The returned list is never null but could be empty. + * + * @return a list of monitors * * @see JavaMonitor * @see javax.tools.diagnostics.image.CorruptData @@ -110,22 +129,30 @@ List getMonitors(); /** - * Get the set of heaps known by the VM - * @return an iterator for all of the Java heaps within this runtime. Heaps - * may be specific to this JavaVM instance, or may be shared between multiple - * JavaVM instances + * Get the set of heaps known by the Java Virtual Machine + * There may be multiple heaps within a Java Virtual Machine, for instance a generational heap and a class heap. + * Heaps may be specific to this Java Virtual Machine instance, or may be shared between multiple + * Java Virtual Machine instances. + * + * The returned list follows the standard semantics for javax.tools.diagnostics collections. * + * The returned list is never null and will always contain at least one JavaHeap object + * + * @return a list for all of the Java heaps within this runtime. * @see JavaHeap * @see javax.tools.diagnostics.image.CorruptData */ List getHeaps(); /** - * Get the set of object and class roots known to the VM. - * Stack frame roots are not included in the set. Instead, they can be retrieved using JavaStackFrame.getHeapRoots(). - * - * @return an iterator over the collection of JavaReferences representing the known global heap roots within this runtime. - * + * Get the complete set of object and class roots known to the Java Virtual Machine + * + * @return a list of JavaReferences representing the known global heap roots within this runtime. + * + * The returned list follows the standard semantics for javax.tools.diagnostics collections. + * + * The returned list is never null but can be empty. + * @see JavaReference * @see JavaStackFrame * @see javax.tools.diagnostics.image.CorruptData @@ -134,6 +161,8 @@ List getHeapRoots(); /** + * @remove candidate for removal as its an arbitary implementation specific method + * * Fetches implementation specific trace buffers, like the verbose GC buffer. * * @param bufferName a String naming the buffer to be fetched Modified: incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaVMInitArgs.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/JavaVMInitArgs.java?rev=795498&r1=795497&r2=795498&view=diff ============================================================================== --- incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaVMInitArgs.java (original) +++ incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaVMInitArgs.java Sun Jul 19 09:02:41 2009 @@ -21,13 +21,16 @@ /** - * This class models the JavaVMInitArgs C structure passed to JNI_CreateJavaVM - * to create this VM. + * This class models the JavaVMInitArgs C structure passed to JNI_CreateJavaVM + * to create this Java Virtual Machine + * + * Typically the options passed to the JVM are similar but necessarily identical to these used to invoke the Java Virtual Machine from a command line. + * */ public interface JavaVMInitArgs { /** - * The JNI specified version constant for the Java 1.1 version of JNI + * The JNI specified version constant for the Java 1.1 version of JNI */ public static final int JNI_VERSION_1_1 = 0x00010001; @@ -42,8 +45,13 @@ public static final int JNI_VERSION_1_4 = 0x00010004; /** - * Fetch the JNI version from the JavaVMInitArgs structure used to create this VM. - * See the JNI specification for the meaning for this field. + * The JNI specified version constant for the Java 1.6 version of JNI + */ + public static final int JNI_VERSION_1_6 = 0x00010006; + + /** + * Fetch the JNI version from the JavaVMInitArgs structure used to create this Java Virtual Machine. + * See the JNI specification for the meaning for this field. * * @return the JNI version * @throws DataUnavailable @@ -52,19 +60,24 @@ int getVersion() throws DataUnavailable, CorruptDataException; /** - * Fetch the ignoreUnrecognized field from the JavaVMInitArgs structure used to create this VM. - * See the JNI specification for the meaning of this field. + * Fetch the ignoreUnrecognized field from the JavaVMInitArgs structure used to create this Java Virtual Machine. + * See the JNI specification for the meaning for this field. * - * @return true if ignoreUnrecognized was set to a non-zero value with the VM was invoked + * @return true if ignoreUnrecognized was set to a non-zero value when the Java Virtual Machine was invoked * @throws DataUnavailable * @throws CorruptDataException */ boolean getIgnoreUnrecognized() throws DataUnavailable, CorruptDataException; /** - * Fetch the options used to start this VM, in the order they were originally specified. + * Fetch the options used to start this Java Virtual Machine, in the order they were originally specified. + * + * The returned list follows the standard semantics for javax.tools.diagnostics collections + * + * The order of the options returned in the list is the same as that passed to the to JNI_CreateJavaVM function. + * A list is always returned but could be empty * - * @return an Iterator over the collection of JavaVMOptions + * @return an List of JavaVMOptions * @throws DataUnavailable * * @see JavaVMOption Modified: incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaVMOption.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/JavaVMOption.java?rev=795498&r1=795497&r2=795498&view=diff ============================================================================== --- incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaVMOption.java (original) +++ incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.api/src/main/java/javax/tools/diagnostics/java/JavaVMOption.java Sun Jul 19 09:02:41 2009 @@ -18,10 +18,10 @@ import javax.tools.diagnostics.image.ImagePointer; /** - * This class models the JavaVMOption C structures passed to JNI_CreateJavaVM - * to create this VM. + * This class models the JavaVMOption C structures passed to the JNI invocation API entry point JNI_CreateJavaVM + * used to create a Java Virtual Machine. * - * Each JavaVMOption consists of two components: + * Each JavaVMOption consists of two components : *
    *
  1. an optionString string, used to identify the option.
    2. *
  2. an extraInfo pointer, used to pass additional information. This component is usually NULL.
    3. Added: incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/.classpath URL: http://svn.apache.org/viewvc/incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/.classpath?rev=795498&view=auto ============================================================================== --- incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/.classpath (added) +++ incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/.classpath Sun Jul 19 09:02:41 2009 @@ -0,0 +1,6 @@ + + + + + + Added: incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/.project URL: http://svn.apache.org/viewvc/incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/.project?rev=795498&view=auto ============================================================================== --- incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/.project (added) +++ incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/.project Sun Jul 19 09:02:41 2009 @@ -0,0 +1,23 @@ + + + kato.docs + + + + + + org.eclipse.jdt.core.javabuilder + + + + + org.maven.ide.eclipse.maven2Builder + + + + + + org.eclipse.jdt.core.javanature + org.maven.ide.eclipse.maven2Nature + + Added: incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/.settings/org.eclipse.jdt.core.prefs URL: http://svn.apache.org/viewvc/incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/.settings/org.eclipse.jdt.core.prefs?rev=795498&view=auto ============================================================================== --- incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/.settings/org.eclipse.jdt.core.prefs (added) +++ incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/.settings/org.eclipse.jdt.core.prefs Sun Jul 19 09:02:41 2009 @@ -0,0 +1,5 @@ +#Thu Jul 16 08:21:03 BST 2009 +eclipse.preferences.version=1 +org.eclipse.jdt.core.compiler.codegen.targetPlatform=1.6 +org.eclipse.jdt.core.compiler.compliance=1.6 +org.eclipse.jdt.core.compiler.source=1.6 Added: incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/.settings/org.maven.ide.eclipse.prefs URL: http://svn.apache.org/viewvc/incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/.settings/org.maven.ide.eclipse.prefs?rev=795498&view=auto ============================================================================== --- incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/.settings/org.maven.ide.eclipse.prefs (added) +++ incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/.settings/org.maven.ide.eclipse.prefs Sun Jul 19 09:02:41 2009 @@ -0,0 +1,9 @@ +#Thu Jul 16 08:21:03 BST 2009 +activeProfiles= +eclipse.preferences.version=1 +fullBuildGoals=process-test-resources +includeModules=false +resolveWorkspaceProjects=true +resourceFilterGoals=process-resources resources\:testResources +skipCompilerPlugin=true +version=1 Added: incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/pom.xml URL: http://svn.apache.org/viewvc/incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/pom.xml?rev=795498&view=auto ============================================================================== --- incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/pom.xml (added) +++ incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/pom.xml Sun Jul 19 09:02:41 2009 @@ -0,0 +1,99 @@ + + + kato + org.apache.kato + 0.0.1-SNAPSHOT + + 4.0.0 + org.apache.kato + kato.docs + pom + 0.0.1-SNAPSHOT + + + + + + org.apache.maven.plugins + maven-antrun-plugin + 1.3 + + + compile + compile + + + + + + + + + + + + + run + + + + + + ant + ant-trax + 1.6.5 + + + + + + + + + com.agilejava.docbkx + docbkx-maven-plugin + + + + + generate-pdf + + compile + + + + + org.docbook + docbook-xml + 4.4 + runtime + + + + true + true + true + src/docbkx/fo.xsl + + http://docbook.sourceforge.net/release/images/draft.png + + + + + + + + + + + org.apache.kato + kato.anttasks + 0.0.1-SNAPSHOT + + + + \ No newline at end of file Added: incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/src/ant/buildjavadoc.xml URL: http://svn.apache.org/viewvc/incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/src/ant/buildjavadoc.xml?rev=795498&view=auto ============================================================================== --- incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/src/ant/buildjavadoc.xml (added) +++ incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/src/ant/buildjavadoc.xml Sun Jul 19 09:02:41 2009 @@ -0,0 +1,63 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file Propchange: incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/src/ant/buildjavadoc.xml ------------------------------------------------------------------------------ svn:executable = * Added: incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/src/docbkx/chapters/API.xml URL: http://svn.apache.org/viewvc/incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/src/docbkx/chapters/API.xml?rev=795498&view=auto ============================================================================== --- incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/src/docbkx/chapters/API.xml (added) +++ incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/src/docbkx/chapters/API.xml Sun Jul 19 09:02:41 2009 @@ -0,0 +1,27 @@ + + + Using the Application Programming Interface + +
    + Structure + + JSR 326 consists of a series of packages that are separated into three logical groups + + + Common facilities and factory discovery + Java Runtime abstraction + Process abstraction + + +
    + + + +     \ No newline at end of file Added: incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/src/docbkx/chapters/Introduction.xml URL: http://svn.apache.org/viewvc/incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/src/docbkx/chapters/Introduction.xml?rev=795498&view=auto ============================================================================== --- incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/src/docbkx/chapters/Introduction.xml (added) +++ incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/src/docbkx/chapters/Introduction.xml Sun Jul 19 09:02:41 2009 @@ -0,0 +1,22 @@ + + + Introduction + +
    + What is JSR 326? + + Places to visit + + Kato Wiki + +
    + + +     \ No newline at end of file Added: incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/src/docbkx/fo.xsl URL: http://svn.apache.org/viewvc/incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/src/docbkx/fo.xsl?rev=795498&view=auto ============================================================================== --- incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/src/docbkx/fo.xsl (added) +++ incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/src/docbkx/fo.xsl Sun Jul 19 09:02:41 2009 @@ -0,0 +1,47 @@ + + + + + + + + + + + 0.5pt solid black + 0.5pt solid black + 6pt + 3pt + + + + + + pt + + + + + + + pt + + + + + + + pt + + + + + + Added: incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/src/docbkx/spec.xml URL: http://svn.apache.org/viewvc/incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/src/docbkx/spec.xml?rev=795498&view=auto ============================================================================== --- incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/src/docbkx/spec.xml (added) +++ incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/src/docbkx/spec.xml Sun Jul 19 09:02:41 2009 @@ -0,0 +1,55 @@ + + + + + JSR 326 Post mortem JVM Diagnostics API + Early Draft Review + + + + + + Apache Software Foundation + + + + + + licence goes here + + + + + + + + + + +Preface + +
    +Audience +
    +
    +Prerequisites +
    +
    +References +
    +
    +Related Documentation +
    +
    +How to comment on the specification +
    +     + + + + + +     \ No newline at end of file Added: incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/src/xslt/packagecontents.xslt URL: http://svn.apache.org/viewvc/incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/src/xslt/packagecontents.xslt?rev=795498&view=auto ============================================================================== --- incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/src/xslt/packagecontents.xslt (added) +++ incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/src/xslt/packagecontents.xslt Sun Jul 19 09:02:41 2009 @@ -0,0 +1,156 @@ + + + + + + + + API Reference + This chapter contains the details of the Java classes that comprise the API. + + + + + + + + + + + <xsl:value-of select="@name"/> +
    + +
    + + + + interfacelist. + + + + + + + + + + + + + + + + + + + + +
    Interface Summary
    NameSummary
    +     + + + + classlist. + + + + + + + + + + + + + + + + + +
    Class Summary
    NameSummary
    +     + + + + + + + Details + + + <xsl:value-of select="@name"/> +
    + + + Field + + + + + constructors. + + + + + + + + + + + + + + + + + +
    Constructor Summary
    SignatureSummary
    +     + + + methods. + + + + + + + + + + + + + + + + + + + + +
    Method Summary
    Return TypeSignatureSummary
    +     +     + +     +     +     + +     +     + +     + +     + + +     \ No newline at end of file Added: incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/src/xslt/packagelist.xslt URL: http://svn.apache.org/viewvc/incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/src/xslt/packagelist.xslt?rev=795498&view=auto ============================================================================== --- incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/src/xslt/packagelist.xslt (added) +++ incubator/kato/branches/experimental/maven_restructure/org.apache.kato/kato.docs/src/xslt/packagelist.xslt Sun Jul 19 09:02:41 2009 @@ -0,0 +1,44 @@ + + + + + + + + + Packages + + + + + + Name + Title + + + + + + + + para> + + + + + + +
    +     + + +     + + +     \ No newline at end of file Modified: incubator/kato/branches/experimental/maven_restructure/org.apache.kato/pom.xml URL: http://svn.apache.org/viewvc/incubator/kato/branches/experimental/maven_restructure/org.apache.kato/pom.xml?rev=795498&r1=795497&r2=795498&view=diff ============================================================================== --- incubator/kato/branches/experimental/maven_restructure/org.apache.kato/pom.xml (original) +++ incubator/kato/branches/experimental/maven_restructure/org.apache.kato/pom.xml Sun Jul 19 09:02:41 2009 @@ -19,6 +19,7 @@ kato.demo.tomcat kato.anttasks kato.tck.testsuite + kato.docs