Mailing-List: contact commits-help@camel.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@camel.apache.org
Content-Type: text/plain; charset="us-ascii"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
From: bvahdat@apache.org
To: commits@camel.apache.org
Message-Id: <5634a93e4cae41c993430d0563c0b9cd@git.apache.org>
Subject: git commit: CAMEL-6951: Improve ServiceHelper utility class.
Date: Sun, 10 Nov 2013 12:56:19 +0000 (UTC)

Updated Branches:
  refs/heads/master a185e7d76 -> 435026f23


CAMEL-6951: Improve ServiceHelper utility class.

Project: http://git-wip-us.apache.org/repos/asf/camel/repo
Commit: http://git-wip-us.apache.org/repos/asf/camel/commit/435026f2
Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/435026f2
Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/435026f2

Branch: refs/heads/master
Commit: 435026f23c6b49ced53d4e301dee45e8bbe8361a
Parents: a185e7d
Author: Babak Vahdat <bvahdat@apache.org>
Authored: Sun Nov 10 13:56:07 2013 +0100
Committer: Babak Vahdat <bvahdat@apache.org>
Committed: Sun Nov 10 13:56:07 2013 +0100

----------------------------------------------------------------------
 .../org/apache/camel/impl/ProducerCache.java    |   4 +-
 .../org/apache/camel/util/ServiceHelper.java    | 185 +++++++++++++------
 2 files changed, 134 insertions(+), 55 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/camel/blob/435026f2/camel-core/src/main/java/org/apache/camel/impl/ProducerCache.java
----------------------------------------------------------------------
diff --git a/camel-core/src/main/java/org/apache/camel/impl/ProducerCache.java b/camel-core/src/main/java/org/apache/camel/impl/ProducerCache.java
index 4b2a172..dd3b0a0 100644
--- a/camel-core/src/main/java/org/apache/camel/impl/ProducerCache.java
+++ b/camel-core/src/main/java/org/apache/camel/impl/ProducerCache.java
@@ -259,7 +259,7 @@ public class ProducerCache extends ServiceSupport {
                     ServiceHelper.stopAndShutdownService(producer);
                 } catch (Exception e) {
                     // ignore and continue
-                    LOG.warn("Error stopping/shutdown producer: " + producer, e);
+                    LOG.warn("Error stopping/shutting down producer: " + producer, e);
                 }
             }
         }
