Added documentation

6 files changed, 154 insertions, 11 deletions

diff --git a/framework/bundles/org.eclipse.ecf.discovery/src/org/eclipse/ecf/discovery/IDiscoveryContainer.java b/framework/bundles/org.eclipse.ecf.discovery/src/org/eclipse/ecf/discovery/IDiscoveryContainer.java
index 2e6164571..3c3192486 100644
--- a/framework/bundles/org.eclipse.ecf.discovery/src/org/eclipse/ecf/discovery/IDiscoveryContainer.java
+++ b/framework/bundles/org.eclipse.ecf.discovery/src/org/eclipse/ecf/discovery/IDiscoveryContainer.java
@@ -13,16 +13,102 @@ import java.io.IOException;
 
 import org.eclipse.ecf.core.identity.ServiceID;
 
+/**
+ * Adapter interface for shared object containers that support lookup and discovery.
+ * This interface exposes the ability to add/remove listeners for newly
+ * discovered services and service types, register and unregister locally provided
+ * services, and get (synch) and request (asynch) service info from a remote
+ * service provider.  
+ * <p>
+ * This interface can be used by container provider implementations as an adapter
+ * so that calls to ISharedObjectContainer.getAdapter(IDiscoveryContainer.class)
+ * will return a non-null instance of a class that implements this interface.
+ * Clients can then proceed to use this interface to interact with the given
+ * discovery implementation.
+ * 
+ * @author slewis
+ *
+ */
 public interface IDiscoveryContainer {
+	/**
+	 * Add a service listener.  The given listener will have its method called
+	 * when a service with a type matching that specified by the first parameter
+	 * is discovered.
+	 * 
+	 * @param type the ServiceID of the desired type to listen for
+	 * @param listener the listener to be notified
+	 */
 	public void addServiceListener(ServiceID type, IServiceListener listener);
+	/**
+	 * Remove a service listener.  Remove the listener associated with the type
+	 * specified by the first parameter.
+	 * 
+	 * @param type the ServiceID of the desired type to remove the listener
+	 * @param listener the listener to be removed
+	 */
 	public void removeServiceListener(ServiceID type, IServiceListener listener);
+	/**
+	 * Add a service type listener.  The given listener will have its method called
+	 * when a service type is discovered.
+	 * 
+	 * @param listener the listener to be notified
+	 */
 	public void addServiceTypeListener(IServiceTypeListener listener);
+	/**
+	 * Remove a service type listener.  Remove the type listener.
+	 * 
+	 * @param listener the listener to be removed
+	 */
 	public void removeServiceTypeListener(IServiceTypeListener listener);
+	/**
+	 * Register the given service type.  This publishes the given service type to the
+	 * underlying publishing mechanism
+	 * 
+	 * @param serviceType the ServiceID of the type to be published
+	 */
 	public void registerServiceType(ServiceID serviceType);
+	/**
+	 * Register the given service.  This publishes the service defined by the first parameter to the
+	 * underlying publishing mechanism
+	 * 
+	 * @param serviceInfo the IServiceInfo of the service to be published
+	 */
 	public void registerService(IServiceInfo serviceInfo) throws IOException;
+	/**
+	 * Synchronously (within given timeout) retrieve info about the service defined by
+	 * the first parameter.
+	 * 
+	 * @param service the ServiceID of the service to get info about
+	 * @param timeout the time to wait for a response (in ms)
+	 * @return IServiceInfo the service info retrieved.  Null if no information retrieved within timeout.
+	 */
 	public IServiceInfo getServiceInfo(ServiceID service, int timeout);
+	/**
+	 * Asynchronously (within given timeout) retrieve info about the service defined by
+	 * the first parameter.  Sends a request for service information and returns.  Answers to
+	 * such requests occur via the IServiceListener.resolveService() method.
+	 * 
+	 * @param service the ServiceID of the service to get info about
+	 * @param timeout the time to wait for a response (in ms)
+	 */
 	public void requestServiceInfo(ServiceID service, int timeout);
+	/**
+	 * Unregister service defined by serviceInfo.
+	 * 
+	 * @param serviceInfo the info defining the service to unregister
+	 */
 	public void unregisterService(IServiceInfo serviceInfo);
+	/**
+	 * Unregister all services
+	 *
+	 */
 	public void unregisterAllServices();
+	/**
+	 * Get service info about all known services of given service type
+	 * 
+	 * @param type the ServiceID defining the type of service we are interested in getting
+	 * service info about
+	 * @return IServiceInfo[] the resulting array of service info instances
+	 */
 	public IServiceInfo [] getServices(ServiceID type);
 }
diff --git a/framework/bundles/org.eclipse.ecf.discovery/src/org/eclipse/ecf/discovery/IServiceEvent.java b/framework/bundles/org.eclipse.ecf.discovery/src/org/eclipse/ecf/discovery/IServiceEvent.java
index ced25e108..bc2079956 100644
--- a/framework/bundles/org.eclipse.ecf.discovery/src/org/eclipse/ecf/discovery/IServiceEvent.java
+++ b/framework/bundles/org.eclipse.ecf.discovery/src/org/eclipse/ecf/discovery/IServiceEvent.java
@@ -12,6 +12,9 @@ package org.eclipse.ecf.discovery;
 import org.eclipse.ecf.core.events.IContainerEvent;
 
 public interface IServiceEvent extends IContainerEvent {
-
+	/**
+	 * Get the service info associated with this event
+	 * @return IServiceInfo any info associated with this event.  May be null.
+	 */
 	public IServiceInfo getServiceInfo();
 }
