incubator-kato-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From monte...@apache.org
Subject svn commit: r804275 - in /incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters: API.xml principles.xml
Date Fri, 14 Aug 2009 16:04:34 GMT
Author: monteith
Date: Fri Aug 14 16:04:33 2009
New Revision: 804275

URL: http://svn.apache.org/viewvc?rev=804275&view=rev
Log:
Separate principles section, some rewrites and corrections.

Added:
    incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/principles.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=804275&r1=804274&r2=804275&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 14
16:04:33 2009
@@ -20,7 +20,7 @@
 			<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>
+			<para>Lastly, there are examples of how to call the API.</para>
 		</listitem>
 	</itemizedlist>
 	</para>
@@ -137,209 +137,8 @@
 		</sect2>
 	</sect1>
 
-	<sect1 xml:id="api.principles">
-		<title>Principles</title>
-		<sect2 xml:id="api.principles.intro">
-			<title>Introduction</title>
-			<para>
-			This section describes the principles that are common across the whole API.  
-			</para>
-		</sect2>
-		<sect2 xml:id="api.principles.lists">
-			<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>
-			<para>
-			All lists are unmodifiable.
-			</para>
-		</sect2>
-		<sect2 xml:id="api.principles.typenames">
-			<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 xml:id="api.principles.memory">
-			<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 xml:id="api.principles.packages">
-		<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. 
-		For example, the following is allowed as it refers to the image package:
-		<programlisting>
-		ImageThread JavaThread.getImageThread()
-		</programlisting>
-		But the converse is not:
-		<programlisting>
-		JavaThread ImageThread.getJavaThread()
-		</programlisting>
-		</para>
-		</sect2>
-		
-		<sect2 xml:id="api.principles.errors">
-			<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 xml:id="api.principles.optional">
-		<title>Optional and missing data</title>
-		<para>
-		There are circumstances where information cannot be supplied. 
-		Methods that throw the exception <classname>DataUnavailable</classname> will
do so if the
-		information is either not presentable by the implmentation of the API, or if it is not
available
-		for that particular snapshot.
-		</para>
-		<para>
-		There are circumstances where <code>null</code> is returned by a method. These
circumstances will 
-		be explicitly documented in the Javadoc.	
-		</para>
-		<para>
-		<classname>DataUnavailable</classname> is thrown when the API <emphasis>cannnot</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 
-		</para>
-		</sect2>
-		
-		<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.
-		</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.

-		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. 
-		</para>
-		</sect2>
-	</sect1>
+	<xi:include href="principles.xml" />
+	
 		
 	<sect1 xml:id="api.examples">
 		<title>Examples</title>

Added: 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=804275&view=auto
==============================================================================
--- incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/principles.xml (added)
+++ incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/principles.xml Fri
Aug 14 16:04:33 2009
@@ -0,0 +1,260 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<sect1 xml:id="api.principles" 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>Principles</title>
+		<sect2 xml:id="api.principles.intro">
+			<title>Introduction</title>
+			<para>
+			This section describes the principles that are common across the whole API.  
+			</para>
+		</sect2>
+		<sect2 xml:id="api.principles.lists">
+			<title>Lists</title>
+			<para>
+			Methods use <classname>java.util.List</classname> to return multiple objects.

+			All lists are unmodifiable and unsynchronised.
+			</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>
+			<para>
+			Lists are sometimes used in the API to access a larger number of objects than would be
used in most
+			Java applications.
+			For this reason, use of the 
+			<code>java.util.List.toArray()</code> method is discouraged in situations
where there would be a large number of array elements.
+			For example:
+			<programlisting>
+			JavaObject[] heapAsArray(JavaHeap heap) {
+				return heap.getObjects().toArray(new JavaObject[0]);
+			}			
+			</programlisting>
+			would return an array with all of the objects in the heap, perhaps numbering in the hundreds
of millions.
+			This should be considered when implementing or calling the API.
+			</para>
+		</sect2>
+		
+		<sect2 xml:id="api.principles.typenames">
+			<title>Type names</title>
+			<para>
+			Type names and signatures use the same format as JNI. Please see the JavaDoc for each

