Update Javadoc for net.sf.j2s.ajax

jossonsmith · jossonsmith · commit c10939504017 · 2006-08-18T16:03:21.000Z
diff --git a/sources/net.sf.j2s.ajax/ajaxcore/net/sf/j2s/ajax/AClass.java b/sources/net.sf.j2s.ajax/ajaxcore/net/sf/j2s/ajax/AClass.java
@@ -14,22 +14,36 @@
 package net.sf.j2s.ajax;
 
 /**
+ * This class is an asynchronous version of Class. It is designed for function
+ * of Class#forName. While Class#forName will try to load class in synchronous
+ * mode, this class AClass#load  is trying to load class in asynchronous mode.
+ * A callback object is provided for action to be executed after the class is
+ * loaded.
+ * 
  * @author josson smith
  *
  * 2006-8-4
  */
 public class AClass {
 	
 	/**
+	 * AClass should NOT be instantialized outside package net.sf.j2s.ajax.
+	 * User should always use its static methods.
+	 * 
 	 * @j2sIgnore
 	 */
 	protected AClass() {
 		// prevent from instantialization
 	}
 	
 	/**
-	 * @param clazzName
-	 * @param afterLoaded
+	 * Load the class by the given class name and execute the given callback
+	 * after class is loaded.
+	 * 
+	 * @param clazzName String given class name.
+	 * @param afterLoaded Runnable given callback. If this parameter is an 
+	 * instance of <code>ARunnable</code>, the callback will receive the 
+	 * loaded class automatically.
 	 * 
 	 * @j2sNativeSrc
 	 * ClazzLoader.loadClass (clazzName, function () {
diff --git a/sources/net.sf.j2s.ajax/ajaxcore/net/sf/j2s/ajax/ARunnable.java b/sources/net.sf.j2s.ajax/ajaxcore/net/sf/j2s/ajax/ARunnable.java
@@ -14,17 +14,29 @@
 package net.sf.j2s.ajax;
 
 /**
+ * This abstract class provides a wrapper of interface Runnable to
+ * give convenience for <code>AClass</code> or <code>ASWTClass</code>
+ * to set and to get the class that is loaded.
+ *  
  * @author josson smith
  *
  * 2006-8-4
  */
 public abstract class ARunnable implements Runnable {
 	private Class clazz;
 
+	/**
+	 * Return the loaded class.
+	 * @return Class loaded class.
+	 */
 	public Class getClazz() {
 		return clazz;
 	}
 
+	/**
+	 * Set the loaded class
+	 * @param clazz Class class that is already loaded.
+	 */
 	public void setClazz(Class clazz) {
 		this.clazz = clazz;
 	}
diff --git a/sources/net.sf.j2s.ajax/ajaxcore/net/sf/j2s/ajax/HttpRequest.java b/sources/net.sf.j2s.ajax/ajaxcore/net/sf/j2s/ajax/HttpRequest.java
@@ -30,6 +30,10 @@
 import org.w3c.dom.Document;
 
 /**
+ * This class is a Java implementation of browser's XMLHttpRequest object.
+ * This class can be considered as a bridge of Java's AJAX programming and
+ * JavaScript/Browser's AJAX programming.
+ * 
  * @author josson smith
  *
  * 2006-2-11
@@ -51,12 +55,26 @@ public final class HttpRequest {
 	private Map headers = new HashMap();
 	private String content;
 	
+	/**
+	 * Return read state of XMLHttpRequest.
+	 * @return int ready state
+	 */
 	public int getReadyState() {
 		return readyState;
 	}
+	/**
+	 * Return response raw text of XMLHttpRequest 
+	 * @return String response text. May be null if the request is not sent
+	 * or an error happens. 
+	 */
 	public String getResponseText() {
 		return responseText;
 	}
+	/**
+	 * Return the parsed XML document of the response of XMLHttpRequest.
+	 * @return Document XML document. May be null if the response text is not
+	 * a valid XML document.
+	 */
 	public Document getResponseXML() {
 		if (responseXML != null) {
 			return responseXML;
@@ -75,21 +93,57 @@ public Document getResponseXML() {
 		}
 		return responseXML;
 	}
+	/**
+	 * Return respose code.
+	 * @return int response code. For more information please read about
+	 * HTTP protocol.
+	 */
 	public int getResponseCode() {
 		return status;
 	}
+	/**
+	 * Register XMLHttpRequest callback.
+	 * 
+	 * @param onreadystatechange IXHRCallback callback
+	 */
 	public void registerOnReadyStateChange(IXHRCallback onreadystatechange) {
 		this.onreadystatechange = onreadystatechange;
 	}
+	/**
+	 * Set request header with given key and value.
+	 * @param key String request header keyword. For more information please 
+	 * read about HTTP protocol.
+	 * @param value String request header value
+	 */
 	public void setRequestHeader(String key, String value) {
 		headers.put(key, value);
 	}
+	/**
+	 * Get response header with given key.
+	 * @param key String header keyword. For more information please 
+	 * read about HTTP protocol.
+	 * @return String the reponse header value.
+	 */
 	public String getResponseHeader(String key) {
 		return connection.getHeaderField(key);
 	}
+	/**
+	 * Open connection for HTTP request with given method and URL 
+	 * synchronously.
+	 * 
+	 * @param method String "POST" or "GET" usually.
+	 * @param url String remote URL. Should always be absolute URL.
+	 */
 	public void open(String method, String url) {
 		open(method, url, false);
 	}
+	/**
+	 * Open connection for HTTP request with given method, URL and mode.
+	 * 
+	 * @param method String "POST" or "GET" usually.
+	 * @param url String remote URL. Should always be absolute URL.
+	 * @param async boolean whether send request asynchronously or not. 
+	 */
 	public void open(String method, String url, boolean async) {
 		this.asynchronous = async;
 		this.method = method;
@@ -101,9 +155,17 @@ public void open(String method, String url, boolean async) {
 			onreadystatechange.onLoading();
 		}
 	}
+	
+	/**
+	 * Send the HTTP request without extra content.
+	 */
 	public void send() {
 		send(null);
 	}
+	/**
+	 * Send the HTTP request with given content.
+	 * @param str String HTTP request content. May be null.
+	 */
 	public void send(String str) {
 		content = str;
 		if (asynchronous) {
@@ -116,6 +178,9 @@ public void run() {
 			request();
 		}
 	}
+	/*
+	 * Try setup the real connection and send the request over HTTP protocol. 
+	 */
 	private void request() {
 		try {
 			connection = (HttpURLConnection) new URL(url).openConnection();
diff --git a/sources/net.sf.j2s.ajax/ajaxcore/net/sf/j2s/ajax/IXHRCallback.java b/sources/net.sf.j2s.ajax/ajaxcore/net/sf/j2s/ajax/IXHRCallback.java
@@ -14,14 +14,29 @@
 package net.sf.j2s.ajax;
 
 /**
+ * Interface of XMLHttpRequest callback.
+ * 
  * @author josson smith
  *
  * 2006-2-11
  */
 public interface IXHRCallback {
 	//public void onUninitialized();
+	/**
+	 * Method will be called when XMLHttpRequest is loading.
+	 */
 	public void onLoading();
+	/**
+	 * Method will be called when XMLHttpRequest already setup HTTP connection.
+	 */
 	public void onLoaded();
+	/**
+	 * Method will be called when XMLHttpRequest is transforming request and 
+	 * receiving response.
+	 */
 	public void onInteractive();
+	/**
+	 * Method will be called when XMLHttpRequest receives all reponses.
+	 */
 	public void onComplete();
 }
diff --git a/sources/net.sf.j2s.ajax/ajaxcore/net/sf/j2s/ajax/XHRCallbackAdapter.java b/sources/net.sf.j2s.ajax/ajaxcore/net/sf/j2s/ajax/XHRCallbackAdapter.java
@@ -14,24 +14,38 @@
 package net.sf.j2s.ajax;
 
 /**
+ * This adapter provides a default implementation of IXHRCallback.
+ * 
  * @author josson smith
  *
  * 2006-2-11
  */
 public class XHRCallbackAdapter implements IXHRCallback {
 
+	/**
+	 * Will be called when all responses are received.
+	 */
 	public void onComplete() {
 		
 	}
 
+	/**
+	 * Will be called when the request is sending and the reponse comes.
+	 */
 	public void onInteractive() {
 		
 	}
 
+	/**
+	 * Will be called when the HTTP connection is setup.
+	 */
 	public void onLoaded() {
 		
 	}
 
+	/**
+	 * Will be called when <code>HttPRequest#open</code> is called.
+	 */
 	public void onLoading() {
 		
 	}
diff --git a/sources/net.sf.j2s.ajax/ajaxswt/net/sf/j2s/ajax/ASWTClass.java b/sources/net.sf.j2s.ajax/ajaxswt/net/sf/j2s/ajax/ASWTClass.java
@@ -17,19 +17,47 @@
 import org.eclipse.swt.widgets.Shell;
 
 /**
+ * This class is designed to load class asynchronously within the same thread 
+ * of given Shell or Display. Because executing callback after given class is 
+ * loaded will be in another thread scope of current Display. In order to 
+ * avoid nasty codes of such 
+ * <pre>
+	Display.getDefault().asyncExec(new Runnable() {
+			public void run() {
+				//...
+			}
+	});
+ * </pre>
+ * This class ASWTClass is designed so developer won't need to code in such 
+ * nasty way. Just call <code>ASWTClass#swtLoad</code> with the same
+ * parameter as <code>AClass#load</code>. Or call <code>ASWTClass#shellLoad</code>
+ * or <code>ASWTClass#displayLoad</code> with extra Shell/Display argument. 
+ * 
  * @author josson smith
  *
  * 2006-8-4
  */
 public class ASWTClass extends AClass {
 	
 	/**
+	 * ASWTClass should NOT be instantialized outside package net.sf.j2s.ajax.
+	 * User should always use its static methods.
+	 * 
 	 * @j2sIgnore
 	 */
 	protected ASWTClass() {
 		// prevent from instantialization
 	}
 
+	/**
+	 * Load class by given class name and execute callback in the same thread
+	 * of default Display's thread.
+	 *  
+	 * @param clazzName String given class name.
+	 * @param afterLoaded Runnable given callback. If this parameter is an 
+	 * instance of <code>ARunnable</code>, the callback will receive the 
+	 * loaded class automatically.
+	 */
 	public static void swtLoad(String clazzName, Runnable afterLoaded) {
 		Display display = null;
 		/**
@@ -46,9 +74,14 @@ public static void swtLoad(String clazzName, Runnable afterLoaded) {
 
 
 	/**
-	 * @param display
-	 * @param clazzName
-	 * @param afterLoaded
+	 * Load class by given class name and execute callback in the same thread
+	 * of given Display's thread.
+	 * 
+	 * @param display Display given display
+	 * @param clazzName String given class name.
+	 * @param afterLoaded Runnable given callback. If this parameter is an 
+	 * instance of <code>ARunnable</code>, the callback will receive the 
+	 * loaded class automatically.
 	 * 
 	 * @j2sNativeSrc
 	 * ClazzLoader.loadClass (clazzName, function () {
@@ -86,9 +119,30 @@ public void run() {
 		});
 	}
 
+	/**
+	 * Load class asynchronously and execute callback in the same thread
+	 * of given Display's thread.
+	 * 
+	 * @param display Display given display
+	 * @param clazzName String given class name.
+	 * @param afterLoaded Runnable given callback. If this parameter is an 
+	 * instance of <code>ARunnable</code>, the callback will receive the 
+	 * loaded class automatically.
+	 */
 	public static void displayLoad(Display display, final String clazzName, final Runnable afterLoaded) {
 		objectLoad(display, clazzName, afterLoaded);
 	}
+	/**
+	 * Load class asynchronously and execute callback in the same thread of 
+	 * given Shell's Display.
+	 * 
+	 * @param shell Shell given shell
+	 * @param clazzName String given class name.
+	 * @param afterLoaded Runnable given callback. If this parameter is an 
+	 * instance of <code>ARunnable</code>, the callback will receive the 
+	 * loaded class automatically.
+	 * 
+	 */
 	public static void shellLoad(Shell shell, String clazzName, Runnable afterLoaded) {
 		objectLoad(shell.getDisplay(), clazzName, afterLoaded);
 	}
diff --git a/sources/net.sf.j2s.ajax/ajaxswt/net/sf/j2s/ajax/XHRCallbackSWTAdapter.java b/sources/net.sf.j2s.ajax/ajaxswt/net/sf/j2s/ajax/XHRCallbackSWTAdapter.java
