Preparation for publishing to Maven repo -- modifying parent POM, fixing JavaDocs

Author: vsilaev

HEADER.txt

@@ -0,0 +1,18 @@
+Copyright � 2013-2016 Valery Silaev ([email protected])
+
+This project is based on the code licensed to the Apache Software 
+Foundation (ASF) under one or more contributor license agreements.  
+See the NOTICE file distributed with this work for additional information 
+regarding copyright ownership.
+
+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.

NOTICE.txt

@@ -0,0 +1,5 @@
+Apache Commons Javaflow
+Copyright 1999-2004 The Apache Software Foundation
+
+This product includes software developed by
+The Apache Software Foundation (http://www.apache.org/).

net.tascalate.javaflow.api/src/main/java/org/apache/commons/javaflow/api/ContinuableAnnotation.java

@@ -6,6 +6,32 @@
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+/**
+ *
+ * Meta-annotation that is used to annotate other continuation-related annotations.
+ * It provides an option to declare and use own annotations instead of supplied 
+ * {@link continuable} and {@link ccs} annotations, for ex:
+ * 
+ * <pre><code>
+ * import java.lang.annotation.Documented;
+ * import java.lang.annotation.ElementType;
+ * import java.lang.annotation.Retention;
+ * import java.lang.annotation.RetentionPolicy;
+ * import java.lang.annotation.Target;
+ * 
+ * {@literal @}Documented
+ * {@literal @}Retention(RetentionPolicy.CLASS)
+ * {@literal @}Target({ElementType.METHOD})
+ * <b>{@literal @}ContinuableAnnotation</b>
+ * public {@literal @}interface ContinuableMethod {
+ *   // The annotation to mark continuable methods
+ * }
+ * 
+ * </code></pre>
+ * 
+ * @author Valery Silaev
+ *
+ */
 @Documented
 @Retention(RetentionPolicy.CLASS)
 @Target(ElementType.ANNOTATION_TYPE)

net.tascalate.javaflow.api/src/main/java/org/apache/commons/javaflow/api/Continuation.java

@@ -86,16 +86,19 @@ public static Object getContext() {
      * <p>
      * Unlike the {@link #startWith(Runnable)} method, this method doesn't actually
      * execute the <tt>Runnable</tt> object. It will be executed when
-     * it's {@link #resume() continued}.
+     * it's {@link #resume() resumed}.</p>
+     * 
+     * @param target
+     *      The object whose <tt>run</tt> method will be executed. 
      * 
      * @return
      *      always return a non-null valid object.
      */
-    public static Continuation startSuspendedWith( final Runnable pTarget ) {
-        if(pTarget == null) {
+    public static Continuation startSuspendedWith( final Runnable target ) {
+        if(target == null) {
             throw new IllegalArgumentException("target is null");
         }
-        return new Continuation( new StackRecorder(pTarget), null );
+        return new Continuation( new StackRecorder(target), null );
     }
 
     /**
@@ -104,11 +107,15 @@ public static Continuation startSuspendedWith( final Runnable pTarget ) {
      *
      * <p>
      * This is a short hand for <tt>startWith(target,null)</tt>.
-     *
+     * 
+     * @param target
+     *      The object whose <tt>run</tt> method will be executed.  
+     * @return
+     *      Continuation object if runnable supplied is supended, otherwise <code>null</code>
      * @see #startWith(Runnable, Object)
      */
-    public static Continuation startWith( final Runnable pTarget ) {
-        return startWith(pTarget, null);
+    public static Continuation startWith( final Runnable target ) {
+        return startWith(target, null);
     }
 
     /**
@@ -117,7 +124,7 @@ public static Continuation startWith( final Runnable pTarget ) {
      *
      * This method blocks until the continuation suspends or completes.
      *
-     * @param pTarget
+     * @param target
      *      The object whose <tt>run</tt> method will be executed.
      * @param pContext
      *      This value can be obtained from {@link #getContext()} until this method returns.
@@ -128,12 +135,12 @@ public static Continuation startWith( final Runnable pTarget ) {
      *      a new non-null continuation is returned.
      * @see #getContext()
      */
-    public static Continuation startWith( final Runnable pTarget, final Object pContext ) {
+    public static Continuation startWith( final Runnable target, final Object pContext ) {
         if (log.isDebugEnabled()) {
-        	log.debug("starting new flow from " + ReflectionUtils.getClassName(pTarget) + "/" + ReflectionUtils.getClassLoaderName(pTarget));
+        	log.debug("starting new flow from " + ReflectionUtils.getClassName(target) + "/" + ReflectionUtils.getClassLoaderName(target));
         }
 
-        return startSuspendedWith(pTarget).resume(pContext);
+        return startSuspendedWith(target).resume(pContext);
     }
 
     /**
@@ -143,13 +150,21 @@ public static Continuation startWith( final Runnable pTarget, final Object pCont
      *
      * <p>
      * This is a short hand for <tt>continueWith(resumed,null)</tt>.
+     * 
+     * @param continuation
+     *      The suspended continuation to be resumed. Must not be null.
+     * 
+     * @return
+     *      If the execution completes and there's nothing more to continue, return null.
+     *      Otherwise, the execution has been {@link #suspend() suspended}, in which case
+     *      a new non-null continuation is returned.
      *
      * @see #continueWith(Continuation, Object)
      * 
      * @deprecated
      */
-    public static Continuation continueWith(final Continuation pOldContinuation) {
-        return continueWith(pOldContinuation, (Object)null);
+    public static Continuation continueWith(final Continuation continuation) {
+        return continueWith(continuation, (Object)null);
     }
 
     /**
@@ -160,32 +175,39 @@ public static Continuation continueWith(final Continuation pOldContinuation) {
      *
      * This method blocks until the continuation suspends or completes.
      *
-     * @param pOldContinuation
-     *      The resumed continuation to be executed. Must not be null.
-     * @param pContext
-     *      This value can be obtained from {@link #getContext()} until this method returns.
-     *      Can be null.
+     * @param continuation
+     *      The suspended continuation to be resumed. Must not be null.
+     *      
+     * @param value
+     *      The value to be returned as a result form {@link #suspend() Continuation.suspend()} call or 
+     *      from {@link #getContext()} until this method returns. Can be null.
      * @return
      *      If the execution completes and there's nothing more to continue, return null.
      *      Otherwise, the execution has been {@link #suspend() suspended}, in which case
      *      a new non-null continuation is returned.
-     * @see #resume(Object) #getContext()
+     * @see #getContext() 
+     * @see #suspend()
      * 
      * @deprecated
      */
-    public static Continuation continueWith(final Continuation pOldContinuation, final Object pContext) {
-        if (pOldContinuation == null) {
+    public static Continuation continueWith(final Continuation continuation, final Object value) {
+        if (continuation == null) {
             throw new IllegalArgumentException("continuation parameter must not be null.");
         }
 
-        return pOldContinuation.resume(pContext);
+        return continuation.resume(value);
     }
 
     /**
      * Resumes the execution of the specified continuation from where it's left off.
      *
      * <p>
      * This is a short hand for <tt>resume(null)</tt>.
+     * 
+     * @return
+     *      If the execution completes and there's nothing more to continue, return null.
+     *      Otherwise, the execution has been {@link #suspend() suspended}, in which case
+     *      a new non-null continuation is returned.
      *
      * @see #resume(Object)
      * 
@@ -202,20 +224,26 @@ public Continuation resume() {
      * This method blocks until the continuation suspends or completes.
      *
      * @param value
-     *      This value can be obtained from {@link #getContext()} until this method returns.
-     *      Can be null.
+     *      The value to be returned as a result form {@link #suspend() Continuation.suspend()} call or 
+     *      from {@link #getContext()} until this method returns. Can be null.
      * @return
      *      If the execution completes and there's nothing more to continue, return null.
      *      Otherwise, the execution has been {@link #suspend() suspended}, in which case
      *      a new non-null continuation is returned.
      * @see #getContext()
+     * @see #suspend()
      * 
      */    
     public Continuation resume(final Object value) {
     	return resumeWith(ResumeParameter.value(value));
     }
 
-    public void destroy() {
+    /**
+     * Abnormally terminates the suspended call chain represented by this continuation.
+     * <p>Use this method to execute any clean-up code of suspended methods (<code>finally</code> blocks)
+     * when there is no need to {@link #resume()} the continuation.</p>
+     */
+    public void terminate() {
     	resumeWith(ResumeParameter.exit());
     }
 
@@ -242,6 +270,11 @@ protected Continuation resumeWith(final ResumeParameter param) {
         }    	
     }
 
+    /**
+     * Check if captured continuation is serializable
+     * @return
+     *      true if all variables on captured stack and runnable supplied are serializeble, false otherwise.  
+     */
     public boolean isSerializable() {
         return stackRecorder.isSerializable();
     }
@@ -283,11 +316,11 @@ public static Object suspend() {
      * <p>
      * This method can be only called inside {@link #continueWith} or {@link #startWith} methods.
      * When called, the thread returns from the above methods with a new {@link Continuation}
-     * object that captures the thread state and with {@link #result} equals to parameter passed.
+     * object that captures the thread state and with {@link #value()} equals to parameter passed.
      *
      * @param value 
      *      The intermediate result yielded by suspended continuations
-     *      The value may be accessed via {@link #result} method of continuation returned
+     *      The value may be accessed via {@link #value()} method of continuation returned
      *
      * @return
      *      The value to be returned to suspended code after continuation is resumed.

net.tascalate.javaflow.api/src/main/java/org/apache/commons/javaflow/core/ContinuationDeath.java

@@ -5,8 +5,7 @@
  * a control flow change that needs
  * the cooperation inside {@link StackRecorder}.
  *
- * <p>
- * This class is only for javaflow internal code.
+ * <p>This class is only for javaflow internal code.</p>
  *
  * @author Kohsuke Kawaguchi
  */

net.tascalate.javaflow.api/src/main/java/org/apache/commons/javaflow/core/StackRecorder.java

@@ -58,16 +58,21 @@ public final class StackRecorder extends Stack {
 
     /**
      * Creates a new empty {@link StackRecorder} that runs the given target.
+     * @param target
+     *       a target to run
      */
-    public StackRecorder( final Runnable pTarget ) {
-        super(pTarget);
+    public StackRecorder( final Runnable target ) {
+        super(target);
     }
 
     /**
      * Creates a clone of the given {@link StackRecorder}.
+     * @param parent
+     *       a StackRecorder to clone
+     * 
      */
-    public StackRecorder(final Stack pParent) {
-        super(pParent);
+    public StackRecorder(final Stack parent) {
+        super(parent);
     }
 
     public static Object suspend(final SuspendResult value) {
@@ -162,6 +167,12 @@ public static void exit() {
     	throw ContinuationDeath.INSTANCE;
     }
 
+    /**
+     * Access value supplied to resumed method
+     * 
+     * @return value passed to the resumed method (may be <code>null</code>)
+     * 
+     */
     public Object getContext() {
         return null == parameter ? null : parameter.value();
     }
@@ -184,6 +195,8 @@ private void deregisterThread(final StackRecorder old) {
 
     /**
      * Return the continuation, which is associated to the current thread.
+     * @return currently associated continuation stack, or <code>null</code> if invoked outside
+     * of continuation context
      */
     public static StackRecorder get() {
         return threadMap.get();

net.tascalate.javaflow.examples/src/main/java/org/apache/commons/javaflow/examples/cancel/CancelExample.java

@@ -14,7 +14,7 @@ public static void main(final String[] argv) throws Exception {
 			System.out.println("In main after #" + i + " suspend (cc.value = " + cc.value() + ") ");
 		}
 		// This will gracefully complete continuation -- finally blocks will be executed
-		cc.destroy();
+		cc.terminate();
 		System.out.println("In main after destroy");
 		System.out.println("===");
 	}

net.tascalate.javaflow.spi/src/main/java/org/apache/commons/javaflow/spi/ResourceTransformer.java

@@ -20,12 +20,10 @@
  * Byte-code transformer that enhances the class files for javaflow.
  *
  * <p>
- * When {@link Continuation#suspend()} is called, all the methods
+ * When Continuation.suspend is called, all the methods
  * in the stack frame needs to be enhanced.
  *
  * @author tcurdt
- * @see BcelClassTransformer
- * @see AsmClassTransformer
  */
 public interface ResourceTransformer {
     abstract public byte[] transform( byte[] original );

net.tascalate.javaflow.tools.ant/src/main/java/org/apache/commons/javaflow/ant/AntRewriteTask.java

@@ -37,15 +37,19 @@ public class AntRewriteTask extends MatchingTask {
     /**
      * Directory to which the transformed files will be written.
      * This can be the same as the source directory.
+     * 
+     * @param pFile destination directory
      */
     public void setDestdir(final File pFile) {
         dstDir = pFile;
     }
 
     /**
      * Directory from which the input files are read.
-     * This and the inherited {@link MatchingTask} forms an implicit
-     * {@link FileSet}.
+     * This and the inherited MatchingTask forms an implicit
+     * FileSet.
+     * 
+     * @param pFile source directory
      */
     public void setSrcDir(final File pFile) {
         srcDir = pFile;

net.tascalate.javaflow.tools.cdi-javaagent/src/main/java/org/apache/commons/javaflow/instrumentation/cdi/CdiProxyInstrumentationAgent.java

@@ -11,7 +11,7 @@ public class CdiProxyInstrumentationAgent {
      * will be called. Then the real application main method will be called.
      * 
      * @param args
-     * @param inst
+     * @param instrumentation
      * @throws Exception
      */
     public static void premain(String args, Instrumentation instrumentation) throws Exception {
@@ -25,7 +25,7 @@ public static void premain(String args, Instrumentation instrumentation) throws
      * started after VM startup.
      * 
      * @param args
-     * @param inst
+     * @param instrumentation
      * @throws Exception
      */
     public static void agentmain(String args, Instrumentation instrumentation) throws Exception {