+			method for the exact formats.
+			</para>			
+			<para>
+			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 xml:id="api.principles.memory">
+			<title>Memory and Identification</title>
+			<sect3>
+			<title>Address space</title>
+			<para>
+			Memory in the API consists of a collection of flat (i.e. not segmented) address spaces
represented by the 
+			<classname>ImageAddressSpace</classname> class. Implementations do not have
to report any memory as being present
+			in the snapshot.
+			</para>
+			</sect3>
+			
+			<sect3>
+			<title>Memory sections</title>
+			<para>
+			The <classname>ImageSection</classname> interface is used to describe arbitrary
areas of memory by returning
+			a pointer (represented by a <classname>ImagePointer</classname> instance)
and a size along with an optional name.
+			<classname>ImageAddressSpace</classname> instances use them to describe what
memory is mapped in a snapshot.  
+			They are also used to describe the memory layout of the entities that
+			the API interfaces represent. This is normally done with methods such as <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 size could be derived
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> instance representing the
memory a 
+				<classname>JavaObject</classname> occupies. With knowledge
+				of how an object is laid out on the heap, it would be possible to retrieve more information
than
+				is retrieved presented by the API.
+				</para></listitem>
+			</itemizedlist>						
+			</para>
+		
+			</sect3>
+			
+			<sect3>
+			<title>Addresses and Identification</title>
+			<para>
+			The API uses the <classname>ImagePointer</classname> interface to identify
objects returned by the API.
+			<classname>ImagePointer</classname> represents an address in memory, and enables
programs to access memory
+			at that address and at offsets from that address. Given that not all implementations of
the API allow access to
+			memory, the addresses returned could be entirely artificial.
+			</para>
+			<para>When an <classname>ImagePointer</classname> is used as an address
of an object from the API, it is up to
+			the implementation to decide what it is actually pointing at. It is important though that
objects of the same
+			type have unique addresses. For example, <classname>JavaObject</classname>
instances much each return an 
+			<classname>ImagePointer</classname> different from all other, but there may
be instances of <classname>JavaClass</classname>
+			that share the same address.  			 
+			</para>
+			
+			<para>
+			<classname>ImagePointer</classname> allows access to memory using Java types,
corrected for endianness.
+			This means that only twos-complement values can be returned, apart from the <code>char</code>
which is unsigned in
+			Java. There is no conversion from the native platform's floating point formats. Floating
point values are assumed to
+			be stored as Java floating point types.
+			</para>
+			</sect3>
+			
+			</sect2>
+		
+		<sect2 xml:id="api.principles.packages">
+			<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. 
+			For example, the following is allowed as it refers to the image package:
+			
+			<programlisting>
+			ImageThread JavaThread.getImageThread()
+			</programlisting>
+			
+			But the converse is not:
+			
+			<programlisting>
+			JavaThread ImageThread.getJavaThread()
+			</programlisting>
+			</para>
+		</sect2>
+		
+		<sect2 xml:id="api.principles.errors">
+			<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 xml:id="api.principles.optional">
+		<title>Optional and missing data</title>
+		<para>
+		There are circumstances where information cannot be supplied. 
+		Methods that throw the exception <classname>DataUnavailable</classname> will
do so if the
+		information is either not presentable by the implmentation of the API, or if it is not
available
+		for that particular snapshot.
+		</para>
+		<para>
+		There are circumstances where <code>null</code> is returned by a method. These
circumstances will 
+		be explicitly documented in the Javadoc.	
+		</para>
+		<para>
+		<classname>DataUnavailable</classname> is thrown when the API <emphasis>cannnot</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 
+		</para>
+		</sect2>
+		
+		<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.
+		</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.

+		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. 
+		</para>
+		</sect2>
+		
+		<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 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. 
+		</para>
+		<para>
+		The behaviour of <methodname>equals</methodname> against objects from different
snapshots is not
+		defined.
+		</para>
+		</sect2>
+	</sect1>
\ No newline at end of file

Propchange: incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/principles.xml
------------------------------------------------------------------------------
    svn:mime-type = text/plain



Mime
View raw message