Adding Javadoc

pom.xml

@@ -5,6 +5,12 @@
 
 	<modelVersion>4.0.0</modelVersion>
 
+	<parent>
+		<groupId>org.sonatype.oss</groupId>
+		<artifactId>oss-parent</artifactId>
+		<version>7</version>
+	</parent>
+
 	<groupId>org.zkybase</groupId>
 	<artifactId>kite</artifactId>
 	<version>0.5.0-SNAPSHOT</version>
@@ -28,10 +34,9 @@
 	</licenses>
 
 	<scm>
-		<connection>git://github.com/williewheeler/kite.git</connection>
-		<developerConnection>git@github.com:williewheeler/kite.git</developerConnection>
-		<tag>HEAD</tag>
-		<url>https://github.com/williewheeler/kite</url>
+		<connection>scm:git:git://github.com/williewheeler/kite.git</connection>
+		<developerConnection>scm:git:git@github.com:williewheeler/kite.git</developerConnection>
+		<url>git://github.com/williewheeler/kite.git</url>
 	</scm>
 
 	<developers>

src/main/java/org/zkybase/kite/AbstractGuard.java

@@ -19,6 +19,8 @@
 import org.springframework.jmx.export.annotation.ManagedAttribute;
 
 /**
+ * Abstract base class for implementing guards.
+ * 
  * @author Willie Wheeler (willie.wheeler@gmail.com)
  * @since 1.0
  */

src/main/java/org/zkybase/kite/Guard.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2010-2012 the original author or authors.
+ * Copyright (c) 2010 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.

src/main/java/org/zkybase/kite/GuardCallback.java

@@ -16,10 +16,16 @@
 package org.zkybase.kite;
 
 /**
+ * Callback interface for the {@link Guard} template.
+ * 
  * @author Willie Wheeler (willie.wheeler@gmail.com)
  * @since 1.0
  */
 public interface GuardCallback<T> {
 
+	/**
+	 * @return execution result
+	 * @throws Exception if there's a problem executing the callback
+	 */
 	T doInGuard() throws Exception;
 }

src/main/java/org/zkybase/kite/guard/CircuitBreakerTemplate.java

@@ -15,6 +15,9 @@
  */
 package org.zkybase.kite.guard;
 
+import static org.springframework.util.Assert.isTrue;
+import static org.springframework.util.Assert.notNull;
+
 import java.util.ArrayList;
 import java.util.List;
 import java.util.concurrent.atomic.AtomicInteger;
@@ -24,37 +27,38 @@
 import org.springframework.jmx.export.annotation.ManagedAttribute;
 import org.springframework.jmx.export.annotation.ManagedOperation;
 import org.springframework.jmx.export.annotation.ManagedResource;
-import org.springframework.util.Assert;
 import org.zkybase.kite.AbstractGuard;
 import org.zkybase.kite.GuardCallback;
 import org.zkybase.kite.exception.CircuitOpenException;
 
 /**
  * <p>
- * Template for circuit breakers, which are components designed to protect
- * clients from broken services by preventing faults from propagating across
- * integration points.
+ * Template for circuit breakers, which are components designed to protect clients from broken services by preventing
+ * faults from propagating across integration points.
+ * </p>
+ * <p>
+ * For example, suppose that we have a web application that calls a web service. If the web service is having a problem
+ * (e.g., severe latency or perhaps complete unavailability), we don't want this to create problems for the app. Instead
+ * we want to isolate the problem.
  * </p>
  * <p>
- * For example, suppose that we have a web application that calls a web service.
- * If the web service is having a problem (e.g., severe latency or perhaps
- * complete unavailability), we don't want this to create problems for the app.
- * Instead we want to isolate the problem.
+ * The circuit breaker allows us to do just this. We associate a circuit breaker with each integration point, and the
+ * breaker mediates calls from the client to the service. Under normal circumstances the breaker is in the closed state,
+ * and calls pass through to the service. If however there is a problem, then the breaker goes into the open state for
+ * some period of time. While the breaker is open, all attempts to call the service fail with a {@link
+ * CircuitOpenException}. Once the problem is resolved, the breaker returns to the closed state and normal operations
+ * resume.
  * </p>
  * <p>
- * The circuit breaker allows us to do just this. We associate a circuit breaker
- * with each integration point, and calls from the client to the service are
- * mediated by the breaker. Under normal circumstances the breaker is in the
- * closed state, and calls pass through to the service. If however there is a
- * problem, then the breaker goes into the open state for some period of time.
- * While the breaker is open, all attempts to call the service fail with a
- * {@link CircuitOpenException}. Once the problem is resolved, the breaker
- * returns to the closed state and normal operations resume.
+ * <img src="http://zkybase.org/kite/images/circuit-breaker-state-transition.png" alt="State transition diagram" />
  * </p>
  * <p>
- * The circuit breaker pattern is described in detail in Michael Nygard's book,
- * <a href="http://www.pragprog.com/titles/mnee/release-it">Release It!</a>
- * (Pragmatic).
+ * The circuit breaker pattern is described in detail in Michael Nygard's book, <a
+ * href="http://www.pragprog.com/titles/mnee/release-it">Release It!</a> (Pragmatic).
+ * </p>
+ * <p>
+ * We expose this guard as a JMX MBean so it can be queried and manipulated in management contexts. You can, for
+ * example, use JMX to trip and reset breakers manually.
  * </p>
  * 
  * @author Willie Wheeler (willie.wheeler@gmail.com)
@@ -77,9 +81,7 @@ public enum State { CLOSED, OPEN, HALF_OPEN };
 	private final AtomicInteger exceptionCount = new AtomicInteger();
 	private volatile long retryTime = NO_SCHEDULED_RETRY;
 
-	public CircuitBreakerTemplate() {
-		handledExceptions.add(Exception.class);
-	}
+	public CircuitBreakerTemplate() { handledExceptions.add(Exception.class); }
 
 	/**
 	 * <p>
@@ -90,9 +92,7 @@ public CircuitBreakerTemplate() {
 	 * @return exception threshold for this breaker
 	 */
 	@ManagedAttribute(description = "Breaker trips when threshold is reached")