@@ -323,7 +323,7 @@ public class ProducerCache extends ServiceSupport {
                                 ServiceHelper.stopAndShutdownService(producer);
                             } catch (Exception e) {
                                 // ignore and continue
-                                LOG.warn("Error stopping/shutdown producer: " + producer, e);
+                                LOG.warn("Error stopping/shutting down producer: " + producer, e);
                             }
                         }
                     } finally {

http://git-wip-us.apache.org/repos/asf/camel/blob/435026f2/camel-core/src/main/java/org/apache/camel/util/ServiceHelper.java
----------------------------------------------------------------------
diff --git a/camel-core/src/main/java/org/apache/camel/util/ServiceHelper.java b/camel-core/src/main/java/org/apache/camel/util/ServiceHelper.java
index b613d13..9709723 100644
--- a/camel-core/src/main/java/org/apache/camel/util/ServiceHelper.java
+++ b/camel-core/src/main/java/org/apache/camel/util/ServiceHelper.java
@@ -33,9 +33,9 @@ import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
 /**
- * A collection of helper methods for working with {@link Service} objects
- *
- * @version 
+ * A collection of helper methods for working with {@link Service} objects.
+ * 
+ * @version
  */
 public final class ServiceHelper {
     private static final Logger LOG = LoggerFactory.getLogger(ServiceHelper.class);
@@ -47,7 +47,12 @@ public final class ServiceHelper {
     }
 
     /**
-     * Starts all of the given services
+     * Starts the given {@code value} if it's a {@link Service} or a collection of it.
+     * <p/>
+     * Calling this method has no effect if {@code value} is {@code null}.
+     * 
+     * @see #startService(Service)
+     * @see #startServices(Collection)
      */
     public static void startService(Object value) throws Exception {
         if (value instanceof Service) {
@@ -58,7 +63,11 @@ public final class ServiceHelper {
     }
     
     /**
-     * Start the given service
+     * Starts the given {@code service}.
+     * <p/>
+     * Calling this method has no effect if {@code service} is {@code null}.
+     * 
+     * @see Service#start()
      */
     public static void startService(Service service) throws Exception {
         if (service != null) {
@@ -67,19 +76,24 @@ public final class ServiceHelper {
     }
 
     /**
-     * Starts all of the given services
+     * Starts each element of the given {@code services} if {@code services} itself is
+     * not {@code null}, otherwise this method would return immediately.
+     * 
+     * @see #startServices(Collection)
      */
     public static void startServices(Object... services) throws Exception {
         if (services == null) {
             return;
         }
-        for (Object value : services) {
-            startService(value);
-        }
+        List<Object> list = Arrays.asList(services);
+        startServices(list);
     }
 
     /**
-     * Starts all of the given services
+     * Starts each element of the given {@code services} if {@code services} itself is
+     * not {@code null}, otherwise this method would return immediately.
+     * 
+     * @see #startService(Object)
      */
     public static void startServices(Collection<?> services) throws Exception {
         if (services == null) {
@@ -91,7 +105,13 @@ public final class ServiceHelper {
     }
 
     /**
-     * Stops all of the given services, throwing the first exception caught
+     * Stops each element of the given {@code services} if {@code services} itself is
+     * not {@code null}, otherwise this method would return immediately.
+     * <p/>
+     * If there's any exception being thrown while stopping the elements one after the
+     * other this method would rethrow the <b>first</b> such exception being thrown.
+     * 
+     * @see #stopServices(Collection)
      */
     public static void stopServices(Object... services) throws Exception {
         if (services == null) {
@@ -102,7 +122,12 @@ public final class ServiceHelper {
     }
 
     /**
-     * Stops the given service, throwing the first exception caught
+     * Stops the given {@code value}, rethrowing the first exception caught.
+     * <p/>
+     * Calling this method has no effect if {@code value} is {@code null}.
+     * 
+     * @see Service#stop()
+     * @see #stopServices(Collection)
      */
     public static void stopService(Object value) throws Exception {
         if (isStopped(value)) {
@@ -120,7 +145,13 @@ public final class ServiceHelper {
     }
 
     /**
-     * Stops all of the given services, throwing the first exception caught
+     * Stops each element of the given {@code services} if {@code services} itself is
+     * not {@code null}, otherwise this method would return immediately.
+     * <p/>
+     * If there's any exception being thrown while stopping the elements one after the
+     * other this method would rethrow the <b>first</b> such exception being thrown.
+     * 
+     * @see #stopService(Object)
      */
     public static void stopServices(Collection<?> services) throws Exception {
         if (services == null) {
@@ -145,7 +176,13 @@ public final class ServiceHelper {
     }
 
     /**
-     * Stops and shutdowns all of the given services, throwing the first exception caught
+     * Stops and shutdowns each element of the given {@code services} if {@code services} itself is
+     * not {@code null}, otherwise this method would return immediately.
+     * <p/>
+     * If there's any exception being thrown while stopping/shutting down the elements one after
+     * the other this method would rethrow the <b>first</b> such exception being thrown.
+     * 
+     * @see #stopAndShutdownServices(Collection)
      */
     public static void stopAndShutdownServices(Object... services) throws Exception {
         if (services == null) {
@@ -156,7 +193,12 @@ public final class ServiceHelper {
     }
 
     /**
-     * Stops and shutdowns the given service, throwing the first exception caught
+     * Stops and shutdowns the given {@code service}, rethrowing the first exception caught.
+     * <p/>
+     * Calling this method has no effect if {@code value} is {@code null}.
+     * 
+     * @see #stopService(Object)
+     * @see ShutdownableService#shutdown()
      */
     public static void stopAndShutdownService(Object value) throws Exception {
         stopService(value);
@@ -170,7 +212,14 @@ public final class ServiceHelper {
     }
 
     /**
-     * Stops and shutdowns all of the given services, throwing the first exception caught
+     * Stops and shutdowns each element of the given {@code services} if {@code services}
+     * itself is not {@code null}, otherwise this method would return immediately.
+     * <p/>
+     * If there's any exception being thrown while stopping/shutting down the elements one after
+     * the other this method would rethrow the <b>first</b> such exception being thrown.
+     * 
+     * @see #stopService(Object)
+     * @see ShutdownableService#shutdown()
      */
     public static void stopAndShutdownServices(Collection<?> services) throws Exception {
         if (services == null) {
@@ -180,22 +229,22 @@ public final class ServiceHelper {
 
         for (Object value : services) {
 
-            // must stop it first
-            stopService(value);
+            try {
+                // must stop it first
+                stopService(value);
 
-            // then try to shutdown
-            if (value instanceof ShutdownableService) {
-                ShutdownableService service = (ShutdownableService)value;
-                try {
+                // then try to shutdown
+                if (value instanceof ShutdownableService) {
+                    ShutdownableService service = (ShutdownableService)value;
                     LOG.trace("Shutting down service: {}", service);
                     service.shutdown();
-                } catch (Exception e) {
-                    if (LOG.isDebugEnabled()) {
-                        LOG.debug("Caught exception shutting down service: " + service, e);
-                    }
-                    if (firstException == null) {
-                        firstException = e;
-                    }
+                }
+            } catch (Exception e) {
+                if (LOG.isDebugEnabled()) {
+                    LOG.debug("Caught exception shutting down service: " + value, e);
+                }
+                if (firstException == null) {
+                    firstException = e;
                 }
             }
         }
@@ -204,6 +253,15 @@ public final class ServiceHelper {
         }
     }
 
+    /**
+     * Resumes each element of the given {@code services} if {@code services} itself is
+     * not {@code null}, otherwise this method would return immediately.
+     * <p/>
+     * If there's any exception being thrown while resuming the elements one after the
+     * other this method would rethrow the <b>first</b> such exception being thrown.
+     * 
+     * @see #resumeService(Service)
+     */
     public static void resumeServices(Collection<?> services) throws Exception {
         if (services == null) {
             return;
@@ -230,20 +288,25 @@ public final class ServiceHelper {
     }
 
     /**
-     * Resumes the given service.
+     * Resumes the given {@code service}.
      * <p/>
-     * If the service is a {@link org.apache.camel.SuspendableService} then the <tt>resume</tt>
-     * operation is <b>only</b> invoked if the service is suspended.
+     * If {@code service} is a {@link org.apache.camel.SuspendableService} then
+     * it's {@link org.apache.camel.SuspendableService#resume()} is called but
+     * <b>only</b> if {@code service} is already {@link #isSuspended(Object)
+     * suspended}.
      * <p/>
-     * If the service is a {@link org.apache.camel.support.ServiceSupport} then the <tt>start</tt>
-     * operation is <b>only</b> invoked if the service is startable.
+     * If {@code service} is <b>not</b> a
+     * {@link org.apache.camel.SuspendableService} then it's
+     * {@link org.apache.camel.Service#start()} is called.
      * <p/>
-     * Otherwise the service is started.
-     *
+     * Calling this method has no effect if {@code service} is {@code null}.
+     * 
      * @param service the service
-     * @return <tt>true</tt> if either <tt>resume</tt> or <tt>start</tt> was invoked,
-     * <tt>false</tt> if the service is already in the desired state.
+     * @return <tt>true</tt> if either <tt>resume</tt> method or
+     *         {@link #startService(Service)} was called, <tt>false</tt>
+     *         otherwise.
      * @throws Exception is thrown if error occurred
+     * @see #startService(Service)
      */
     public static boolean resumeService(Service service) throws Exception {
         if (service instanceof SuspendableService) {
@@ -261,6 +324,15 @@ public final class ServiceHelper {
         }
     }
 
+    /**
+     * Suspends each element of the given {@code services} if {@code services} itself is
+     * not {@code null}, otherwise this method would return immediately.
+     * <p/>
+     * If there's any exception being thrown while suspending the elements one after the
+     * other this method would rethrow the <b>first</b> such exception being thrown.
+     * 
+     * @see #suspendService(Service)
+     */
     public static void suspendServices(Collection<?> services) throws Exception {
         if (services == null) {
             return;
@@ -287,20 +359,25 @@ public final class ServiceHelper {
     }
 
     /**
-     * Suspends the given service.
+     * Suspends the given {@code service}.
      * <p/>
-     * If the service is a {@link org.apache.camel.SuspendableService} then the <tt>suspend</tt>
-     * operation is <b>only</b> invoked if the service is <b>not</b> suspended.
+     * If {@code service} is a {@link org.apache.camel.SuspendableService} then
+     * it's {@link org.apache.camel.SuspendableService#suspend()} is called but
+     * <b>only</b> if {@code service} is <b>not</b> already
+     * {@link #isSuspended(Object) suspended}.
      * <p/>
-     * If the service is a {@link org.apache.camel.support.ServiceSupport} then the <tt>stop</tt>
-     * operation is <b>only</b> invoked if the service is stoppable.
+     * If {@code service} is <b>not</b> a
+     * {@link org.apache.camel.SuspendableService} then it's
+     * {@link org.apache.camel.Service#stop()} is called.
      * <p/>
-     * Otherwise the service is stopped.
-     *
+     * Calling this method has no effect if {@code service} is {@code null}.
+     * 
      * @param service the service
-     * @return <tt>true</tt> if either <tt>suspend</tt> or <tt>stop</tt> was invoked,
-     * <tt>false</tt> if the service is already in the desired state.
+     * @return <tt>true</tt> if either the <tt>suspend</tt> method or
+     *         {@link #stopService(Object)} was called, <tt>false</tt>
+     *         otherwise.
      * @throws Exception is thrown if error occurred
+     * @see #stopService(Object)
      */
     public static boolean suspendService(Service service) throws Exception {
         if (service instanceof SuspendableService) {
@@ -321,7 +398,7 @@ public final class ServiceHelper {
     /**
      * Is the given service stopping or stopped?
      *
-     * @return <tt>true</tt> if already stopped, otherwise <tt>false</tt>
+     * @return <tt>true</tt> if already stopped, <tt>false</tt> otherwise
      */
     public static boolean isStopped(Object value) {
         if (value instanceof StatefulService) {
@@ -336,7 +413,7 @@ public final class ServiceHelper {
     /**
      * Is the given service starting or started?
      *
-     * @return <tt>true</tt> if already started, otherwise <tt>false</tt>
+     * @return <tt>true</tt> if already started, <tt>false</tt> otherwise
      */
     public static boolean isStarted(Object value) {
         if (value instanceof StatefulService) {
@@ -349,9 +426,9 @@ public final class ServiceHelper {
     }
     
     /**
-     * Is the given service suspended
+     * Is the given service suspended?
      *
-     * @return <tt>true</tt> if already suspended, otherwise <tt>false</tt>
+     * @return <tt>true</tt> if already suspended, <tt>false</tt> otherwise
      */
     public static boolean isSuspended(Object value) {
         if (value instanceof StatefulService) {
@@ -364,7 +441,9 @@ public final class ServiceHelper {
     }
 
     /**
-     * Gather all child services by navigating the service to recursively gather all child services.
+     * Gathers all child services by navigating the service to recursively gather all child services.
+     * <p/>
+     * The returned set does <b>not</b> include the childern being error handler.
      *
      * @param service the service
      * @return the services, including the parent service, and all its children
@@ -374,7 +453,7 @@ public final class ServiceHelper {
     }
 
     /**
-     * Gather all child services by navigating the service to recursively gather all child services.
+     * Gathers all child services by navigating the service to recursively gather all child services.
      *
      * @param service the service
      * @param includeErrorHandler whether to include error handlers