diff --git a/framework/bundles/org.eclipse.ecf.discovery/src/org/eclipse/ecf/discovery/IServiceInfo.java b/framework/bundles/org.eclipse.ecf.discovery/src/org/eclipse/ecf/discovery/IServiceInfo.java
index e6d4bfadb..00940b782 100644
--- a/framework/bundles/org.eclipse.ecf.discovery/src/org/eclipse/ecf/discovery/IServiceInfo.java
+++ b/framework/bundles/org.eclipse.ecf.discovery/src/org/eclipse/ecf/discovery/IServiceInfo.java
@@ -13,13 +13,49 @@ import java.net.InetAddress;
 import java.util.Map;
 
 import org.eclipse.ecf.core.identity.ServiceID;
-
+/**
+ * Service information.  Defines the information associated
+ * with a service
+ * 
+ * @author slewis
+ *
+ */
 public interface IServiceInfo {
-
+	/**
+	 * Get InetAddress for service
+	 * @return InetAddress the address for the service.  
+	 * May be null if address is not known.
+	 */
 	public InetAddress getAddress();
+	/**
+	 * Get ServiceID for service. 
+	 * 
+	 * @return ServiceID the serviceID for the service.  Must not be null.
+	 */
 	public ServiceID getServiceID();
+	/**
+	 * The port for the service
+	 * 
+	 * @return port
+	 */
 	public int getPort();
+	/**
+	 * The priority for the service
+	 * 
+	 * @return int the priority.  Zero if no priority information for service.
+	 */
 	public int getPriority();
+	/**
+	 * The weight for the service.  Zero if no weight information for service.
+	 * 
+	 * @return int the weight
+	 */
 	public int getWeight();
+	/**
+	 * Map with any/all properties associated with the service.
+	 * Properties are assumed to be name/value pairs, both of type String.
+	 *
+	 * @return Map the properties associated with this service
+	 */
 	public Map getProperties();
 }
diff --git a/framework/bundles/org.eclipse.ecf.discovery/src/org/eclipse/ecf/discovery/IServiceListener.java b/framework/bundles/org.eclipse.ecf.discovery/src/org/eclipse/ecf/discovery/IServiceListener.java
index 6e1d48273..dc1895976 100644
--- a/framework/bundles/org.eclipse.ecf.discovery/src/org/eclipse/ecf/discovery/IServiceListener.java
+++ b/framework/bundles/org.eclipse.ecf.discovery/src/org/eclipse/ecf/discovery/IServiceListener.java
@@ -9,9 +9,29 @@
 
 package org.eclipse.ecf.discovery;
 
+/**
+ * Listener for receiving service events.
+ * 
+ * @author slewis
+ *
+ */
 public interface IServiceListener {
-
+	/**
+	 * Notification that a service has been added.
+	 * 
+	 * @param event
+	 */
 	public void serviceAdded(IServiceEvent event);
+	/**
+	 * Notification that a service has been removed.
+	 * 
+	 * @param event
+	 */
 	public void serviceRemoved(IServiceEvent event);
+	/**
+	 * Notification that a service has been resolved (that complete service info is now available).
+	 * 
+	 * @param event
+	 */
 	public void serviceResolved(IServiceEvent event);
 }
diff --git a/framework/bundles/org.eclipse.ecf.discovery/src/org/eclipse/ecf/discovery/IServiceTypeListener.java b/framework/bundles/org.eclipse.ecf.discovery/src/org/eclipse/ecf/discovery/IServiceTypeListener.java
index 5d3110b2d..35fdcd56f 100644
--- a/framework/bundles/org.eclipse.ecf.discovery/src/org/eclipse/ecf/discovery/IServiceTypeListener.java
+++ b/framework/bundles/org.eclipse.ecf.discovery/src/org/eclipse/ecf/discovery/IServiceTypeListener.java
@@ -10,6 +10,10 @@
 package org.eclipse.ecf.discovery;
 
 public interface IServiceTypeListener {
-
+	/**
+	 * Notification that a service type has been added
+	 * 
+	 * @param event
+	 */
 	public void serviceTypeAdded(IServiceEvent event);
 }
diff --git a/framework/bundles/org.eclipse.ecf.discovery/src/org/eclipse/ecf/discovery/ServiceInfo.java b/framework/bundles/org.eclipse.ecf.discovery/src/org/eclipse/ecf/discovery/ServiceInfo.java
index 9982096c0..79bee2470 100644
--- a/framework/bundles/org.eclipse.ecf.discovery/src/org/eclipse/ecf/discovery/ServiceInfo.java
+++ b/framework/bundles/org.eclipse.ecf.discovery/src/org/eclipse/ecf/discovery/ServiceInfo.java
@@ -18,17 +18,11 @@ import org.eclipse.ecf.core.identity.ServiceID;
 public class ServiceInfo implements IServiceInfo, Serializable {
 
 	private static final long serialVersionUID = 1L;
-
 	InetAddress addr = null;
-
 	ServiceID serviceID;
-
 	int port;
-
 	int priority;
-
 	int weight;
-
 	Map properties;
 
 	public ServiceInfo(InetAddress address, ServiceID id, int port,