diff --git a/src/main/java/org/kiwiproject/base/KiwiObjects.java b/src/main/java/org/kiwiproject/base/KiwiObjects.java index b1460d84..e9aef07f 100644 --- a/src/main/java/org/kiwiproject/base/KiwiObjects.java +++ b/src/main/java/org/kiwiproject/base/KiwiObjects.java @@ -36,7 +36,7 @@ public static T firstNonNullOrNull(T first, T second, T... rest) { * @param second the second object supplier * @param rest zero or more additional object suppliers * @param the type of objects - * @return the first non-null supplied object or null if all suppliers return null + * @return the first non-null object supplied, or null if all suppliers return null * @implNote once a non-null object is supplied, no further suppliers are called */ @SafeVarargs diff --git a/src/main/java/org/kiwiproject/base/KiwiPreconditions.java b/src/main/java/org/kiwiproject/base/KiwiPreconditions.java index 7ceab542..1c917cc6 100644 --- a/src/main/java/org/kiwiproject/base/KiwiPreconditions.java +++ b/src/main/java/org/kiwiproject/base/KiwiPreconditions.java @@ -34,7 +34,7 @@ * @implNote Several methods in this class use Lombok {@link lombok.SneakyThrows} so that they do not need to declare * that they throw {@code Exception}s of type T, for the case that T is a checked exception. Read more details about * how this works in {@link lombok.SneakyThrows}. Most notably, this should give you more insight into how the JVM (versus - * Java the language) actually work: "The JVM does not check for the consistency of the checked exception system; + * Java the language) actually works: "The JVM does not check for the consistency of the checked exception system; * javac does, and this annotation lets you opt out of its mechanism." */ @UtilityClass @@ -601,7 +601,7 @@ public static void checkArgumentNotEmpty(Map map, /** * Ensures that a collection of items has an even count, throwing an {@link IllegalArgumentException} if - * items is null or there is an odd number of items. + * {@code items} is null or there is an odd number of items. * * @param items items to count * @param the object type @@ -614,7 +614,7 @@ public static void checkEvenItemCount(T... items) { /** * Ensures that a collection of items has an even count, throwing an {@link IllegalArgumentException} if - * items is null or there is an odd number of items. + * {@code items} is null or there is an odd number of items. * * @param items items to count * @param the object type @@ -678,7 +678,7 @@ public static T requireNotNullElseGet(T obj, Supplier supplier) * Ensures int {@code value} is a positive number (greater than zero). * * @param value the value to check for positivity - * @throws IllegalStateException if the value is not positive (e.g. greater than zero) + * @throws IllegalStateException if the value is not positive (e.g., greater than zero) * @see Preconditions#checkState(boolean, Object) */ public static void checkPositive(int value) { @@ -690,7 +690,7 @@ public static void checkPositive(int value) { * * @param value the value to check for positivity * @param errorMessage the error message to put in the exception if not positive - * @throws IllegalStateException if the value is not positive (e.g. greater than zero) + * @throws IllegalStateException if the value is not positive (e.g., greater than zero) * @see Preconditions#checkState(boolean, Object) */ public static void checkPositive(int value, String errorMessage) { @@ -704,7 +704,7 @@ public static void checkPositive(int value, String errorMessage) { * @param errorMessageTemplate a template for the exception message if value is not positive, according to how * {@link KiwiStrings#format(String, Object...)} handles placeholders * @param errorMessageArgs the arguments to populate into the error message template - * @throws IllegalStateException if the value is not positive (e.g. greater than zero) + * @throws IllegalStateException if the value is not positive (e.g., greater than zero) * @see Preconditions#checkState(boolean, Object) */ public static void checkPositive(int value, String errorMessageTemplate, Object... errorMessageArgs) { @@ -717,7 +717,7 @@ public static void checkPositive(int value, String errorMessageTemplate, Object. * Ensures long {@code value} is a positive number (greater than zero). * * @param value the value to check for positivity - * @throws IllegalStateException if the value is not positive (e.g. greater than zero) + * @throws IllegalStateException if the value is not positive (e.g., greater than zero) * @see Preconditions#checkState(boolean, Object) */ public static void checkPositive(long value) { @@ -729,7 +729,7 @@ public static void checkPositive(long value) { * * @param value the value to check for positivity * @param errorMessage the error message to put in the exception if not positive - * @throws IllegalStateException if the value is not positive (e.g. greater than zero) + * @throws IllegalStateException if the value is not positive (e.g., greater than zero) * @see Preconditions#checkState(boolean, Object) */ public static void checkPositive(long value, String errorMessage) { @@ -743,7 +743,7 @@ public static void checkPositive(long value, String errorMessage) { * @param errorMessageTemplate a template for the exception message if value is not positive, according to how * {@link KiwiStrings#format(String, Object...)} handles placeholders * @param errorMessageArgs the arguments to be substituted into the message template - * @throws IllegalStateException if the value is not positive (e.g. greater than zero) + * @throws IllegalStateException if the value is not positive (e.g., greater than zero) * @see Preconditions#checkState(boolean, Object) */ public static void checkPositive(long value, String errorMessageTemplate, Object... errorMessageArgs) { @@ -768,7 +768,7 @@ public static void checkPositiveOrZero(int value) { * * @param value the value to check for positivity * @param errorMessage the error message to put in the exception if not positive - * @throws IllegalStateException if the value is not positive (e.g. greater than zero) + * @throws IllegalStateException if the value is not positive (e.g., greater than zero) * @see Preconditions#checkState(boolean, Object) */ public static void checkPositiveOrZero(int value, String errorMessage) { @@ -782,7 +782,7 @@ public static void checkPositiveOrZero(int value, String errorMessage) { * @param errorMessageTemplate a template for the exception message if value is not zero or positive, according to how * {@link KiwiStrings#format(String, Object...)} handles placeholders * @param errorMessageArgs the arguments to populate into the error message template - * @throws IllegalStateException if the value is not positive (e.g. greater than zero) + * @throws IllegalStateException if the value is not positive (e.g., greater than zero) * @see Preconditions#checkState(boolean, Object) */ public static void checkPositiveOrZero(int value, String errorMessageTemplate, Object... errorMessageArgs) { @@ -807,7 +807,7 @@ public static void checkPositiveOrZero(long value) { * * @param value the value to check for positivity * @param errorMessage the error message to put in the exception if not positive - * @throws IllegalStateException if the value is not positive (e.g. greater than zero) + * @throws IllegalStateException if the value is not positive (e.g., greater than zero) * @see Preconditions#checkState(boolean, Object) */ public static void checkPositiveOrZero(long value, String errorMessage) { @@ -821,7 +821,7 @@ public static void checkPositiveOrZero(long value, String errorMessage) { * @param errorMessageTemplate a template for the exception message if value is not zero or positive, according to how * {@link KiwiStrings#format(String, Object...)} handles placeholders * @param errorMessageArgs the arguments to populate into the error message template - * @throws IllegalStateException if the value is not positive (e.g. greater than zero) + * @throws IllegalStateException if the value is not positive (e.g., greater than zero) * @see Preconditions#checkState(boolean, Object) */ public static void checkPositiveOrZero(long value, String errorMessageTemplate, Object... errorMessageArgs) { @@ -848,7 +848,7 @@ public static int requirePositive(int value) { * @param value the value to check for positivity * @param errorMessage the error message to put in the exception if not positive * @return the given value if positive - * @throws IllegalStateException if the value is not positive (e.g. greater than zero) + * @throws IllegalStateException if the value is not positive (e.g., greater than zero) * @see Preconditions#checkState(boolean, Object) */ public static int requirePositive(int value, String errorMessage) { @@ -864,7 +864,7 @@ public static int requirePositive(int value, String errorMessage) { * {@link KiwiStrings#format(String, Object...)} handles placeholders * @param errorMessageArgs the arguments to populate into the error message template * @return the given value if positive - * @throws IllegalStateException if the value is not positive (e.g. greater than zero) + * @throws IllegalStateException if the value is not positive (e.g., greater than zero) * @see Preconditions#checkState(boolean, Object) */ public static int requirePositive(int value, String errorMessageTemplate, Object... errorMessageArgs) { @@ -890,7 +890,7 @@ public static long requirePositive(long value) { * @param value the value to check for positivity * @param errorMessage the error message to put in the exception if not positive * @return the given value if positive - * @throws IllegalStateException if the value is not positive (e.g. greater than zero) + * @throws IllegalStateException if the value is not positive (e.g., greater than zero) * @see Preconditions#checkState(boolean, Object) */ public static long requirePositive(long value, String errorMessage) { @@ -906,7 +906,7 @@ public static long requirePositive(long value, String errorMessage) { * {@link KiwiStrings#format(String, Object...)} handles placeholders * @param errorMessageArgs the arguments to populate into the error message template * @return the given value if positive - * @throws IllegalStateException if the value is not positive (e.g. greater than zero) + * @throws IllegalStateException if the value is not positive (e.g., greater than zero) * @see Preconditions#checkState(boolean, Object) */ public static long requirePositive(long value, String errorMessageTemplate, Object... errorMessageArgs) { @@ -919,7 +919,7 @@ public static long requirePositive(long value, String errorMessageTemplate, Obje * * @param value the value to check for positivity or zero * @return the given value if positive or zero - * @throws IllegalStateException if the value is not positive zero + * @throws IllegalStateException if the value is not positive or zero */ public static int requirePositiveOrZero(int value) { checkPositiveOrZero(value); @@ -932,7 +932,7 @@ public static int requirePositiveOrZero(int value) { * @param value the value to check for positivity * @param errorMessage the error message to put in the exception if not positive * @return the given value if positive or zero - * @throws IllegalStateException if the value is not positive (e.g. greater than zero) + * @throws IllegalStateException if the value is not positive (e.g., greater than zero) * @see Preconditions#checkState(boolean, Object) */ public static int requirePositiveOrZero(int value, String errorMessage) { @@ -948,7 +948,7 @@ public static int requirePositiveOrZero(int value, String errorMessage) { * {@link KiwiStrings#format(String, Object...)} handles placeholders * @param errorMessageArgs the arguments to populate into the error message template * @return the given value if positive or zero - * @throws IllegalStateException if the value is not positive (e.g. greater than zero) + * @throws IllegalStateException if the value is not positive (e.g., greater than zero) * @see Preconditions#checkState(boolean, Object) */ public static int requirePositiveOrZero(int value, String errorMessageTemplate, Object... errorMessageArgs) { @@ -961,7 +961,7 @@ public static int requirePositiveOrZero(int value, String errorMessageTemplate, * * @param value the value to check for positivity or zero * @return the given value if positive or zero - * @throws IllegalStateException if the value is not positive zero + * @throws IllegalStateException if the value is not positive or zero */ public static long requirePositiveOrZero(long value) { checkPositiveOrZero(value); @@ -974,7 +974,7 @@ public static long requirePositiveOrZero(long value) { * @param value the value to check for positivity * @param errorMessage the error message to put in the exception if not positive * @return the given value if positive or zero - * @throws IllegalStateException if the value is not positive (e.g. greater than zero) + * @throws IllegalStateException if the value is not positive (e.g., greater than zero) * @see Preconditions#checkState(boolean, Object) */ public static long requirePositiveOrZero(long value, String errorMessage) { @@ -990,7 +990,7 @@ public static long requirePositiveOrZero(long value, String errorMessage) { * {@link KiwiStrings#format(String, Object...)} handles placeholders * @param errorMessageArgs the arguments to populate into the error message template * @return the given value if positive or zero - * @throws IllegalStateException if the value is not positive (e.g. greater than zero) + * @throws IllegalStateException if the value is not positive (e.g., greater than zero) * @see Preconditions#checkState(boolean, Object) */ public static long requirePositiveOrZero(long value, String errorMessageTemplate, Object... errorMessageArgs) { diff --git a/src/main/java/org/kiwiproject/base/KiwiPrimitives.java b/src/main/java/org/kiwiproject/base/KiwiPrimitives.java index 8f964006..41d71c2d 100644 --- a/src/main/java/org/kiwiproject/base/KiwiPrimitives.java +++ b/src/main/java/org/kiwiproject/base/KiwiPrimitives.java @@ -9,7 +9,7 @@ import java.util.OptionalLong; /** - * Static utilities that operate on primitive values, and are not already provided by classes in Guava's + * Static utilities that operate on primitive values, and are not provided by classes in Guava's * {@link com.google.common.primitives} package. */ @UtilityClass diff --git a/src/main/java/org/kiwiproject/collect/KiwiProperties.java b/src/main/java/org/kiwiproject/collect/KiwiProperties.java index c80a7958..1da8d5c8 100644 --- a/src/main/java/org/kiwiproject/collect/KiwiProperties.java +++ b/src/main/java/org/kiwiproject/collect/KiwiProperties.java @@ -21,7 +21,7 @@ public class KiwiProperties { /** - * Crates a mutable {@link Properties} instance by parsing the items argument in pairs. + * Crates a mutable {@link Properties} instance by parsing the {@code items} argument in pairs. * The items argument contains keys and values in the form: *

* key-1, value-1, key-2, value-2, ... , key-N, value-N @@ -41,7 +41,7 @@ public static Properties newProperties(Object... items) { } /** - * Creates a mutable {@link Properties} instance by parsing the items argument in pairs. + * Creates a mutable {@link Properties} instance by parsing the {@code items} argument in pairs. * The items argument contains keys and values in the form: *

* key-1, value-1, key-2, value-2, ... , key-N, value-N @@ -58,7 +58,7 @@ public static Properties newProperties(String... items) { } /** - * Creates a mutable {@link Properties} instance by parsing the items argument in pairs from the list. + * Creates a mutable {@link Properties} instance by parsing the {@code items} argument in pairs from the list. * * @param items the items containing keys and values, in pairs * @return a new Properties instance with data from items @@ -78,11 +78,11 @@ public static Properties newProperties(List items) { * @return a new Properties instance with data from the map * @throws NullPointerException if any of the items is null * @implNote The reason this method restricts the map keys and values to strings is because Properties is derived - * from {@link java.util.Hashtable} and the JavaDoc states: + * from {@link java.util.Hashtable} and the Javadoc states: * "Because {@code Properties} inherits from {@code Hashtable}, the {@code put} and {@code putAll} methods can be * applied to a {@code Properties} object. Their use is strongly discouraged as they allow the caller to insert * entries whose keys or values are not {@code Strings}. The {@code setProperty} method should be used instead." - * This of course is simply poor design (they should have used composition and hidden the internal storage details + * This, of course, is simply poor design (they should have used composition and hidden the internal storage details * instead of extending Hashtable). */ public static Properties newProperties(Map map) { @@ -94,17 +94,17 @@ public static Properties newProperties(Map map) { /** * Creates a mutable {@link Properties} instance from each key/value pair list inside the outer list. - * The items argument must contain keys and values in teh form: + * The {@code items} argument must contain keys and values in teh form: *

* [ [key-1, value-1], [key-2, value-2], ... , [key-N, value-N] *

* - * @param items the items list containing a series of two-items key/value pair lists + * @param items a list containing a series of two-items key/value pair lists * @return a new Properties instance with data from items * @throws NullPointerException if any of the items is null * @throws IllegalArgumentException if any of the key/value pair lists do not have at least two elements * @implNote only the first and second elements of the key/value pair sub-lists are used when creating the - * Properties instance. Thus while it does not make much sense, this method will not throw an exception if the + * Properties instance. Thus, while it makes little sense, this method will not throw an exception if the * sub-lists contain more than two elements. */ public static Properties newPropertiesFromStringPairs(List> items) { diff --git a/src/main/java/org/kiwiproject/collect/KiwiSets.java b/src/main/java/org/kiwiproject/collect/KiwiSets.java index 1af910bf..06b1560d 100644 --- a/src/main/java/org/kiwiproject/collect/KiwiSets.java +++ b/src/main/java/org/kiwiproject/collect/KiwiSets.java @@ -17,7 +17,7 @@ public class KiwiSets { * * @param set the set * @param the type of items in the set - * @return {@code true} if set is null or empty; {@code false} otherwise + * @return {@code true} if {@code set} is null or empty; {@code false} otherwise */ public static boolean isNullOrEmpty(Set set) { return set == null || set.isEmpty(); @@ -28,7 +28,7 @@ public static boolean isNullOrEmpty(Set set) { * * @param set the set * @param the type of items in the set - * @return {@code true} if set is neither null nor empty; {@code false} otherwise + * @return {@code true} if {@code set} is neither null nor empty; {@code false} otherwise */ public static boolean isNotNullOrEmpty(Set set) { return !isNullOrEmpty(set); @@ -39,7 +39,7 @@ public static boolean isNotNullOrEmpty(Set set) { * * @param set the set * @param the type of items in the set - * @return {@code true} if set is non-null and has exactly one item; {@code false} + * @return {@code true} if {@code set} is non-null and has exactly one item; {@code false} */ public static boolean hasOneElement(Set set) { return nonNull(set) && set.size() == 1; diff --git a/src/main/java/org/kiwiproject/jaxrs/KiwiResources.java b/src/main/java/org/kiwiproject/jaxrs/KiwiResources.java index 1ecd8166..a5ec483c 100644 --- a/src/main/java/org/kiwiproject/jaxrs/KiwiResources.java +++ b/src/main/java/org/kiwiproject/jaxrs/KiwiResources.java @@ -27,14 +27,14 @@ import java.util.Optional; /** - * Static utilities for use in Jakarta REST resource classes. Contains utilities for verifying entities (e.g. obtained + * Static utilities for use in Jakarta REST resource classes. Contains utilities for verifying entities (e.g., obtained * from a service or data access class), factories for creating new responses, and for validating query parameters. * * @apiNote Some methods in this class accept {@link Optional} arguments, which we know is considered a code smell * by various people and analysis tools such as IntelliJ's inspections, Sonar, etc. However, we also like to return * {@link Optional} from data access code (e.g. a DAO "findById" method where the object might not exist if it was * recently deleted). In such cases, we can simply take the Optional returned by those finder methods and pass them - * directly to the utilities provided here without needing to call additional methods, for example without needing to + * directly to the utilities provided here without needing to call additional methods, for example, without needing to * call {@code orElse(null)}. So, we acknowledge that it is generally not good to accept {@link Optional} arguments, * but we're trading off convenience in this class against "generally accepted" practice. * @see KiwiResponses @@ -250,7 +250,7 @@ public static Response newResponse(Response.Status status, Object entity) { /** * Creates a {@link Response.ResponseBuilder} having the given status and entity. - * You can further modify the returned build, e.g. add custom headers, set cookies. etc. + * You can further modify the returned build, e.g., add custom headers, set cookies. Etc. * * @param status the response status * @param entity the response entity @@ -276,7 +276,7 @@ public static Response newResponse(Response.Status status, /** * Creates a {@link Response.ResponseBuilder} having the given status, entity, and content type. - * You can further modify the returned build, e.g. add custom headers, set cookies. etc. + * You can further modify the returned build, e.g., add custom headers, set cookies. Etc. * * @param status the response status * @param entity the response entity @@ -305,7 +305,7 @@ public static Response newResponse(Response.Status status, /** * Creates a {@link Response.ResponseBuilder} having the given status, entity, and (single-valued) headers. - * You can further modify the returned build, e.g. add custom headers, set cookies. etc. + * You can further modify the returned build, e.g., add custom headers, set cookies. Etc. * * @param status the response status * @param entity the response entity @@ -337,7 +337,7 @@ public static Response newResponse(Response.Status status, /** * Creates a {@link Response.ResponseBuilder} having the given status, entity, and headers. - * You can further modify the returned build, e.g. add custom headers, set cookies. etc. + * You can further modify the returned build, e.g., add custom headers, set cookies. Etc. * * @param status the response status * @param entity the response entity @@ -368,7 +368,7 @@ public static Response createdResponse(URI location, Object entity) { /** * Creates a {@link Response.ResponseBuilder} having 201 Created status and a specified Location header and entity. - * You can further modify the returned build, e.g. add custom headers, set cookies. etc. + * You can further modify the returned build, e.g., add custom headers, set cookies. Etc. * * @param location the value for the Location header * @param entity the response entity @@ -390,7 +390,7 @@ public static Response okResponse(Object entity) { /** * Creates a {@link Response.ResponseBuilder} having 200 OK status and a specified entity. - * You can further modify the returned build, e.g. add custom headers, set cookies. etc. + * You can further modify the returned build, e.g., add custom headers, set cookies. Etc. * * @param entity the response entity * @return a 200 OK response builder @@ -476,7 +476,7 @@ public static int validateIntParameter(Map parameters, String par * @param parameterName name of the parameter which should be present * @param the type of values in the multivalued map * @return the int value of the validated parameter - * @throws JaxrsBadRequestException if the specified parameter is not present with at least one value, or is + * @throws JaxrsBadRequestException if the specified parameter is not present with at least one value or is * not an integer */ public static int validateOneIntParameter(MultivaluedMap parameters, @@ -499,7 +499,7 @@ public static int validateOneIntParameter(MultivaluedMap paramete * @param parameterName name of the parameter which should be present * @param the type of values in the multivalued map * @return the int value of the validated parameter - * @throws JaxrsBadRequestException if the specified parameter is not present with only one value, or is + * @throws JaxrsBadRequestException if the specified parameter is not present with only one value or is * not an integer */ public static int validateExactlyOneIntParameter(MultivaluedMap parameters, @@ -523,7 +523,7 @@ public static int validateExactlyOneIntParameter(MultivaluedMap p * @param parameterName name of the parameter which should be present * @param the type of values in the multivalued map * @return an unmodifiable List containing the int values of the validated parameter - * @throws JaxrsBadRequestException if the specified parameter is not present with at least one value, or is + * @throws JaxrsBadRequestException if the specified parameter is not present with at least one value or is * not an integer */ public static List validateOneOrMoreIntParameters(MultivaluedMap parameters, @@ -548,13 +548,13 @@ static int parseIntOrThrowBadRequest(Object value, String parameterName) { /** * Checks whether {@code parameters} contains parameter named {@code parameterName} that is a long or - * something that can be converted into a long. + * something that can be converted into a {@code long}. * * @param parameters the parameters to check * @param parameterName name of the parameter which should be present * @param the type of values in the map * @return the long value of the validated parameter - * @throws JaxrsBadRequestException if the specified parameter is not present, or is not a long + * @throws JaxrsBadRequestException if the specified parameter is not present or is not a {@code long} */ public static long validateLongParameter(Map parameters, String parameterName) { checkArgumentNotNull(parameters, PARAMETERS_MUST_NOT_BE_NULL); @@ -568,15 +568,15 @@ public static long validateLongParameter(Map parameters, String p /** * Checks whether {@code parameters} contains a parameter named {@code parameterName} that has at least one - * value that can be converted into a long. If there is more than one value, then the first one returned + * value that can be converted into a {@code long}. If there is more than one value, then the first one returned * by {@link MultivaluedMap#getFirst(Object)} is returned. * * @param parameters the multivalued parameters to check * @param parameterName name of the parameter which should be present * @param the type of values in the multivalued map * @return the long value of the validated parameter - * @throws JaxrsBadRequestException if the specified parameter is not present with at least one value, or is - * not a long + * @throws JaxrsBadRequestException if the specified parameter is not present with at least one value or is + * not a {@code long} */ public static long validateOneLongParameter(MultivaluedMap parameters, String parameterName) { @@ -591,15 +591,15 @@ public static long validateOneLongParameter(MultivaluedMap parame /** * Checks whether {@code parameters} contains a parameter named {@code parameterName} that has exactly one - * value that can be converted into a long. If there is more than one value, this is considered a bad request + * value that can be converted into a {@code long}. If there is more than one value, this is considered a bad request * and a {@link JaxrsBadRequestException} is thrown. * * @param parameters the multivalued parameters to check * @param parameterName name of the parameter which should be present * @param the type of values in the multivalued map * @return the long value of the validated parameter - * @throws JaxrsBadRequestException if the specified parameter is not present with at least one value, or is - * not a long + * @throws JaxrsBadRequestException if the specified parameter is not present with at least one value or is + * not a {@code long} */ public static long validateExactlyOneLongParameter(MultivaluedMap parameters, String parameterName) { @@ -615,15 +615,15 @@ public static long validateExactlyOneLongParameter(MultivaluedMap /** * Checks whether {@code parameters} contains a parameter named {@code parameterName} that has at least one - * value that can be converted into a long. All the values must be convertible to long, and they are + * value that can be converted into a {@code long}. All the values must be convertible to long, and they are * all converted and returned in a List. * * @param parameters the multivalued parameters to check * @param parameterName name of the parameter which should be present * @param the type of values in the multivalued map * @return an unmodifiable List containing the long values of the validated parameter - * @throws JaxrsBadRequestException if the specified parameter is not present with only one value, or is - * not a long + * @throws JaxrsBadRequestException if the specified parameter is not present with only one value or is + * not a {@code long} */ public static List validateOneOrMoreLongParameters(MultivaluedMap parameters, String parameterName) { diff --git a/src/main/java/org/kiwiproject/jdbc/postgres/KiwiPostgres.java b/src/main/java/org/kiwiproject/jdbc/postgres/KiwiPostgres.java index 8e3e2ebd..af5fbde4 100644 --- a/src/main/java/org/kiwiproject/jdbc/postgres/KiwiPostgres.java +++ b/src/main/java/org/kiwiproject/jdbc/postgres/KiwiPostgres.java @@ -44,7 +44,7 @@ public static PGobject newJSONBObject(String jsonValue) { /** * Creates a new {@link PGobject} of the specified type and with the given value. * - * @param type the type of object, e.g. json or jsonb + * @param type the type of object, e.g., {@code json} or {@code jsonb} * @param value the value as a String * @return a new {@link PGobject} * @implNote We are catching the {@link SQLException} thrown by {@link PGobject#setType(String)} and wrapping diff --git a/src/main/java/org/kiwiproject/reflect/KiwiReflection.java b/src/main/java/org/kiwiproject/reflect/KiwiReflection.java index 51bb9f0d..930100dc 100644 --- a/src/main/java/org/kiwiproject/reflect/KiwiReflection.java +++ b/src/main/java/org/kiwiproject/reflect/KiwiReflection.java @@ -200,7 +200,7 @@ public static Object getFieldValue(Object target, Field field) { * @param target the target object in which the field resides * @param fieldName the field name * @param value the new value - * @throws RuntimeReflectionException if any error occurs setting the field value + * @throws RuntimeReflectionException if any error occurs while setting the field value * @see Field#set(Object, Object) */ public static void setFieldValue(Object target, String fieldName, Object value) { @@ -216,7 +216,7 @@ public static void setFieldValue(Object target, String fieldName, Object value) * @param target the target object in which the field resides * @param field the field to set * @param value the new value - * @throws RuntimeReflectionException if any error occurs setting the field value + * @throws RuntimeReflectionException if any error occurs while setting the field value * @see Field#set(Object, Object) */ public static void setFieldValue(Object target, Field field, Object value) { @@ -623,7 +623,7 @@ public static Method findMethod(Class targetClass, String methodName, Class the return type parameter * @return result of calling the method (which could be {@code null}), cast to type {@code T} - * @throws RuntimeReflectionException if any error occurs invoking the method (excluding type cast errors) + * @throws RuntimeReflectionException if any error occurs while invoking the method (excluding type cast errors) * @throws ClassCastException if the given return type is not correct */ public static T invokeExpectingReturn(Method method, Object target, Class returnType, Object... args) { @@ -637,7 +637,7 @@ public static T invokeExpectingReturn(Method method, Object target, Class * @param target the object on which to invoke the method * @param args optionally, the method arguments * @return result of calling the method (which could be {@code null}) - * @throws RuntimeReflectionException if any error occurs invoking the method + * @throws RuntimeReflectionException if any error occurs while invoking the method * @see Method#invoke(Object, Object...) */ public static Object invokeExpectingReturn(Method method, Object target, Object... args) { @@ -657,7 +657,7 @@ public static Object invokeExpectingReturn(Method method, Object target, Object. * @param method the method to invoke * @param target the object on which to invoke the method * @param args optionally, the method arguments - * @throws RuntimeReflectionException if any error occurs invoking the method + * @throws RuntimeReflectionException if any error occurs while invoking the method * @see Method#invoke(Object, Object...) */ public static void invokeVoidReturn(Method method, Object target, Object... args) { @@ -677,7 +677,7 @@ public static void invokeVoidReturn(Method method, Object target, Object... args * @param the type of object * @param type the {@link Class} representing the object type * @return a new instance - * @throws RuntimeReflectionException if any error occurs invoking the constructor + * @throws RuntimeReflectionException if any error occurs while invoking the constructor * @throws IllegalArgumentException if a no-args constructor does not exist, is private, etc. * @see Class#getDeclaredConstructor(Class...) * @see java.lang.reflect.Constructor#newInstance(Object...) @@ -702,7 +702,7 @@ public static T newInstanceUsingNoArgsConstructor(Class type) { * Create a new instance of the given type using {@code arguments} to determine the constructor * argument types, using the first matching constructor based on the argument types and actual * constructor parameters. A constructor will match if the constructor parameter type is assignable - * from the argument type. For example if a one-argument constructor accepts a {@link CharSequence} and + * from the argument type. For example, if a one-argument constructor accepts a {@link CharSequence} and * the actual argument type is {@link String}, the constructor matches since String is assignable to * CharSequence. *

@@ -716,7 +716,7 @@ public static T newInstanceUsingNoArgsConstructor(Class type) { * @return a new instance * @throws IllegalArgumentException if no matching constructor was found for the given arguments * @throws NullPointerException if any of the arguments is {@code null} - * @throws RuntimeReflectionException if any error occurs invoking the constructor + * @throws RuntimeReflectionException if any error occurs while invoking the constructor * @see Class#getDeclaredConstructors() * @see java.lang.reflect.Constructor#newInstance(Object...) */ @@ -781,7 +781,7 @@ static boolean matchesPrimitive(Class parameterType, Class argType) { /** * This method is an alias for {@link #newInstance(Class, List, List)}, with the arguments as varargs, which - * may be more convenient in some situations. See that method's javadoc for more details, including the types + * may be more convenient in some situations. See that method's Javadoc for more details, including the types * of exceptions that can be thrown. * * @param the type of object @@ -813,7 +813,7 @@ public static T newInstanceExactParamTypes(Class type, List> par * @return a new instance * @throws IllegalArgumentException if any of the arguments is null, if the length of parameter types and * arguments is different, or if no constructor exists with the given parameter types - * @throws RuntimeReflectionException if any error occurs invoking the constructor + * @throws RuntimeReflectionException if any error occurs while invoking the constructor * @see Class#getDeclaredConstructor(Class...) * @see java.lang.reflect.Constructor#newInstance(Object...) */ diff --git a/src/main/java/org/kiwiproject/retry/KiwiRetryer.java b/src/main/java/org/kiwiproject/retry/KiwiRetryer.java index ef98aba9..65208bd1 100644 --- a/src/main/java/org/kiwiproject/retry/KiwiRetryer.java +++ b/src/main/java/org/kiwiproject/retry/KiwiRetryer.java @@ -277,7 +277,7 @@ public T call(Callable callable) { /** * Invoke the retryer with the given ID and {@link Callable}. *

- * This method allows you to use different IDs with the same {@link KiwiRetryer} instance, for example if + * This method allows you to use different IDs with the same {@link KiwiRetryer} instance, for example, if * the same retryer is called in separate threads it will be useful to be able to distinguish between them * in logs. * diff --git a/src/main/java/org/kiwiproject/retry/KiwiRetryerException.java b/src/main/java/org/kiwiproject/retry/KiwiRetryerException.java index 65aad55e..d736b080 100644 --- a/src/main/java/org/kiwiproject/retry/KiwiRetryerException.java +++ b/src/main/java/org/kiwiproject/retry/KiwiRetryerException.java @@ -13,7 +13,7 @@ *

* A {@link RetryException} indicates that all attempts failed, while an {@link InterruptedException} occurs when * a thread is interrupted. Note specifically that failed attempts may have failed due to a specific result or - * because an exception was thrown. In other words, a {@link Retryer} can be configured with result as well as + * because an exception was thrown. In other words, a {@link Retryer} can be configured with result and * exception predicates to trigger a retry. */ public class KiwiRetryerException extends RuntimeException { @@ -114,7 +114,7 @@ public boolean isCauseInterruptedException() { * * @return an Optional of the last failed Attempt */ - @SuppressWarnings("java:S1452") // suppress generic wildcard type, since it's in retrying-again like this + @SuppressWarnings("java:S1452") // suppress the generic wildcard type, since it's in retrying-again like this public Optional> getLastAttempt() { return unwrapAsRetryException().map(RetryException::getLastFailedAttempt); } diff --git a/src/main/java/org/kiwiproject/search/KiwiSearching.java b/src/main/java/org/kiwiproject/search/KiwiSearching.java index 93dc0957..19fe8870 100644 --- a/src/main/java/org/kiwiproject/search/KiwiSearching.java +++ b/src/main/java/org/kiwiproject/search/KiwiSearching.java @@ -7,7 +7,7 @@ import lombok.experimental.UtilityClass; /** - * Utilities related to searching and pagination. Supports both zero- and one-based page numbering but the + * Utilities related to searching and pagination. Supports both zero- and one-based page numbering, but the * default is one-based. Use the methods that accept {@link PageNumberingScheme} to work with either zero- * or one-based numbering. */ @@ -64,7 +64,7 @@ public void checkPageNumber(int pageNumber) { public static final int DEFAULT_PAGE_SIZE = 25; /** - * The rather opinionated value for default page size as a String, in order to support web framework annotations + * The rather opinionated value for default page size as a String, to support web framework annotations * like Jakarta REST's {@code jakarta.ws.rs.DefaultValue} that require a String. * * @implNote This must be a constant not an expression, otherwise trying to use it in an annotation like @@ -105,7 +105,7 @@ public static void checkPageNumber(int pageNumber) { * * @param pageNumber the page number to check * @param numberingScheme the page numbering scheme to use - * @throws IllegalArgumentException if the page number is invalid according to the numbering scheme + * @throws IllegalArgumentException if the page number is invalid, according to the numbering scheme * @see PageNumberingScheme */ public static void checkPageNumber(int pageNumber, PageNumberingScheme numberingScheme) { @@ -122,7 +122,7 @@ public static void checkPageNumber(int pageNumber, PageNumberingScheme numbering * * @param pageNumber the page number (one-based) * @param pageSize the page size - * @return the zero-based offset, e.g. for use in SQL queries using OFFSET and LIMIT + * @return the zero-based offset, e.g., for use in SQL queries using OFFSET and LIMIT * @throws IllegalArgumentException if the page number or size is invalid * @see PageNumberingScheme#ONE_BASED * @see #zeroBasedOffset(int, PageNumberingScheme, int) @@ -140,7 +140,7 @@ public static int zeroBasedOffset(int pageNumber, int pageSize) { * * @param pageNumber the page number (one-based) * @param pageSize the page size - * @return the zero-based offset, e.g. for use in SQL queries using OFFSET and LIMIT + * @return the zero-based offset, e.g., for use in SQL queries using OFFSET and LIMIT * @see #zeroBasedOffset(int, int) */ public static int zeroBasedOffsetForOneBasedPaging(int pageNumber, int pageSize) { @@ -154,7 +154,7 @@ public static int zeroBasedOffsetForOneBasedPaging(int pageNumber, int pageSize) * * @param pageNumber the page number (zero-based) * @param pageSize the page size - * @return the zero-based offset, e.g. for use in SQL queries using OFFSET and LIMIT + * @return the zero-based offset, e.g., for use in SQL queries using OFFSET and LIMIT */ public static int zeroBasedOffsetForZeroBasedPaging(int pageNumber, int pageSize) { return zeroBasedOffset(pageNumber, PageNumberingScheme.ZERO_BASED, pageSize); @@ -168,7 +168,7 @@ public static int zeroBasedOffsetForZeroBasedPaging(int pageNumber, int pageSize * @param pageNumber the page number * @param numberingScheme the page numbering scheme to use * @param pageSize the page size - * @return the zero-based offset, e.g. for use in SQL queries using OFFSET and LIMIT + * @return the zero-based offset, e.g., for use in SQL queries using OFFSET and LIMIT * @throws IllegalArgumentException if the page number or size is invalid * @see PageNumberingScheme */ diff --git a/src/main/java/org/kiwiproject/security/KiwiSecurity.java b/src/main/java/org/kiwiproject/security/KiwiSecurity.java index c5fce276..41efc44f 100644 --- a/src/main/java/org/kiwiproject/security/KiwiSecurity.java +++ b/src/main/java/org/kiwiproject/security/KiwiSecurity.java @@ -29,7 +29,7 @@ *

* WARNING: This is a low-level utility class. As such, many of its methods have a large number of arguments. This * is simply a byproduct of the many different objects that are required by the JDK classes to create objects such - * as {@link SSLContext}. It is intended that this class will be used by other, higher-level, utilities + * as {@link SSLContext}. It is intended that this class will be used by other, higher-level utilities * at higher levels of abstraction. */ @UtilityClass @@ -44,7 +44,7 @@ public class KiwiSecurity { * key and trust store types are {@link KeyStoreType#JKS}. Uses the default key and trust manager algorithms * as defined by {@link KeyManagerFactory} and {@link TrustManagerFactory}. *

- * If only the trust store is needed, supply {@code null} values for the {@code keyStorePath} and + * If only the trust store is necessary, supply {@code null} values for the {@code keyStorePath} and * {@code keyStorePassword}. * * @param keyStorePath path to the key store @@ -75,7 +75,7 @@ public static SSLContext createSslContext(@Nullable String keyStorePath, * key and trust store types are {@link KeyStoreType#JKS}. Uses the default key and trust manager algorithms * as defined by {@link KeyManagerFactory} and {@link TrustManagerFactory}. *

- * If only the trust store is needed, supply {@code null} values for the {@code keyStorePath} and + * If only the trust store is necessary, supply {@code null} values for the {@code keyStorePath} and * {@code keyStorePassword}. * * @param keyStorePath path to the key store @@ -112,7 +112,7 @@ public static SSLContext createSslContext(@Nullable String keyStorePath, * as defined by {@link KeyManagerFactory} and {@link TrustManagerFactory}. The key and trust store types should * be one of the algorithms defined in {@link KeyStoreType}. *

- * If only the trust store is needed, supply {@code null} values for the {@code keyStorePath} and + * If only the trust store is necessary, supply {@code null} values for the {@code keyStorePath} and * {@code keyStorePassword}. *

* WARNING: While public, this is very low-level and not generally intended for client code to call directly. @@ -160,7 +160,7 @@ public static SSLContext createSslContext(@Nullable String keyStorePath, * {@link TrustManagerFactory}. The key and trust store types should be one of the algorithms defined * in {@link KeyStoreType}. *

- * If only the trust store is needed, supply {@code null} values for the {@code keyStorePath} and + * If only the trust store is necessary, supply {@code null} values for the {@code keyStorePath} and * {@code keyStorePassword}. *

* WARNING: While public, this is very low-level and not generally intended for client code to call directly. @@ -208,7 +208,7 @@ public static SSLContext createSslContext(@Nullable String keyStorePath, * trust manager algorithms, and protocol. The key and trust store types should be one of the algorithms * defined in {@link KeyStoreType}. *

- * If only the trust store is needed, supply {@code null} values for the {@code keyStorePath} and + * If only the trust store is necessary, supply {@code null} values for the {@code keyStorePath} and * {@code keyStorePassword}. *

* WARNING: While public, this is very low-level and not generally intended for client code to call directly. @@ -296,7 +296,7 @@ private static Throwable unwrapNestedSslContextExceptionOrTake(Exception ex) { * Return an {@link Optional} containing a {@link KeyStore} for the given {@link KeyStoreType}, path, and * password, or an empty {@link Optional} if either path or password is null. *

- * This method is intended to load an existing key store. If you need to programatically create a new + * This method is intended to load an existing key store. If you need to programmatically create a new * one, use the {@link KeyStore} API directly. *

* If the returned Optional contains a KeyStore, it has been successfully loaded. @@ -424,4 +424,4 @@ public static TrustManager[] getTrustManagers(KeyStore trustStore, String algori throw new SSLContextException("Error getting trust managers", e); } } -} \ No newline at end of file +} diff --git a/src/main/java/org/kiwiproject/spring/config/KiwiSpringJavaConfigs.java b/src/main/java/org/kiwiproject/spring/config/KiwiSpringJavaConfigs.java index 721d7164..1ec28dff 100644 --- a/src/main/java/org/kiwiproject/spring/config/KiwiSpringJavaConfigs.java +++ b/src/main/java/org/kiwiproject/spring/config/KiwiSpringJavaConfigs.java @@ -11,7 +11,7 @@ import java.util.Set; /** - * Static utility methods for Spring Java-based configuration, i.e. Spring JavaConfig. + * Static utility methods for Spring Java-based configuration, i.e., Spring JavaConfig. */ @UtilityClass public class KiwiSpringJavaConfigs { diff --git a/src/main/java/org/kiwiproject/spring/data/KiwiPage.java b/src/main/java/org/kiwiproject/spring/data/KiwiPage.java index 4f06ee22..05902111 100644 --- a/src/main/java/org/kiwiproject/spring/data/KiwiPage.java +++ b/src/main/java/org/kiwiproject/spring/data/KiwiPage.java @@ -13,9 +13,9 @@ import java.util.List; /** - * Represents one page of an overall list of results. + * Represents one page from a list of results. *

- * By default, pagination assumes a start page index of 0 (i.e. the page offset). You can change this + * By default, pagination assumes a start page index of 0 (i.e., the page offset). You can change this * by calling {@code setPagingStartsWith(int)} or {@code usingOneAsFirstPage()}. *

* You can also indicate whether a sort has been applied to the data by setting the {@link KiwiSort} via @@ -35,10 +35,10 @@ public class KiwiPage { private List content; /** - * The size limit of the pagination, for example each page can have up to 25 items. The last page will often + * The size limit of the pagination, for example, each page can have up to 25 items. The last page will often * contain fewer items than this limit unless the total number of items is such that there is no remainder - * when dividing the total by the page size. e.g. if the total number of items is 100 and the page size is 20, - * then each of the 5 pages has exactly 20 items (the page size). + * when dividing the total by the page size. For example, if the total number of items is 100 and the page size is + * 20, then each of the five pages has exactly 20 items (the page size). */ private long size; @@ -63,7 +63,7 @@ public class KiwiPage { private long totalElements; /** - * Describes any sort that is active for the pagination. Default value is null. + * Describes any sort that is active for the pagination. The default value is null. */ private KiwiSort sort; @@ -78,7 +78,7 @@ public class KiwiPage { * If you need to add a sort or change {@code pagingStartsWith}, you can chain the {@link #addKiwiSort(KiwiSort)} * and {@link #usingOneAsFirstPage()} in a fluent style. * - * @param pageNum the number of this page, can be 0 or 1-based (0 is the default) + * @param pageNum the number of this page; it can be 0 or 1-based (0 is the default) * @param limit the page size limit * @param total the total number of elements in the overall result list * @param contentList the content on this page diff --git a/src/main/java/org/kiwiproject/spring/data/KiwiSort.java b/src/main/java/org/kiwiproject/spring/data/KiwiSort.java index 55ec6c40..962e5448 100644 --- a/src/main/java/org/kiwiproject/spring/data/KiwiSort.java +++ b/src/main/java/org/kiwiproject/spring/data/KiwiSort.java @@ -80,7 +80,7 @@ public boolean isDescending() { private boolean ascending; /** - * Create a new instance with ascending sort direction. + * Create a new instance with an ascending sort direction. *

* If you want to specify that the sort is not case-sensitive, you can immediately call the * {@link #ignoringCase()} in a fluent style. @@ -93,7 +93,7 @@ public static KiwiSort ofAscending(String property) { } /** - * Create a new instance with descending sort direction. + * Create a new instance with a descending sort direction. *

* If you want to specify that the sort is not case-sensitive, you can immediately call the * {@link #ignoringCase()} in a fluent style. @@ -148,7 +148,7 @@ public static KiwiSort of(String property, KiwiSort.Direction direction) { } /** - * Specifies that the sort is not case-sensitive, i.e. it ignores case. + * Specifies that the sort is not case-sensitive, i.e., it ignores the case. * * @return this instance, for method chaining */ diff --git a/src/main/java/org/kiwiproject/spring/data/KiwiSpringMongoQueries.java b/src/main/java/org/kiwiproject/spring/data/KiwiSpringMongoQueries.java index a2bab977..9cce19d4 100644 --- a/src/main/java/org/kiwiproject/spring/data/KiwiSpringMongoQueries.java +++ b/src/main/java/org/kiwiproject/spring/data/KiwiSpringMongoQueries.java @@ -97,15 +97,15 @@ public static Page paginate(MongoTemplate mongoTe * Add date restrictions to the given property. *

* Specify both start and end milliseconds (since the epoch) to create a closed range, or specify only start or - * end milliseconds to create an open-range. E.g. if only start milliseconds is specified, then the criteria + * end milliseconds to create an open-range. E.g., if only start milliseconds is specified, then the criteria * includes only dates that are equal to or after the given value, with no upper bound. *

* If both start and end milliseconds are null, the call is a no-op. * * @param query the MongoDB query on which to add the criteria * @param propertyName the property name, which is expected to be of type {@link Date} - * @param startDateInclusiveMillis the start date, inclusive. May be null. - * @param endDateInclusiveMillis the end date, inclusive. May be null. + * @param startDateInclusiveMillis the start date, inclusive; it may be null. + * @param endDateInclusiveMillis the end date, inclusive; it may be null. */ public static void addDateBounds(Query query, String propertyName, @@ -222,7 +222,7 @@ public static void addPartialOrEqualMatchCriteria(Query query, /** * Add a partial or equal match criteria for the given property and match strings. Any of the match strings - * are considered to be a match, i.e. this effectively performs an OR operation. + * are considered to be a match, i.e., this effectively performs an OR operation. * * @param query the MongoDB query on which to add the criteria * @param matchStrings the strings to match, using an OR operation diff --git a/src/test/java/org/kiwiproject/retry/KiwiRetryerTest.java b/src/test/java/org/kiwiproject/retry/KiwiRetryerTest.java index b1964eca..7b8ad21a 100644 --- a/src/test/java/org/kiwiproject/retry/KiwiRetryerTest.java +++ b/src/test/java/org/kiwiproject/retry/KiwiRetryerTest.java @@ -480,10 +480,10 @@ void shouldHandleMixedSuccessAndFailure() { assertThatThrownBy(allFutures::join).isExactlyInstanceOf(CompletionException.class); - // First one should have succeeded + // The first one should have succeeded assertThat(future1).isCompletedWithValueMatching(response -> response.getStatus() == 200); - // Second one should have failed because of bad response status 500 + // The second one should have failed because of bad response status 500 var thrownByFuture2 = catchThrowable(future2::join); assertThat(thrownByFuture2) .isExactlyInstanceOf(CompletionException.class) @@ -496,7 +496,7 @@ void shouldHandleMixedSuccessAndFailure() { assertThat(result2.getStatus()).isEqualTo(500); assertThat(result2.getEntity()).isEqualTo(2); - // Third one should have failed because of SocketTimeoutException + // The third one should have failed because of SocketTimeoutException var thrownByFuture3 = catchThrowable(future3::join); assertThat(thrownByFuture3) .isExactlyInstanceOf(CompletionException.class) diff --git a/src/test/java/org/kiwiproject/security/KiwiSecurityTest.java b/src/test/java/org/kiwiproject/security/KiwiSecurityTest.java index 4caa5a67..491d55b3 100644 --- a/src/test/java/org/kiwiproject/security/KiwiSecurityTest.java +++ b/src/test/java/org/kiwiproject/security/KiwiSecurityTest.java @@ -393,7 +393,7 @@ void whenInvalidPath() { } /** - * @implNote Per JavaDocs on {@link java.security.KeyStore#load(InputStream, char[])} the root cause of + * @implNote Per Javadocs on {@link java.security.KeyStore#load(InputStream, char[])} the root cause of * an incorrect password should be {@link UnrecoverableKeyException} */ @Test diff --git a/src/test/java/org/kiwiproject/spring/data/KiwiPagingTest.java b/src/test/java/org/kiwiproject/spring/data/KiwiPagingTest.java index c56f976f..d512101d 100644 --- a/src/test/java/org/kiwiproject/spring/data/KiwiPagingTest.java +++ b/src/test/java/org/kiwiproject/spring/data/KiwiPagingTest.java @@ -55,7 +55,7 @@ void shouldCreatePageable_WhenPagingRequestSortPropertiesAreNotPresent() { request.setPage(5); request.setLimit(25); - // These should be null by default, but be explicit anyway + // These should be null by default but be explicit anyway request.setPrimarySort(null); request.setSecondarySort(null);