incubator-kato-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From spo...@apache.org
Subject svn commit: r806529 - in /incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters: API.xml examples.xml principles.xml
Date Fri, 21 Aug 2009 12:39:30 GMT
Author: spoole
Date: Fri Aug 21 12:39:30 2009
New Revision: 806529

URL: http://svn.apache.org/viewvc?rev=806529&view=rev
Log:
final small tweeks to doc 

Modified:
    incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/API.xml
    incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/examples.xml
    incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/principles.xml

Modified: incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/API.xml
URL: http://svn.apache.org/viewvc/incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/API.xml?rev=806529&r1=806528&r2=806529&view=diff
==============================================================================
--- incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/API.xml (original)
+++ incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/API.xml Fri Aug 21
12:39:30 2009
@@ -7,22 +7,7 @@
 
 	<sect1 xml:id="api.introduction">
 	<title>Introduction</title>
-	<para>This chapter describes the behaviour and structure of the API. Developers who
are implementing
-	the API or writing programs that use the API should read this.
-	</para>
-	<para>
-	The chapter is structured as follows:
-	<itemizedlist>
-		<listitem>
-			<para>First, the overall structure of the API is explained.</para>
-		</listitem>
-		<listitem>
-			<para>Secondly, the fundamental principles of the API are explained.</para>
-		</listitem>		
-		<listitem>
-			<para>Lastly, there are examples of how to call the API.</para>
-		</listitem>
-	</itemizedlist>
+	<para>This chapter describes the conceptual behaviour and structure of the API
 	</para>
 	</sect1>
 

Modified: incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/examples.xml
URL: http://svn.apache.org/viewvc/incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/examples.xml?rev=806529&r1=806528&r2=806529&view=diff
==============================================================================
--- incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/examples.xml (original)
+++ incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/examples.xml Fri Aug
21 12:39:30 2009
@@ -68,10 +68,11 @@
 	by a synchronous SIGABRT. 
 	</para>
 	
-	<para>
+	<para><emphasis>
 	The following examples are extracts from the example program in <xref linkend="appendix.causeexample"/>.
+	</emphasis>
 	</para>
-
+	<para/>
 	The examples implement the <classname>ImageAnalyzer</classname> interface, they
just need to implement
 	the <methodname>analyze(Image)</methodname> method. 
 <example xml:id="api.examples.cause.class">
@@ -172,8 +173,8 @@
 </example>
 
 This section of code relies on the relationship between <classname>JavaThread</classname>
instances
-and <classname>ImageThread</classname> instances to determine which Java thread
caused the snapshot.
-As the relationship is one-way, from Java to Image, all of the <classname>JavaThread</classname>
instances
+and <classname>ImageThread</classname> instances to determine which Java<superscript>tm</superscript>
thread caused the snapshot.
+As the relationship is one-way, from Java<superscript>tm</superscript> to Image,
all of the <classname>JavaThread</classname> instances
 have to be queried. Because <methodname>JavaThread.getImageThread()</methodname>
might be <code>null</code>,
 <methodname>java.lang.Object.equals</methodname> is executed against the <classname>ImageThread</classname>
 which we know to be not null. Once the <classname>JavaThread</classname> is found,
it's name can be
@@ -206,7 +207,7 @@
 	
 	
 	<sect2 xml:id="api.examples.what">
-	<title>Identifying Java VM</title>
+	<title>Identifying Java<superscript>tm</superscript> VM</title>
 	<para>
 	This example demonstrates how the JVM that generated a snapshot might be identifyed. The
following information
 	is reported using the image and java APIs:
@@ -214,7 +215,7 @@
 	<listitem><para>hostname of the machine the snapshot was generated on.</para></listitem>
 	<listitem><para>The process ID.</para></listitem>
 	<listitem><para>The command line.</para></listitem>
-	<listitem><para>The executable that was running the Java program (e.g. "/usr/bin/java").</para></listitem>
+	<listitem><para>The executable that was running the Java<superscript>tm</superscript>
program (e.g. "/usr/bin/java").</para></listitem>
 	<listitem><para>The command line.</para></listitem>
 	<listitem><para>The loaded native libraries.</para></listitem>
 	<listitem><para>The version reported by the JVM.</para></listitem>
@@ -300,12 +301,12 @@
 </programlisting>
 </example>
 
-The following code reports the Java VM version. This is implementation dependent,
-but is expected to contain more than just the version of Java that is supported, but
+The following code reports the Java<superscript>tm</superscript> VM version.
This is implementation dependent,
+but is expected to contain more than just the version of Java<superscript>tm</superscript>
that is supported, but
 actually identify which implementation of the JVM it is.
 
 <example xml:id="api.examples.what.version">
