More Javadoc elaboration and cleanup

git-svn-id: http://scm.dspace.org/svn/repo/modules/dspace-services/trunk@4982 9c30dcfa-912a-0410-8fc2-9e0234be79fd

api/src/main/java/org/dspace/kernel/ServiceManager.java

@@ -14,16 +14,17 @@ import java.util.List;
 import java.util.Map;
 
 /**
- * This is the interface for the service manager which allows for non-specific access to the core services,
- * no dependency on the underlying mechanism is exposed
+ * Allows for non-specific access to the core services.
+ * No dependency on the underlying mechanism is exposed.
  * 
  * @author Aaron Zeckoski (azeckoski @ gmail.com)
  */
 public interface ServiceManager {
 
     /**
-     * Allows developers to get the desired service singleton by the provided type <br/>
-     * This should return all instantiated objects of the type specified (may not all be singletons)
+     * Allows developers to get the desired service singleton by the provided type. <br/>
+     * This should return all instantiated objects of the type specified 
+     * (may not all be singletons).
      * 
      * @param <T>
      * @param type the type for the requested service (this will typically be the interface class but can be concrete as well)
@@ -32,25 +33,35 @@ public interface ServiceManager {
     public <T> List<T> getServicesByType(Class<T> type);
 
     /**
-     * Allows developers to get the desired service singleton by the provided name and type,
-     * can provide null for the name if it is not known but it is better to ensure it is set <br/>
-     * NOTE: This also allows special access to the underlying service manager objects,
-     * if using spring this allows access to the underlying ApplicationContext object like so: <br/>
+     * Allows developers to get the desired service singleton by the provided name and type.
+     * Provide {@code null} for the name if it is not known, but it is
+     * better to ensure it is set.
+     * <p>
+     * <em>NOTE</em>: This also allows special access to the underlying
+     * service manager objects.  If using Spring this allows access to the
+     * underlying ApplicationContext object like so:
+     * <xmp>
      * getServiceByName(ApplicationContext.class.getName(), ApplicationContext.class);
-     * if using Guice then the same applies like so: <br/>
+     * </xmp>
+     * If using Guice then the same applies like so:
+     * <xmp>
      * getServiceByName(Injector.class.getName(), Injector.class);
-     * it is also possible to register a module and cause Guice to fill in any injected core services (see register method)
+     * </xmp>
+     * It is also possible to register a module and cause Guice to fill
+     * in any injected core services (see register method).
+     * </p>
      * 
      * @param <T>
-     * @param name (optional) the unique name for this service, 
-     * if null then the bean will be returned if there is only one service of this type 
+     * @param name (optional) the unique name for this service.
+     * If null then the bean will be returned if there is only one
+     * service of this type.
      * @param type the type for the requested service (this will typically be the interface class but can be concrete as well)
      * @return the service singleton OR null if none is found
      */
     public <T> T getServiceByName(String name, Class<T> type);
 
     /**
-     * Lookup to see if a service exists with the given name
+     * Lookup to see if a service exists with the given name.
      * 
      * @param name the unique name for this service
      * @return true if it exists, false otherwise
@@ -58,22 +69,31 @@ public interface ServiceManager {
     public boolean isServiceExists(String name);
 
     /**
-     * Get the names of all registered service singletons (by convention, 
-     * the name typically matches the fully qualified class name)
+     * Get the names of all registered service singletons.  By
+     * convention, the name typically matches the fully qualified class 
+     * name).
      * 
      * @return the list of all current registered services
      */
     public List<String> getServicesNames();
 
     /**
-     * Allows adding singleton services and providers in at runtime or after the service manager has started up,
-     * this is primarily useful for registering providers, filters, and plugins with the DSpace core <br/>
-     * NOTE: It is important that you also call {@link #unregisterService(String)} if you are shutting
-     * down the context (webapp, etc.) that registered the service so that the full lifecycle completes
-     * correctly <br/>
-     * NOTE: if using Guice it is possible to register a Guice Module as a service which will not 
-     * actually register it but will cause anything in the Module to have existing core services
-     * injected into it, you can use anything as the name in this case
+     * Allows adding singleton services and providers in at runtime or 
+     * after the service manager has started up.
+     * This is primarily useful for registering providers, filters, and
+     * plugins with the DSpace core.
+     * <p>
+     * <em>NOTE:</em> It is important that you also call
+     * {@link #unregisterService(String)} if you are shutting
+     * down the context (webapp, etc.) that registered the service so 
+     * that the full lifecycle completes correctly.
+     * </p>
+     * <p>
+     * <em>NOTE:</em> if using Guice it is possible to register a Guice
+     * Module as a service, which will not actually register it but will 
+     * cause anything in the Module to have existing core services injected
+     * into it.  You can use anything as the name in this case.
+     * </p>
      * 
      * @param name the name of the service (must be unique)
      * @param service the object to register as a singleton service
@@ -82,12 +102,16 @@ public interface ServiceManager {
     public void registerService(String name, Object service);
 
     /**
-     * Allows adding singleton services and providers in at runtime or after the service manager has started up,
-     * this is the same as {@link #registerService(String, Object)} except that it allows the core service
-     * manager to startup your service for you instead of you providing a service to the core.
-     * In general, it is better if you use your own service manager (like Spring or Guice) to manage your services
-     * and simply inherit the core service beans from the DSpace core service manager using the special 
-     * capabilities of {@link #getServiceByName(String, Class)}
+     * Allows adding singleton services and providers in at runtime or 
+     * after the service manager has started up.
+     * This is the same as {@link #registerService(String, Object)}
+     * except that it allows the core service manager to startup your 
+     * service for you instead of you providing a service to the core.
+     * In general, it is better if you use your own service manager 
+     * (like Spring or Guice) to manage your services  and simply 
+     * inherit the core service beans from the DSpace core service
+     * manager using the special capabilities of
+     * {@link #getServiceByName(String, Class)}.
      * 
      * @see ServiceManager#getServiceByName(String, Class)
      * @param name the name of the service (must be unique)
@@ -97,10 +121,14 @@ public interface ServiceManager {
     public <T> T registerServiceClass(String name, Class<T> type);
 
     /**
-     * Allows a service to be unregistered (this will only work if nothing depends on it),
-     * this is primarily used for providers, filters, plugins, etc. which were registered
-     * but are no longer available because the context they are running in is shutting down or restarting <br/>
-     * WARNING: This should not be used to attempt to unregister core services as that will fail
+     * Allows a service to be unregistered (which will only work if
+     * nothing depends on it).
+     * This is primarily used for providers, filters, plugins, etc. 
+     * which were registered but are no longer available because the 
+     * context they are running in is shutting down or restarting.
+     * <br/>
+     * WARNING: This should not be used to attempt to unregister core 
+     * services as that will fail.
      * 
      * @param name the name of the service (must be unique)
      * @throws IllegalArgumentException if the bean cannot be unregistered
@@ -108,9 +136,11 @@ public interface ServiceManager {
     public void unregisterService(String name);
 
     /**
-     * Allows new configuration settings to be pushed into the core DSpace configuration,
-     * these will cause a settings refresh action to be called for all services which are listening
-     * and will cause any bean properties to be pushed into existing beans
+     * Allows new configuration settings to be pushed into the core 
+     * DSpace configuration.
+     * These will cause a settings refresh action to be called for all
+     * services which are listening and will cause any bean properties 
+     * to be pushed into existing beans.
      * 
      * @param settings a map of keys (names) and values
      */