Author: monteith
Date: Tue Aug 18 16:02:37 2009
New Revision: 805473
URL: http://svn.apache.org/viewvc?rev=805473&view=rev
Log:
Split out examples from API.xml. Add two examples.
Added:
incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/examples.xml (with
props)
Modified:
incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/API.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=805473&r1=805472&r2=805473&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 Tue Aug 18
16:02:37 2009
@@ -138,9 +138,5 @@
</sect1>
<xi:include href="principles.xml" />
-
-
- <sect1 xml:id="api.examples">
- <title>Examples</title>
- </sect1>
+ <xi:include href="examples.xml" />
</chapter>
Added: 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=805473&view=auto
==============================================================================
--- incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/examples.xml (added)
+++ incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/examples.xml Tue Aug
18 16:02:37 2009
@@ -0,0 +1,233 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<sect1 xml:id="api.examples" version="5.0"
+ xmlns="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns:mml="http://www.w3.org/1998/Math/MathML"
+ xmlns:html="http://www.w3.org/1999/xhtml"
+ xmlns:db="http://docbook.org/ns/docbook">
+ <title>Examples</title>
+ <sect2 xml:id="api.examples.intro">
+ <title>Introduction</title>
+ <para>
+ This section contains annotated examples to demonstrate some simple tasks and show how the
API
+ should be called.
+ </para>
+ </sect2>
+
+ <sect2 xml:id="api.examples.open">
+ <title>Opening Images</title>
+ <para><classname>Image</classname> instances are obtained using the <classname>javax.tools.diagnostics.FactoryRegistry</classname>
class.
+ </para>
+ <para>
+ Programs using the API can obtain an Image like so:
+
+ <example xml:id="api.examples.open.getimage">
+ <title>Opening an Image</title>
+ <programlisting>
+ <![CDATA[
+ Image image = FactoryRegistry.getDefaultRegistry().
+ getImage(new File("example.file"));
+ ]]>
+ </programlisting>
+ </example>
+
+ </para>
+
+ <para>
+ <classname>FactoryRegistry</classname> uses
+ <link xlink:href="http://java.sun.com/javase/6/docs/api/javax/imageio/spi/ServiceRegistry.html">javax.imageio.spi.ServiceRegistry</link>
+ 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
+ the name of the ImageFactory implementation, such as
+ <programlisting>javax.tools.diagnostics.hprof.image.ImageFactoryImpl</programlisting>
+ </para>
+ </sect2>
+
+ <sect2 xml:id="api.examples.cause">
+ <title>Determining Snapshot Cause</title>
+ <para>
+ Snapshots can be generated for a variety of reasons. The API can report when a snapshot
is generated when the
+ JVM receives a POSIX type signal, whether that be synchronous or asynchronous.
+ For example, if a JNI library causes a <code>SIGSEGV</code> when running, this
might be detectable
+ through the API. In most cases, it should be possible through <methodname>ImageAddressSpace.getCurrentProcess()</methodname>
+ and <methodname>ImageProcess.getCurrentThread()</methodname> to determine which
process and which thread caused
+ the snapshot.
+ </para>
+
+ <para>
+ If a snapshot was generated for a reason other than a POSIX signal being received, then
the reason
+ has to be derived through knowledge of the JVM implementation. For example, if an option
was passed to
+ the JVM to generate a snapshot on entry to a particular method, all of the stack traces
could be searched
+ to determine if that method was present, and therefore probably causing the snapshot.
+ </para>
+
+ <para>
+ Here is an example of how to determine the cause of a snapshot.
+ </para>
+ <para>
+ First of all, there are the declarations. This implements a method in an interface that
expects
+ to simply be passed an <classname>Image</classname>.
+<example xml:id="api.examples.cause.class">
+<title>CauseAnalyzer Class declaration</title>
+<programlisting>
+<![CDATA[
+package org.apache.kato.examples;
+
+import javax.tools.diagnostics.image.CorruptDataException;
+import javax.tools.diagnostics.image.DataUnavailable;
+import javax.tools.diagnostics.image.Image;
+import javax.tools.diagnostics.image.ImageAddressSpace;
+import javax.tools.diagnostics.image.ImageProcess;
+import javax.tools.diagnostics.image.ImageStackFrame;
+import javax.tools.diagnostics.image.ImageThread;
+import javax.tools.diagnostics.runtime.ManagedRuntime;
+import javax.tools.diagnostics.runtime.java.JavaRuntime;
+import javax.tools.diagnostics.runtime.java.JavaStackFrame;
+import javax.tools.diagnostics.runtime.java.JavaThread;
+
+/**
+ * This analyzer determines what process and thread
+ * caused the snapshot, and what signal, if any.
+ *
+ */
+public class CauseAnalyzer implements ImageAnalyzer {
+
+ @Override
+ public void analyze(Image image) {
+]]>
+</programlisting>
+</example>
+Next, the containing <classname>ImageAddressSpace</classname> instances are searched
for a current process.
+It is probable that there will be one address space and one process. Note the use of <code>for</code>.
+<example xml:id="api.examples.cause.cuurentprocess">
+<title>Find Current Process</title>
+<programlisting>
+<![CDATA[
+
+ for (ImageAddressSpace as : image.getAddressSpaces()) {
+ ImageProcess process = as.getCurrentProcess();
+
+ // Only invoked if there is a "current" process,
+ // This is a process that caused the snapshot to occur.
+ if (process != null) {
+ try {
+]]>
+</programlisting>
+</example>
+
+Once found, the process can be queried for signal information and thread information.
+If a signal was raised, <methodname>ImageProcess.getSignalName()</methodname>
will not be null.
+The example reports this to the user, along with the number.
+
+<example xml:id="api.examples.cause.signalinfo">
+<title>Reporting signal information</title>
+<programlisting>
+<![CDATA[
+ int signum = process.getSignalNumber();
+ String signame = process.getSignalName();
+
+ // Identify the process by number and command line.
+ System.out.println("Process "+process.getID()+
+ " was started with `" +
+ process.getCommandLine()+"'");
+
+ // The signals that cause the snapshot to be generated
+ if (signame != null) {
+ System.out.println("Snapshot caused by signal " + signame+"("+signum+")");
+ }
+]]>
+</programlisting>
+</example>
+
+The program determines which thread caused the snapshot to be generated.
+If one is found, the thread is identified by ID and its properties (implementation dependent).
+
+<example xml:id="api.examples.cause.threadid">
+<title>Thread identification</title>
+<programlisting>
+<![CDATA[
+ ImageThread thread = process.getCurrentThread();
+ // Identify the thread, by id, various properties and a stack trace.
+ if (thread != null) {
+ System.out.println("\nSnapshot caused by thread "+
+ thread.getID()+
+ ", "+thread.getProperties());
+]]>
+</programlisting>
+</example>
+
+Next, the thread's stack frames are printed out. The example relies on
+<methodname>java.lang.Object.toString()</methodname> being implemented correctly.
+
+<example xml:id="api.examples.cause.stacktrace">
+<title>ImageThread stack trace</title>
+<programlisting>
+<![CDATA[
+
+ for(ImageStackFrame frame: thread.getStackFrames()) {
+ System.out.println("\t" + frame);
+ }
+]]>
+</programlisting>
+</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
+have to be queried. As <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.
+
+<example xml:id="api.examples.cause.imagejavathread">
+<title>JavaThread/ImageThread correlation</title>
+<programlisting>
+<![CDATA[
+ // Find JavaThread and then do stacktrace.
+RUNTIME: for(ManagedRuntime runtime : process.getRuntimes() ) {
+ if (runtime instanceof JavaRuntime) {
+ JavaRuntime jr = (JavaRuntime) runtime;
+
+ for(JavaThread jthread : jr.getThreads()) {
+ if (thread.equals(jthread.getImageThread())) {
+ System.out.println("\nSnapshot caused by JavaThread "+
+ jthread.getName());
+
+ for(JavaStackFrame frame : jthread.getStackFrames()) {
+ System.out.println("\t" + frame);
+ }
+ break RUNTIME;
+ }
+ }
+ }
+ }
+ }
+]]>
+</programlisting>
+</example>
+Here is the end of the definition of the class. In order to reduce the size of the example,
+the exceptions are handled outside of the API calls.
+<example xml:id="api.examples.cause.exceptions">
+<title>Exceptions</title>
+<programlisting>
+<![CDATA[
+ } catch (DataUnavailable e) {
+ e.printStackTrace();
+ } catch (CorruptDataException e) {
+ e.printStackTrace();
+ }
+ }
+ }
+ }
+}
+
+]]>
+</programlisting>
+</example>
+
+ </para>
+ </sect2>
+</sect1>
\ No newline at end of file
Propchange: incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/examples.xml
------------------------------------------------------------------------------
svn:mime-type = text/plain
|