Author: monteith
Date: Wed Aug 12 17:25:38 2009
New Revision: 803617
URL: http://svn.apache.org/viewvc?rev=803617&view=rev
Log:
Add section on API principles.
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=803617&r1=803616&r2=803617&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 Wed Aug 12
17:25:38 2009
@@ -5,6 +5,27 @@
xmlns:html="http://www.w3.org/1999/xhtml" xmlns:db="http://docbook.org/ns/docbook">
<title>Using the Application Programming Interface</title>
+ <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, some examples are given to show how some tasks are performed with
the API.</para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </sect1>
+
<sect1 xml:id="api.structure">
<title>Structure</title>
@@ -115,6 +136,163 @@
</sect2>
</sect1>
-
-</chapter>
\ No newline at end of file
+ <sect1 xml:id="api.principles">
+ <title>Principles</title>
+ <sect2>
+ <title>Introduction</title>
+ <para>
+ This section describes the principles that are common across the whole API.
+ </para>
+ </sect2>
+ <sect2>
+ <title>Lists</title>
+ <para>
+ The API is mostly arranged as a hierarchy. Each object will using "contain" multiple
+ other objects and the <classname>java.util.List</classname> interface is used
to access them.
+ </para>
+ <para>
+ For example, an <classname>ImageProcess</classname> may contain multiple instances
of <classname>ManagedRuntime</classname>.
+ To retrieve the <classname>ManagedRuntime</classname> instances, a call would
be made to:
+ <code>List<ManagedRuntime> ImageProcess.getRuntimes()</code>.
+ </para>
+ </sect2>
+ <sect2>
+ <title>Type names</title>
+ <para>
+ Types names and signatures use the same format as in JNI. Please see the relevant JavaDoc
for each
+ relevant method.
+ </para>
+ <para>
+ Here are some examples.
+ The class <classname>java.util.Map.entry</classname> would be formatted like
so:
+ <programlisting>
+ java/util/Map$Entry
+ </programlisting>
+ An multidimensional array <classname>java.util.Map.entry[][]</classname> is
formatted like:
+ <programlisting>
+ [[Ljava/util/Map$Entry;
+ </programlisting>
+ A primitive array class for <code>int[][]</code> is formatted like so:
+ <programlisting>
+ [[I
+ </programlisting>
+ </para>
+ </sect2>
+ <sect2>
+ <title>Memory and Identification</title>
+ <para>
+ Memory in the API consists of a series flat (i.e. not segmented) address spaces represented
by the <classname>ImageAddressSpace</classname>
+ class. These address spaces are as large as the pointer size of the process the snapshot
was generated from.
+ Areas of addressable memory in the dump are represented by <classname>ImageSection</classname>
instances
+ that describe a beginning address and a size. Addresses are represented by <classname>ImagePointer</classname>
+ instances. They are used for retrieving values from the dump. They are also used to uniquely
identify
+ the entities the API class represent. For example, each <classname>JavaClass</classname>
is located
+ and identified in memory using the <code>ImagePointer JavaClass.getID()</code>
call. Most API interfaces
+ have a <methodname>getID()</methodname> method.
+ </para>
+ <para>
+ All values retrieved by <classname>ImagePointer</classname> are corrected
for endianness before being
+ returned as Java types. All Java types (apart from <code>char</code>) are
signed. Pointers themselves
+ are held in signed 64 bit longs. After endianness conversion, floating point values are
assumed to be
+ in Java's floating point format, rather than whatever native format there may be.
+ </para>
+ <para>
+ It is not expected that all implementation of the API will be able to present memory from
the address
+ spaces. In such instances, the <methodname>getID()</methodname> is expected
to return an <classname>ImagePointer</classname> that
+ can report an address, but not return any memory contents.
+ </para>
+ <para>
+ <classname>ImageSection</classname> instances are used to describe the memory
layout of the constructs that
+ the API interfaces represent. This is normally done with methods like <code>List<ImageSection>
getSections()</code>.
+ The actual <classname>ImageSection</classname> instances returned are implementation
specific and
+ it is acceptable for there to be none. It is expected that they will be used for:
+ <itemizedlist>
+ <listitem><para>
+ determining the memory occupancy of items. For example, the heap from <code>JavaHeap.getSections</code>.
+ </para></listitem>
+ <listitem><para>
+ accessing structures in memory. For example, <code>JavaObject.getSections()</code>
will return
+ all of the <classname>ImageSection</classname> instances representing a JavaObject.
With knowledge
+ of how an object is laid out on the heap, it would be possible to retrieve more information
than
+ is retrieved by the API.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>Package Separation</title>
+ <para>
+ While aspects of the <code>image</code> API are used by the <code>runtime.java</code>
API, the reverse
+ will never occur. The <code>image</code> API should, in principle, be implementable
standalone.
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>Error Handling</title>
+ <para>
+ Implementations of the API should present data as accurate and complete as reasonably
possible under any circumstances. The purpose of the
+ API includes presenting the state of a running process, a Java Virtual Machine, when it
encountered
+ abnormal conditions. The most extreme of these situations is when the native code implementing
the JVM
+ itself has crashed. As such, there will be situations where information cannot be retrieved
or may be incorrect.
+ This should be regarded as normal. Both implementors of the API and those calling the
API should code
+ anticipating errors to be normal rather than exceptional conditions.
+ </para>
+ <para>
+ Data is retrieved from the API from two types of methods. Those returning multiple items
using
+ generisised Lists and those returning items directly.
+ The lists that are returned are expected to return all items that they can.
+ </para>
+ <para>
+ When implementing lists, implementors should take care to:
+ <itemizedlist>
+ <listitem><para>
+ ensure that lists have a finite number of items. For example, a corrupted linked list
+ may be corrupt or terminated incorrectly. The API implementation should detect this and
+ terminate the list.
+ </para></listitem>
+
+ <listitem><para>
+ process as little of the items being returned as possible. Better to continue reading
the
+ collection of items rather than fail on one item that is slightly wrong. For example,
+ if the objects are being retrieved using the list from the following method call:
+ <programlisting>
+ List<JavaObject> JavaHeap.getObjects()
+ </programlisting>
+ ... then if one object fails to identify it's 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>.
+ </para></listitem>
+ </itemizedlist>
+ </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>.
+ The exceptions are:
+ <itemizedlist>
+ <listitem><para>
+ <classname>MemoryAccessException</classname>. This is thrown when an attempt
has been
+ made to access memory that is not present in the snapshot.
+ </para></listitem>
+ <listitem><para>
+ <classname>CorruptDataException</classname>. This is thrown when the data
used to
+ form a response to the method call is incorrect.
+ </para></listitem>
+ </itemizedlist>
+ </para>
+ </sect2>
+
+ <sect2>
+ <title>Optional and missing data</title>
+ <para>
+
+ </para>
+ </sect2>
+ </sect1>
+
+ <sect1 xml:id="api.examples">
+ <title>Examples</title>
+ </sect1>
+</chapter>
|