incubator-kato-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From monte...@apache.org
Subject svn commit: r806240 - in /incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx: appendices/objectfieldsexample.xml appendices/runtimeexample.xml chapters/examples.xml
Date Thu, 20 Aug 2009 16:30:10 GMT
Author: monteith
Date: Thu Aug 20 16:30:10 2009
New Revision: 806240

URL: http://svn.apache.org/viewvc?rev=806240&view=rev
Log:
Cut back on the example contents. Change KatoException.

Modified:
    incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/appendices/objectfieldsexample.xml
    incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/appendices/runtimeexample.xml
    incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/examples.xml

Modified: incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/appendices/objectfieldsexample.xml
URL: http://svn.apache.org/viewvc/incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/appendices/objectfieldsexample.xml?rev=806240&r1=806239&r2=806240&view=diff
==============================================================================
--- incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/appendices/objectfieldsexample.xml
(original)
+++ incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/appendices/objectfieldsexample.xml
Thu Aug 20 16:30:10 2009
@@ -34,8 +34,8 @@
 import java.lang.reflect.Array;
 
 import javax.tools.diagnostics.image.CorruptDataException;
+import javax.tools.diagnostics.image.DiagnosticException;
 import javax.tools.diagnostics.image.ImagePointer;
-import javax.tools.diagnostics.image.KatoException;
 import javax.tools.diagnostics.image.MemoryAccessException;
 import javax.tools.diagnostics.runtime.java.JavaClass;
 import javax.tools.diagnostics.runtime.java.JavaField;
@@ -115,7 +115,7 @@
 				for (JavaField nextField : clazz.getDeclaredFields()) {					
 					printField(prefix, nextField, jObject);						
 				}
-			} catch (KatoException e) {
+			} catch (DiagnosticException e) {
 				System.err.println("Error printing out fields.");
 				e.printStackTrace();
 			}

Modified: incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/appendices/runtimeexample.xml
URL: http://svn.apache.org/viewvc/incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/appendices/runtimeexample.xml?rev=806240&r1=806239&r2=806240&view=diff
==============================================================================
--- incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/appendices/runtimeexample.xml
(original)
+++ incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/appendices/runtimeexample.xml
Thu Aug 20 16:30:10 2009
@@ -41,7 +41,7 @@
 public abstract class RuntimeAnalyzer implements ImageAnalyzer {
 
 	/**
-	 * Calls the {@link #analyzeRuntime(JavaRuntime jr)} method against all {@link JavaRuntime}
+	 * Calls the analyzeRuntime(JavaRuntime jr) method against all JavaRuntime
 	 * instances found in the image.
 	 * 
 	 * @param image Image to analyse

Modified: incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/examples.xml
URL: http://svn.apache.org/viewvc/incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/examples.xml?rev=806240&r1=806239&r2=806240&view=diff
==============================================================================
--- incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/examples.xml (original)
+++ incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/examples.xml Thu Aug
20 16:30:10 2009
@@ -11,15 +11,15 @@
 	<sect2 xml:id="api.examples.intro">
 	<title>Introduction</title>
 	<para>
-	This section contains annotated examples to demonstrate some simple tasks and show how the
API
-	should be called.	
+	This chapter contains snippets of code demonstrating how to call the API. The appendices
contain
+	the unedited samples.
 	</para>
 	</sect2>
 	
 	<sect2 xml:id="api.examples.open">
 	<title>Opening Images</title>
-	<para><classname>Image</classname> instances are obtained using the <classname>javax.tools.diagnostics.FactoryRegistry</classname>
class.
-	See <xref linkend="appendix.readimageexample"/> for a complete example.
+	<para><classname>Image</classname> instances are obtained using the <classname>javax.tools.diagnostics.FactoryRegistry</classname>
+	class. See <xref linkend="appendix.readimageexample"/> for a complete example.
 	</para>
 	<para>
 	Programs using the API can obtain an Image like so:
@@ -51,8 +51,8 @@
 	<sect2 xml:id="api.examples.cause">
 	<title>Determining Snapshot Cause</title>
 	<para>
-	Snapshots can be generated for a variety of reasons. The API can report	when a snapshot
is generated when the 
-	JVM receives a POSIX type signal, whether that be synchronous or asynchronous.
+	Snapshots can be generated for a variety of reasons. The API can report	that a snapshot
has been generated 
+	because the JVM received a POSIX type signal, whether it was synchronous or asynchronous.
 	For example, if a JNI library causes a <code>SIGSEGV</code> when running, this
might be detectable
 	through the API. In most cases, it should be possible through <methodname>ImageAddressSpace.getCurrentProcess()</methodname>
 	and <methodname>ImageProcess.getCurrentThread()</methodname> to determine which
process and which thread caused
@@ -63,38 +63,21 @@
 	If a snapshot was generated for a reason other than a POSIX signal being received, then
the reason
 	has to be derived through knowledge of the JVM implementation. For example, if an option
was passed to
 	the JVM to generate a snapshot on entry to a particular method, all of the stack traces
could be searched
-	to determine if that method was present, and therefore probably causing the snapshot.
+	to determine if that method was present, and therefore probably causing the snapshot. Likewise,
detecting
+	a call to <function>abort()</function> in the native stack would suggest that
the snapshot was caused
+	by a synchronous SIGABRT. 
 	</para>
 	
 	<para>
-	The complete listing is in <xref linkend="appendix.causeexample"/>.
+	The following examples are extracts from the example program in <xref linkend="appendix.causeexample"/>.
 	</para>
-	<para>
-	First of all, there are the declarations. This implements a method in an interface that
expects
-	to simply be passed an <classname>Image</classname>. 
+
+	The examples implement the <classname>ImageAnalyzer</classname> interface, they
just need to implement
+	the <methodname>analyze(Image)</methodname> method. 
 <example xml:id="api.examples.cause.class">
 <title>CauseAnalyzer Class declaration</title>
 <programlisting>
 <![CDATA[
-package org.apache.kato.examples;
-
-import javax.tools.diagnostics.image.CorruptDataException;
-import javax.tools.diagnostics.image.DataUnavailable;
-import javax.tools.diagnostics.image.Image;
-import javax.tools.diagnostics.image.ImageAddressSpace;
-import javax.tools.diagnostics.image.ImageProcess;
-import javax.tools.diagnostics.image.ImageStackFrame;
-import javax.tools.diagnostics.image.ImageThread;
-import javax.tools.diagnostics.runtime.ManagedRuntime;
-import javax.tools.diagnostics.runtime.java.JavaRuntime;
-import javax.tools.diagnostics.runtime.java.JavaStackFrame;
-import javax.tools.diagnostics.runtime.java.JavaThread;
-
-/**
- * This analyzer determines what process and thread
- * caused the snapshot, and what signal, if any.
- *
- */
 public class CauseAnalyzer implements ImageAnalyzer {
 
 	@Override
@@ -102,41 +85,33 @@
 ]]>
 </programlisting>
 </example>
