incubator-kato-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From monte...@apache.org
Subject svn commit: r803617 - /incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/API.xml
Date Wed, 12 Aug 2009 17:25:38 GMT
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&lt;ManagedRuntime&gt; 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&lt;ImageSection&gt;
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&lt;JavaObject&gt; 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>



Mime
View raw message