From 08333cb7f6c88bf6a3162068e60602c445b21c8e Mon Sep 17 00:00:00 2001 From: sukidayou <77531556+sukidayou@users.noreply.github.com> Date: Wed, 9 Oct 2024 23:53:10 +0800 Subject: [PATCH] feat: fix javadoc (#432) --- pom.xml | 6 +- .../org/casbin/jcasbin/main/CoreEnforcer.java | 62 +++++++++++++++++-- .../jcasbin/main/DistributedEnforcer.java | 10 +-- .../java/org/casbin/jcasbin/model/Model.java | 9 +++ .../java/org/casbin/jcasbin/model/Policy.java | 8 +++ .../casbin/jcasbin/persist/Dispatcher.java | 34 +++++----- .../jcasbin/rbac/ConditionalRoleManager.java | 33 ++++++++++ .../jcasbin/rbac/DefaultRoleManager.java | 2 + .../casbin/jcasbin/util/BuiltInFunctions.java | 19 ++++-- .../casbin/jcasbin/util/EnforceContext.java | 4 +- .../java/org/casbin/jcasbin/util/Util.java | 4 +- .../jcasbin/util/function/KeyMatch5Func.java | 4 +- 12 files changed, 159 insertions(+), 36 deletions(-) diff --git a/pom.xml b/pom.xml index 07447381..8beeb892 100644 --- a/pom.xml +++ b/pom.xml @@ -85,7 +85,11 @@ 11 false - -Xdoclint:none + + none + + **/*.java + notnull diff --git a/src/main/java/org/casbin/jcasbin/main/CoreEnforcer.java b/src/main/java/org/casbin/jcasbin/main/CoreEnforcer.java index 7973811f..60d88e9a 100644 --- a/src/main/java/org/casbin/jcasbin/main/CoreEnforcer.java +++ b/src/main/java/org/casbin/jcasbin/main/CoreEnforcer.java @@ -486,7 +486,7 @@ public void enableAutoBuildRoleLinks(boolean autoBuildRoleLinks) { /** * EnableAcceptJsonRequest controls whether to accept json as a request parameter * - * @param acceptJsonRequest + * @param acceptJsonRequest a boolean that indicates whether JSON requests are accepted. */ public void enableAcceptJsonRequest(boolean acceptJsonRequest) { this.acceptJsonRequest = acceptJsonRequest; @@ -782,6 +782,11 @@ public EnforceResult enforceExWithMatcher(String matcher, Object... rvals) { /** * addNamedMatchingFunc add MatchingFunc by ptype RoleManager + * + * @param ptype the type of the role manager. + * @param name the name of the matching function to be added. + * @param fn the matching function. + * @return whether the matching function was successfully added. */ public boolean addNamedMatchingFunc(String ptype, String name, BiPredicate fn) { if (rmMap.containsKey(ptype)) { @@ -798,6 +803,11 @@ public boolean addNamedMatchingFunc(String ptype, String name, BiPredicate fn) { if (rmMap.containsKey(ptype)) { @@ -813,8 +823,14 @@ public boolean addNamedDomainMatchingFunc(String ptype, String name, BiPredicate } /** - * addNamedLinkConditionFunc Add condition function fn for Link userName->roleName, + * addNamedLinkConditionFunc Add condition function fn for Link userName->roleName, * when fn returns true, Link is valid, otherwise invalid + * + * @param ptype the type of the role manager. + * @param user the username for which the link condition is being added. + * @param role the role associated with the user for which the condition is evaluated. + * @param fn a function that takes an array of parameters (e.g., [user, role]) and returns a Boolean indicating the validity of the link. + * @return whether the Link is valid. */ public boolean addNamedLinkConditionFunc(String ptype, String user, String role, Function fn){ if (condRmMap.containsKey(ptype)){ @@ -826,8 +842,15 @@ public boolean addNamedLinkConditionFunc(String ptype, String user, String role, } /** - * addNamedDomainLinkConditionFunc Add condition function fn for Link userName-> {roleName, domain}, + * addNamedDomainLinkConditionFunc Add condition function fn for Link userName-> {roleName, domain}, * when fn returns true, Link is valid, otherwise invalid + * + * @param ptype the type of the conditional role manager. + * @param user the username for which the link condition is being added. + * @param role the role associated with the user for which the condition is evaluated. + * @param domain the domain associated with the role. + * @param fn a function that takes an array of parameters (e.g., [user, role, domain]) and returns a Boolean indicating the validity of the link. + * @return whether the Link is valid. */ public boolean addNamedDomainLinkConditionFunc(String ptype, String user, String role, String domain, Function fn) { if (condRmMap.containsKey(ptype)){ @@ -839,7 +862,13 @@ public boolean addNamedDomainLinkConditionFunc(String ptype, String user, String } /** - * setNamedLinkConditionFuncParams Sets the parameters of the condition function fn for Link userName->roleName + * setNamedLinkConditionFuncParams Sets the parameters of the condition function fn for Link userName->roleName + * + * @param ptype the type of the conditional role manager. + * @param user the username for which the link condition parameters are being set. + * @param role the role associated with the user for which the parameters are being configured. + * @param params an array of parameters to be passed to the condition function. + * @return whether the Link is valid. */ public boolean setNamedLinkConditionFuncParams(String ptype, String user, String role, String... params){ if (condRmMap.containsKey(ptype)){ @@ -852,7 +881,14 @@ public boolean setNamedLinkConditionFuncParams(String ptype, String user, String /** * setNamedDomainLinkConditionFuncParams Sets the parameters of the condition function fn - * for Link userName->{roleName, domain} + * for Link userName->{roleName, domain} + * + * @param ptype the type of the conditional role manager. + * @param user the username for which the link condition parameters are being set. + * @param role the role associated with the user for which the parameters are being configured. + * @param domain the domain associated with the role and user. + * @param params an array of parameters to be passed to the condition function, allowing customization of the condition logic. + * @return whether the parameters were successfully set. */ public boolean setNamedDomainLinkConditionFuncParams(String ptype, String user, String role, String domain, String... params){ if (condRmMap.containsKey(ptype)){ @@ -863,6 +899,14 @@ public boolean setNamedDomainLinkConditionFuncParams(String ptype, String user, return false; } + /*** + * getRTokens Retrieves request tokens and populates them into the provided parameters map. + * + * @param parameters a map to store the request tokens and their corresponding values. + * @param rType the type of the request for which tokens are being retrieved, used to access the appropriate model. + * @param rvals the request needs to be mediated, usually an array + * of strings, can be class instances if ABAC is used. + */ private void getRTokens(Map parameters, String rType, Object... rvals) { String[] requestTokens = model.model.get("r").get(rType).tokens; if(requestTokens.length != rvals.length) { @@ -874,6 +918,14 @@ private void getRTokens(Map parameters, String rType, Object... } } + /*** + * getPTokens Retrieves policy tokens and populates them into the provided parameters map. + * + * @param parameters a map to store the policy tokens and their corresponding values. + * @param pType the type of the policy for which tokens are being retrieved, used for context. + * @param pvals a list of values corresponding to the policy tokens. + * @param pTokens an array of tokens associated with the policy. + */ private void getPTokens(Map parameters, String pType, List pvals, String[] pTokens) { if (pTokens.length != pvals.size()) { throw new CasbinMatcherException("invalid policy size: expected " + pTokens.length + diff --git a/src/main/java/org/casbin/jcasbin/main/DistributedEnforcer.java b/src/main/java/org/casbin/jcasbin/main/DistributedEnforcer.java index 84992b6c..ddbd4d7e 100644 --- a/src/main/java/org/casbin/jcasbin/main/DistributedEnforcer.java +++ b/src/main/java/org/casbin/jcasbin/main/DistributedEnforcer.java @@ -101,7 +101,7 @@ public DistributedEnforcer(String modelPath, String policyFile, boolean enableLo * AddPolicySelf provides a method for dispatcher to add authorization rules to the current policy. * The function returns the rules affected and error. * - * @param shouldPersist + * @param shouldPersist whether the changes should be persisted. * @param sec the section, "p" or "g". * @param ptype the policy type, "p", "p2", .. or "g", "g2", .. * @param rules the rules. @@ -146,7 +146,7 @@ public List> addPolicySelf(BooleanSupplier shouldPersist, String se * RemovePolicySelf provides a method for dispatcher to remove policies from current policy. * The function returns the rules affected and error. * - * @param shouldPersist + * @param shouldPersist whether the changes should be persisted. * @param sec the section, "p" or "g". * @param ptype the policy type, "p", "p2", .. or "g", "g2", .. * @param rules the rules. @@ -184,7 +184,7 @@ public List> removePolicySelf(BooleanSupplier shouldPersist, String * field filters can be specified. * The function returns the rules affected and error. * - * @param shouldPersist + * @param shouldPersist whether the changes should be persisted. * @param sec the section, "p" or "g". * @param ptype the policy type, "p", "p2", .. or "g", "g2", .. * @param fieldIndex the policy rule's start index to be matched. @@ -220,7 +220,7 @@ public List> removeFilteredPolicySelf(BooleanSupplier shouldPersist /** * ClearPolicySelf provides a method for dispatcher to clear all rules from the current policy. * - * @param shouldPersist + * @param shouldPersist whether the changes should be persisted. */ public void clearPolicySelf(BooleanSupplier shouldPersist) { if (shouldPersist.getAsBoolean()) { @@ -239,7 +239,7 @@ public void clearPolicySelf(BooleanSupplier shouldPersist) { /** * UpdatePolicySelf provides a method for dispatcher to update an authorization rule from the current policy. * - * @param shouldPersist + * @param shouldPersist whether the changes should be persisted. * @param sec the section, "p" or "g". * @param ptype the policy type, "p", "p2", .. or "g", "g2", .. * @param oldRule the old rule. diff --git a/src/main/java/org/casbin/jcasbin/model/Model.java b/src/main/java/org/casbin/jcasbin/model/Model.java index 1f7f3a6a..c8170b99 100644 --- a/src/main/java/org/casbin/jcasbin/model/Model.java +++ b/src/main/java/org/casbin/jcasbin/model/Model.java @@ -165,6 +165,8 @@ private void loadSections(Config cfg) { /** * SetLogger sets the model's logger. + * + * @param logger the logger to be set for the model. */ public void setLogger(Logger logger) { for (Map astMap : model.values()) { @@ -177,6 +179,8 @@ public void setLogger(Logger logger) { /** * NewModel creates an empty model. + * + * @return a new instance of the Model. */ public static Model newModel() { Model model = new Model(); @@ -188,6 +192,7 @@ public static Model newModel() { * NewModelFromString creates a model from a string which contains model text. * * @param path the path of the model file. + * @return the model loaded from file. */ public static Model newModelFromFile(String path) { Model model = new Model(); @@ -199,6 +204,7 @@ public static Model newModelFromFile(String path) { * NewModelFromString creates a model from a string which contains model text. * * @param text the path of the file. + * @return the model loaded from text. */ public static Model newModelFromString(String text) { Model model = new Model(); @@ -250,6 +256,9 @@ public void loadModelFromConfig(Config cfg) { /** * hasSection checks if the section exists in the model. + * + * @param sec the section name to check, such as "p" or "g". + * @return whether the section exists in the model. */ public boolean hasSection(String sec) { Map section = model.get(sec); diff --git a/src/main/java/org/casbin/jcasbin/model/Policy.java b/src/main/java/org/casbin/jcasbin/model/Policy.java index 316831a0..d9a9a3c9 100644 --- a/src/main/java/org/casbin/jcasbin/model/Policy.java +++ b/src/main/java/org/casbin/jcasbin/model/Policy.java @@ -392,6 +392,12 @@ public boolean hasPolicies(String sec, String ptype, List> rules) { /** * buildIncrementalConditionalRoleLinks provides incremental build the role inheritance relations. + * + * @param condRmMap a map of conditional role managers used for role link management. + * @param op the operation to perform, such as adding or removing role links. + * @param sec the section of the policy, typically "g" for role inheritance. + * @param ptype the policy type, which specifies the kind of roles being managed. + * @param rules the rules that define the role links to be built. */ public void buildIncrementalConditionalRoleLinks(Map condRmMap, Model.PolicyOperations op, String sec, String ptype, List> rules){ if ("g".equals(sec) && condRmMap.containsKey(ptype)) { @@ -401,6 +407,8 @@ public void buildIncrementalConditionalRoleLinks(Map condRmMap){ printPolicy(); diff --git a/src/main/java/org/casbin/jcasbin/persist/Dispatcher.java b/src/main/java/org/casbin/jcasbin/persist/Dispatcher.java index d72a5628..690f6f76 100644 --- a/src/main/java/org/casbin/jcasbin/persist/Dispatcher.java +++ b/src/main/java/org/casbin/jcasbin/persist/Dispatcher.java @@ -22,27 +22,30 @@ */ public interface Dispatcher { /** - * // AddPolicies adds policies rule to all instance. - * @param sec - * @param ptype - * @param rules + * AddPolicies adds policies rule to all instance. + * + * @param sec the section to which the policies belong, e.g., "p" or "g". + * @param ptype the policy type, such as "p" for permissions or "g" for roles. + * @param rules the list of policy rules to be added, where each rule is represented as a list of strings. */ void addPolicies(String sec, String ptype, List> rules); /** * RemovePolicies removes policies rule from all instance. - * @param sec - * @param ptype - * @param rules + * + * @param sec the section from which to remove policies, e.g., "p" or "g". + * @param ptype the policy type to remove, such as "p" or "g". + * @param rules the list of policy rules to be removed, where each rule is represented as a list of strings. */ void removePolicies(String sec, String ptype, List> rules); /** * RemoveFilteredPolicy removes policy rules that match the filter from all instance. - * @param sec - * @param ptype - * @param fieldIndex - * @param fieldValues + * + * @param sec the section from which to remove policies, e.g., "p" or "g". + * @param ptype the policy type to filter, such as "p" or "g". + * @param fieldIndex the index of the field to filter on. + * @param fieldValues the values to filter by for the specified field index. */ void removeFilteredPolicy(String sec, String ptype, int fieldIndex, String... fieldValues); @@ -53,10 +56,11 @@ public interface Dispatcher { /** * UpdatePolicy updates policy rule from all instance. - * @param sec - * @param ptype - * @param oldRule - * @param newRule + * + * @param sec the section containing the policy, e.g., "p" or "g". + * @param ptype the policy type to update, such as "p" or "g". + * @param oldRule the existing policy rule to be updated, represented as a list of strings. + * @param newRule the new policy rule that will replace the old one, represented as a list of strings. */ void updatePolicy(String sec, String ptype, List oldRule, List newRule); } diff --git a/src/main/java/org/casbin/jcasbin/rbac/ConditionalRoleManager.java b/src/main/java/org/casbin/jcasbin/rbac/ConditionalRoleManager.java index b5954ed8..bd083ad3 100644 --- a/src/main/java/org/casbin/jcasbin/rbac/ConditionalRoleManager.java +++ b/src/main/java/org/casbin/jcasbin/rbac/ConditionalRoleManager.java @@ -114,6 +114,10 @@ public boolean getNextRoles(Role currentRole, Role nextRole, String[] domains, M /** * getLinkConditionFunc get LinkConditionFunc based on userName, roleName + * + * @param userName the name of the user for whom the link condition function is retrieved. + * @param roleName the name of the role for which the link condition function is retrieved. + * @return the link condition function that determines the validity of the link for the given user and role. */ public Function getLinkConditionFunc(String userName, String roleName){ return getDomainLinkConditionFunc(userName, roleName, ""); @@ -121,6 +125,12 @@ public Function getLinkConditionFunc(String userName, String /** * getDomainLinkConditionFunc get LinkConditionFunc based on userName, roleName, domain + * + * @param userName the name of the user for whom the link condition function is retrieved. + * @param roleName the name of the role for which the link condition function is retrieved. + * @param domain the domain associated with the link condition function. + * @return the link condition function that determines the validity of the link for the given user, role, and domain, + * or null if either the user or role does not exist. */ public Function getDomainLinkConditionFunc(String userName, String roleName, String domain){ Role user = getRole(userName); @@ -138,6 +148,11 @@ public Function getDomainLinkConditionFunc(String userName, S /** * getLinkConditionFuncParams gets parameters of LinkConditionFunc based on userName, roleName, domain + * + * @param userName the name of the user whose link condition function parameters are retrieved. + * @param roleName the name of the role whose link condition function parameters are retrieved. + * @param domain an array of domain names associated with the link condition function. + * @return a list of parameters for the link condition function, or null if no parameters are found. */ public List getLinkConditionFuncParams(String userName, String roleName, String[] domain){ boolean userCreated = !this.allRoles.containsKey(userName); @@ -165,6 +180,10 @@ public List getLinkConditionFuncParams(String userName, String roleName, /** * addLinkConditionFunc is based on userName, roleName, add LinkConditionFunc + * + * @param userName the name of the user for whom the link condition function is being added. + * @param roleName the name of the role associated with the link condition function. + * @param fn the link condition function to be added, which takes an array of strings and returns a boolean. */ public void addLinkConditionFunc(String userName, String roleName, Function fn){ addDomainLinkConditionFunc(userName, roleName, "", fn); @@ -172,6 +191,11 @@ public void addLinkConditionFunc(String userName, String roleName, Function fn){ Role user = getRole(userName); @@ -182,6 +206,10 @@ public void addDomainLinkConditionFunc(String userName, String roleName, String /** * SetLinkConditionFuncParams sets parameters of LinkConditionFunc based on userName, roleName, domain + * + * @param userName the name of the user for whom the link condition function parameters are being set. + * @param roleName the name of the role associated with the link condition function. + * @param params the parameters to be set for the link condition function. */ public void setLinkConditionFuncParams(String userName, String roleName, String... params) { setDomainLinkConditionFuncParams(userName, roleName, "", params); @@ -189,6 +217,11 @@ public void setLinkConditionFuncParams(String userName, String roleName, String. /** * SetDomainLinkConditionFuncParams sets parameters of LinkConditionFunc based on userName, roleName, domain + * + * @param userName the name of the user for whom the link condition function parameters are being set. + * @param roleName the name of the role associated with the link condition function. + * @param domain the domain related to the link condition function. + * @param params the parameters to be set for the link condition function. */ public void setDomainLinkConditionFuncParams(String userName, String roleName, String domain, String... params) { Role user = getRole(userName); diff --git a/src/main/java/org/casbin/jcasbin/rbac/DefaultRoleManager.java b/src/main/java/org/casbin/jcasbin/rbac/DefaultRoleManager.java index 38262053..5544fa82 100644 --- a/src/main/java/org/casbin/jcasbin/rbac/DefaultRoleManager.java +++ b/src/main/java/org/casbin/jcasbin/rbac/DefaultRoleManager.java @@ -64,6 +64,7 @@ public DefaultRoleManager(int maxHierarchyLevel, final BiPredicate matchingFunc) { @@ -74,6 +75,7 @@ public void addMatchingFunc(String name, BiPredicate matchingFun /** * addDomainMatchingFunc support use domain pattern in g * + * @param name the name of the domain matching function. * @param domainMatchingFunc the domain matching function. */ public void addDomainMatchingFunc(String name, BiPredicate domainMatchingFunc) { diff --git a/src/main/java/org/casbin/jcasbin/util/BuiltInFunctions.java b/src/main/java/org/casbin/jcasbin/util/BuiltInFunctions.java index 9dbf2471..4c4aa743 100644 --- a/src/main/java/org/casbin/jcasbin/util/BuiltInFunctions.java +++ b/src/main/java/org/casbin/jcasbin/util/BuiltInFunctions.java @@ -40,6 +40,9 @@ public class BuiltInFunctions { /** * validate the variadic string parameter size + * + * @param args the expected number of arguments. + * @param expectedLen the variadic string arguments to validate. */ public static void validateVariadicStringArgs(int expectedLen, String... args) throws IllegalArgumentException { int length = args!=null?args.length:0; @@ -194,7 +197,7 @@ public static boolean keyMatch4(String key1, String key2) { * KeyMatch5 determines whether key1 matches the pattern of key2 and ignores the parameters in key2. * * 
-     * For example, "/foo/bar?status=1&type=2" matches "/foo/bar"
+     * For example, "/foo/bar?status=1&type=2" matches "/foo/bar"
      *
* * @param key1 the first argument. @@ -232,8 +235,9 @@ public static String keyGetFunc(String key1, String key2) { /** * KeyGet2 returns value matched pattern.For example, "/resource1" matches "/:resource", if the pathVar == "resource", then "resource1" will be returned. * - * @param key1 the first argument. - * @param key2 the second argument. + * @param key1 the first argument. + * @param key2 the second argument. + * @param pathVar the name of the variable to retrieve from the matched pattern. * @return the matched part. */ public static String keyGet2Func(String key1, String key2, String pathVar) { @@ -417,7 +421,7 @@ public static class GenerateConditionalGFunctionClass { /** * GenerateConditionalGFunction is the factory method of the g(_, _[, _]) function with conditions. * - * @param name the name of the g(_, _) function, can be "g", "g2", .. + * @param name the name of the g(_, _) function, can be "g", "g2", .. * @param condRm the conditional role manager used by the function. * @return the function. */ @@ -497,6 +501,9 @@ public static boolean eval(String eval, Map env, AviatorEvaluato /** * timeMatchFunc is the wrapper for TimeMatch. + * + * @param args the arguments for the time match function. + * @return whether the time matches the pattern. */ public static boolean timeMatchFunc(String... args) { try { @@ -511,6 +518,10 @@ public static boolean timeMatchFunc(String... args) { /** * TimeMatch determines whether the current time is between startTime and endTime. * You can use "_" to indicate that the parameter is ignored + * + * @param startTime the start time as a string in the format "yyyy-MM-dd HH:mm:ss". Use "_" to ignore the start time. + * @param endTime the end time as a string in the format "yyyy-MM-dd HH:mm:ss". Use "_" to ignore the end time. + * @return whether the current time is between startTime and endTime */ public static boolean timeMatch(String startTime, String endTime) { LocalDateTime now = LocalDateTime.now(); diff --git a/src/main/java/org/casbin/jcasbin/util/EnforceContext.java b/src/main/java/org/casbin/jcasbin/util/EnforceContext.java index a07525b1..3d9849ea 100644 --- a/src/main/java/org/casbin/jcasbin/util/EnforceContext.java +++ b/src/main/java/org/casbin/jcasbin/util/EnforceContext.java @@ -14,9 +14,9 @@ package org.casbin.jcasbin.util; /** + * EnforceContext is used as the first element of the parameter "rvals" in method "enforce" * @author Yixiang Zhao (@seriouszyx) - * @description EnforceContext is used as the first element of the parameter "rvals" in method "enforce" - * @date 2021-11-30 18:56 + * 2021-11-30 18:56 **/ public class EnforceContext { diff --git a/src/main/java/org/casbin/jcasbin/util/Util.java b/src/main/java/org/casbin/jcasbin/util/Util.java index d27923b5..4077ee18 100644 --- a/src/main/java/org/casbin/jcasbin/util/Util.java +++ b/src/main/java/org/casbin/jcasbin/util/Util.java @@ -336,8 +336,8 @@ private static MessageDigest getDigest(String algorithm) { /** * Helper method to check if a string is a valid JSON * - * @param str - * @return boolean + * @param str the string to be checked. + * @return whether the string is a valid */ public static boolean isJsonString(String str) { try { diff --git a/src/main/java/org/casbin/jcasbin/util/function/KeyMatch5Func.java b/src/main/java/org/casbin/jcasbin/util/function/KeyMatch5Func.java index b0ece900..6f37f006 100644 --- a/src/main/java/org/casbin/jcasbin/util/function/KeyMatch5Func.java +++ b/src/main/java/org/casbin/jcasbin/util/function/KeyMatch5Func.java @@ -22,9 +22,9 @@ import java.util.Map; /** + * KeyMatch5Func is the wrapper for KeyMatch5. * @author Yixiang Zhao (@seriouszyx) - * @description KeyMatch5Func is the wrapper for KeyMatch5. - * @date 2021-11-13 20:32 + * 2021-11-13 20:32 **/ public class KeyMatch5Func extends AbstractFunction {