Added documentation to listener interfacesv20090519-2112

2 files changed, 111 insertions, 1 deletions

diff --git a/compendium/bundles/org.eclipse.ecf.osgi.services.distribution/src/org/eclipse/ecf/osgi/services/distribution/IHostDistributionListener.java b/compendium/bundles/org.eclipse.ecf.osgi.services.distribution/src/org/eclipse/ecf/osgi/services/distribution/IHostDistributionListener.java
index 567321aef..0c1b45eed 100644
--- a/compendium/bundles/org.eclipse.ecf.osgi.services.distribution/src/org/eclipse/ecf/osgi/services/distribution/IHostDistributionListener.java
+++ b/compendium/bundles/org.eclipse.ecf.osgi.services.distribution/src/org/eclipse/ecf/osgi/services/distribution/IHostDistributionListener.java
@@ -13,13 +13,48 @@ import org.eclipse.ecf.remoteservice.IRemoteServiceContainer;
 import org.eclipse.ecf.remoteservice.IRemoteServiceRegistration;
 import org.osgi.framework.ServiceReference;
 
+/**
+ * Listener for host distribution events. Services registered with this as their
+ * service interface will have their methods called when the distribution
+ * implementation events occur.
+ * 
+ */
 public interface IHostDistributionListener {
 
+	/**
+	 * Event indicating that a remote service has been registered, with the
+	 * given local serviceReference, the given remoteServiceContainer, and the
+	 * given remoteRegistration.
+	 * 
+	 * @param serviceReference
+	 *            the ServiceReference of the locally registered service. Will
+	 *            not be <code>null</code>.
+	 * 
+	 * @param remoteServiceContainer
+	 *            the remoteServiceContainer that is doing the distribution for
+	 *            this remote service. Will not be <code>null</code>.
+	 * 
+	 * @param remoteRegistration
+	 *            The remote service registration created with successful
+	 *            registration with the remoteServiceContainer. Will not be
+	 *            <code>null</code>.
+	 */
 	public void registered(ServiceReference serviceReference,
 			IRemoteServiceContainer remoteServiceContainer,
 			IRemoteServiceRegistration remoteRegistration);
 
+	/**
+	 * Event indicating that a remote service has been unregistered.
+	 * 
+	 * @param serviceReference
+	 *            the ServiceReference of the locally registered service. Will
+	 *            not be <code>null</code>.
+	 * 
+	 * @param remoteRegistration
+	 *            The remote service registration previously created upon
+	 *            registration. Will not be <code>null</code>.
+	 */
 	public void unregistered(ServiceReference serviceReference,
-			IRemoteServiceRegistration remoteReference);
+			IRemoteServiceRegistration remoteRegistration);
 
 }
diff --git a/compendium/bundles/org.eclipse.ecf.osgi.services.distribution/src/org/eclipse/ecf/osgi/services/distribution/IProxyDistributionListener.java b/compendium/bundles/org.eclipse.ecf.osgi.services.distribution/src/org/eclipse/ecf/osgi/services/distribution/IProxyDistributionListener.java
index 259382f87..f4d527a37 100644
--- a/compendium/bundles/org.eclipse.ecf.osgi.services.distribution/src/org/eclipse/ecf/osgi/services/distribution/IProxyDistributionListener.java
+++ b/compendium/bundles/org.eclipse.ecf.osgi.services.distribution/src/org/eclipse/ecf/osgi/services/distribution/IProxyDistributionListener.java
@@ -14,23 +14,98 @@ import org.eclipse.ecf.remoteservice.IRemoteServiceContainer;
 import org.eclipse.ecf.remoteservice.IRemoteServiceReference;
 import org.osgi.framework.ServiceRegistration;
 
+/**
+ * Listener for proxy distribution events. Services registered with this as
+ * their service interface will have their methods called when the distribution
+ * implementation events occur.
+ * 
+ */
 public interface IProxyDistributionListener {
 
+	/**
+	 * Event that indicates that an endpointDescription has been discovered and
+	 * that the remote service references (specified by the endpointDescription)
+	 * are being lookedup using the given remoteServiceContainer. If multiple
+	 * remoteServiceContainers are found, this method will be called multiple
+	 * times, each with a distinct remoteServiceContainer.
+	 * 
+	 * @param endpointDescription
+	 *            the endpointDescription that describes the discovered endpoint
+	 *            that exposes some remote services. Will not be
+	 *            <code>null</code>.
+	 * @param remoteServiceContainer
+	 *            a remote service container that has been found (via the
+	 *            {@link IProxyContainerFinder}) and will be used for remote
+	 *            lookup.
+	 */
 	public void retrievingRemoteServiceReferences(
 			IRemoteServiceEndpointDescription endpointDescription,
 			IRemoteServiceContainer remoteServiceContainer);
 
+	/**
+	 * Event that indicates that the given endpointDescription and
+	 * remoteServiceContainer have resulted in a remoteServiceReference that
+	 * will be used to register a remote service.
+	 * 
+	 * @param endpointDescription
+	 *            the endpointDescription that describes the discovered endpoint
+	 *            that exposes some remote services. Will not be
+	 *            <code>null</code>.
+	 * @param remoteServiceContainer
+	 *            a remote service container that has been found (via the
+	 *            {@link IProxyContainerFinder}) and will be used for remote
+	 *            lookup. Will not be <code>null</code>.
+	 * @param remoteServiceReference
+	 *            a remote service reference that has resulted from using the
+	 *            endpointDescription meta-data and remoteServiceContainer to
+	 *            successfully lookup this reference. Will not be
+	 *            <code>null</code>.
+	 */
 	public void registering(
 			IRemoteServiceEndpointDescription endpointDescription,
 			IRemoteServiceContainer remoteServiceContainer,
 			IRemoteServiceReference remoteServiceReference);
 
+	/**
+	 * Event that indicates that a remote service proxy has been successfully
+	 * been looked up, created, and registered in the local service registry.
+	 * 
+	 * @param endpointDescription
+	 *            the endpointDescription that describes the discovered endpoint
+	 *            that exposes some remote services. Will not be
+	 *            <code>null</code>.
+	 * @param remoteServiceContainer
+	 *            a remote service container that has been found (via the
+	 *            {@link IProxyContainerFinder}) and will be used for remote
+	 *            lookup. Will not be <code>null</code>.
+	 * @param remoteServiceReference
+	 *            a remote service reference that has resulted from using the
+	 *            endpointDescription meta-data and remoteServiceContainer to
+	 *            successfully lookup this reference. Will not be
+	 *            <code>null</code>.
+	 * @param proxyServiceRegistration
+	 *            the local ServiceRegistration that was created when the local
+	 *            proxy was successfully added to the service registry.
+	 */
 	public void registered(
 			IRemoteServiceEndpointDescription endpointDescription,
 			IRemoteServiceContainer remoteServiceContainer,
 			IRemoteServiceReference remoteServiceReference,
 			ServiceRegistration proxyServiceRegistration);
 
+	/**
+	 * Event that indicates that a remote service proxy has been unregistered
+	 * from the local service registry.
+	 * 
+	 * @param endpointDescription
+	 *            the endpointDescription that describes the discovered endpoint
+	 *            that exposes some remote services. May be <code>null</code> if
+	 *            the service is unregistered for some event other than
+	 *            discovery (e.g. container disconnection).
+	 * @param proxyServiceRegistration
+	 *            the local ServiceRegistration that was created when the local
+	 *            proxy was successfully added to the service registry.
+	 */
 	public void unregistered(
 			IRemoteServiceEndpointDescription endpointDescription,
 			ServiceRegistration proxyServiceRegistration);