You are viewing a plain text version of this content. The canonical link for it is here.
Posted to kato-commits@incubator.apache.org by mo...@apache.org on 2009/08/13 15:51:20 UTC
svn commit: r803934 -
/incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/API.xml
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<ManagedRuntime> 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>