Repository: commons-scxml Updated Branches: refs/heads/master 5a5bf80da -> e3c841e10
SCXML-237 fix javadoc errors Project: http://git-wip-us.apache.org/repos/asf/commons-scxml/repo Commit: http://git-wip-us.apache.org/repos/asf/commons-scxml/commit/e3c841e1 Tree: http://git-wip-us.apache.org/repos/asf/commons-scxml/tree/e3c841e1 Diff: http://git-wip-us.apache.org/repos/asf/commons-scxml/diff/e3c841e1 Branch: refs/heads/master Commit: e3c841e10f951fc54b51e7949d7a65f996c73b8d Parents: 5a5bf80 Author: Woonsan Ko <woon...@apache.org> Authored: Sat Jul 25 16:25:43 2015 -0400 Committer: Woonsan Ko <woon...@apache.org> Committed: Sat Jul 25 16:25:43 2015 -0400 ---------------------------------------------------------------------- .../commons/scxml2/ActionExecutionContext.java | 1 + .../org/apache/commons/scxml2/Evaluator.java | 2 +- .../apache/commons/scxml2/EvaluatorFactory.java | 24 +++++++++--------- .../org/apache/commons/scxml2/SCInstance.java | 4 ++- .../apache/commons/scxml2/SCXMLExecutor.java | 4 +-- .../apache/commons/scxml2/SCXMLSemantics.java | 26 ++++++++++---------- .../org/apache/commons/scxml2/TriggerEvent.java | 12 ++++----- .../scxml2/env/AbstractStateMachine.java | 7 ++++-- .../commons/scxml2/env/EffectiveContextMap.java | 5 +++- .../org/apache/commons/scxml2/env/LogUtils.java | 1 + .../commons/scxml2/env/SimpleErrorReporter.java | 10 ++++++++ .../scxml2/env/groovy/GroovyContext.java | 7 ++++-- .../scxml2/env/groovy/GroovyEvaluator.java | 2 ++ .../env/groovy/GroovyExtendableScriptCache.java | 22 ++++++++--------- .../scxml2/env/groovy/GroovySCXMLScript.java | 24 ++++++++++++------ .../scxml2/env/javascript/JSEvaluator.java | 2 +- .../scxml2/env/javascript/JSFunctions.java | 2 ++ .../commons/scxml2/env/jexl/JexlBuiltin.java | 2 ++ .../apache/commons/scxml2/invoke/Invoker.java | 25 +++++++++---------- .../apache/commons/scxml2/io/SCXMLReader.java | 16 ++++++------ .../commons/scxml2/model/ActionsContainer.java | 6 +++-- .../commons/scxml2/model/PayloadProvider.java | 2 +- .../commons/scxml2/model/SimpleTransition.java | 5 +++- .../scxml2/semantics/SCXMLSemanticsImpl.java | 10 +++++--- 24 files changed, 132 insertions(+), 89 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/commons-scxml/blob/e3c841e1/src/main/java/org/apache/commons/scxml2/ActionExecutionContext.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/scxml2/ActionExecutionContext.java b/src/main/java/org/apache/commons/scxml2/ActionExecutionContext.java index 29e13c3..96c6d1b 100644 --- a/src/main/java/org/apache/commons/scxml2/ActionExecutionContext.java +++ b/src/main/java/org/apache/commons/scxml2/ActionExecutionContext.java @@ -54,6 +54,7 @@ public class ActionExecutionContext { } /** + * @param state an EnterableState * @return Returns the context for an EnterableState */ public Context getContext(EnterableState state) { http://git-wip-us.apache.org/repos/asf/commons-scxml/blob/e3c841e1/src/main/java/org/apache/commons/scxml2/Evaluator.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/scxml2/Evaluator.java b/src/main/java/org/apache/commons/scxml2/Evaluator.java index 58f9181..ae2e744 100644 --- a/src/main/java/org/apache/commons/scxml2/Evaluator.java +++ b/src/main/java/org/apache/commons/scxml2/Evaluator.java @@ -36,7 +36,7 @@ public interface Evaluator { String DEFAULT_DATA_MODEL = ""; /** - * The allowable types of <assign/> including and in particular when using XPath + * The allowable types of <assign/> including and in particular when using XPath */ enum AssignType { http://git-wip-us.apache.org/repos/asf/commons-scxml/blob/e3c841e1/src/main/java/org/apache/commons/scxml2/EvaluatorFactory.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/scxml2/EvaluatorFactory.java b/src/main/java/org/apache/commons/scxml2/EvaluatorFactory.java index 6a42608..e306e0a 100644 --- a/src/main/java/org/apache/commons/scxml2/EvaluatorFactory.java +++ b/src/main/java/org/apache/commons/scxml2/EvaluatorFactory.java @@ -36,21 +36,21 @@ import static org.apache.commons.scxml2.Evaluator.DEFAULT_DATA_MODEL; * </p> * <p> * The builtin supported providers are: - * <ul> - * <li>no or empty datamodel (default) or datamodel="jexl": {@link JexlEvaluator.JexlEvaluatorProvider}</li> - * <li>datamodel="ecmascript": {@link JSEvaluator.JSEvaluatorProvider}</li> - * <li>datamodel="groovy": {@link GroovyEvaluator.GroovyEvaluatorProvider}</li> - * <li>datamodel="xpath": {@link XPathEvaluator.XPathEvaluatorProvider}</li> - * <li>datamodel="null": {@link MinimalEvaluator.MinimalEvaluatorProvider}</li> - * </ul> - * </p> - * <p> + * </p> + * <ul> + * <li>no or empty datamodel (default) or datamodel="jexl": {@link JexlEvaluator.JexlEvaluatorProvider}</li> + * <li>datamodel="ecmascript": {@link JSEvaluator.JSEvaluatorProvider}</li> + * <li>datamodel="groovy": {@link GroovyEvaluator.GroovyEvaluatorProvider}</li> + * <li>datamodel="xpath": {@link XPathEvaluator.XPathEvaluatorProvider}</li> + * <li>datamodel="null": {@link MinimalEvaluator.MinimalEvaluatorProvider}</li> + * </ul> + * <p> * For adding additional or overriding the builtin Evaluator implementations use * {@link #registerEvaluatorProvider(EvaluatorProvider)} or {@link #unregisterEvaluatorProvider(String)}. - * </p> - * <p> + * </p> + * <p> * The default provider can be overridden using the {@link #setDefaultProvider(EvaluatorProvider)} which will - * register the provider under the {@link Evaluator#DEFAULT_DATA_MODEL} ("") value for the datamodel.<br/> + * register the provider under the {@link Evaluator#DEFAULT_DATA_MODEL} ("") value for the datamodel.<br> * Note: this is <em>not</em> the same as datamodel="null"! * </p> */ http://git-wip-us.apache.org/repos/asf/commons-scxml/blob/e3c841e1/src/main/java/org/apache/commons/scxml2/SCInstance.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/scxml2/SCInstance.java b/src/main/java/org/apache/commons/scxml2/SCInstance.java index 562a5ff..6b0e5b8 100644 --- a/src/main/java/org/apache/commons/scxml2/SCInstance.java +++ b/src/main/java/org/apache/commons/scxml2/SCInstance.java @@ -206,7 +206,9 @@ public class SCInstance implements Serializable { * If not re-attaching and this state machine instance has been initialized before, * it will be initialized again, destroying all existing state! * </p> - * @param evaluator The evaluator for this state machine instance. + * @param evaluator The evaluator for this state machine instance + * @param reAttach Flag whether or not re-attaching it + * @throws ModelException if {@code evaluator} is null */ protected void setEvaluator(Evaluator evaluator, boolean reAttach) throws ModelException { this.evaluator = evaluator; http://git-wip-us.apache.org/repos/asf/commons-scxml/blob/e3c841e1/src/main/java/org/apache/commons/scxml2/SCXMLExecutor.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/scxml2/SCXMLExecutor.java b/src/main/java/org/apache/commons/scxml2/SCXMLExecutor.java index cef47fd..78f17f6 100644 --- a/src/main/java/org/apache/commons/scxml2/SCXMLExecutor.java +++ b/src/main/java/org/apache/commons/scxml2/SCXMLExecutor.java @@ -142,8 +142,8 @@ public class SCXMLExecutor implements SCXMLIOProcessor { * @param atomicStateIds The set of atomic state ids for the state machine * @throws ModelException when the state machine hasn't been properly configured yet, when an unknown or illegal * stateId is specified, or when the specified active configuration does not represent a legal configuration. - * @see {@link SCInstance#initialize()} - * @see {@link SCXMLSemantics#isLegalConfiguration(java.util.Set, ErrorReporter)} + * @see SCInstance#initialize() + * @see SCXMLSemantics#isLegalConfiguration(java.util.Set, ErrorReporter) */ public synchronized void setConfiguration(Set<String> atomicStateIds) throws ModelException { exctx.initialize(); http://git-wip-us.apache.org/repos/asf/commons-scxml/blob/e3c841e1/src/main/java/org/apache/commons/scxml2/SCXMLSemantics.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/scxml2/SCXMLSemantics.java b/src/main/java/org/apache/commons/scxml2/SCXMLSemantics.java index a473903..ae24472 100644 --- a/src/main/java/org/apache/commons/scxml2/SCXMLSemantics.java +++ b/src/main/java/org/apache/commons/scxml2/SCXMLSemantics.java @@ -29,20 +29,20 @@ import org.apache.commons.scxml2.model.SCXML; * from the <code>SCXMLExecutor</code> and therefore make it pluggable.</p> * <p> * From an SCXML execution POV, there are only three entry points needed into the Algorithm, namely: + * </p> * <ul> - * <li>Performing the initialization of the state machine and completing a first macro step, - * see: {@link #firstStep(SCXMLExecutionContext)}. The state machine thereafter should be ready - * for processing external events (or be terminated already)</li> - * <li>Processing a single external event and completing the macro step for it, after which the - * state machine should be ready for processing another external event (if any), or be terminated already. - * See: {@link #nextStep(SCXMLExecutionContext, TriggerEvent)}. - * </li> - * <li>Finally, if the state machine terminated ({@link SCXMLExecutionContext#isRunning()} == false), after either - * of the above steps, finalize the state machine by performing the final step. - * See: {@link #finalStep(SCXMLExecutionContext)}. - * </li> + * <li>Performing the initialization of the state machine and completing a first macro step, + * see: {@link #firstStep(SCXMLExecutionContext)}. The state machine thereafter should be ready + * for processing external events (or be terminated already)</li> + * <li>Processing a single external event and completing the macro step for it, after which the + * state machine should be ready for processing another external event (if any), or be terminated already. + * See: {@link #nextStep(SCXMLExecutionContext, TriggerEvent)}. + * </li> + * <li>Finally, if the state machine terminated ({@link SCXMLExecutionContext#isRunning()} == false), after either + * of the above steps, finalize the state machine by performing the final step. + * See: {@link #finalStep(SCXMLExecutionContext)}. + * </li> * </ul> - * </p> * <p>After a state machine has been terminated you can re-initialize the execution context, and start again.</p> * <p> * Except for the loading of the SCXML document and (re)initializing the {@link SCXMLExecutionContext}, the above steps @@ -165,7 +165,7 @@ public interface SCXMLSemantics { * </p> * <p> * This method is also first invoked when manually initializing the status of a state machine through - * {@link SCXMLExecutor#setConfiguration(java.util.Set}. + * {@link SCXMLExecutor#setConfiguration(java.util.Set)}. * </p> * @param states a set of states * @param errRep ErrorReporter to report detailed error info if needed http://git-wip-us.apache.org/repos/asf/commons-scxml/blob/e3c841e1/src/main/java/org/apache/commons/scxml2/TriggerEvent.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/scxml2/TriggerEvent.java b/src/main/java/org/apache/commons/scxml2/TriggerEvent.java index 5e5f3c3..fbf3328 100644 --- a/src/main/java/org/apache/commons/scxml2/TriggerEvent.java +++ b/src/main/java/org/apache/commons/scxml2/TriggerEvent.java @@ -97,8 +97,8 @@ public class TriggerEvent implements Serializable { * Indicates that an error internal to the execution of the document has occurred, such as one arising from * expression evaluation. * </p> - * @see: <a href="http://www.w3.org/TR/2014/CR-scxml-20140313/#errorsAndEvents";> - * http://www.w3.org/TR/2014/CR-scxml-20140313/#errorsAndEvents</a> + * @see <a href="http://www.w3.org/TR/scxml/#errorsAndEvents";> + * http://www.w3.org/TR/scxml/#errorsAndEvents</a> */ public static final String ERROR_EXECUTION = "error.execution"; @@ -107,8 +107,8 @@ public class TriggerEvent implements Serializable { * <p> * Indicates that an error has occurred while trying to communicate with an external entity. * </p> - * @see: <a href="http://www.w3.org/TR/2014/CR-scxml-20140313/#errorsAndEvents";> - * http://www.w3.org/TR/2014/CR-scxml-20140313/#errorsAndEvents</a> + * @see <a href="http://www.w3.org/TR/scxml/#errorsAndEvents";> + * http://www.w3.org/TR/scxml/#errorsAndEvents</a> */ public static final String ERROR_COMMUNICATION = "error.communication"; @@ -117,8 +117,8 @@ public class TriggerEvent implements Serializable { * <p> * Indicates that a platform- or application-specific error has occurred. * </p> - * @see: <a href="http://www.w3.org/TR/2014/CR-scxml-20140313/#errorsAndEvents";> - * http://www.w3.org/TR/2014/CR-scxml-20140313/#errorsAndEvents</a> + * @see <a href="http://www.w3.org/TR/scxml/#errorsAndEvents";> + * http://www.w3.org/TR/scxml/#errorsAndEvents</a> */ public static final String ERROR_PLATFORM = "error.platform"; http://git-wip-us.apache.org/repos/asf/commons-scxml/blob/e3c841e1/src/main/java/org/apache/commons/scxml2/env/AbstractStateMachine.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/scxml2/env/AbstractStateMachine.java b/src/main/java/org/apache/commons/scxml2/env/AbstractStateMachine.java index c3642a0..80b5d59 100644 --- a/src/main/java/org/apache/commons/scxml2/env/AbstractStateMachine.java +++ b/src/main/java/org/apache/commons/scxml2/env/AbstractStateMachine.java @@ -98,6 +98,7 @@ public abstract class AbstractStateMachine { * @param scxmlDocument The URL pointing to the SCXML document that * describes the "lifecycle" of the * instances of this class. + * @throws ModelException in case there is a fatal SCXML object model problem */ public AbstractStateMachine(final URL scxmlDocument) throws ModelException { // default is JEXL @@ -112,6 +113,7 @@ public abstract class AbstractStateMachine { * instances of this class. * @param rootCtx The root context for this instance. * @param evaluator The expression evaluator for this instance. + * @throws ModelException in case there is a fatal SCXML object model problem * * @see Context * @see Evaluator @@ -137,7 +139,7 @@ public abstract class AbstractStateMachine { * @param stateMachine The parsed SCXML instance that * describes the "lifecycle" of the * instances of this class. - * + * @throws ModelException in case there is a fatal SCXML object model problem * @since 0.7 */ public AbstractStateMachine(final SCXML stateMachine) throws ModelException { @@ -153,7 +155,7 @@ public abstract class AbstractStateMachine { * instances of this class. * @param rootCtx The root context for this instance. * @param evaluator The expression evaluator for this instance. - * + * @throws ModelException in case there is a fatal SCXML object model problem * @see Context * @see Evaluator * @@ -171,6 +173,7 @@ public abstract class AbstractStateMachine { * @param stateMachine The state machine * @param rootCtx The root context * @param evaluator The expression evaluator + * @throws ModelException in case there is a fatal SCXML object model problem */ private void initialize(final SCXML stateMachine, final Context rootCtx, final Evaluator evaluator) throws ModelException { http://git-wip-us.apache.org/repos/asf/commons-scxml/blob/e3c841e1/src/main/java/org/apache/commons/scxml2/env/EffectiveContextMap.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/scxml2/env/EffectiveContextMap.java b/src/main/java/org/apache/commons/scxml2/env/EffectiveContextMap.java index c118c86..0640062 100644 --- a/src/main/java/org/apache/commons/scxml2/env/EffectiveContextMap.java +++ b/src/main/java/org/apache/commons/scxml2/env/EffectiveContextMap.java @@ -34,7 +34,10 @@ public final class EffectiveContextMap extends AbstractMap<String, Object> imple /** The {@link org.apache.commons.scxml2.Context} for the current state. */ private final Context leaf; - /** Constructor. */ + /** + * Constructor. + * @param ctx context of the current leave state node + */ public EffectiveContextMap(final Context ctx) { super(); this.leaf = ctx; http://git-wip-us.apache.org/repos/asf/commons-scxml/blob/e3c841e1/src/main/java/org/apache/commons/scxml2/env/LogUtils.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/scxml2/env/LogUtils.java b/src/main/java/org/apache/commons/scxml2/env/LogUtils.java index e69caa2..bf27a43 100644 --- a/src/main/java/org/apache/commons/scxml2/env/LogUtils.java +++ b/src/main/java/org/apache/commons/scxml2/env/LogUtils.java @@ -31,6 +31,7 @@ public final class LogUtils { * @param from The source TransitionTarget * @param to The destination TransitionTarget * @param transition The Transition that is taken + * @param event The event name triggering the transition * @return String The human readable log entry */ public static String transToString(final TransitionTarget from, http://git-wip-us.apache.org/repos/asf/commons-scxml/blob/e3c841e1/src/main/java/org/apache/commons/scxml2/env/SimpleErrorReporter.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/scxml2/env/SimpleErrorReporter.java b/src/main/java/org/apache/commons/scxml2/env/SimpleErrorReporter.java index eb4ae6b..aa39d47 100644 --- a/src/main/java/org/apache/commons/scxml2/env/SimpleErrorReporter.java +++ b/src/main/java/org/apache/commons/scxml2/env/SimpleErrorReporter.java @@ -121,6 +121,16 @@ public class SimpleErrorReporter implements ErrorReporter, Serializable { /** * Final handling of the resulting errorMessage build by {@link #onError(String, String, Object)} onError}. * <p>The default implementation write the errorMessage as a warning to the log.</p> + * + * @param errorCode + * one of the ErrorReporter's constants + * @param errDetail + * human readable description + * @param errCtx + * typically an SCXML element which caused an error, + * may be accompanied by additional information + * @param errorMessage + * human readable detail of the error including the state, transition and data */ protected void handleErrorMessage(final String errorCode, final String errDetail, final Object errCtx, final CharSequence errorMessage) { http://git-wip-us.apache.org/repos/asf/commons-scxml/blob/e3c841e1/src/main/java/org/apache/commons/scxml2/env/groovy/GroovyContext.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/scxml2/env/groovy/GroovyContext.java b/src/main/java/org/apache/commons/scxml2/env/groovy/GroovyContext.java index a30ac76..9799216 100644 --- a/src/main/java/org/apache/commons/scxml2/env/groovy/GroovyContext.java +++ b/src/main/java/org/apache/commons/scxml2/env/groovy/GroovyContext.java @@ -16,6 +16,8 @@ */ package org.apache.commons.scxml2.env.groovy; +import groovy.lang.Closure; + import java.io.ByteArrayInputStream; import java.io.ByteArrayOutputStream; import java.io.IOException; @@ -30,8 +32,6 @@ import org.apache.commons.logging.LogFactory; import org.apache.commons.scxml2.Context; import org.apache.commons.scxml2.env.SimpleContext; -import groovy.lang.Closure; - /** * Groovy Context implementation for Commons SCXML. */ @@ -63,7 +63,9 @@ public class GroovyContext extends SimpleContext { /** * Constructor with initial vars. * + * @param parent The parent context. * @param initialVars The initial set of variables. + * @param evaluator The groovy evaluator */ public GroovyContext(final Context parent, final Map<String, Object> initialVars, GroovyEvaluator evaluator) { super(parent, initialVars); @@ -74,6 +76,7 @@ public class GroovyContext extends SimpleContext { * Constructor with parent context. * * @param parent The parent context. + * @param evaluator The groovy evaluator */ public GroovyContext(final Context parent, GroovyEvaluator evaluator) { super(parent); http://git-wip-us.apache.org/repos/asf/commons-scxml/blob/e3c841e1/src/main/java/org/apache/commons/scxml2/env/groovy/GroovyEvaluator.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/scxml2/env/groovy/GroovyEvaluator.java b/src/main/java/org/apache/commons/scxml2/env/groovy/GroovyEvaluator.java index 749ea9c..f67e7d1 100644 --- a/src/main/java/org/apache/commons/scxml2/env/groovy/GroovyEvaluator.java +++ b/src/main/java/org/apache/commons/scxml2/env/groovy/GroovyEvaluator.java @@ -130,6 +130,8 @@ public class GroovyEvaluator implements Evaluator, Serializable { * The default implementation configures the scriptCache to use the {@link #scriptPreProcessor GroovyEvaluator scriptPreProcessor} * and the {@link GroovySCXMLScript} as script base class. * </p> + * + * @return GroovyExtendableScriptCache for this GroovyEvaluator */ protected GroovyExtendableScriptCache newScriptCache() { GroovyExtendableScriptCache scriptCache = new GroovyExtendableScriptCache(); http://git-wip-us.apache.org/repos/asf/commons-scxml/blob/e3c841e1/src/main/java/org/apache/commons/scxml2/env/groovy/GroovyExtendableScriptCache.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/scxml2/env/groovy/GroovyExtendableScriptCache.java b/src/main/java/org/apache/commons/scxml2/env/groovy/GroovyExtendableScriptCache.java index 0cc04d7..e9424e0 100644 --- a/src/main/java/org/apache/commons/scxml2/env/groovy/GroovyExtendableScriptCache.java +++ b/src/main/java/org/apache/commons/scxml2/env/groovy/GroovyExtendableScriptCache.java @@ -16,6 +16,11 @@ */ package org.apache.commons.scxml2.env.groovy; +import groovy.lang.GroovyClassLoader; +import groovy.lang.GroovyCodeSource; +import groovy.lang.GroovyRuntimeException; +import groovy.lang.Script; + import java.io.IOException; import java.io.ObjectInputStream; import java.io.Serializable; @@ -25,11 +30,6 @@ import java.util.LinkedHashMap; import org.codehaus.groovy.control.CompilerConfiguration; -import groovy.lang.GroovyClassLoader; -import groovy.lang.GroovyCodeSource; -import groovy.lang.GroovyRuntimeException; -import groovy.lang.Script; - /** * GroovyExtendableScriptCache is a general purpose and <em>{@link Serializable}</em> Groovy Script cache. * <p> @@ -41,7 +41,7 @@ import groovy.lang.Script; * </p> * <p> * Internally it uses a non-serializable and thus transient {@link GroovyClassLoader}, {@link CompilerConfiguration} and - * the parent classloader to use.<br/> + * the parent classloader to use.<br> * To be able to be serializable, the {@link GroovyClassLoader} is automatically (re)created if not defined yet, and for * the {@link CompilerConfiguration} and parent classloader it uses serializable instances of * {@link CompilerConfigurationFactory} and {@link ParentClassLoaderFactory} interfaces which either can be configured @@ -50,13 +50,13 @@ import groovy.lang.Script; * <p> * The underlying {@link GroovyClassLoader} can be accessed through {@link #getGroovyClassLoader()}, which might be needed * to de-serialize previously defined/created classes and objects through this class, from within a containing object - * readObject(ObjectInputStream in) method.<br/> + * readObject(ObjectInputStream in) method.<br> * For more information how this works and should be done, see: * <a href="http://jira.codehaus.org/browse/GROOVY-1627";>Groovy-1627: Deserialization fails to work</a> * </p> * <p> * One other optional feature is script pre-processing which can be configured through an instance of the - * {@link ScriptPreProcessor} interface (also {@link Serializable} of course).<br/> + * {@link ScriptPreProcessor} interface (also {@link Serializable} of course).<br> * When configured, the script source will be passed through the {@link ScriptPreProcessor#preProcess(String)} method * before being compiled. * </p> @@ -185,11 +185,11 @@ public class GroovyExtendableScriptCache implements Serializable { public GroovyExtendableScriptCache() { } - /** + /* * Hook into the de-serialization process, reloading the transient GroovyClassLoader, CompilerConfiguration and * re-generate Script classes through {@link #ensureInitializedOrReloaded()} */ - private void readObject(ObjectInputStream in) throws IOException,ClassNotFoundException { + private void readObject(ObjectInputStream in) throws IOException, ClassNotFoundException { in.defaultReadObject(); ensureInitializedOrReloaded(); } @@ -289,7 +289,7 @@ public class GroovyExtendableScriptCache implements Serializable { } /** - * @param scriptCodeBase The CodeSource code base to be used for the compilation of the Groovy scripts.<br/> + * @param scriptCodeBase The CodeSource code base to be used for the compilation of the Groovy scripts.<br> * When null, of zero length or not (at least) starting with a '/', * the {@link #DEFAULT_SCRIPT_CODE_BASE} will be set instead. */ http://git-wip-us.apache.org/repos/asf/commons-scxml/blob/e3c841e1/src/main/java/org/apache/commons/scxml2/env/groovy/GroovySCXMLScript.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/scxml2/env/groovy/GroovySCXMLScript.java b/src/main/java/org/apache/commons/scxml2/env/groovy/GroovySCXMLScript.java index d0f5a01..29407ef 100644 --- a/src/main/java/org/apache/commons/scxml2/env/groovy/GroovySCXMLScript.java +++ b/src/main/java/org/apache/commons/scxml2/env/groovy/GroovySCXMLScript.java @@ -16,6 +16,10 @@ */ package org.apache.commons.scxml2.env.groovy; +import groovy.lang.Binding; +import groovy.lang.MissingPropertyException; +import groovy.lang.Script; + import java.lang.reflect.Array; import java.util.Collection; import java.util.Map; @@ -24,10 +28,6 @@ import org.apache.commons.scxml2.Builtin; import org.apache.commons.scxml2.SCXMLExpressionException; import org.apache.commons.scxml2.XPathBuiltin; -import groovy.lang.Binding; -import groovy.lang.MissingPropertyException; -import groovy.lang.Script; - /** * Groovy {@link Script} base class for SCXML, providing the standard 'builtin' functions {@link #In(String)}, * {@link #Data(String)} and {@link #Location(String)}, as well as JEXL like convenience functions @@ -62,6 +62,7 @@ public abstract class GroovySCXMLScript extends Script { * Implements the Data() predicate for SCXML documents. * @param expression the XPath expression * @return the data matching the expression + * @throws SCXMLExpressionException A malformed expression exception */ public Object Data(final String expression) throws SCXMLExpressionException { return XPathBuiltin.eval(context, expression); @@ -71,6 +72,7 @@ public abstract class GroovySCXMLScript extends Script { * Implements the Location() predicate for SCXML documents. * @param location the XPath expression * @return the location list for the location expression + * @throws SCXMLExpressionException A malformed expression exception */ public Object Location(final String location) throws SCXMLExpressionException { return XPathBuiltin.evalLocation(context, location); @@ -89,11 +91,14 @@ public abstract class GroovySCXMLScript extends Script { * So, use <code>var('name')</code>, not <code>var(name)</code> * </p> * <p> - * Note: this function doesn't support object navigation, like <code>var('name.property')</code>.<br/> + * Note: this function doesn't support object navigation, like <code>var('name.property')</code>.<br> * Instead, once you established a variable 'name' exists, you <em>thereafter</em> can use the standard Groovy - * Safe Navigation operator (?.), like so: <code>name?.property</code>.<br/> + * Safe Navigation operator (?.), like so: <code>name?.property</code>.<br> * See for more information: <a href="http://docs.codehaus.org/display/GROOVY/Operators#Operators-SafeNavigationOperator(?.)">Groovy SafeNavigationOperator</a> * </p> + * + * @param property the name of variable to check if it exists + * @return true if the variable exists, false otherwise */ public boolean var(String property) { if (!context.has(property)) { @@ -116,10 +121,13 @@ public abstract class GroovySCXMLScript extends Script { * <li>an empty Map</li> * </ul> * <p> - * Note: one difference with the JEXL language is that Groovy doesn't allow checking for undefined variables.<br/> - * Before being able to check, Groovy will already have raised an MissingPropertyException if the variable cannot be found.<br/> + * Note: one difference with the JEXL language is that Groovy doesn't allow checking for undefined variables.<br> + * Before being able to check, Groovy will already have raised an MissingPropertyException if the variable cannot be found.<br> * To work around this, the custom {@link #var(String)} function is available. * </p> + * + * @param obj the object to check if it is empty + * @return true if the object is empty, false otherwise */ public boolean empty(Object obj) { return obj == null || http://git-wip-us.apache.org/repos/asf/commons-scxml/blob/e3c841e1/src/main/java/org/apache/commons/scxml2/env/javascript/JSEvaluator.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/scxml2/env/javascript/JSEvaluator.java b/src/main/java/org/apache/commons/scxml2/env/javascript/JSEvaluator.java index b67ccbc..9fee8ea 100644 --- a/src/main/java/org/apache/commons/scxml2/env/javascript/JSEvaluator.java +++ b/src/main/java/org/apache/commons/scxml2/env/javascript/JSEvaluator.java @@ -42,7 +42,7 @@ import org.apache.commons.scxml2.model.SCXML; * is implemented in the same way as the JEXL expression evaluator i.e. using * the Data() function, for example, * <assign location="Data(hotelbooking,'hotel/rooms')" expr="2" /> - * <p> + * </p> */ public class JSEvaluator implements Evaluator { http://git-wip-us.apache.org/repos/asf/commons-scxml/blob/e3c841e1/src/main/java/org/apache/commons/scxml2/env/javascript/JSFunctions.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/scxml2/env/javascript/JSFunctions.java b/src/main/java/org/apache/commons/scxml2/env/javascript/JSFunctions.java index 9b2a93e..bf99ee7 100644 --- a/src/main/java/org/apache/commons/scxml2/env/javascript/JSFunctions.java +++ b/src/main/java/org/apache/commons/scxml2/env/javascript/JSFunctions.java @@ -55,6 +55,7 @@ public class JSFunctions implements Serializable { * Provides the Commons SCXML Data() predicate extension for SCXML documents. * @param expression the XPath expression * @return the data matching the expression + * @throws SCXMLExpressionException A malformed expression exception */ public Object Data(String expression) throws SCXMLExpressionException { return XPathBuiltin.eval(ctx, expression); @@ -64,6 +65,7 @@ public class JSFunctions implements Serializable { * Provides the Commons SCXML Location() predicate extension for SCXML documents. * @param expression the XPath expression * @return the location matching the expression + * @throws SCXMLExpressionException A malformed expression exception */ public Object Location(String expression) throws SCXMLExpressionException { return XPathBuiltin.evalLocation(ctx, expression); http://git-wip-us.apache.org/repos/asf/commons-scxml/blob/e3c841e1/src/main/java/org/apache/commons/scxml2/env/jexl/JexlBuiltin.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/scxml2/env/jexl/JexlBuiltin.java b/src/main/java/org/apache/commons/scxml2/env/jexl/JexlBuiltin.java index 02c6467..b1ece86 100644 --- a/src/main/java/org/apache/commons/scxml2/env/jexl/JexlBuiltin.java +++ b/src/main/java/org/apache/commons/scxml2/env/jexl/JexlBuiltin.java @@ -51,6 +51,7 @@ public final class JexlBuiltin { * Provides the Commons SCXML Data() predicate extension for SCXML documents. * @param expression the XPath expression * @return the data matching the expression + * @throws SCXMLExpressionException A malformed expression exception */ public Object Data(final String expression) throws SCXMLExpressionException { return XPathBuiltin.eval(context, expression); @@ -60,6 +61,7 @@ public final class JexlBuiltin { * Provides the Commons SCXML Location() predicate extension for SCXML documents. * @param expression the XPath expression * @return the location matching the expression + * @throws SCXMLExpressionException A malformed expression exception */ public Object Location(final String expression) throws SCXMLExpressionException { return XPathBuiltin.evalLocation(context, expression); http://git-wip-us.apache.org/repos/asf/commons-scxml/blob/e3c841e1/src/main/java/org/apache/commons/scxml2/invoke/Invoker.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/scxml2/invoke/Invoker.java b/src/main/java/org/apache/commons/scxml2/invoke/Invoker.java index 67831c8..09dcf84 100644 --- a/src/main/java/org/apache/commons/scxml2/invoke/Invoker.java +++ b/src/main/java/org/apache/commons/scxml2/invoke/Invoker.java @@ -46,19 +46,18 @@ import org.apache.commons.scxml2.TriggerEvent; * event. The name of the special "done" event must be "done.invoke.id" with * the ID of the parent state wherein the corresponding <invoke> resides,</p> * - * <p>The Invoker "lifecycle" is outlined below: - * <ol> - * <li>Instantiation via {@link Class#newInstance()} - * (Invoker implementation requires accessible constructor).</li> - * <li>Configuration (setters for invoke ID and - * {@link org.apache.commons.scxml2.SCXMLExecutor}).</li> - * <li>Initiation of invoked activity via invoke() method, passing - * the source URI and the map of params.</li> - * <li>Zero or more bi-directional event triggering.</li> - * <li>Either completion or cancellation.</li> - * </ol> - * </p> - * + * <p>The Invoker "lifecycle" is outlined below:</p> + * <ol> + * <li>Instantiation via {@link Class#newInstance()} + * (Invoker implementation requires accessible constructor).</li> + * <li>Configuration (setters for invoke ID and + * {@link org.apache.commons.scxml2.SCXMLExecutor}).</li> + * <li>Initiation of invoked activity via invoke() method, passing + * the source URI and the map of params.</li> + * <li>Zero or more bi-directional event triggering.</li> + * <li>Either completion or cancellation.</li> + * </ol> + * * <p><b>Note:</b> The semantics of <invoke> are necessarily * asynchronous, tending towards long(er) running interactions with external * processes. Implementations cannot communicate with the parent state http://git-wip-us.apache.org/repos/asf/commons-scxml/blob/e3c841e1/src/main/java/org/apache/commons/scxml2/io/SCXMLReader.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/scxml2/io/SCXMLReader.java b/src/main/java/org/apache/commons/scxml2/io/SCXMLReader.java index 3a6c847..d4d2715 100644 --- a/src/main/java/org/apache/commons/scxml2/io/SCXMLReader.java +++ b/src/main/java/org/apache/commons/scxml2/io/SCXMLReader.java @@ -2893,8 +2893,8 @@ public final class SCXMLReader { /** * Returns true if it is set to read models silently without any model error warning logs. - * @return - * @see {@link #silent} + * @return true if it is set to read models silently without any model error warning logs + * @see #silent */ public boolean isSilent() { return silent; @@ -2902,8 +2902,8 @@ public final class SCXMLReader { /** * Turn on/off silent mode (whether to read models silently without any model error warning logs) - * @param silent - * @see {@link #silent} + * @param silent silent mode (whether to read models silently without any model error warning logs) + * @see #silent */ public void setSilent(boolean silent) { this.silent = silent; @@ -2911,8 +2911,8 @@ public final class SCXMLReader { /** * Returns true if it is set to check model strictly with throwing exceptions on any model error. - * @return - * @see {@link #strict} + * @return true if it is set to check model strictly with throwing exceptions on any model error + * @see #strict */ public boolean isStrict() { return strict; @@ -2920,8 +2920,8 @@ public final class SCXMLReader { /** * Turn on/off strict model (whether to check model strictly with throwing exception on any model error) - * @param strict - * @see {@link #strict} + * @param strict strict model (whether to check model strictly with throwing exception on any model error) + * @see #strict */ public void setStrict(boolean strict) { this.strict = strict; http://git-wip-us.apache.org/repos/asf/commons-scxml/blob/e3c841e1/src/main/java/org/apache/commons/scxml2/model/ActionsContainer.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/scxml2/model/ActionsContainer.java b/src/main/java/org/apache/commons/scxml2/model/ActionsContainer.java index 34a683a..85f3480 100644 --- a/src/main/java/org/apache/commons/scxml2/model/ActionsContainer.java +++ b/src/main/java/org/apache/commons/scxml2/model/ActionsContainer.java @@ -23,9 +23,10 @@ import java.util.List; */ public interface ActionsContainer { - /** The <if> ActionsContainer element name */ + /** The <if> ActionsContainer element name */ String ELEM_IF = "if"; - /** The <foreach> ActionsContainer element name */ + + /** The <foreach> ActionsContainer element name */ String ELEM_FOREACH = "foreach"; /** @@ -34,6 +35,7 @@ public interface ActionsContainer { * @return Returns the element type */ String getContainerElementName(); + /** * Get the executable actions contained in this <container>. * http://git-wip-us.apache.org/repos/asf/commons-scxml/blob/e3c841e1/src/main/java/org/apache/commons/scxml2/model/PayloadProvider.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/scxml2/model/PayloadProvider.java b/src/main/java/org/apache/commons/scxml2/model/PayloadProvider.java index be1a6a8..639acf3 100644 --- a/src/main/java/org/apache/commons/scxml2/model/PayloadProvider.java +++ b/src/main/java/org/apache/commons/scxml2/model/PayloadProvider.java @@ -147,7 +147,7 @@ public abstract class PayloadProvider extends Action { * @param evaluator the evaluator to test for which datamodel type this event payload is intended * @param payload the payload data map * @return payload for an event - * @throws ModelException + * @throws ModelException if it fails to create payload or data node */ protected Object makeEventPayload(final Evaluator evaluator, final Map<String, Object> payload) throws ModelException { http://git-wip-us.apache.org/repos/asf/commons-scxml/blob/e3c841e1/src/main/java/org/apache/commons/scxml2/model/SimpleTransition.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/scxml2/model/SimpleTransition.java b/src/main/java/org/apache/commons/scxml2/model/SimpleTransition.java index f1f6ae0..331861d 100644 --- a/src/main/java/org/apache/commons/scxml2/model/SimpleTransition.java +++ b/src/main/java/org/apache/commons/scxml2/model/SimpleTransition.java @@ -149,16 +149,17 @@ public class SimpleTransition extends Executable * Returns the effective Transition type. * <p> * A transition type is only effectively internal if: + * </p> * <ul> * <li>its {@link #getType()} == {@link TransitionType#internal}</li> * <li>its source state {@link #getParent()} {@link State#isComposite()}</li> * <li>all its {@link #getTargets()} are proper descendants of its {@link #getParent()}</li> * </ul> + * <p> * Otherwise it is treated (for determining its exit states) as if it is of type {@link TransitionType#external} * </p> * @see <a href="http://www.w3.org/TR/2014/CR-scxml-20140313/#SelectingTransitions";> * http://www.w3.org/TR/2014/CR-scxml-20140313/#SelectingTransitions</a> - * </p> * @return true if the effective Transition type is {@link TransitionType#internal} */ public final boolean isTypeInternal() { @@ -189,10 +190,12 @@ public class SimpleTransition extends Executable * </p> * <p> * If the transition has targets then the transition domain is the compound State parent such that: + * </p> * <ul> * <li>all states that are exited or entered as a result of taking this transition are descendants of it</li> * <li>no descendant of it has this property</li> * </ul> + * <p> * If there is no such compound state parent, the transition domain effectively becomes the SCXML document itself, * which is not a (Transitional)State, and thus null will be returned instead. * </p> http://git-wip-us.apache.org/repos/asf/commons-scxml/blob/e3c841e1/src/main/java/org/apache/commons/scxml2/semantics/SCXMLSemanticsImpl.java ---------------------------------------------------------------------- diff --git a/src/main/java/org/apache/commons/scxml2/semantics/SCXMLSemanticsImpl.java b/src/main/java/org/apache/commons/scxml2/semantics/SCXMLSemanticsImpl.java index 0312423..13bc848 100644 --- a/src/main/java/org/apache/commons/scxml2/semantics/SCXMLSemanticsImpl.java +++ b/src/main/java/org/apache/commons/scxml2/semantics/SCXMLSemanticsImpl.java @@ -44,17 +44,17 @@ import org.apache.commons.scxml2.model.Executable; import org.apache.commons.scxml2.model.Final; import org.apache.commons.scxml2.model.History; import org.apache.commons.scxml2.model.Invoke; +import org.apache.commons.scxml2.model.ModelException; import org.apache.commons.scxml2.model.OnEntry; import org.apache.commons.scxml2.model.OnExit; -import org.apache.commons.scxml2.model.Script; -import org.apache.commons.scxml2.model.SimpleTransition; -import org.apache.commons.scxml2.model.TransitionalState; -import org.apache.commons.scxml2.model.ModelException; import org.apache.commons.scxml2.model.Parallel; import org.apache.commons.scxml2.model.SCXML; +import org.apache.commons.scxml2.model.Script; +import org.apache.commons.scxml2.model.SimpleTransition; import org.apache.commons.scxml2.model.State; import org.apache.commons.scxml2.model.Transition; import org.apache.commons.scxml2.model.TransitionTarget; +import org.apache.commons.scxml2.model.TransitionalState; import org.apache.commons.scxml2.system.EventVariable; /** @@ -552,6 +552,7 @@ public class SCXMLSemanticsImpl implements SCXMLSemantics { * <p> * @param exctx The execution context for this step * @param step The step + * @throws ModelException if there is a fatal SCXML state error */ public void selectTransitions(final SCXMLExecutionContext exctx, final Step step) throws ModelException { step.getTransitList().clear(); @@ -1047,6 +1048,7 @@ public class SCXMLSemanticsImpl implements SCXMLSemantics { * * @param exctx provides the execution context * @param statesToInvoke the set of activated states which invokes need to be invoked + * @throws ModelException if there is a fatal SCXML state error */ public void initiateInvokes(final SCXMLExecutionContext exctx, final Set<TransitionalState> statesToInvoke) throws ModelException {
