Added Javadocs and performed light refactoring.

core/src/main/java/gov/nist/secauto/metaschema/core/metapath/cst/AbstractCSTVisitorBase.java

@@ -28,6 +28,10 @@
 import edu.umd.cs.findbugs.annotations.NonNull;
 import edu.umd.cs.findbugs.annotations.Nullable;
 
+/**
+ * Provides utility methods for processing Metapath abstract syntax tree (AST)
+ * nodes to produce a compact syntax tree (CST).
+ */
 @SuppressWarnings({
     "PMD.CouplingBetweenObjects"
 })

core/src/main/java/gov/nist/secauto/metaschema/core/metapath/cst/AbstractExpression.java

@@ -5,34 +5,11 @@
 
 package gov.nist.secauto.metaschema.core.metapath.cst;
 
-import gov.nist.secauto.metaschema.core.metapath.item.ISequence;
-import gov.nist.secauto.metaschema.core.metapath.item.atomic.IAnyAtomicItem;
-import gov.nist.secauto.metaschema.core.metapath.type.TypeMetapathException;
-
-import edu.umd.cs.findbugs.annotations.NonNull;
-import edu.umd.cs.findbugs.annotations.Nullable;
-
+/**
+ * A common base class for Metapath expression implementations, providing common
+ * utility functions.
+ */
 public abstract class AbstractExpression implements IExpression {
-  /**
-   * Get the first data item of the provided {@code sequence} cast to an
-   * {@link IAnyAtomicItem}.
-   *
-   * @param sequence
-   *          the sequence to get the data item from
-   * @param requireSingleton
-   *          if {@code true} then a {@link TypeMetapathException} is thrown if
-   *          the sequence contains more than one item
-   * @return {@code null} if the sequence is empty, or the item otherwise
-   * @throws TypeMetapathException
-   *           if the sequence contains more than one item and requireSingleton is
-   *           {@code true}, or if the data item cannot be cast
-   */
-  @Nullable
-  public static IAnyAtomicItem getFirstDataItem(@NonNull ISequence<?> sequence,
-      boolean requireSingleton) {
-    return ISequence.of(sequence.atomize()).getFirstItem(requireSingleton);
-  }
-
   @Override
   public String toString() {
     return CSTPrinter.toString(this);

core/src/main/java/gov/nist/secauto/metaschema/core/metapath/cst/DynamicFunctionCall.java

@@ -23,7 +23,8 @@
  * determine the function and multiple argument expressions that are used to
  * determine the function arguments.
  */
-public class DynamicFunctionCall implements IExpression {
+public class DynamicFunctionCall
+    extends AbstractExpression {
   @NonNull
   private final IExpression functionIdentifier;
   @NonNull

core/src/main/java/gov/nist/secauto/metaschema/core/metapath/cst/For.java

@@ -22,7 +22,8 @@
  * expression</a> supporting variable-based iteration.
  */
 @SuppressWarnings("PMD.ShortClassName")
-public class For implements IExpression {
+public class For
+    extends AbstractExpression {
   @NonNull
   private final Let.VariableDeclaration variable;
   @NonNull

core/src/main/java/gov/nist/secauto/metaschema/core/metapath/cst/FunctionCallAccessor.java

@@ -25,7 +25,8 @@
 
 import edu.umd.cs.findbugs.annotations.NonNull;
 
-public class FunctionCallAccessor implements IExpression {
+public class FunctionCallAccessor
+    extends AbstractExpression {
   @NonNull
   private final IExpression base;
   @NonNull

core/src/main/java/gov/nist/secauto/metaschema/core/metapath/cst/Let.java

@@ -21,7 +21,8 @@
  * expression</a> supporting variable value binding.
  */
 @SuppressWarnings("PMD.ShortClassName")
-public class Let implements IExpression {
+public class Let
+    extends AbstractExpression {
   @NonNull
   private final VariableDeclaration variable;
   @NonNull

core/src/main/java/gov/nist/secauto/metaschema/core/metapath/cst/StaticFunctionCall.java

@@ -33,7 +33,8 @@
  */
 // FIXME: Change compilation to error when a non-existant function is called.
 // Manage this error where the compilation is requested
-public class StaticFunctionCall implements IExpression {
+public class StaticFunctionCall
+    extends AbstractExpression {
   @NonNull
   private final Lazy<IFunction> functionSupplier;
   @NonNull

core/src/main/java/gov/nist/secauto/metaschema/core/metapath/cst/VariableReference.java

@@ -20,7 +20,8 @@
  * <a href="https://www.w3.org/TR/xpath-31/#id-variables">variable
  * reference</a>.
  */
-public class VariableReference implements IExpression {
+public class VariableReference
+    extends AbstractExpression {
   @NonNull
   private final IEnhancedQName name;
 

core/src/main/java/gov/nist/secauto/metaschema/core/metapath/cst/items/AbstractLookup.java

@@ -5,7 +5,7 @@
 
 package gov.nist.secauto.metaschema.core.metapath.cst.items;
 
-import gov.nist.secauto.metaschema.core.metapath.cst.IExpression;
+import gov.nist.secauto.metaschema.core.metapath.cst.AbstractExpression;
 import gov.nist.secauto.metaschema.core.metapath.item.function.IArrayItem;
 import gov.nist.secauto.metaschema.core.metapath.item.function.IKeySpecifier;
 import gov.nist.secauto.metaschema.core.metapath.item.function.IMapItem;
@@ -20,7 +20,8 @@
  * Provides support for various types of key- and index-based lookups related to
  * {@link IMapItem} and {@link IArrayItem} objects.
  */
-public abstract class AbstractLookup implements IExpression {
+public abstract class AbstractLookup
+    extends AbstractExpression {
   @NonNull
   private final IKeySpecifier keySpecifier;
 

core/src/main/java/gov/nist/secauto/metaschema/core/metapath/cst/items/ArraySequenceConstructor.java

@@ -6,6 +6,7 @@
 package gov.nist.secauto.metaschema.core.metapath.cst.items;
 
 import gov.nist.secauto.metaschema.core.metapath.DynamicContext;
+import gov.nist.secauto.metaschema.core.metapath.cst.AbstractExpression;
 import gov.nist.secauto.metaschema.core.metapath.cst.IExpression;
 import gov.nist.secauto.metaschema.core.metapath.cst.IExpressionVisitor;
 import gov.nist.secauto.metaschema.core.metapath.item.ISequence;
@@ -20,7 +21,8 @@
  * <a href="https://www.w3.org/TR/xpath-31/#id-array-constructors">Array Curly
  * Constructor</a> supporting the creation of a Metapath {@link IArrayItem}.
  */
-public class ArraySequenceConstructor implements IExpression {
+public class ArraySequenceConstructor
+    extends AbstractExpression {
   @Nullable
   private final IExpression expr;
 

core/src/main/java/gov/nist/secauto/metaschema/core/metapath/cst/items/ArraySquareConstructor.java

@@ -6,6 +6,7 @@
 package gov.nist.secauto.metaschema.core.metapath.cst.items;
 
 import gov.nist.secauto.metaschema.core.metapath.DynamicContext;
+import gov.nist.secauto.metaschema.core.metapath.cst.AbstractExpression;
 import gov.nist.secauto.metaschema.core.metapath.cst.IExpression;
 import gov.nist.secauto.metaschema.core.metapath.cst.IExpressionVisitor;
 import gov.nist.secauto.metaschema.core.metapath.item.IItem;
@@ -21,7 +22,8 @@
  * <a href="https://www.w3.org/TR/xpath-31/#id-array-constructors">Array Square
  * Constructor</a> supporting the creation of a Metapath {@link IArrayItem}.
  */
-public class ArraySquareConstructor implements IExpression {
+public class ArraySquareConstructor
+    extends AbstractExpression {
   @NonNull
   private final List<IExpression> children;
 

core/src/main/java/gov/nist/secauto/metaschema/core/metapath/cst/items/MapConstructor.java

@@ -6,6 +6,7 @@
 package gov.nist.secauto.metaschema.core.metapath.cst.items;
 
 import gov.nist.secauto.metaschema.core.metapath.DynamicContext;
+import gov.nist.secauto.metaschema.core.metapath.cst.AbstractExpression;
 import gov.nist.secauto.metaschema.core.metapath.cst.IExpression;
 import gov.nist.secauto.metaschema.core.metapath.cst.IExpressionVisitor;
 import gov.nist.secauto.metaschema.core.metapath.item.ICollectionValue;
@@ -27,7 +28,8 @@
  * <a href="https://www.w3.org/TR/xpath-31/#id-map-constructors">Map
  * Constructor</a> supporting the creation of a Metapath {@link IMapItem}.
  */
-public class MapConstructor implements IExpression {
+public class MapConstructor
+    extends AbstractExpression {
   @NonNull
   private final List<MapConstructor.Entry> entries;
 
@@ -74,7 +76,8 @@ public <RESULT, CONTEXT> RESULT accept(IExpressionVisitor<RESULT, CONTEXT> visit
   /**
    * A map entry expression used to produce an entry in a {@link IMapItem}.
    */
-  public static class Entry implements IExpression {
+  public static class Entry
+      extends AbstractExpression {
     @NonNull
     private final IExpression keyExpression;
     @NonNull

core/src/main/java/gov/nist/secauto/metaschema/core/metapath/cst/items/Range.java

@@ -47,8 +47,8 @@ public Class<IIntegerItem> getBaseResultType() {
 
   @Override
   public ISequence<IIntegerItem> accept(DynamicContext dynamicContext, ISequence<?> focus) {
-    IAnyAtomicItem leftItem = getFirstDataItem(getLeft().accept(dynamicContext, focus), true);
-    IAnyAtomicItem rightItem = getFirstDataItem(getRight().accept(dynamicContext, focus), true);
+    IAnyAtomicItem leftItem = ISequence.of(getLeft().accept(dynamicContext, focus).atomize()).getFirstItem(true);
+    IAnyAtomicItem rightItem = ISequence.of(getRight().accept(dynamicContext, focus).atomize()).getFirstItem(true);
 
     IIntegerItem left = leftItem == null ? null : IIntegerItem.cast(leftItem);
     IIntegerItem right = rightItem == null ? null : IIntegerItem.cast(rightItem);

core/src/main/java/gov/nist/secauto/metaschema/core/metapath/cst/logic/Negate.java

@@ -55,7 +55,7 @@ public <RESULT, CONTEXT> RESULT accept(IExpressionVisitor<RESULT, CONTEXT> visit
   @Override
   public ISequence<? extends INumericItem> accept(DynamicContext dynamicContext, ISequence<?> focus) {
     INumericItem item = FunctionUtils.toNumericOrNull(
-        getFirstDataItem(getChild().accept(dynamicContext, focus), true));
+        ISequence.of(getChild().accept(dynamicContext, focus).atomize()).getFirstItem(true));
     if (item != null) {
       item = OperationFunctions.opNumericUnaryMinus(item);
     }

core/src/main/java/gov/nist/secauto/metaschema/core/metapath/cst/logic/PredicateExpression.java

@@ -7,6 +7,7 @@
 
 import gov.nist.secauto.metaschema.core.metapath.DynamicContext;
 import gov.nist.secauto.metaschema.core.metapath.MetapathEvaluationFeature;
+import gov.nist.secauto.metaschema.core.metapath.cst.AbstractExpression;
 import gov.nist.secauto.metaschema.core.metapath.cst.IExpression;
 import gov.nist.secauto.metaschema.core.metapath.cst.IExpressionVisitor;
 import gov.nist.secauto.metaschema.core.metapath.cst.items.IntegerLiteral;
@@ -25,7 +26,8 @@
 
 import edu.umd.cs.findbugs.annotations.NonNull;
 
-public class PredicateExpression implements IExpression {
+public class PredicateExpression
+    extends AbstractExpression {
   @NonNull
   private final IExpression base;
   @NonNull
@@ -82,10 +84,7 @@ ISequence<? extends IItem> accept(@NonNull DynamicContext dynamicContext,
       AtomicInteger index = new AtomicInteger();
 
       Stream<? extends IItem> stream = ObjectUtils.notNull(
-          retval.stream().map(item -> {
-            // build a positional index of the items
-            return Map.entry(BigInteger.valueOf(index.incrementAndGet()), item);
-          }).filter(entry -> {
+          retval.stream().map(item -> Map.entry(BigInteger.valueOf(index.incrementAndGet()), item)).filter(entry -> {
             @SuppressWarnings("null")
             @NonNull
             IItem item = entry.getValue();

core/src/main/java/gov/nist/secauto/metaschema/core/metapath/cst/logic/ValueComparison.java

@@ -48,8 +48,8 @@ public <RESULT, CONTEXT> RESULT accept(IExpressionVisitor<RESULT, CONTEXT> visit
 
   @Override
   public ISequence<? extends IBooleanItem> accept(DynamicContext dynamicContext, ISequence<?> focus) {
-    IAnyAtomicItem left = getFirstDataItem(getLeft().accept(dynamicContext, focus), false);
-    IAnyAtomicItem right = getFirstDataItem(getRight().accept(dynamicContext, focus), false);
+    IAnyAtomicItem left = ISequence.of(getLeft().accept(dynamicContext, focus).atomize()).getFirstItem(false);
+    IAnyAtomicItem right = ISequence.of(getRight().accept(dynamicContext, focus).atomize()).getFirstItem(false);
 
     return resultOrEmpty(left, right);
   }

core/src/main/java/gov/nist/secauto/metaschema/core/metapath/cst/math/AbstractArithmeticExpression.java

@@ -15,8 +15,9 @@
 import edu.umd.cs.findbugs.annotations.NonNull;
 
 /**
- * An immutable binary expression that supports arithmetic evaluation. The
- * result type is determined through static analysis of the sub-expressions,
+ * An immutable binary expression that supports arithmetic evaluation.
+ * <p>
+ * The result type is determined through static analysis of the sub-expressions,
  * which may result in a more specific type that is a sub-class of the base
  * result type.
  *

core/src/main/java/gov/nist/secauto/metaschema/core/metapath/cst/math/AbstractBasicArithmeticExpression.java

@@ -13,6 +13,17 @@
 import edu.umd.cs.findbugs.annotations.NonNull;
 import edu.umd.cs.findbugs.annotations.Nullable;
 
+/**
+ * An immutable binary expression that supports basic arithmetic evaluation.
+ * <p>
+ * The result type is determined through static analysis of the sub-expressions,
+ * which may result in a more specific type that is a sub-class of the base
+ * result type.
+ * <p>
+ * The arithmetic operation method
+ * {@link #operation(IAnyAtomicItem, IAnyAtomicItem)} must be implemented by
+ * extending classes to provide the evaluation logic.
+ */
 public abstract class AbstractBasicArithmeticExpression
     extends AbstractArithmeticExpression<IAnyAtomicItem> {
 
@@ -35,8 +46,8 @@ public Class<IAnyAtomicItem> getBaseResultType() {
 
   @Override
   public ISequence<? extends IAnyAtomicItem> accept(DynamicContext dynamicContext, ISequence<?> focus) {
-    IAnyAtomicItem leftItem = getFirstDataItem(getLeft().accept(dynamicContext, focus), true);
-    IAnyAtomicItem rightItem = getFirstDataItem(getRight().accept(dynamicContext, focus), true);
+    IAnyAtomicItem leftItem = ISequence.of(getLeft().accept(dynamicContext, focus).atomize()).getFirstItem(true);
+    IAnyAtomicItem rightItem = ISequence.of(getRight().accept(dynamicContext, focus).atomize()).getFirstItem(true);
 
     return resultOrEmpty(leftItem, rightItem);
   }

core/src/main/java/gov/nist/secauto/metaschema/core/metapath/cst/math/IntegerDivision.java

@@ -46,9 +46,9 @@ public <RESULT, CONTEXT> RESULT accept(IExpressionVisitor<RESULT, CONTEXT> visit
   @Override
   public ISequence<? extends IIntegerItem> accept(DynamicContext dynamicContext, ISequence<?> focus) {
     INumericItem dividend = FunctionUtils.toNumericOrNull(
-        getFirstDataItem(getLeft().accept(dynamicContext, focus), true));
+        ISequence.of(getLeft().accept(dynamicContext, focus).atomize()).getFirstItem(true));
     INumericItem divisor = FunctionUtils.toNumericOrNull(
-        getFirstDataItem(getRight().accept(dynamicContext, focus), true));
+        ISequence.of(getRight().accept(dynamicContext, focus).atomize()).getFirstItem(true));
 
     return resultOrEmpty(dividend, divisor);
   }

core/src/main/java/gov/nist/secauto/metaschema/core/metapath/cst/AbstractNamedInstanceExpression.java → core/src/main/java/gov/nist/secauto/metaschema/core/metapath/cst/path/AbstractNamedInstanceExpression.java

@@ -3,18 +3,21 @@
  * SPDX-License-Identifier: CC0-1.0
  */
 
-package gov.nist.secauto.metaschema.core.metapath.cst;
+package gov.nist.secauto.metaschema.core.metapath.cst.path;
 
-import gov.nist.secauto.metaschema.core.metapath.cst.path.AbstractPathExpression;
-import gov.nist.secauto.metaschema.core.metapath.cst.path.INodeTestExpression;
-import gov.nist.secauto.metaschema.core.metapath.cst.path.NameNodeTest;
-import gov.nist.secauto.metaschema.core.metapath.cst.path.WildcardNodeTest;
+import gov.nist.secauto.metaschema.core.metapath.cst.IExpression;
 import gov.nist.secauto.metaschema.core.metapath.item.node.INodeItem;
 
 import java.util.List;
 
 import edu.umd.cs.findbugs.annotations.NonNull;
 
+/**
+ * A path expression that references a named instance.
+ *
+ * @param <RESULT_TYPE>
+ *          the Java type of the referenced node item
+ */
 public abstract class AbstractNamedInstanceExpression<RESULT_TYPE extends INodeItem>
     extends AbstractPathExpression<RESULT_TYPE> {
   @NonNull

core/src/main/java/gov/nist/secauto/metaschema/core/metapath/cst/path/Flag.java

@@ -6,7 +6,6 @@
 package gov.nist.secauto.metaschema.core.metapath.cst.path;
 
 import gov.nist.secauto.metaschema.core.metapath.DynamicContext;
-import gov.nist.secauto.metaschema.core.metapath.cst.AbstractNamedInstanceExpression;
 import gov.nist.secauto.metaschema.core.metapath.cst.IExpressionVisitor;
 import gov.nist.secauto.metaschema.core.metapath.item.ISequence;
 import gov.nist.secauto.metaschema.core.metapath.item.ItemUtils;

core/src/main/java/gov/nist/secauto/metaschema/core/metapath/cst/path/KindNodeTest.java

@@ -6,6 +6,7 @@
 package gov.nist.secauto.metaschema.core.metapath.cst.path;
 
 import gov.nist.secauto.metaschema.core.metapath.DynamicContext;
+import gov.nist.secauto.metaschema.core.metapath.cst.AbstractExpression;
 import gov.nist.secauto.metaschema.core.metapath.cst.IExpressionVisitor;
 import gov.nist.secauto.metaschema.core.metapath.item.ISequence;
 import gov.nist.secauto.metaschema.core.metapath.item.ItemUtils;
@@ -22,6 +23,7 @@
  */
 @SuppressWarnings("PMD.TestClassWithoutTestCases")
 public class KindNodeTest
+    extends AbstractExpression
     implements INodeTestExpression {
 
   @NonNull

core/src/main/java/gov/nist/secauto/metaschema/core/metapath/cst/path/ModelInstance.java

@@ -6,7 +6,6 @@
 package gov.nist.secauto.metaschema.core.metapath.cst.path;
 
 import gov.nist.secauto.metaschema.core.metapath.DynamicContext;
-import gov.nist.secauto.metaschema.core.metapath.cst.AbstractNamedInstanceExpression;
 import gov.nist.secauto.metaschema.core.metapath.cst.IExpressionVisitor;
 import gov.nist.secauto.metaschema.core.metapath.item.ISequence;
 import gov.nist.secauto.metaschema.core.metapath.item.ItemUtils;

core/src/main/java/gov/nist/secauto/metaschema/core/metapath/cst/path/Step.java

@@ -6,6 +6,7 @@
 package gov.nist.secauto.metaschema.core.metapath.cst.path;
 
 import gov.nist.secauto.metaschema.core.metapath.DynamicContext;
+import gov.nist.secauto.metaschema.core.metapath.cst.AbstractExpression;
 import gov.nist.secauto.metaschema.core.metapath.cst.ExpressionUtils;
 import gov.nist.secauto.metaschema.core.metapath.cst.IExpression;
 import gov.nist.secauto.metaschema.core.metapath.cst.IExpressionVisitor;
@@ -23,7 +24,9 @@
  * with the evaluation of a series of predicate expressions that filter the
  * result of the evaluation.
  */
-public class Step implements IExpression { // NOPMD - intentional
+@SuppressWarnings("PMD.ShortClassName")
+public class Step
+    extends AbstractExpression {
 
   @NonNull
   private final Axis axisExpression;