incubator-kato-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From monte...@apache.org
Subject svn commit: r803934 - /incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/API.xml
Date Thu, 13 Aug 2009 15:51:20 GMT
Author: monteith
Date: Thu Aug 13 15:51:20 2009
New Revision: 803934

URL: http://svn.apache.org/viewvc?rev=803934&view=rev
Log:
Some more additions to the API guidelines.

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=803934&r1=803933&r2=803934&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 Thu Aug 13
15:51:20 2009
@@ -139,13 +139,13 @@
 
 	<sect1 xml:id="api.principles">
 		<title>Principles</title>
-		<sect2>
+		<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>
+		<sect2 xml:id="api.principles.lists">
 			<title>Lists</title>
 			<para>
 			The API is mostly arranged as a hierarchy. Each object will using "contain" multiple
@@ -156,8 +156,11 @@
 			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>
+		<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 
@@ -179,7 +182,7 @@
 			</programlisting>
 			</para>			
 		</sect2>
-		<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>
@@ -221,15 +224,23 @@
 			</para>
 		</sect2>
 		
-		<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>
+		<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
@@ -278,16 +289,54 @@
 			</para></listitem>
 			<listitem><para>
 				<classname>CorruptDataException</classname>. This is thrown when the data
used to
-				form a response to the method call is incorrect.				
+				form a response to the method call is incorrect.
 			</para></listitem>
 			</itemizedlist>
 			</para>
 		</sect2>
 		
-		<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>



Mime
View raw message