-Next, the containing <classname>ImageAddressSpace</classname> instances are searched
for a current process.
-It is probable that there will be one address space and one process. Note the use of <code>for</code>.
-<example xml:id="api.examples.cause.cuurentprocess">
+The containing <classname>ImageAddressSpace</classname> instances are searched
for a current process.
+It is probable that there will be one address space and one process. If <methodname>getCurrentProcess()</methodname>
+returns <code>null</code>, there was no current process. Because <code>List</code>
is returned, we can
+use a for-each loop.
+<example xml:id="api.examples.cause.currentprocess">
 <title>Find Current Process</title>
 <programlisting>
 <![CDATA[
-
 		for (ImageAddressSpace as : image.getAddressSpaces()) {
 			ImageProcess process = as.getCurrentProcess();
-			
-			// Only invoked if there is a "current" process,
-			// This is a process that caused the snapshot to occur.
+
 			if (process != null) {
-				try {
 ]]>
 </programlisting>
 </example>
 
 Once found, the process can be queried for signal information and thread information.
 If a signal was raised, <methodname>ImageProcess.getSignalName()</methodname>
will not be null.
-The example reports this to the user, along with the number.
+The example reports the signal name and number to the user.
 
 <example xml:id="api.examples.cause.signalinfo">
 <title>Reporting signal information</title>
 <programlisting>
-<![CDATA[				
+<![CDATA[
 					int signum = process.getSignalNumber();
 					String signame = process.getSignalName();
 
-					// Identify the process by number and command line.
-					System.out.println("Process "+process.getID()+
-							" was started with `" + 
-							process.getCommandLine()+"'");
-					
-					// The signals that cause the snapshot to be generated
 					if (signame != null) {
 						System.out.println("Snapshot caused by signal " + signame+"("+signum+")");						
 					}
@@ -144,15 +119,35 @@
 </programlisting>
 </example>
 
+<para>
+The <classname>ImageProcess</classname> can report the command line. This is
the command name
+and arguments that were used to start the process. The command and arguments are returned
in a single
+string, separated by spaces.
+</para>
+
+<para>The process ID returned by <methodname>getID()</methodname> in a
String. This is implementation
+specific, and so could be in any format, whether that be hexadecimal, decimal or some other
arbitrary string.
+
+<example xml:id="api.examples.cause.idandcommand">
+<title>Process ID and commandline</title>
+<programlisting>
+<![CDATA[
+					System.out.println("Process "+process.getID()+
+							" was started with `" + 
+							process.getCommandLine()+"'");
+]]>
+</programlisting>
+</example>
+
 The program determines which thread caused the snapshot to be generated.
-If one is found, the thread is identified by ID and its properties (implementation dependent).
+If the current thread isn't null, the thread is identified by ID and its 
+properties (implementation dependent).
 
 <example xml:id="api.examples.cause.threadid">
 <title>Thread identification</title>
 <programlisting>
 <![CDATA[				
 					ImageThread thread = process.getCurrentThread();
-					// Identify the thread, by id, various properties and a stack trace.
 					if (thread != null) {
 						System.out.println("\nSnapshot caused by thread "+
 								thread.getID()+
@@ -161,14 +156,14 @@
 </programlisting>
 </example>
 
-Next, the thread's stack frames are printed out. The example relies on
+Next, the thread's stack frames are printed out. The code relies on
 <methodname>java.lang.Object.toString()</methodname> being implemented correctly.
							
+It is expected that the most recent frame will be returned first.
 
 <example xml:id="api.examples.cause.stacktrace">
 <title>ImageThread stack trace</title>
 <programlisting>
-<![CDATA[				
-								
+<![CDATA[												
 						for(ImageStackFrame frame: thread.getStackFrames()) {
 							System.out.println("\t" + frame);
 						}
@@ -179,15 +174,15 @@
 This section of code relies on the relationship between <classname>JavaThread</classname>
instances
 and <classname>ImageThread</classname> instances to determine which Java thread
caused the snapshot.
 As the relationship is one-way, from Java to Image, all of the <classname>JavaThread</classname>
instances
-have to be queried. As <methodname>JavaThread.getImageThread()</methodname> might
be <code>null</code>,
+have to be queried. Because <methodname>JavaThread.getImageThread()</methodname>
might be <code>null</code>,
 <methodname>java.lang.Object.equals</methodname> is executed against the <classname>ImageThread</classname>
-which we know to be not null. 
+which we know to be not null. Once the <classname>JavaThread</classname> is found,
it's name can be
+printed.
 
 <example xml:id="api.examples.cause.imagejavathread">
 <title>JavaThread/ImageThread correlation</title>
 <programlisting>
 <![CDATA[										
-						// Find JavaThread and then do stacktrace.
 RUNTIME:				for(ManagedRuntime runtime : process.getRuntimes() ) {
 							if (runtime instanceof JavaRuntime) {
 								JavaRuntime jr = (JavaRuntime) runtime;
@@ -201,30 +196,7 @@
 											System.out.println("\t" + frame);
 										}
 										break RUNTIME;
-									}
-								}
-							}
-						}
-					}
-]]>
-</programlisting>
-</example>
-Here is the end of the definition of the class. In order to reduce the size of the example,
-the exceptions are handled outside of the API calls.
-<example xml:id="api.examples.cause.exceptions">
-<title>Exceptions</title>
-<programlisting>
-<![CDATA[																				
-				} catch (DataUnavailable e) {					
-					e.printStackTrace();
-				} catch (CorruptDataException e) {
-					e.printStackTrace();
-				}			
-			}
-		}
-	}
-}
-
+									}}}}
 ]]>
 </programlisting>
 </example>
@@ -253,28 +225,13 @@
 	The complete listing is in <xref linkend="appendix.whatexample"/>.
 	</para>
 	<para>
-	First, we have the class declaration, and imports. Note the use of both API's.
+	Like the previous example, this implements <classname>ImageAnalyzer</classname>.
There is some
+	functionality that is also present in the previous example - it is not repeated here.
+
 <example xml:id="api.examples.what.declaration">
 <title>Declaration of WhatAnalyzer class</title>
 <programlisting>
 <![CDATA[
-package org.apache.kato.examples;
-
-import javax.tools.diagnostics.image.CorruptDataException;
-import javax.tools.diagnostics.image.DataUnavailable;
-import javax.tools.diagnostics.image.Image;
-import javax.tools.diagnostics.image.ImageAddressSpace;
-import javax.tools.diagnostics.image.ImageModule;
-import javax.tools.diagnostics.image.ImagePointer;
-import javax.tools.diagnostics.image.ImageProcess;
-import javax.tools.diagnostics.runtime.ManagedRuntime;
-import javax.tools.diagnostics.runtime.java.JavaRuntime;
-import javax.tools.diagnostics.runtime.java.JavaVMOption;
-/**
- * This Analyzer generates a reports information useful for
- * identifying the JVM that was running when the snapshot was taken.
- * Elements from the Java and Image APIs are used.
- */
 public class WhatAnalyzer implements ImageAnalyzer {
 
 	@Override
@@ -283,11 +240,13 @@
 </programlisting>
 </example>
 
-The hostname is first printed out. Unlike some examples, the exceptions are being properly
here.
+The hostname of the machine where the snapshot was generated is printed out. This isn't information
that
+is necessarily available in most core dump formats, instead this would normally be recorded
by the program.
 As it is important to get out as much information as possible, calls to the API are made
with
-try/catch blocks around each individual method
+try/catch blocks around each individual method. This is necessary as exceptions should be
expected to be raised
+under most circumstances.
 The stack traces for <classname>DataUnavailable</classname> are not usually reported
as this
-is not an error condition. Instead, a message is inserted to indicate that information is
uknown.
+is not an error condition. Instead, a message is inserted to indicate that the information
is not known.
 
 <example xml:id="api.examples.what.hostname">
 <title>Getting the hostname</title>
@@ -307,72 +266,17 @@
 ]]>
 </programlisting>
 </example>
-	
-Here the program iterates over all of the address spaces, and then the processes.
-The process ID is printed out, which is returned as a String. It is suggested
-that implementors return a decimal integer.
-		
-<example xml:id="api.examples.what.processid">
-<title>Reporting the process ID</title>
-<programlisting>
-<![CDATA[
-		for (ImageAddressSpace as : image.getAddressSpaces()) {
-			for(ImageProcess process : as.getProcesses()) {
-				String processID;
-				try {
-					processID = process.getID();
-				} catch (DataUnavailable e) {					
-					processID = "<Unknown>";
-				} catch (CorruptDataException e) {
-					processID = "<Error>";
-					e.printStackTrace();
-				}
-				System.out.println("Process ID="+processID);
-]]>
-</programlisting>
-</example>
-
-The API can return the command line that was used to start a process.
-The command line is a single String that was generated from the options
-passed to the process concatenated and separated by spaces. 
-
-<example xml:id="api.examples.what.commandline">
-<title>Command line</title>
-<programlisting>
-<![CDATA[
-
-				String commandLine;
-				try {
-					commandLine = process.getCommandLine();
-				} catch (DataUnavailable e) {
-					commandLine = "<Unknown>";
-				} catch (CorruptDataException e) {
-					commandLine = "<Error>";
-					e.printStackTrace();
-				}
-				System.out.println("Command line: "+commandLine);
-]]>
-</programlisting>
-</example>
-
 Here the executable that started the process is reported. This is the executable that 
-launched the JVM -t ypically this is the "java" program. Alternatives include  
-"javac" and "appletviewer".
+launched the JVM - typically this is the "java" program. Alternatives include  
+"javac" and "appletviewer". This is the name of the executable the operating system loaded
+into memory when creating the process.
 			
 <example xml:id="api.examples.what.executable">
 <title>Executable name</title>
 <programlisting>
 <![CDATA[
-
 				String executable;
-				try {
-					executable = process.getExecutable().getName();
-				} catch (CorruptDataException e) {
-					executable = "<Unknown>";
-				} catch (DataUnavailable e) {
-					executable = "<Error>";
-					e.printStackTrace();
-				}
+				executable = process.getExecutable().getName();
 				System.out.println("Process Executable "+ executable);
 ]]>
 </programlisting>
@@ -380,50 +284,31 @@
 
 This code prints out the names of the libraries that were loaded by the process.
 This should include any JNI libraries that were configured. Note that it is also
-possible to determine where in memory these libraries have been mapped using the
-<methodname>ImageModule</methodname>.
-. This can
+possible to determine where in memory these libraries have been loaded into memory
+using the <methodname>getSections()</methodname> method. This can
 be used to identify where a thread might have crashed.
 			
 <example xml:id="api.examples.what.libaries">
 <title>Process libraries</title>
 <programlisting>
 <![CDATA[
-
 				System.out.println("Loaded Libraries:");
-				try {
-					for(ImageModule module : process.getLibraries()) {
-						System.out.println("\t" + module.getName());
-					}
-				} catch (DataUnavailable e) {
-					System.out.println("No libraries found.");
-				} catch (CorruptDataException e) {
-					System.out.println("Error retrieving libraries:");
-					e.printStackTrace();
-				}
-				
-				for (ManagedRuntime runtime : process.getRuntimes()) {
-					if (runtime instanceof JavaRuntime) {
-						analyzeRuntime ((JavaRuntime) runtime);
-					}
+				for(ImageModule module : process.getLibraries()) {
+					System.out.println("\t" + module.getName());
 				}
-			}
-		}
-	}
-
-	public void analyzeRuntime(JavaRuntime jr) {
 ]]>
 </programlisting>
 </example>
 
 The following code reports the Java VM version. This is implementation dependent,
-but is expected to contain more than just the version of Java that is supported.
-			
+but is expected to contain more than just the version of Java that is supported, but
+actually identify which implementation of the JVM it is.
+
 <example xml:id="api.examples.what.version">
 <title>Java VM Version</title>
 <programlisting>
 <![CDATA[
-		
+	public void analyzeRuntime(JavaRuntime jr) {		
 		try {
 			System.out.println("Java VM version:`"+jr.getVersion()+"'");
 		} catch (CorruptDataException e1) {
@@ -443,27 +328,17 @@
 <title>Java VM Options</title>
 <programlisting>
 <![CDATA[
-		
 		System.out.println("VM options:");
-		try {
-			for (JavaVMOption option : jr.getJavaVMInitArgs().getOptions()) {
-				String optionString = "\t\t\""+option.getOptionString()+"\"";
-				
-				ImagePointer extra = option.getExtraInfo();
-				if (extra != null) {
-					optionString += ", extraInfo=0x"+Long.toHexString(extra.getAddress());
-				}
-				
-				System.out.println(optionString);
+		for (JavaVMOption option : jr.getJavaVMInitArgs().getOptions()) {
+			String optionString = "\t\t\""+option.getOptionString()+"\"";
+								
+			ImagePointer extra = option.getExtraInfo();
+			if (extra != null) {
+				optionString += ", extraInfo=0x"+Long.toHexString(extra.getAddress());
 			}
-		} catch (DataUnavailable e) {
-			System.out.println("Unable to report VM options");
-		} catch (CorruptDataException e) {
-			System.out.println("Error retrieving VM options");
-			e.printStackTrace();
-		}
-	}
-}
+				
+			System.out.println(optionString);
+		}}
 ]]>
 </programlisting>
 </example>
@@ -480,35 +355,7 @@
 	The complete listing is in <xref linkend="appendix.objectfieldsexample"/>.	 
 	</para>
 	<para>
-	The follow is the declaration for this example class. It extends a class that will
-	call the <methodname>analyzeRuntime(JavaRuntime)</methodname> method with a
valid
-	<classname>JavaRuntime</classname>. Some applications and implementations will
only be
-	interested in the Java API.
-	
-<example xml:id="api.examples.fields.declaration">
-<title>Object fields class declaration</title>
-<programlisting>
-<![CDATA[	
-package org.apache.kato.examples;
-
-import java.lang.reflect.Array;
-
-import javax.tools.diagnostics.image.CorruptDataException;
-import javax.tools.diagnostics.image.ImagePointer;
-import javax.tools.diagnostics.image.KatoException;
-import javax.tools.diagnostics.image.MemoryAccessException;
-import javax.tools.diagnostics.runtime.java.JavaClass;
-import javax.tools.diagnostics.runtime.java.JavaField;
-import javax.tools.diagnostics.runtime.java.JavaHeap;
-import javax.tools.diagnostics.runtime.java.JavaObject;
-import javax.tools.diagnostics.runtime.java.JavaRuntime;
-
-public class ObjectFields extends RuntimeAnalyzer {
-]]>
-</programlisting>
-</example>		
-
-The <methodname>analyzeRuntime</methodname> method walks over the heaps within
the JVM.
+	The <methodname>analyzeRuntime</methodname> method walks over the heaps within
the JVM.
 While Java programmers will be used to the concept of the heap, the API allows a number
 of heaps to be accessed in a single JVM. It is expected the different heaps will have 
 different garbage collection policies and that each heap will be identified with a
@@ -523,15 +370,14 @@
 	public void analyzeRuntime(JavaRuntime jr) {
 		for (JavaHeap heap : jr.getHeaps()) {
 				walkHeap (heap);
-		} 		
-	}
-	
+		} }
+
 ]]>
 </programlisting>
 </example>		
 
 <para>
-This section of code retrieves each object from the heap. For API implementations
+This section of code retrieves each object from a heap. For API implementations
 backed by a core file, the objects will probably be retrieved in order from lowest
 address in memory to the highest, but there is no relationship between 
 <classname>JavaObject</classname> list indexes and the results of <methodname>JavaObject.getID()</methodname>
@@ -542,29 +388,18 @@
 an array or an ordinary object as they are handled differently.
 </para>
 
-
 <example xml:id="api.examples.fields.objects">
 <title>Iterate over Objects</title>
 <programlisting>
 <![CDATA[
 	public void walkHeap(JavaHeap heap) {
 		for (JavaObject jObject : heap.getObjects()) {
-
-			try {
-				if (jObject.isArray()) {
-					walkArray (jObject);
-				} else {
-					walkObject (jObject);
-				}
-
-			} catch (CorruptDataException e) {
-				System.err.println("Corrupt data exception calling jObject.isArray() at "+
-						pointerToHexString(jObject.getID()));
-				e.printStackTrace();
+			if (jObject.isArray()) {
+				walkArray (jObject);
+			} else {
+				walkObject (jObject);
 			}
-		} 
-	}
-
+		}
 ]]>
 </programlisting>
 </example>		
@@ -572,24 +407,18 @@
 <para>
 This method takes a <classname>JavaObject</classname> and prints out the
 values of all of the instance fields (not the static fields).
+To identify each object, its ID is used. This is turned into a hex string
+using the <methodname>pointerToHexString(ImagePointer)</methodname> that is
+included in this example.
 </para>
 
 <example xml:id="api.examples.fields.object">
 <title>Print object fields</title>
 <programlisting>
 <![CDATA[
-	
-	/**
-	 * Prints out all of the values of the fields in an object, along with
-	 * identifying information of the type itself.
-	 * 
-	 * @param jObject A JavaObject
-	 */
 	public void walkObject(JavaObject jObject) {	
-		// Just identify the object by its ID - this would the address on the heap.
 		System.out.println("JavaObject @ " + pointerToHexString(jObject.getID()));
-		// Handle indentation.
-		String prefix = "\t";
+
 ]]>
 </programlisting>
 </example>		
@@ -609,26 +438,19 @@
 <example xml:id="api.examples.fields.getjavaclass">
 <title>Get the object's type</title>
 <programlisting>
-<![CDATA[
-		
-		// Get the type of this object.		
+<![CDATA[		
 		JavaClass clazz;
-		try {
-			clazz = jObject.getJavaClass();
-		} catch (CorruptDataException e) {
-			System.err.println(prefix+"Error getting JavaClass");
-			e.printStackTrace();
-			return;
-		}
+		clazz = jObject.getJavaClass();
 ]]>
 </programlisting>
 </example>		
 
 <para>
 A class will only report its fields, the superclasses must be retrieved in order to
-retrieve <emphasis>their</emphasis> fields. This while loop retrieves each superclass
+retrieve <emphasis>their</emphasis> fields. This <code>while</code>
loop retrieves each superclass
 until the superclass is null, which will be returned by the <classname>java.lang.Object</classname>
-class.
+class. The class name is printed out, which should match what <methodname>java.lang.Class.getName()</methodname>
+would return, except for "." characters being replaced by "/".
 </para>
 
 <example xml:id="api.examples.fields.superclasses">
@@ -636,10 +458,8 @@
 <programlisting>
 <![CDATA[		
 		while (clazz != null) {
-			// print out the name of the class and the the fields.
-			try {
-				System.out.println( prefix + clazz.getName() +":");
-				prefix += "  ";
+			System.out.println( prefix + clazz.getName() +":");
+			prefix += "  ";
 ]]>
 </programlisting>
 </example>		
@@ -651,18 +471,18 @@
 Field[] java.lang.Class.getDeclaredFields()
 </programlisting>
 
-This should return all fields, even synthetic fields.
+This should return all fields, even synthetic fields. The <classname>DiagnosticException</classname>
+is a superclass of <classname>CorruptDataException</classname> and <classname>DataUnavailable</classname>.
 </para>
 
 <example xml:id="api.examples.fields.getfields">
 <title>Print out each field</title>
 <programlisting>
-<![CDATA[		
-		
+<![CDATA[
 				for (JavaField nextField : clazz.getDeclaredFields()) {					
 					printField(prefix, nextField, jObject);						
 				}
-			} catch (KatoException e) {
+			} catch (DiagnosticException e) {
 				System.err.println("Error printing out fields.");
 				e.printStackTrace();
 			}
@@ -671,7 +491,9 @@
 </example>		
 
 <para>
-Here the next superclass is retrieved. The loop is terminated by the
+Here the next superclass is retrieved. This will return <code>null</code> if
the class
+has no superclass, such as <classname>java.lang.Object</classname>.
+The loop is terminated by the
 <code>break</code> if the superclass couldn't be retrieved.
 </para>
 
@@ -679,24 +501,16 @@
 <title>get next superclass</title>
 <programlisting>
 <![CDATA[		
-			try {
-				clazz = clazz.getSuperclass();
-			} catch (CorruptDataException e) {				
-				e.printStackTrace();
-				break;
-			}
-			
+			clazz = clazz.getSuperclass();
 		} // while (class != null)
-	}
-	
 ]]>
 </programlisting>
 </example>		
 
 <para>
 This method demonstrates how to print out an instance field.
-Note that the <classname>JavaObject</classname> is passed as it must passed
-to the <classname>JavaField</classname> in order to actually retrieve the value
of the field
+Note that the <classname>JavaObject</classname> is passed as it must passed on
+to the <classname>JavaField</classname> for it to retrieve the value of the field
 in that instance.
 </para>
 
@@ -704,7 +518,7 @@
 <title>Print fields class</title>
 <programlisting>
 <![CDATA[			
-	private void printField(String prefix, JavaField field, JavaObject object) throws CorruptDataException,
MemoryAccessException {
+	private void printField(String prefix, JavaField field, JavaObject object) 		
 ]]>
 </programlisting>
 </example>		
@@ -722,11 +536,9 @@
 <example xml:id="api.examples.fields.modifiers">
 <title>Testing JavaField.getModifiers()</title>
 <programlisting>
-<![CDATA[		
-
-		if (java.lang.reflect.Modifier.isStatic(field.getModifiers())) {
+<![CDATA[
+		if (java.lang.reflect.Modifier.isStatic(field.getModifiers()))
 			return;
-		}
 ]]>
 </programlisting>
 </example>		
@@ -742,12 +554,13 @@
 <programlisting>
 <![CDATA[		
 		Object fieldValue = field.get(object);
-		
-		String valueString = "";
 ]]>
 </programlisting>
 </example>		
 
+Object references that were <code>null</code> in the running program are also
returned
+as <code>null</code> by the API.
+
 <example xml:id="api.examples.fields.null">
 <title>JavaField.get() returns null</title>
 <programlisting>
@@ -796,10 +609,8 @@
 <programlisting>
 <![CDATA[			
 		} else if (fieldValue instanceof JavaObject) {
-			// Note how we have to get an instance of the object to know anything about it.
 			JavaObject reference = (JavaObject) fieldValue;
 			
-			// classname: @ 0xadddress
 			valueString = reference.getJavaClass().getName() + ": @ " + pointerToHexString(reference.getID());
 ]]>
 </programlisting>
@@ -825,14 +636,13 @@
 
 		System.out.println(prefix + field.getSignature() + " " + 
 				field.getName() + " = " + valueString);		
-	}
-
 ]]>
 </programlisting>
 </example>		
 
 <para>
-This method deals only with arrays.
+This method deals only with arrays, which are treated differently from ordinary objects when
+retrieving their contents. Note that arrays don't have a field called "length".
 </para>
 
 <example xml:id="api.examples.fields.walkarray">
@@ -840,17 +650,15 @@
 <programlisting>
 <![CDATA[
 	public void walkArray(JavaObject object) {
-		// Just identify the object by its ID - this would the address on the heap.
 		System.out.println("JavaObject @ " + pointerToHexString(object.getID()));
-		// Handle indentation.		
-		String className;
 ]]>
 </programlisting>
 </example>		
 
 <para>
 All instances of <classname>JavaObject</classname> have a <classname>JavaClass</classname>
-with a name. For arrays, this follows the JNI conventions.
+with a name. For arrays, this follows the JNI conventions. An integer array would be
+called <code>"[I"</code>, whereas an array of strings would be called <code>"[Ljava/lang/String;"</code>.
 </para>
 
 <example xml:id="api.examples.fields.arrayclass">
@@ -858,23 +666,9 @@
 <programlisting>
 <![CDATA[		
 		JavaClass clazz;
-		try {
-			clazz = object.getJavaClass();
-		} catch (CorruptDataException e) {
-			System.err.println("Unable to determine array's JavaClass. aborting");
-			e.printStackTrace();
-			return;
-		}
+		clazz = object.getJavaClass();		
 		
-		// The class name is needed to determine the element types
-		try {
-			className = clazz.getName();
-		} catch (CorruptDataException e) {
-			System.err.println("Error getting Array class name.");
-			e.printStackTrace();
-			return;
-		}
-
+		className = clazz.getName();		
 ]]>
 </programlisting>
 </example>		
@@ -891,21 +685,14 @@
 <programlisting>
 <![CDATA[
 		int arraySize = 0;
- 
-		try {
-			arraySize = object.getArraySize();
-		} catch (CorruptDataException e) {
-			System.err.println("Unable to get object size.");
-			e.printStackTrace();
-			return;
-		}		
+		arraySize = object.getArraySize();		
 ]]>
 </programlisting>
 </example>		
 
 <para>
-An array's class should be able to report the type of it's elements.
-We use this call to determine the type of array to receive the contents of
+An array's class should be able to report the type of its elements.
+This call is used to determine the type of array to receive the contents of
 the array.
 </para>
 
@@ -914,23 +701,18 @@
 <programlisting>
 <![CDATA[
 		String componentName;
-		try {
-			componentName = clazz.getComponentType().getName();
-		} catch (CorruptDataException e) {
-			System.err.println("Unable to determine component type name. Quitting.");
-			e.printStackTrace();
-			return;
-		}
+		componentName = clazz.getComponentType().getName();
 		]]>
 </programlisting>
 </example>		
 
 <para>
-Arrays elements are accessed on an individual basis. Instead,
+Arrays elements are not accessed on an individual basis. Instead,
 their contents are copied to real arrays.
 This code demonstrates that there are <classname>JavaClass</classname> for
 primitive types, in the same way there is in reflection. These names
-are used to create primitive arrays of the correct type.
+are used to create primitive arrays of the correct type. Java reflection
+functions in the same way.
 </para>
 
 <example xml:id="api.examples.fields.destarray">
@@ -963,17 +745,16 @@
 <para>
 If an array is not an array of primitives, it must be an array
 of objects. As there is no means of converting a <classname>JavaObject</classname>
-into a "real" object, an array of <classname>JavaObject</classname> must suffice.
-This will also retrieve subarrays if the array was a multidimensional array.
+into a "real" object, an array of <classname>JavaObject</classname> instance
is returned.
+Multidimensional arrays are returned as arrays of <classname>JavaObject</classname>
instances
+that are themselves arrays. The example code shows how a array to receive object arrays is
allocated.
 </para>
 
 <example xml:id="api.examples.fields.objectarray">
 <title>Array of JavaObjects as destination</title>
 <programlisting>
 <![CDATA[
-			arrayCopy = new JavaObject[arraySize];
-		}
-							
+		arrayCopy = new JavaObject[arraySize];
 ]]>
 </programlisting>
 </example>
@@ -990,22 +771,7 @@
 <title>Copying array contents</title>
 <programlisting>
 <![CDATA[
-		try {
 			object.arraycopy(0, arrayCopy, 0, arraySize);
-		} catch (CorruptDataException e) {
-			e.printStackTrace();
-			return;
-		} catch (MemoryAccessException e) {
-			e.printStackTrace();
-			return;
-		} catch (IllegalArgumentException e){
-			e.printStackTrace();
-			return;
-		} catch (IndexOutOfBoundsException e) {
-			e.printStackTrace();
-			return;
-		}
-		
 ]]>
 </programlisting>
 </example>		
@@ -1014,7 +780,9 @@
 This code prints out the contents of the array elements. The <methodname>java.lang.Array.get()</methodname>
 method is used to retrieve elements from the array in a generic fashion. If <code>null</code>
is
 retrieved, that is printed, otherwise if it is an object the type and address of the object
is printed
-and failing that it must be an autoboxed primitive that can be printed out using its <methodname>toString()</methodname>.

+and failing that it must be an autoboxed primitive that can be printed out using its <methodname>toString()</methodname>.
+The <classname>CorruptDataException</classname> is caught within the loop to
allow the printing to continue
+even if some of the elements can't be located. 
 </para>
 
 <example xml:id="api.examples.fields.arrayelements">
@@ -1047,23 +815,6 @@
 </programlisting>
 </example>		
 
-<para>
-This is a helper function to get a standardized representation for <classname>ImagePointer</classname>.
-</para>
-
-<example xml:id="api.examples.fields.imagepointer">
-<title>Convert ImagePointer to a hex address</title>
-<programlisting>
-<![CDATA[
-	public static String pointerToHexString(ImagePointer pointer) {
-		return "0x"+Long.toHexString(pointer.getAddress());
-	}
-}
-]]>
-</programlisting>
-</example>		
-	
-
 	</para>
 	</sect2>
 </chapter>



Mime
View raw message