-<title>Java VM Version</title>
+<title>Java<superscript>tm</superscript> VM Version</title>
 <programlisting>
 <![CDATA[
 	public void analyzeRuntime(JavaRuntime jr) {		
@@ -325,7 +326,7 @@
 options taken in from configuration files, as well as being generated by the launcher itself.
 			
 <example xml:id="api.examples.what.options">
-<title>Java VM Options</title>
+<title>Java<superscript>tm</superscript> VM Options</title>
 <programlisting>
 <![CDATA[
 		System.out.println("VM options:");
@@ -356,7 +357,7 @@
 	</para>
 	<para>
 	The <methodname>analyzeRuntime</methodname> method walks over the heaps within
the JVM.
-While Java programmers will be used to the concept of the heap, the API allows a number
+While Java<superscript>tm</superscript> programmers will be used to the concept
of the heap, the API allows a number
 of heaps to be accessed in a single JVM. It is expected the different heaps will have 
 different garbage collection policies and that each heap will be identified with a
 descriptive name through <methodname>JavaHeap.getName()</methodname>. The number
of
@@ -466,7 +467,7 @@
 
 <para>
 This code retrieves each field from a <classname>JavaClass</classname>.
-This is equivalent to the following method in Java reflection:
+This is equivalent to the following method in Java<superscript>tm</superscript>
reflection:
 <programlisting>
 Field[] java.lang.Class.getDeclaredFields()
 </programlisting>
@@ -617,7 +618,7 @@
 </example>		
 
 <para>
-The following code tests the object type to see if it is a Java String instance. 
+The following code tests the object type to see if it is a Java<superscript>tm</superscript>
String instance. 
 The <classname>JavaClass</classname> representing <classname>java.lang.String</classname>
could be cached
 and compared against the objects classes, but instead we compare against the name of the
object's class.
 The method <methodname>JavaField.getString()</methodname> is used to retrieve
the <classname>JavaObject</classname>
@@ -711,7 +712,7 @@
 their contents are copied to real arrays.
 This code demonstrates that there are <classname>JavaClass</classname> for
 primitive types, in the same way there is in reflection. These names
-are used to create primitive arrays of the correct type. Java reflection
+are used to create primitive arrays of the correct type. Java<superscript>tm</superscript>
reflection
 functions in the same way.
 </para>
 

Modified: incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/principles.xml
URL: http://svn.apache.org/viewvc/incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/principles.xml?rev=806529&r1=806528&r2=806529&view=diff
==============================================================================
--- incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/principles.xml (original)
+++ incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/principles.xml Fri
Aug 21 12:39:30 2009
@@ -224,23 +224,23 @@
 		<sect2 xml:id="api.principles.faked">
 		<title>Faked objects</title>
 		<para>
-		The possible implementations of the Java Virtual Machine can have various optimisations
that corresponding
-		implementations of this API will have to compensate for. This may require the creation
of things that 
-		don't actually exist in the snapshot.
+		There are many possible implementations of a Java<superscript>tm</superscript>
Virtual Machine each of which can have various and different optimisations.
+		Mapping a particular implementation to this API may require the creation of synthetic objects
for entities which do not 
+		actually exist in the diagnostic artifact.
 		</para>
-		<para>An example of this would be the array classes. These classes
-		are never loaded by a Java Virtual Machine, they are constructed as and when they are necessary.

+		<para>An example of this would be array classes. These classes
+		are never loaded by a Java<superscript>tm</superscript> Virtual Machine, they
are constructed as and when they are necessary. 
 		It is conceivable that there would be no actual entities that could directly correspond
with <classname>JavaClass</classname>
 		instances. In circumstances like these the API implementor would have to create a <classname>JavaClass</classname>
 		for the array class, as that is the only means the API has for identifying that objects
type.  
 		</para>
 		<para>
-		Faked objects should be implemented carefully. If a faked <classname>JavaMethod</classname>
is created,
-		then the class it declares itself as belonging to should report it, for instance. Otherwise
inconsistencies
-		can arise that could cause calling programs to fail. Also, there should be no collisions
between real
-		and faked objects.
-		However, implementations should not be misleading. If a faked object has been created,
don't report it
-		as having any <classname>ImageSection</classname> instances, because it never
will. 
+		Faked objects should be implemented carefully. For instance, if a faked <classname>JavaMethod</classname>
is created,
+		then the class it declares itself as belonging to should report it, otherwise inconsistencies
+		can arise that could cause calling programs to fail.</para>
+		<para>There should be no collisions between real and faked objects.</para>

+		<para>Implementations should not be misleading. If a faked object has been created,
then related fack objects should be kept to a minimum. 
+		For instance a faked <classname>JavaObject</classname> should not return <classname>ImageSection</classname>
instances. 
 		</para>
 		</sect2>
 		
@@ -248,9 +248,10 @@
 		<title>Object identities</title>
 		<para>
 		All implementations should override the <code>java.lang.Object.equals(Object)</code>
method.
-		All API's should use <methodname>equals</methodname> to test object identity.
As it is not expected
-		for implementations to store every object it returns, the recreation of already requested
objects
-		is allowed. 
+		All API's should use <methodname>equals</methodname> to test object identity.
</para>
+		<para>The quantity of objects held within a diagnostic artifact normally means that
it is impractical to keep an in-memory
+		instance for everything.  Therefore the API does not require that repeated calls to return
a specific object will in fact return the same instance.
+		<emphasis>The API allows for recreation of already requested objects</emphasis>
 		</para>
 		<para>
 		The behaviour of <methodname>equals</methodname> against objects from different
snapshots is not



Mime
View raw message