Version 1.2.2-SNAPSHOT pre-release

src/main/java/com/conversantmedia/util/collection/FixedStack.java

@@ -1,5 +1,25 @@
 package com.conversantmedia.util.collection;
 
+/*
+ * #%L
+ * Conversant Disruptor
+ * ~~
+ * Conversantmedia.com © 2016, Conversant, Inc. Conversant® is a trademark of Conversant, Inc.
+ * ~~
+ * 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.
+ * #L%
+ */
+
 /**
  * A very high performance stack to replace java.util.Stack.  This
  * stack wraps around rather than checking for bounds.
@@ -13,43 +33,46 @@
  *
  * This object is not thread safe.
  *
- * @author John Cairns <jcairns@dotomi.com> Date: 7/9/12 Time: 8:53 AM
+ * @author John Cairns  {@literal <john@2ad.com>} Date: 7/9/12 Time: 8:53 AM
  */
 public class FixedStack<N> implements Stack<N> {
-	// implement a ring buffer to make sure that it is always safe to push an object into the stack,
-	// if stack size is exceeded, the eldest objects are overwritten
-	private final int size;
-	private final int mask;
-	private final N[] stack;
-	// use a ring buffer to avoid object manipulation on the stack
-	private int   stackTop;
+    // implement a ring buffer to make sure that it is always safe to push an object into the stack,
+    // if stack size is exceeded, the eldest objects are overwritten
+    private final int size;
+    private final int mask;
+    private final N[] stack;
+    // use a ring buffer to avoid object manipulation on the stack
+    private int   stackTop;
 
-	/**
-	 *	 construct a new stack of given capacity
-	 */
-	public FixedStack(final int size) {
-		int stackSize = 1;
-		while(stackSize < size) stackSize <<=1;
-		this.size = stackSize;
-		this.mask = this.size-1;
-		stack = (N[])new Object[stackSize];
-		stackTop=0;
-	}
+    /**
+     *   construct a new stack of given capacity
+     * 
+     * @param size - the stack size 
+     */
+    public FixedStack(final int size) {
+        int stackSize = 1;
+        while(stackSize < size) stackSize <<=1;
+        this.size = stackSize;
+        this.mask = this.size-1;
+        stack = (N[])new Object[stackSize];
+        stackTop=0;
+    }
 
-	/**
-	 *	add a node to the stack
-	 *
-	 * @param n
-	 */
-	@Override
-	public boolean push(final N n) {
-		if(stackTop < size) {
-			stack[(stackTop++) & mask] = n;
-			return true;
-		}
-		return false;
+    /**
+     *  add an element to the stack
+     *
+     * @param n - the element to add
+     * @return boolean - true if the operation succeeded
+     */
+    @Override
+    public boolean push(final N n) {
+        if(stackTop < size) {
+            stack[(stackTop++) & mask] = n;
+            return true;
+        }
+        return false;
 
-	}
+    }
 
     @Override
     public boolean contains(final N n) {
@@ -60,65 +83,65 @@ public boolean contains(final N n) {
         return false;
     }
 
-	/**
-	 *	peek at the top of the stack
-	 *
-	 * @return N - the object at the top of the stack
-	 */
-	@Override
-	public N peek() {
-		return stack[(stackTop-1)&mask];
-	}
+    /**
+     *  peek at the top of the stack
+     *
+     * @return N - the object at the top of the stack
+     */
+    @Override
+    public N peek() {
+        return stack[(stackTop-1)&mask];
+    }
 
-	/**
-	 * pop the next element off the stack
-	 * @return N - The object on the top of the stack
-	 */
-	@Override
-	public N pop() {
-		try {
-			return stack[(--stackTop)&mask];
-		} finally {
-			// remove the reference to the element in the
-			// stack to prevent hanging references from living forever
-			stack[(stackTop&mask)] = null;
-		}
-	}
+    /**
+     * pop the next element off the stack
+     * @return N - The object on the top of the stack
+     */
+    @Override
+    public N pop() {
+        try {
+            return stack[(--stackTop)&mask];
+        } finally {
+            // remove the reference to the element in the
+            // stack to prevent hanging references from living forever
+            stack[(stackTop&mask)] = null;
+        }
+    }
 
-	// return the size of the stack
+    // return the size of the stack
 
-	/**
-	 * Return the size of the stack
-	 * @return int - number of elements in the stack
-	 */
-	@Override
-	public int size() {
-		return stackTop;
-	}
+    /**
+     * Return the size of the stack
+     * @return int - number of elements in the stack
+     */
+    @Override
+    public int size() {
+        return stackTop;
+    }
 
-	/**
-	 * how much available space in the stack
-	 */
-	@Override
-	public int remainingCapacity() {
-		return size - stackTop;
-	}
+    /**
+     * how much available space in the stack
+     */
+    @Override
+    public int remainingCapacity() {
+        return size - stackTop;
+    }
 
-	/**
-	 *
-	 * @return boolean - true if stack is currently empty
-	 */
-	@Override
-	public boolean isEmpty() {
-		return stackTop==0;
-	}
+    /**
+     *
+     * @return boolean - true if stack is currently empty
+     */
+    @Override
+    public boolean isEmpty() {
+        return stackTop==0;
+    }
 
-	/**
-	 *  clear the stack
-	 */
-	@Override
+    /**
+     *  clear the stack
+     */
+    @Override
     public void clear() {
-		stackTop=0;
-	}
+        stackTop=0;
+    }
 
 }