-	public int getExceptionThreshold() {
-		return exceptionThreshold;
-	}
+	public int getExceptionThreshold() { return exceptionThreshold; }
 
 	/**
 	 * <p>
@@ -112,7 +112,7 @@ public int getExceptionThreshold() {
 		description = "Breaker trips when threshold is reached",
 		defaultValue = "5")
 	public void setExceptionThreshold(int threshold) {
-		Assert.isTrue(threshold >= 1, "threshold must be >= 1");
+		isTrue(threshold >= 1, "threshold must be >= 1");
 		this.exceptionThreshold = threshold;
 	}
 
@@ -141,7 +141,7 @@ public void setExceptionThreshold(int threshold) {
 		description = "Delay in ms before open breaker goes half-open",
 		defaultValue = "30000")
 	public void setTimeout(long timeout) {
-		Assert.isTrue(timeout >= 0L, "timeout must be >= 0");
+		isTrue(timeout >= 0L, "timeout must be >= 0");
 		this.timeout = timeout;
 	}
 
@@ -150,7 +150,7 @@ public List<Class<? extends Exception>> getHandledExceptions() {
 	}
 
 	public void setHandledExceptions(List<Class<? extends Exception>> exceptions) {
-		Assert.notNull(exceptions, "handledExceptions can't be null");
+		notNull(exceptions, "handledExceptions can't be null");
 		this.handledExceptions = exceptions;
 	}
 

src/main/java/org/zkybase/kite/guard/ConcurrencyThrottleTemplate.java

@@ -27,11 +27,14 @@
 
 /**
  * <p>
- * Template component that fails with an exception when a concurrency threshold is exceeded.
+ * Guard that fails with an exception when a concurrency threshold is exceeded.
  * </p>
  * <p>
  * Implementation is based on a counting semaphore.
  * </p>
+ * <p>
+ * We expose this guard as a JMX MBean so it can be queried and manipulated in management contexts.
+ * </p>
  * 
  * @author Willie Wheeler (willie.wheeler@gmail.com)
  * @since 1.0
@@ -44,7 +47,9 @@ public class ConcurrencyThrottleTemplate extends AbstractGuard {
 	private final Semaphore semaphore;
 
 	/**
-	 * @param limit
+	 * Creates a concurrency throttle with the given limit. The throttle rejects requests in excess of the limit.
+	 * 
+	 * @param limit concurrency limit
 	 * @throws IllegalArgumentException if limit &lt; 1
 	 */
 	public ConcurrencyThrottleTemplate(int limit) {

src/main/java/org/zkybase/kite/guard/RateLimitingThrottleTemplate.java

@@ -1,3 +1,18 @@
+/*
+ * Copyright (c) 2012 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
 package org.zkybase.kite.guard;
 
 import java.util.Map;
@@ -22,7 +37,11 @@
  * allow a range of options with respect to the time window.
  * </p>
  * <p>
- * Note that all counts reset on the hour, as measured by the wall clock.
+ * Note that all counts reset on the hour, as measured by the wall clock. This allows us to avoid tracking individual
+ * client requests and their timestamps.
+ * </p>
+ * <p>
+ * We expose this guard as a JMX MBean so it can be queried and manipulated in management contexts.
  * </p>
  * 
  * @author Willie Wheeler (willie.wheeler@gmail.com)