Added Javadoc to IContainer.getAdapter

1 files changed, 32 insertions, 0 deletions

diff --git a/framework/bundles/org.eclipse.ecf/src/org/eclipse/ecf/core/IContainer.java b/framework/bundles/org.eclipse.ecf/src/org/eclipse/ecf/core/IContainer.java
index 1cc74ef5e..41d2e89a4 100644
--- a/framework/bundles/org.eclipse.ecf/src/org/eclipse/ecf/core/IContainer.java
+++ b/framework/bundles/org.eclipse.ecf/src/org/eclipse/ecf/core/IContainer.java
@@ -43,6 +43,38 @@ public interface IContainer extends IAdaptable, IIdentifiable {
 	 * container instance from any previously joined group.
 	 */
 	public void leaveGroup();
+	
+	/**
+	 * This specialization of IAdaptable.getAdapter() returns additional
+	 * services supported by this container. A container that supports
+	 * additional services over and above the methods on <code>IContainer</code>
+	 * should return them using this method. It is recommended that clients use
+	 * this method rather than instanceof checks and downcasts to find out about
+	 * the capabilities of a specific container.
+	 * <p>
+	 * Typically, after obtaining an IContainer, a client would use this
+	 * method as a means to obtain a more meaningful interface to the container.
+	 * This interface may or may not extend IContainer. For example, a client
+	 * could use the following code to obtain an instance of
+	 * ISharedObjectContainer:
+	 * </p>
+	 * <pre>
+	 * IContainer newContainer = ContainerFactory.makeContainer(type);
+     * ISharedObjectContainer soContainer = (ISharedObjectContainer) 
+     *                                       newContainer.getAdapter(ISharedObjectContainer.class);
+     * if (soContainer==null) throw new ContainerInstantiationException(message);
+     * </pre>
+	 * <p>
+	 * Implementations of this method should delegate to
+	 * <code>Platform.getAdapterManager().getAdapter()</code> if the service
+	 * cannot be provided directly to ensure extensibility by third-party
+	 * plug-ins.
+	 * </p>
+	 * @param serviceType the service type to look up
+	 * @return the service instance castable to the given class, or
+	 * <code>null</code> ifnthis container does not support the given service
+	 */
+	public Object getAdapter(Class serviceType);
 
 	/**
 	 * Dispose this ISharedObjectContainer instance. The container instance will