src/main/java/com/conversantmedia/util/collection/Stack.java

@@ -25,11 +25,10 @@
  */
 public interface Stack<N> {
 
-
     /**
      * Linear search the stack for contains - not an efficient operation
      *
-     * @param n
+     * @param n - Object to test for containment
      * @return boolean - true if n is contained somewhere in the stack
      */
     boolean contains(N n);
@@ -38,14 +37,14 @@ public interface Stack<N> {
      * Add the element to the stack top, optionally failing if there is
      * no capacity (overflow)
      *
-     * @param n
-     * @return
+     * @param n - element to push
+     * @return boolean - true if push succeeded
      */
     boolean push(N n);
 
     /**
      * show the current stack top
-     * @return
+     * @return N - the element at the top of the stack or null
      */
     N peek();
 
@@ -57,16 +56,12 @@ public interface Stack<N> {
     N pop();
 
     /**
-     * return the size of the stack in number of elements
-     *
-     * @return
+     * @return int - the size of the stack in number of elements
      */
     int size();
 
     /**
-     * return the number of empty slots available in the stack
-     *
-     * @return
+     * @return int - the number of empty slots available in the stack
      */
     int remainingCapacity();
 
@@ -79,4 +74,5 @@ public interface Stack<N> {
      * clear the stack
      */
     void clear();
+
 }

src/main/java/com/conversantmedia/util/concurrent/BlockingStack.java

@@ -36,6 +36,8 @@ public interface BlockingStack<N> extends Stack<N> {
      * @param time - the maximum time to wait
      * @param unit - unit of waiting time
      * @return boolean - true if item was pushed, false otherwise
+     *
+     * @throws InterruptedException on interrupt
      */
     boolean push(final N n, final long time, final TimeUnit unit) throws InterruptedException;
 
@@ -53,6 +55,8 @@ public interface BlockingStack<N> extends Stack<N> {
      * @param time - the maximum time to wait
      * @param unit - the time unit for the waiting time
      * @return N - the popped element, or null in the event of a timeout
+     *
+     * @throws InterruptedException on interrupt
      */
     N pop(final long time, final TimeUnit unit) throws InterruptedException;
 
@@ -64,4 +68,5 @@ public interface BlockingStack<N> extends Stack<N> {
      * @throws InterruptedException - in the event the current thread is interrupted prior to popping any element
      */
     N popInterruptibly() throws InterruptedException;
+
 }

src/main/java/com/conversantmedia/util/concurrent/ConcurrentStack.java

@@ -115,7 +115,7 @@ public boolean contains(final N n) {
     /**
      * add an element to the stack, failing if the stack is unable to grow
      *
-     * @param n
+     * @param n - the element to push
      *
      * @return boolean - false if stack overflow, true otherwise
      */

src/main/java/com/conversantmedia/util/concurrent/OptimisticLock.java

@@ -18,7 +18,7 @@ public interface OptimisticLock {
      * check if optimistic locking succeeded
      *
      * @param lockToken - the value returned from tryLock
-     * @return
+     * @return boolean - true if lock was held
      */
     boolean readLockHeld(long lockToken);
 
@@ -32,7 +32,7 @@ public interface OptimisticLock {
     /**
      * @return long - the token indicating the lock state
      *
-     * @throws InterruptedException
+     * @throws InterruptedException - on interrupt
      */
     long tryWriteLockInterruptibly() throws InterruptedException;
 
@@ -43,13 +43,15 @@ public interface OptimisticLock {
 
     /**
      * @return long - the token indicating the lock state, or 0 if not available
+     *
+     * @throws InterruptedException on interrupt
      */
     long tryWriteLock(long time, TimeUnit unit) throws InterruptedException;
 
     /**
      * "commit" or unlock the sequence when the write lock is held
      *
-     * @param sequence
+     * @param sequence - lock sequence to unlock
      */
     void unlock(final long sequence);
 

src/main/java/com/conversantmedia/util/estimation/Percentile.java

@@ -101,7 +101,7 @@ public void clear() {
     /**
      * Add a measurement to estimate
      *
-     * @param x
+     * @param x - the value of the measurement
      */
     public void add(final float x) {
         if(isInitializing) {