Added javadocs for RemoteServiceHelper class static methods

1 files changed, 60 insertions, 3 deletions

diff --git a/framework/bundles/org.eclipse.ecf.remoteservice/src/org/eclipse/ecf/remoteservice/RemoteServiceHelper.java b/framework/bundles/org.eclipse.ecf.remoteservice/src/org/eclipse/ecf/remoteservice/RemoteServiceHelper.java
index 96d04836a..e3bb9f351 100644
--- a/framework/bundles/org.eclipse.ecf.remoteservice/src/org/eclipse/ecf/remoteservice/RemoteServiceHelper.java
+++ b/framework/bundles/org.eclipse.ecf.remoteservice/src/org/eclipse/ecf/remoteservice/RemoteServiceHelper.java
@@ -24,6 +24,8 @@ public class RemoteServiceHelper {
 
 	public static long defaultTimeout = 30000; // Default of 30 seconds.
 
+	public static Object[] EMPTY_PARAMS = new Object[] {};
+
 	public static long getDefaultTimeout() {
 		return defaultTimeout;
 	}
@@ -32,21 +34,40 @@ public class RemoteServiceHelper {
 		defaultTimeout = timeout;
 	}
 
+	/**
+	 * Invoke given method asynchronously, and call listener upon successful completion.
+	 * Uses default timeout.
+	 * 
+	 * @param remoteService the IRemoteService to invoke.  Must not be <code>null</code>.
+	 * @param method the method to invoke.  Must not be <code>null</code>.
+	 * @param parameters the parameters associated with the method to invoke.  May be <code>null</code> (no parameters).
+	 * @param listener the listener to call back when remote call initiated and completed.  Must not be <code>null</code>.
+	 */
 	public static void asyncExec(IRemoteService remoteService, final String method, final Object[] parameters, IRemoteCallListener listener) {
 		asyncExec(remoteService, method, parameters, getDefaultTimeout(), listener);
 	}
 
+	/**
+	 * Invoke given method asynchronously, and call listener upon successful completion.
+	 * 
+	 * @param remoteService the IRemoteService to invoke.  Must not be <code>null</code>.
+	 * @param method the method to invoke.  Must not be <code>null</code>.
+	 * @param parameters the parameters associated with the method to invoke.  May be <code>null</code> (no parameters).
+	 * @param timeout the timeout (in ms) for the remote call.
+	 * @param listener the listener to call back when remote call initiated and completed.  Must not be <code>null</code>.
+	 */
 	public static void asyncExec(IRemoteService remoteService, final String method, final Object[] parameters, final long timeout, IRemoteCallListener listener) {
 		Assert.isNotNull(remoteService);
 		Assert.isNotNull(method);
 		Assert.isNotNull(listener);
+		final Object[] params = (parameters == null) ? EMPTY_PARAMS : parameters;
 		remoteService.callAsync(new IRemoteCall() {
 			public String getMethod() {
 				return method;
 			}
 
 			public Object[] getParameters() {
-				return parameters;
+				return params;
 			}
 
 			public long getTimeout() {
@@ -55,16 +76,26 @@ public class RemoteServiceHelper {
 		}, listener);
 	}
 
+	/**
+	 * Invoke given method asynchronously, return an IFuture immediately that can be subsequently queried for
+	 * completion.
+	 * 
+	 * @param remoteService the IRemoteService to invoke.  Must not be <code>null</code>.
+	 * @param method the method to invoke.  Must not be <code>null</code>.
+	 * @param parameters the parameters associated with the method to invoke.  May be <code>null</code> (no parameters).
+	 * @param timeout the timeout (in ms) for the remote call.
+	 */
 	public static IFuture futureExec(IRemoteService remoteService, final String method, final Object[] parameters, final long timeout) {
 		Assert.isNotNull(remoteService);
 		Assert.isNotNull(method);
+		final Object[] params = (parameters == null) ? EMPTY_PARAMS : parameters;
 		return remoteService.callAsync(new IRemoteCall() {
 			public String getMethod() {
 				return method;
 			}
 
 			public Object[] getParameters() {
-				return parameters;
+				return params;
 			}
 
 			public long getTimeout() {
@@ -73,13 +104,31 @@ public class RemoteServiceHelper {
 		});
 	}
 
+	/**
+	 * Invoke given method asynchronously, return an IFuture immediately that can be subsequently queried for
+	 * completion.  Uses default timeout.
+	 * 
+	 * @param remoteService the IRemoteService to invoke.  Must not be <code>null</code>.
+	 * @param method the method to invoke.  Must not be <code>null</code>.
+	 * @param parameters the parameters associated with the method to invoke.  May be <code>null</code> (no parameters).
+	 */
 	public static IFuture futureExec(IRemoteService remoteService, final String method, final Object[] parameters) {
 		return futureExec(remoteService, method, parameters, getDefaultTimeout());
 	}
 
+	/**
+	 * Invoke given method synchronously, blocking the calling thread until a result is received or
+	 * timeout.
+	 * 
+	 * @param remoteService the IRemoteService to invoke.  Must not be <code>null</code>.
+	 * @param method the method to invoke.  Must not be <code>null</code>.
+	 * @param parameters the parameters associated with the method to invoke.  May be <code>null</code> (no parameters).
+	 * @param timeout the timeout (in ms) for the remote call.
+	 */
 	public static Object syncExec(IRemoteService remoteService, final String method, final Object[] parameters, final long timeout) throws ECFException {
 		Assert.isNotNull(remoteService);
 		Assert.isNotNull(method);
+		final Object[] params = (parameters == null) ? EMPTY_PARAMS : parameters;
 		return remoteService.callSync(new IRemoteCall() {
 
 			public String getMethod() {
@@ -87,7 +136,7 @@ public class RemoteServiceHelper {
 			}
 
 			public Object[] getParameters() {
-				return parameters;
+				return params;
 			}
 
 			public long getTimeout() {
@@ -96,6 +145,14 @@ public class RemoteServiceHelper {
 		});
 	}
 
+	/**
+	 * Invoke given method synchronously, blocking the calling thread until a result is received or
+	 * timeout.  Uses default timeout.
+	 * 
+	 * @param remoteService the IRemoteService to invoke.  Must not be <code>null</code>.
+	 * @param method the method to invoke.  Must not be <code>null</code>.
+	 * @param parameters the parameters associated with the method to invoke.  May be <code>null</code> (no parameters).
+	 */
 	public static Object syncExec(IRemoteService remoteService, final String method, final Object[] parameters) throws ECFException {
 		return syncExec(remoteService, method, parameters, getDefaultTimeout());
 	}