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 mo...@apache.org on 2009/09/04 17:17:52 UTC
svn commit: r811497 - in
/incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters:
Introduction.xml examples.xml principles.xml
Author: monteith
Date: Fri Sep 4 17:17:51 2009
New Revision: 811497
URL: http://svn.apache.org/viewvc?rev=811497&view=rev
Log:
Fix some wording and spelling errors in EDR, courtesy of Andrew Johnson's review.
Modified:
incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/Introduction.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/Introduction.xml
URL: http://svn.apache.org/viewvc/incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/Introduction.xml?rev=811497&r1=811496&r2=811497&view=diff
==============================================================================
--- incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/Introduction.xml (original)
+++ incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/Introduction.xml Fri Sep 4 17:17:51 2009
@@ -7,7 +7,7 @@
<section xml:id="introduction.jsr326">
<title>What is JSR 326?</title>
- <para>JSR 326 is intended to be a Java<superscript>tm</superscript> API specification for
+ <para>JSR 326 is intended to be a Java<superscript>TM</superscript> API specification for
standardising how and what can be retrieved from the contents of
post-mortem artefacts -
typically process and JVM dumps.</para>
@@ -34,7 +34,7 @@
create a common, cross industry API, and we can't think of a better
place to do that than in Apache.</para>
<para>
- IBM developed an API called DTFJ ("Diagnostic Tooling and
+ IBM developed an API called DTFJ ("Diagnostic Tool
Framework for
Java") as a means of providing its support teams a basis
on which to
@@ -44,7 +44,7 @@
API, which
was written in pure Java.
</para>
- <para>In 2009 IBM donated the implementation dependent portions of
+ <para>In 2009 IBM donated the implementation independent portions of
DTFJ to the Apache Kato project</para>
</section>
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=811497&r1=811496&r2=811497&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 Sep 4 17:17:51 2009
@@ -42,9 +42,9 @@
as a registry of all API implementations known to the JVM.
Implementors should ensure that <classname>FactoryRegistry</classname> is able to see their
<classname>ImageFactory</classname> by placing their implementation in a jar file that contains a file
- called <filename>META-INF/org.apache.kato.ImageFactory</filename> that contains a line of text that is
+ called <filename>META-INF/javax.tools.diagnostics.image.ImageFactory</filename> that contains a line of text that is
the name of the ImageFactory implementation, such as
- <programlisting>javax.tools.diagnostics.hprof.image.ImageFactoryImpl</programlisting>
+ <programlisting>com.example.dump.ImageFactoryImpl</programlisting>
</para>
</sect2>
@@ -177,7 +177,7 @@
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
+which we know to be not null. Once the <classname>JavaThread</classname> is found, its name can be
printed.
<example xml:id="api.examples.cause.imagejavathread">
@@ -209,7 +209,7 @@
<sect2 xml:id="api.examples.what">
<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
+ This example demonstrates how the JVM that generated a snapshot might be identified. The following information
is reported using the image and java APIs:
<itemizedlist>
<listitem><para>hostname of the machine the snapshot was generated on.</para></listitem>
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=811497&r1=811496&r2=811497&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 Sep 4 17:17:51 2009
@@ -18,7 +18,7 @@
<title>Lists</title>
<para>
Methods use <classname>java.util.List</classname> to return multiple objects.
- All lists are unmodifiable and unsynchronised.
+ All lists are immutable and unsynchronised.
</para>
<para>
For example, an <classname>ImageProcess</classname> may contain multiple instances of <classname>ManagedRuntime</classname>.
@@ -175,7 +175,7 @@
<programlisting>
List<JavaObject> JavaHeap.getObjects()
</programlisting>
- ... then if one object fails to identify it's type properly, it
+ ... then if one object fails to identify its type properly, it
is expected that the list would return the <classname>JavaObject</classname>. Calls
to that <classname>JavaObject</classname> would fail appropriately, such as to
<code>JavaClass JavaObject.getJavaClass()</code>.
@@ -184,7 +184,7 @@
</para>
<para>
Errors are reported on methods returning single items (i.e. not lists) using exceptions.
- There are two exceptions, both subclasses of <classname>KatoException</classname>.
+ There are two exceptions, both subclasses of <classname>DiagnosticException</classname>.
The exceptions are:
<itemizedlist>
<listitem><para>
@@ -212,19 +212,19 @@
be explicitly documented in the Javadoc.
</para>
<para>
- <classname>DataUnavailable</classname> is thrown when the API <emphasis>cannnot</emphasis> return
+ <classname>DataUnavailable</classname> is thrown when the API <emphasis>cannot</emphasis> return
the requested data. <code>null</code> is returned when the data was never there to be returned.
</para>
<para>
Methods that return <classname>java.util.List</classname> instances will always do so under all
- circumstances. When
+ circumstances.
</para>
</sect2>
<sect2 xml:id="api.principles.faked">
<title>Faked objects</title>
<para>
- There are many possible implementations of a Java<superscript>tm</superscript> Virtual Machine each of which can have various and different optimisations.
+ 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>
@@ -247,7 +247,8 @@
<sect2 xml:id="api.principles.identity">
<title>Object identities</title>
<para>
- All implementations should override the <code>java.lang.Object.equals(Object)</code> method.
+ All implementations should override the <code>java.lang.Object.equals(Object)</code> method when objects are not permanently cached
+ and may need to be recreated.
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.