Add some doc comment.

finesoft · Jan 12, 2023 · 976275b · 976275b
1 parent 334bad4
commit 976275b
Show file tree

Hide file tree

Showing 8 changed files with 301 additions and 195 deletions.
diff --git a/corant-context/src/main/java/org/corant/context/command/CommandHandlerResolver.java b/corant-context/src/main/java/org/corant/context/command/CommandHandlerResolver.java
@@ -35,7 +35,7 @@
  *
  * <p>
  * The command handler resolver is used to resolve the appropriate command handler with the given
- * command and handler qualifiers
+ * command and handler qualifiers.
  * <p>
  * Note: Users can use CDI {@link Specializes} to replace and inherit this class by themselves, and
  * re-implement the {@link #resolve(Object, Annotation...)} method to enable it to face more complex
@@ -68,35 +68,36 @@ public class CommandHandlerResolver {
    * @param qualifiers the command handler bean additional qualifiers
    */
   public <C> CommandHandler<C> resolve(C cmd, Annotation... qualifiers) {
-    if (cmd != null) {
-      if (validators.isResolvable()) {
-        validators.get().validate(cmd);
-      }
-      Set<Class<? extends CommandHandler<?>>> handlerClasses =
-          extension.getCommandHandlerTypes(cmd.getClass());
-      CommandHandler<C> handler = null;
-      int size = sizeOf(handlerClasses);
-      if (size == 1) {
-        handler = resolve(handlerClasses.iterator().next(), qualifiers);
-      } else if (size > 1) {
-        for (Class<? extends CommandHandler<?>> handlerClass : handlerClasses) {
-          CommandHandler<C> resolvedHandler = resolve(handlerClass, qualifiers);
-          if (resolvedHandler != null) {
-            if (handler == null) {
-              handler = resolvedHandler;
-            } else if (!getUserClass(resolvedHandler.getClass())
-                .equals(getUserClass(handler.getClass()))) {
-              // Filter @Specializes
-              throw new AmbiguousResolutionException("Can't resolve command handler for "
-                  + cmd.getClass() + " and ambiguous handlers " + String.join(",",
-                      handlerClasses.stream().map(Class::getName).toArray(String[]::new)));
-            }
+    if (cmd == null) {
+      throw new UnsatisfiedResolutionException("Can't resolve command handler for null command!");
+    }
+    if (validators.isResolvable()) {
+      validators.get().validate(cmd);
+    }
+    Set<Class<? extends CommandHandler<?>>> handlerClasses =
+        extension.getCommandHandlerTypes(cmd.getClass());
+    CommandHandler<C> handler = null;
+    int size = sizeOf(handlerClasses);
+    if (size == 1) {
+      handler = resolve(handlerClasses.iterator().next(), qualifiers);
+    } else if (size > 1) {
+      for (Class<? extends CommandHandler<?>> handlerClass : handlerClasses) {
+        CommandHandler<C> resolvedHandler = resolve(handlerClass, qualifiers);
+        if (resolvedHandler != null) {
+          if (handler == null) {
+            handler = resolvedHandler;
+          } else if (!getUserClass(resolvedHandler.getClass())
+              .equals(getUserClass(handler.getClass()))) {
+            // Filter @Specializes
+            throw new AmbiguousResolutionException("Can't resolve command handler for "
+                + cmd.getClass() + " and ambiguous handlers " + String.join(",",
+                    handlerClasses.stream().map(Class::getName).toArray(String[]::new)));
           }
         }
       }
-      if (handler != null) {
-        return handler;
-      }
+    }
+    if (handler != null) {
+      return handler;
     }
     throw new UnsatisfiedResolutionException("Can't resolve command handler for " + cmd.getClass());
   }

diff --git a/...y/corant-modules-query-api/src/main/java/org/corant/modules/query/mapping/FetchQuery.java b/...y/corant-modules-query-api/src/main/java/org/corant/modules/query/mapping/FetchQuery.java
@@ -27,6 +27,14 @@
 
 /**
  * corant-modules-query-api
+ * <p>
+ * Fetch query, mainly used to perform sub-queries based on the parent query result set and
+ * parameters, and inject the results into the result set of the parent query. The fetch query is
+ * generally used to query complex compound object result sets.
+ * <p>
+ * Fetch query actually defines a sub-query invocation, so each fetch query must refer to a real
+ * {@link Query} and define the parameter and result set type of this query, and the processing
+ * method of injecting into the parent query result, etc.
  *
  * @author bingo 上午10:26:45
  *
@@ -103,63 +111,65 @@ public boolean equals(Object obj) {
   }
 
   /**
-   *
-   * @return the id
+   * Returns the fetch query identifier, each fetch query has a unique identifier.
    */
   public String getId() {
     return id;
   }
 
+  /**
+   * Returns the script use to performance inject the fetch query result to parent query results.
+   */
   public Script getInjectionScript() {
     return injectionScript;
   }
 
   /**
-   * @return the injectPropertyName
+   * Returns the name of the parent query result property which use to hold the fetch query results
+   * <p>
+   * If there is a hierarchical result, use '.' as the hierarchical separator for the property path.
    */
   public String getInjectPropertyName() {
     return injectPropertyName;
   }
 
   /**
-   *
-   * @return the injectPropertyNamePath
+   * Returns the hierarchical property names.
    */
   public String[] getInjectPropertyNamePath() {
     return injectPropertyNamePath;
   }
 
   /**
-   * @return the maxSize
+   * Returns the max fetch query result size, -1 means unlimited
    */
   public int getMaxSize() {
     return maxSize;
   }
 
   /**
-   * @return the parameters
+   * Returns the fetch query parameters.
    */
   public List<FetchQueryParameter> getParameters() {
     return parameters;
   }
 
   /**
-   *
-   * @return getPredicateScript
+   * Returns the script use to detect whether performance the fetch query
    */
   public Script getPredicateScript() {
     return predicateScript;
   }
 
   /**
-   * @return the referenceQuery
+   * Returns the real query corresponding to this fetch query
    */
   public QueryReference getReferenceQuery() {
     return referenceQuery;
   }
 
   /**
-   * @return the resultClass
+   * Returns the class of the fetch query result record
    */
   public Class<?> getResultClass() {
     return resultClass;
@@ -173,16 +183,14 @@ public int hashCode() {
   }
 
   /**
-   *
-   * @return the eagerInject
+   * Return whether to performance the fetch query eager.
    */
   public boolean isEagerInject() {
     return eagerInject;
   }
 
   /**
-   *
-   * @return isMultiRecords
+   * Returns true if the fetch query result set is multiple records, otherwise false.
    */
   public boolean isMultiRecords() {
     return multiRecords;
@@ -195,15 +203,11 @@ protected void addParameter(FetchQueryParameter parameter) {
   /**
    * Make query immutable
    */
-  protected void postConstuct() {
+  protected void postConstruct() {
     parameters =
         parameters == null ? Collections.emptyList() : Collections.unmodifiableList(parameters);
   }
 
-  /**
-   *
-   * @param eagerInject the eagerInject to set
-   */
   protected void setEagerInject(boolean eagerInject) {
     this.eagerInject = eagerInject;
   }
@@ -229,10 +233,6 @@ protected void setPredicateScript(Script predicate) {
     predicateScript = defaultObject(predicate, Script.EMPTY);
   }
 
-  /**
-   *
-   * @param referenceQuery the referenceQuery to set
-   */
   protected void setReferenceQuery(QueryReference referenceQuery) {
     this.referenceQuery = referenceQuery;
   }
@@ -241,30 +241,33 @@ protected void setReferenceQueryName(String referenceQueryName) {
     referenceQuery.setName(referenceQueryName);
   }
 
-  /**
-   *
-   * @param referenceQueryQualifier the referenceQueryQualifier to set
-   */
   protected void setReferenceQueryQualifier(String referenceQueryQualifier) {
     referenceQuery.setQualifier(referenceQueryQualifier);
   }
 
-  /**
-   *
-   * @param referenceQueryType the referenceQueryType to set
-   */
   protected void setReferenceQueryType(QueryType referenceQueryType) {
     referenceQuery.setType(referenceQueryType);
   }
 
-  protected void setReferenceQueryversion(String referenceQueryversion) {
-    referenceQuery.setVersion(referenceQueryversion);
+  protected void setReferenceQueryVersion(String referenceQueryVersion) {
+    referenceQuery.setVersion(referenceQueryVersion);
   }
 
   protected void setResultClass(Class<?> resultClass) {
     this.resultClass = defaultObject(resultClass, Map.class);
   }
 
+  /**
+   * corant-modules-query-api
+   * <p>
+   * Fetch query parameter, which defines the query parameters used in the fetch query. Including
+   * parameter name, value source, value type, etc.
+   *
+   * @see FetchQueryParameterSource
+   *
+   * @author bingo 上午11:14:41
+   *
+   */
   public static class FetchQueryParameter implements Serializable {
 
     private static final long serialVersionUID = 5013658267151165784L;
@@ -282,14 +285,18 @@ public static class FetchQueryParameter implements Serializable {
     public FetchQueryParameter() {}
 
     /**
-     * @param name
-     * @param sourceName
-     * @param source
-     * @param value
-     * @param type
-     * @param script
-     * @param distinct
-     * @param singleAsList
+     * @param name the parameter name
+     * @param sourceName the source name used with source
+     * @param source indicates the value source of the fetch query parameter
+     * @param value the parameter value, usually used for the source is the specified constant
+     * @param type the target type of the parameter value, usually the parameter value will undergo
+     *        type conversion
+     * @param script a script function used to calculate parameter values, usually for parameters
+     *        whose source is a script, where the parameters of the script function are parent query
+     *        parameters and parent query result sets, and the return value of the script is the
+     *        fetch query parameter value
+     * @param distinct whether to de-duplicate when there are multiple parameter values
+     * @param singleAsList when the value is a single value, whether to convert it to a list
      */
     public FetchQueryParameter(String name, String sourceName, FetchQueryParameterSource source,
         String value, Class<?> type, Script script, boolean distinct, boolean singleAsList) {
@@ -304,58 +311,66 @@ public FetchQueryParameter(String name, String sourceName, FetchQueryParameterSo
     }
 
     /**
-     * @return the name
+     * Returns the fetch query parameter name
      */
     public String getName() {
       return name;
     }
 
+    /**
+     * Returns a script function used to calculate parameter values, usually for parameters whose
+     * source is a script, where the parameters of the script function are parent query parameters
+     * and parent query result sets, and the return value of the script is the fetch query parameter
+     * value
+     */
     public Script getScript() {
       return script;
     }
 
     /**
-     * @return the source
+     * Returns the value source of the fetch query parameter
      */
     public FetchQueryParameterSource getSource() {
       return source;
     }
 
     /**
-     * @return the sourceName
+     * Returns the source name used with source
      */
     public String getSourceName() {
       return sourceName;
     }
 
-    /**
-     *
-     * @return the sourceNamePath
-     */
     public String[] getSourceNamePath() {
       return sourceNamePath;
     }
 
     /**
-     *
-     * @return the type
+     * Returns the target type of the parameter value, usually the parameter value will undergo type
+     * conversion
      */
     public Class<?> getType() {
       return type;
     }
 
     /**
-     *
-     * @return getValue
+     * Returns the parameter value, usually used for the source is the specified constant. In
+     * general if the source is not a constant this method should return null.
      */
     public String getValue() {
       return value;
     }
 
+    /**
+     * Returns whether to de-duplicate when there are multiple parameter values
+     */
     public boolean isDistinct() {
       return distinct;
     }
 
+    /**
+     * Returns whether to convert the value to a list when the value is a single value.
+     */
     public boolean isSingleAsList() {
       return singleAsList;
     }
@@ -395,8 +410,34 @@ protected void setValue(String value) {
 
   }
 
+  /**
+   * corant-modules-query-api
+   * <p>
+   * Defines the source of several fetch query parameters.
+   *
+   * @author bingo 上午11:21:02
+   *
+   */
   public enum FetchQueryParameterSource {
-    P, R, C, S
+    /**
+     * Indicates that the value of the fetch query parameter is extracted from parent query
+     * parameters.
+     */
+    P,
+    /**
+     * Indicates that the value of the fetch query parameter is extracted from parent query results.
+     */
+    R,
+    /**
+     * Indicates that the value of the fetch query parameter is a constant.
+     */
+    C,
+    /**
+     * Indicates that the value of the fetch query parameter is the execution result of the
+     * specified script function, where the parameters of the script function are the parent query
+     * parameters and the query result set. This is an experimental feature.
+     */
+    S
   }
 
 }