From b0beabf8b46ff3d882ef08c4308064ee8a65da05 Mon Sep 17 00:00:00 2001 From: Konrad Neitzel Date: Thu, 3 Apr 2025 20:15:18 +0200 Subject: [PATCH] Refactor utility classes and update dependencies. Added private constructors to utility classes to enforce non-instantiability. Improved method documentation for clarity and updated dependency versions in the project. These changes enhance code maintainability, readability, and compatibility. --- .../core/commandline/ArgumentProvider.java | 54 +++-- .../neitzel/core/commandline/Parameter.java | 151 ++++++++++++-- .../de/neitzel/core/commandline/Parser.java | 117 ++++++++--- .../de/neitzel/core/config/Configuration.java | 173 ++++++++++------ .../core/io/ConvertedEncodingFileReader.java | 73 ++++--- .../core/io/ISO8859EncodingFileReader.java | 29 +++ .../de/neitzel/core/io/StringEncoder.java | 53 +++-- .../de/neitzel/core/sound/ToneGenerator.java | 12 ++ .../java/de/neitzel/core/sound/ToneTable.java | 12 ++ .../main/java/de/neitzel/core/sql/Query.java | 10 +- .../neitzel/core/sql/TrimmingResultSet.java | 12 +- .../java/de/neitzel/core/util/ArrayUtils.java | 68 ++++++- .../java/de/neitzel/core/util/EnumUtil.java | 42 +++- .../java/de/neitzel/core/util/FileUtils.java | 192 +++++++++++------- .../core/util/RegionalizationMessage.java | 61 ++++-- .../java/de/neitzel/core/util/Strings.java | 120 +++++++---- .../java/de/neitzel/core/util/XmlUtils.java | 120 +++++++---- fx-example/pom.xml | 156 -------------- .../java/de/neitzel/log4j/Log4jUtils.java | 47 +++-- pom.xml | 15 +- 20 files changed, 1004 insertions(+), 513 deletions(-) diff --git a/core/src/main/java/de/neitzel/core/commandline/ArgumentProvider.java b/core/src/main/java/de/neitzel/core/commandline/ArgumentProvider.java index 2c2efd5..c4906b4 100644 --- a/core/src/main/java/de/neitzel/core/commandline/ArgumentProvider.java +++ b/core/src/main/java/de/neitzel/core/commandline/ArgumentProvider.java @@ -3,23 +3,43 @@ package de.neitzel.core.commandline; import java.util.Iterator; /** - * Provides one argument after the other. + * The ArgumentProvider class is a helper utility for iterating over an array + * of command-line arguments. It provides methods to check for available arguments + * and retrieve them in sequence. + * + * This class is designed to work seamlessly with a command-line parser + * and handle tokenized inputs efficiently. It implements the Iterator interface + * for ease of iteration. */ public class ArgumentProvider implements Iterator { /** - * List of Arguments (from command line) + * A String array representing the command-line arguments provided to the application. + * This array holds each tokenized element of the command-line input for further parsing + * and processing by the application logic. It is used within the {@code ArgumentProvider} + * class to iterate through and retrieve arguments systematically. */ private String[] arguments; /** - * Current element we work on. + * Tracks the current position within an array of arguments. + * + * This variable is used to index into the arguments array, enabling + * sequential access to command-line tokens. It is incremented as arguments + * are processed or retrieved using methods such as {@code next()} or {@code peek()} + * in the {@link ArgumentProvider} class. + * + * Its value starts at 0 and increases until it reaches the length of + * the provided arguments array, at which point iteration ends. */ private int current = 0; /** - * Creates a new instance of ArgumentProvider. - * @param arguments List of Arguments. + * Creates an instance of the ArgumentProvider class to iterate over the given array of arguments. + * If the provided array is null, it initializes the arguments with an empty array. + * + * @param arguments The array of command-line arguments to be iterated over. + * If null, it defaults to an empty array. */ public ArgumentProvider(final String[] arguments) { if (arguments == null) { @@ -30,25 +50,29 @@ public class ArgumentProvider implements Iterator { } /** - * Checks if more arguments are available. - * @return True if more arguments are available else false. + * Checks if there are more arguments available to iterate over. + * + * @return true if there are additional arguments available; false otherwise. */ public boolean hasNext() { return current < arguments.length; } /** - * Checks if count more arguments are available. - * @param count Number of arguments we want to get. - * @return True if count more arguments are available else false. + * Determines if the specified number of additional arguments are available in the collection. + * + * @param count the number of additional arguments to check for availability + * @return true if there are at least the specified number of arguments available, otherwise false */ public boolean hasNext(final int count) { return current + count <= arguments.length; } /** - * Get the next token. - * @return The next token or null if no more available. + * Retrieves the next argument in the sequence. + * If no more arguments are available, returns {@code null}. + * + * @return the next argument as a {@code String}, or {@code null} if no further arguments are available */ public String next() { if (!hasNext()) return null; @@ -59,8 +83,10 @@ public class ArgumentProvider implements Iterator { } /** - * Get the next token without removing it. - * @return The next token or null if no more available. + * Returns the next argument in the sequence without advancing the iterator. + * If there are no more arguments available, this method returns null. + * + * @return the next argument in the sequence or null if no arguments are available */ public String peek() { if (!hasNext()) return null; diff --git a/core/src/main/java/de/neitzel/core/commandline/Parameter.java b/core/src/main/java/de/neitzel/core/commandline/Parameter.java index 14a7b54..f47ee86 100644 --- a/core/src/main/java/de/neitzel/core/commandline/Parameter.java +++ b/core/src/main/java/de/neitzel/core/commandline/Parameter.java @@ -8,67 +8,184 @@ import java.util.List; import java.util.function.Consumer; /** - * A parameter on the command line. - *
- * Each parameter has to start with either - or /! + * The `Parameter` class defines a command-line parameter with associated metadata, + * such as constraints on the number of values it accepts, descriptions, and aliases. + * It also allows specifying callbacks to handle parameter processing. + * + * This class is intended to be used as part of a command-line parser, enabling + * structured handling of arguments provided via the command line. */ @Slf4j @Builder @Getter @Setter -@AllArgsConstructor -@NoArgsConstructor public class Parameter { /** - * Name of the parameter. + * Represents a command-line parameter definition within the application. + * + * This class encapsulates the metadata and configuration of a command-line parameter, + * including its name, aliases, descriptions, value constraints, and behavior. Instances + * of this class are used to define and manage the parameters that the `Parser` class + * recognizes and processes. + * + * A parameter can be configured as a default parameter or as a help command. The default + * parameter serves as a catch-all for unmatched command-line inputs, while the help + * command provides usage information for users. + */ + public Parameter() { + } + + /** + * Constructs a new Parameter with the given attributes. + * + * @param name The name of the parameter. + * @param minNumberValues The minimum number of values allowed for this parameter. + * @param maxNumberValues The maximum number of values allowed for this parameter. + * @param multipleEntries Indicates whether multiple entries are allowed for this parameter. + * @param shortDescription A brief description of the parameter. + * @param longDescription A detailed description of the parameter. + * @param callback A consumer function that processes a list of values associated with this parameter. + * @param isHelpCommand Indicates whether this parameter represents a help command. + * @param isDefaultParameter Indicates whether this parameter is the default parameter. + * @param aliasList A list of aliases for this parameter. + */ + public Parameter(String name, int minNumberValues, int maxNumberValues, boolean multipleEntries, String shortDescription, String longDescription, Consumer> callback, boolean isHelpCommand, boolean isDefaultParameter, List aliasList) { + this.name = name; + this.minNumberValues = minNumberValues; + this.maxNumberValues = maxNumberValues; + this.multipleEntries = multipleEntries; + this.shortDescription = shortDescription; + this.longDescription = longDescription; + this.callback = callback; + this.isHelpCommand = isHelpCommand; + this.isDefaultParameter = isDefaultParameter; + this.aliasList = aliasList; + } + + /** + * The `name` variable represents the primary identifier for a parameter. + * This string is used to uniquely identify a command-line parameter when parsing + * arguments. It serves as the key for registering and retrieving parameters in a + * command-line parser. + * + * The value of `name` is case-insensitive and can be used alongside aliases to + * recognize and process parameters provided in the command-line input. */ private String name; /** - * Min number of values given. + * Specifies the minimum number of values required for this parameter. + * + * This variable enforces a constraint on the number of arguments that must + * be provided for the parameter during command-line parsing. If the number of + * provided arguments is less than this value, an exception will be thrown during parsing. + * + * It is primarily used in validation logic within the command-line parser + * to ensure the required input is received for proper processing of the parameter. */ private int minNumberValues; /** - * Max number of values given. + * Specifies the maximum number of values that the corresponding parameter can accept. + * + * This field is used to validate and enforce constraints during command-line parsing. + * If more values than specified are provided for a parameter, the parser throws an exception + * to indicate a violation of this constraint. + * + * A value of 0 implies that the parameter does not support any values, while a positive + * value indicates the exact maximum limit of acceptable values. */ private int maxNumberValues; /** - * Defines if the parameter can be given multiple times. + * Indicates whether the parameter allows multiple entries. + * + * If set to {@code true}, the parameter can be specified multiple times + * on the command-line. This allows the association of multiple values + * or options with the same parameter name. + * + * If set to {@code false}, the parameter can be specified only once + * during command-line parsing. */ private boolean multipleEntries; /** - * Short description of the parameter. + * A concise, human-readable description of the parameter's purpose and functionality. + * + * This description provides a brief summary to help users understand the + * essential role of the parameter within the command-line parser. It is typically + * displayed in usage instructions, help messages, or command summaries. */ private String shortDescription; /** - * Long description of the parameter. + * A detailed, extended description of the parameter's purpose and usage. + * + * This description provides deeper context about what the parameter represents, + * how it fits into the overall command-line application, and any nuances + * associated with its use. It is displayed when help or additional documentation + * for a specific parameter is requested. */ private String longDescription; /** - * Callback wenn der Parameter gefunden wurde. + * A callback function that processes a list of string arguments for a specific parameter. + * The callback is invoked during command-line parsing when a parameter is recognized, + * passing the associated values of the parameter for further processing. + * + * The provided {@link Consumer} implementation defines the logic to + * handle or validate the values supplied for a command-line parameter. The values + * passed are determined based on the parameter's configuration (e.g., minimum and + * maximum number of associated values). + * + * This field is typically set for the `Parameter` class to enable custom handling + * of parameter-specific logic, such as invoking a help command or performing + * business logic with the values parsed from the command-line arguments. */ private Consumer> callback; /** - * Determines if this Element is the parameter for help. + * Indicates whether the parameter is designated as the help command. + * + * When set to {@code true}, this parameter is treated as the special help command + * within the command-line parser. A parameter marked as the help command typically + * provides users with information about available options or detailed descriptions + * of specific commands when invoked. If this flag is enabled, a custom callback + * method for displaying help context is automatically associated with the parameter. */ private boolean isHelpCommand; /** - * Determines if this Parameter is the default parameter. - *
- * A default parameter must take at least one additional value. + * Indicates whether the parameter is designated as the default parameter. + * + * The default parameter is a special type of parameter that can accept arguments + * without an explicit prefix or identifier. It is used when a provided command-line + * argument does not match any defined parameter and does not start with a special + * character (e.g., '-') typically used to denote named parameters. + * + * If this field is set to {@code true}, the parameter is treated as the default + * parameter. Only one parameter can be assigned this role within the parser. + * Attempting to assign multiple default parameters or a default parameter without + * accepting values (both `minNumberValues` and `maxNumberValues` set to 0) will + * result in an exception during configuration. + * + * This property is utilized during the parsing process to determine whether an + * unmatched argument should be handled as a default parameter value, simplifying + * the handling of positional arguments or other unnamed input data. */ private boolean isDefaultParameter; /** - * List of aliases. + * A list of alias names associated with a parameter. + * + * This variable holds alternative names that can be used + * to reference the parameter in command-line input. Each alias + * functions as an equivalent to the primary parameter name. + * Aliases are case-insensitive when used within the command-line parser. + * + * The aliases associated with a parameter allow greater flexibility + * and user convenience when specifying parameters during command-line execution. */ @Singular("alias") private List aliasList; diff --git a/core/src/main/java/de/neitzel/core/commandline/Parser.java b/core/src/main/java/de/neitzel/core/commandline/Parser.java index c6074f2..f6e7728 100644 --- a/core/src/main/java/de/neitzel/core/commandline/Parser.java +++ b/core/src/main/java/de/neitzel/core/commandline/Parser.java @@ -5,26 +5,76 @@ import lombok.extern.slf4j.Slf4j; import java.util.*; /** - * A parser of the CommandLine. - *
- * Parameter are defined. Each parameter will start with either - or /. + * The Parser class is responsible for parsing and handling command-line arguments. + * It allows for the registration of known parameters and provides mechanisms + * to validate and process command-line input. */ @Slf4j public class Parser { /** - * Parameters known by the CommandLineParser. + * A map to store parameters where the key is a string representing + * the parameter name and the value is the corresponding {@link Parameter} object. + * + * This map serves as a registry for defining, organizing, and accessing + * command-line parameters. Each entry holds a parameter's metadata and + * its associated configuration to facilitate effective command-line parsing. + * + * Key considerations: + * - The key represents the primary name of the parameter. + * - The value, encapsulated as a {@link Parameter} object, includes + * details such as descriptions, value constraints, aliases, and processing logic. */ private Map parameters = new HashMap<>(); /** - * The default parameter. + * The `defaultParameter` variable represents the default command-line parameter for a parser. + * + * This parameter is used to capture arguments that do not explicitly match any named parameter + * or alias. It acts as a catch-all for unnamed command-line input, often simplifying the handling + * of positional arguments or other free-form input provided by the user. + * + * It is essential to note: + * - Only one parameter can be designated as the default parameter in a command-line parser. + * - The parameter must allow values to be processed (e.g., its `minNumberValues` or `maxNumberValues` + * should not disallow input). + * - This parameter is automatically invoked if an input does not match any explicitly named + * parameter or alias in the parser configuration. + * + * When set to `null`, the parser does not handle unmatched arguments, and unrecognized inputs + * may result in an error or exception, depending on the parser's implementation. */ private Parameter defaultParameter = null; /** - * Adds a parameter to the list of known parameters. - * @param parameter + * Constructs a new instance of the `Parser` class. + * + * The `Parser` class is responsible for parsing and processing + * command-line arguments. It interprets input data based on defined + * parameters and provides structured access to arguments, enabling + * streamlined application configuration and execution. + * + * This constructor initializes the parser without any predefined + * configuration or parameters. Users can define parameters, + * add handlers, and parse command-line arguments using available + * methods in the class. + */ + public Parser() { + } + + /** + * Adds a new parameter to the internal parameter map. The method registers the parameter + * using its primary name and all specified aliases (case-insensitive). It also sets up + * specific behaviors for help and default parameters based on the parameter's configuration. + * + * @param parameter the Parameter object to be added. It contains the primary name, aliases, + * and other metadata such as whether it is a help command or default parameter. + * The parameter must fulfill specific constraints if defined as the default + * parameter (e.g., accepting values). + * + * @throws IllegalArgumentException if the parameter is defined as a default parameter and + * does not accept values (both minNumberValues and maxNumberValues + * are set to 0). */ public void addParameter(final Parameter parameter) { // Add by name @@ -48,13 +98,12 @@ public class Parser { } /** - * Checks if param is a parameter. - *
- * - When the parameter is known as a parameter, then it is true. - * - Everything that starts with a - must be a known parameter -> false - * - Parameter is not known and does not start with a -? -> Default parameter if available. - * @param param Parameter in lower case to check. - * @return true if it is either a known parameter or an argument for the default parameter. + * Checks whether a given parameter string matches a valid parameter within the defined constraints. + * + * @param param the parameter string to be checked. This can either be a key defined in the `parameters` map + * or a potential default parameter if it does not start with a dash ("-"). + * @return {@code true} if the parameter is a valid entry in the `parameters` map or matches the default parameter; + * {@code false} otherwise, including when the parameter starts with a dash ("-"). */ protected boolean isParameter(final String param) { if (parameters.containsKey(param)) return true; @@ -63,8 +112,15 @@ public class Parser { } /** - * Parse the given commandline arguments. - * @param args Commandline Arguments to parse. + * Parses an array of command-line arguments and processes them as defined by the application's parameters. + * + * The method iteratively checks each argument in the provided array, validates it against + * the registered parameters, and invokes the corresponding processing callback if applicable. + * Unrecognized parameters or missing required values will result in an {@code IllegalArgumentException}. + * + * @param args the array of command-line arguments to be parsed and processed. Each element in this + * array represents a single input argument provided to the application. The format and + * content of the arguments are expected to conform to the application's parameter definitions. */ public void parse(final String[] args) { ArgumentProvider provider = new ArgumentProvider(args); @@ -96,11 +152,19 @@ public class Parser { } /** - * Get the given optional data of a parameter- - * @param provider Provider of token. - * @param min Minimum number of elements to get. - * @param max Maximum number of elements to get. - * @return List of token of the Parameter. + * Retrieves a list of options by consuming arguments from the provided {@link ArgumentProvider} + * within the range specified by the minimum and maximum values. + * + * @param provider The source providing the command-line arguments. This object allows + * retrieving and examining argument strings in sequence. + * @param min The minimum number of arguments to be retrieved. If fewer arguments + * are available, no arguments will be added to the result. + * @param max The maximum number of arguments to be retrieved. If `max` is smaller + * than `min`, it will be adjusted to match `min`. Only up to `max` + * arguments will be added to the result. + * @return A list of argument strings, containing up to `max` elements and at least `min` + * elements if sufficient arguments are available. The list will not include + * arguments already recognized in the `parameters` map. */ private List getOptions(ArgumentProvider provider, int min, int max) { if (max < min) max = min; @@ -120,8 +184,15 @@ public class Parser { } /** - * Callback for help command. - * @param arguments null for general help or name of a command. + * Handles the help command when invoked in the command-line interface, providing information about available parameters. + * If no arguments are provided, it lists all possible parameters and their short descriptions. + * If specific arguments are supplied, it provides the detailed description of the corresponding parameter. + * In case an unknown parameter is specified, it indicates so to the user. + * + * @param arguments a list of strings representing the user-provided arguments. If empty or {@code null}, + * the method lists all available parameters with their short descriptions. If a parameter name + * is provided in the list, its detailed information is displayed. If an unrecognized parameter + * is provided, a corresponding message is shown. */ public void helpCommandCallback(final List arguments) { if (arguments == null || arguments.size() == 0) { diff --git a/core/src/main/java/de/neitzel/core/config/Configuration.java b/core/src/main/java/de/neitzel/core/config/Configuration.java index 8cf7da9..df2f7d9 100644 --- a/core/src/main/java/de/neitzel/core/config/Configuration.java +++ b/core/src/main/java/de/neitzel/core/config/Configuration.java @@ -16,21 +16,49 @@ import java.util.Map; import java.util.Properties; /** - * Base class for a simple configuration. + * Provides a utility class for managing configuration properties in an + * application. This class allows loading properties from files, accessing + * values with various types including environment variable substitution, + * and updating properties. */ @Slf4j public class Configuration { /** - * Properties with configuration data. + * A {@link Properties} object that stores a set of key-value pairs. + * This variable can be used to manage configuration settings or other + * collections of properties within the application. + * + * It provides methods to load, retrieve, and modify properties + * as necessary for the application's requirements. */ - private Properties properties = new Properties(); + private final Properties properties; /** - * Gets a boolean property - * @param defaultValue Default value to return if key is not present. - * @param key Key of the property to get. - * @return The value of the property if it exists or the default value. + * Constructs a new Configuration instance with default properties. + * This constructor initializes the Configuration object using an + * empty set of {@code Properties}. + */ + public Configuration() { + this(new Properties()); + } + + /** + * Constructs a new Configuration instance using the provided properties. + * + * @param properties the Properties object containing configuration key-value pairs + */ + public Configuration(Properties properties) { + this.properties = properties; + } + + /** + * Retrieves a boolean property value associated with the specified key. If the key does not exist in the properties, + * the provided default value is returned. The method also supports interpreting specific string values as true. + * + * @param key the key used to retrieve the boolean property + * @param defaultValue the default value returned if the key is not found in the properties + * @return the boolean value associated with the key, or the defaultValue if the key does not exist */ protected boolean getBooleanProperty(final String key, final boolean defaultValue) { if (!properties.containsKey(key)) return defaultValue; @@ -38,10 +66,12 @@ public class Configuration { } /** - * Gets a String property - * @param key Key of the property to query. - * @param defaultValue Default value to return if property not available. - * @return The property if it exists, else the default value. + * Retrieves the value of the specified property as a trimmed string. + * If the property is not found, the default value is returned. + * + * @param key the key of the property to retrieve + * @param defaultValue the default value to return if the property is not found + * @return the trimmed string value of the property, or the default value if the property is not found */ protected String getStringProperty(final String key, final String defaultValue) { if (!properties.containsKey(key)) return defaultValue; @@ -49,13 +79,13 @@ public class Configuration { } /** - * Gets a String property with all environment variables replaced - *

- * Environment variable can be included with ${variable name}. - *

- * @param key Key of the property to query. - * @param defaultValue Default value to return if property not available. - * @return The property if it exists, else the default value. + * Retrieves a string property value associated with the specified key, applies + * environment variable expansion on the value, and returns the processed result. + * + * @param key the key identifying the property to retrieve. + * @param defaultValue the default value to use if the property is not found. + * @return the processed property value with expanded environment variables, or + * the defaultValue if the property is not found. */ protected String getStringPropertyWithEnv(final String key, final String defaultValue) { String result = getStringProperty(key, defaultValue); @@ -63,26 +93,25 @@ public class Configuration { } /** - * Gets a String property without quotes. - *

- * If the value is put in quotes, then the quote signs are replaced. - *

- * @param key Key of the property to query. - * @param defaultValue Default value to return if property not available. - * @return The property if it exists, else the default value (without leading/ending quote signs). + * Retrieves the value of a string property associated with the specified key, + * removes any surrounding quotes from the value, and returns the resultant string. + * + * @param key the key associated with the desired property + * @param defaultValue the default value to return if the property is not found or is null + * @return the string property without surrounding quotes, or the defaultValue if the property is not found */ protected String getStringPropertyWithoutQuotes(final String key, final String defaultValue) { return Strings.removeQuotes(getStringProperty(key, defaultValue)); } /** - * Gets a String property without quotes. - *

- * If the value is put in quotes, then the quote signs are replaced. - *

- * @param key Key of the property to query. - * @param defaultValue Default value to return if property not available. - * @return The property if it exists, else the default value (without leading/ending quote signs). + * Retrieves the string value of a configuration property identified by the given key, + * removes surrounding quotes if present, and expands any environment variables found + * within the string. If the property is not found, a default value is used. + * + * @param key the key identifying the configuration property + * @param defaultValue the default value to use if the property is not found + * @return the processed string property with quotes removed and environment variables expanded */ protected String getStringPropertyWithoutQuotesWithEnv(final String key, final String defaultValue) { String result = getStringPropertyWithoutQuotes(key, defaultValue); @@ -90,12 +119,15 @@ public class Configuration { } /** - * Gets an Integer property. - *
- * Supports null as value. - * @param defaultValue Default value to return if key is not present. - * @param key Key of the property to get. - * @return The value of the property if it exists or the default value. + * Retrieves the integer value for the specified property key. If the key does + * not exist in the properties or the value is null/empty, the provided default + * value is returned. + * + * @param key the property key to retrieve the value for + * @param defaultValue the default value to return if the key is not present + * or the value is null/empty + * @return the integer value associated with the key, or the defaultValue if + * the key does not exist or its value is null/empty */ protected Integer getIntegerProperty(final String key, final Integer defaultValue) { if (!properties.containsKey(key)) return defaultValue; @@ -104,9 +136,11 @@ public class Configuration { } /** - * Sets an Integer property. - * @param key Key of the property to set. - * @param value Value to set. + * Sets an integer property in the properties object. If the provided value is null, + * an empty string will be stored as the property's value. + * + * @param key the key under which the property will be stored + * @param value the integer value to be stored; if null, an empty string will be used */ protected void setIntegerProperty(final String key, final Integer value) { if (value == null) { @@ -117,13 +151,14 @@ public class Configuration { } /** - * Gets the property as LocalDate. - *
- * An null value or an empty String is given as null. - * @param key Key of the property. - * @param defaultValue default Value. - * @param formatString Format String to use. - * @return The LocalDate stored the property or the default value if property unknown or couldn't be parsed. + * Retrieves a LocalDate value from the properties based on the provided key. + * If the key does not exist or the value is invalid, a default value is returned. + * + * @param key the key to look up the property in the properties map + * @param defaultValue the default LocalDate value to return if the key is not found + * @param formatString the format string to parse the LocalDate value + * @return the LocalDate value from the properties if available and valid, + * otherwise the defaultValue */ protected LocalDate getLocalDateProperty(final String key, final LocalDate defaultValue, final String formatString) { if (!properties.containsKey(key)) return defaultValue; @@ -134,12 +169,12 @@ public class Configuration { } /** - * Sets the LocalDate using the provided format String. - *
- * Null is allowed and is stored as empty string. - * @param key Key of the property to set. - * @param value Value to set. - * @param formatString Format string to use. + * Sets a property with the given key and a formatted LocalDate value. + * If the provided value is null, the property will be set to an empty string. + * + * @param key the key of the property to set + * @param value the LocalDate value to format and set as the property value + * @param formatString the pattern string used to format the LocalDate value */ protected void setLocalDateProperty(final String key, final LocalDate value, final String formatString) { if (value == null) { @@ -150,9 +185,11 @@ public class Configuration { } /** - * Sets a property to a new value. - * @param key Key of property to set. - * @param value New value of property. + * Sets a property with the specified key to the given value. If the value is null, + * it defaults to an empty string. Logs the operation and updates the property. + * + * @param key the key of the property to be set + * @param value the value to be associated with the specified key; defaults to an empty string if null */ public void setProperty(final String key, final String value) { String newValue = value == null ? "" : value; @@ -161,14 +198,22 @@ public class Configuration { } /** - * Loads the configuration of the file. + * Loads the content of the specified file using the provided file name. + * + * @param fileName the name of the file to be loaded */ public void load(final String fileName) { load(fileName, Charset.defaultCharset().name(), true); } /** - * Loads the configuration of the file. + * Loads the configuration from a specified file. If the file does not exist in the + * specified location, it attempts to find the file alongside the JAR file of the application. + * Reads the configuration with the provided encoding and an option to accept UTF-8 encoding. + * + * @param fileName the name of the configuration file to be loaded + * @param encoding the encoding format to be used while reading the configuration file + * @param acceptUTF8 a boolean flag indicating whether to accept UTF-8 encoding */ public void load(final String fileName, final String encoding, final boolean acceptUTF8) { log.info("Reading Config: " + fileName + " with encoding: " + encoding + "accepting UTF-8: " + acceptUTF8); @@ -201,8 +246,9 @@ public class Configuration { } /** - * Insert the configuration settings of the given config. - * @param config Configuration to merge into this instance. + * Merges the properties from the provided configuration into the current configuration. + * + * @param config the Configuration object whose properties will be merged into this instance */ public void merge(final Configuration config) { for(Map.Entry entry: config.properties.entrySet()) { @@ -211,8 +257,9 @@ public class Configuration { } /** - * Removes a key from the configuration. - * @param key + * Removes the specified key-value pair from the properties map if the key exists. + * + * @param key the key to be removed from the properties map */ public void remove(final String key){ if (properties.containsKey(key)) properties.remove(key); diff --git a/core/src/main/java/de/neitzel/core/io/ConvertedEncodingFileReader.java b/core/src/main/java/de/neitzel/core/io/ConvertedEncodingFileReader.java index f2b5ccf..aa37570 100644 --- a/core/src/main/java/de/neitzel/core/io/ConvertedEncodingFileReader.java +++ b/core/src/main/java/de/neitzel/core/io/ConvertedEncodingFileReader.java @@ -8,21 +8,38 @@ import java.nio.charset.Charset; import java.nio.charset.IllegalCharsetNameException; /** - * FileReader that converts an UTF-8 file to ISO-8859-15 if required. - *

- * This FileReader checks, if the file to be read is an UTF-8 file. - * If an UTF-8 encoding is found, a temporary file will be created with the content - * of the original File - just encoded in the new format. - *

- *

- * This Reader is mainly tested ith ISO-8859-15 and UTF-8. Other formats are not really supported. - *

+ * The ConvertedEncodingFileReader class extends {@link InputStreamReader} to provide functionality + * for handling file encoding conversion transparently. If a file is detected to be in UTF-8 encoding, + * this class converts it to the specified target encoding using a temporary file, then opens the reader + * with the converted encoding. If the file is already in the target encoding, it opens the reader directly. + * + * This class is useful for applications needing to process text files in specific encodings and ensures + * encoding compatibility. */ @Slf4j public class ConvertedEncodingFileReader extends InputStreamReader { + /** + * The `checkEncoding` variable specifies the default encoding to be used + * when verifying file encodings within the `ConvertedEncodingFileReader` class. + * This encoding is primarily used to determine whether a file needs conversion + * to the target format or can be read directly in its existing format. + * The default value is set to "ISO-8859-15". + * + * Modifying this variable requires careful consideration, as it affects + * the behavior of methods that rely on encoding validation, particularly + * in the process of detecting UTF-8 files or converting them during file reading. + */ private static String checkEncoding = "ISO-8859-15"; + /** + * Sets the encoding that will be used to check the file encoding for compatibility. + * Throws an exception if the specified encoding is not valid or supported. + * + * @param encoding the name of the character encoding to set as the check encoding; + * it must be a valid and supported Charset. + * @throws IllegalCharsetNameException if the specified encoding is not valid or supported. + */ private static void setCheckEncoding(final String encoding) { if (Charset.forName(encoding) != null) throw new IllegalCharsetNameException("Encoding " + encoding + " is not supported!"); @@ -30,32 +47,42 @@ public class ConvertedEncodingFileReader extends InputStreamReader { } /** - * Creates a new ConvertedEncodingFileReader from a given File. - * @param file File to convert if required and open reader. - * @param targetFormat Target Format to use. - * @throws IOException + * Constructs a ConvertedEncodingFileReader for a specified file and target encoding format. + * The class reads the provided file and ensures that its content is handled in the target encoding. + * If the file is not already in the target encoding, it converts the file's encoding + * transparently using a temporary file before reading it. + * + * @param file The file to be read. Must exist and be accessible. + * @param targetFormat The target character encoding format to which the file content should be converted. + * @throws IOException If the file does not exist, is inaccessible, or an error occurs during the encoding conversion process. */ public ConvertedEncodingFileReader(final File file, final String targetFormat) throws IOException { super(createTargetFormatInputFileStream(file, targetFormat), targetFormat); } /** - * Creates a new ISO8859ConvertedFileReader from a given File. - * @param filename File to convert if required and open reader. - * @throws IOException + * Constructs a ConvertedEncodingFileReader for reading a file with encoding conversion support. + * This constructor takes the file path as a string and ensures the file's encoding is either + * converted to the specified target format or read directly if it matches the target format. + * + * @param filename the path to the file to be read + * @param targetFormat the target encoding format to use for reading the file + * @throws IOException if an I/O error occurs while accessing or reading the specified file */ public ConvertedEncodingFileReader(final String filename, final String targetFormat) throws IOException { this(new File(filename), targetFormat); } /** - * Creates an ISO8859-15 encoded InputFileStream on an file. - *

- * If the file is UTF-8 encoded, then it is converted to a temp file and the temp file will be opened. - *

- * @param file - * @return The InputFileStream on the original file or the converted file in case of an UTF-8 file. - * @throws IOException + * Creates an input file stream for a given file, converting its encoding if necessary. + * If the file is not in UTF-8 encoding, a direct {@link FileInputStream} is returned for the file. + * If the file is in UTF-8 encoding, it is converted to the specified target format using a temporary file, + * and then an input stream for the temporary file is returned. + * + * @param file the file for which the input stream is to be created + * @param targetFormat the desired target encoding format + * @return a {@link FileInputStream} for the file or a temporary file with converted encoding + * @throws IOException if the file does not exist or an error occurs during file operations */ private static FileInputStream createTargetFormatInputFileStream(final File file, final String targetFormat) throws IOException { if (!file.exists()) { diff --git a/core/src/main/java/de/neitzel/core/io/ISO8859EncodingFileReader.java b/core/src/main/java/de/neitzel/core/io/ISO8859EncodingFileReader.java index e7bcdf0..05186c2 100644 --- a/core/src/main/java/de/neitzel/core/io/ISO8859EncodingFileReader.java +++ b/core/src/main/java/de/neitzel/core/io/ISO8859EncodingFileReader.java @@ -3,14 +3,43 @@ package de.neitzel.core.io; import java.io.File; import java.io.IOException; +/** + * The ISO8859EncodingFileReader class extends the ConvertedEncodingFileReader to provide + * file reading functionality with specific encoding support for ISO-8859-15. + * This class ensures that the file content is either read directly in the ISO-8859-15 encoding + * or converted transparently to this encoding if needed. + */ public class ISO8859EncodingFileReader extends ConvertedEncodingFileReader { + /** + * Represents the target encoding format used by the ISO8859EncodingFileReader class. + * The TARGET_FORMAT is set to "ISO-8859-15", which specifies an encoding standard + * that is a variant of ISO-8859-1, adding the Euro symbol and other additional characters. + * This constant is used to indicate the desired character encoding for reading file content. + */ private static final String TARGET_FORMAT = "ISO-8859-15"; + /** + * Constructs an instance of ISO8859EncodingFileReader to read the provided file + * while ensuring the encoding is set to ISO-8859-15. If the file is not in the + * target encoding, this method transparently converts the file content to match + * the encoding before reading. + * + * @param file The file to be read. Must exist and be accessible. + * @throws IOException If the file does not exist, is inaccessible, or an error + * occurs during the encoding conversion process. + */ public ISO8859EncodingFileReader(File file) throws IOException { super(file, TARGET_FORMAT); } + /** + * Constructs an ISO8859EncodingFileReader for reading a file with encoding conversion + * to the ISO-8859-15 format. This constructor accepts the file path as a string. + * + * @param filename the path to the file to be read + * @throws IOException if an I/O error occurs while accessing or reading the specified file + */ public ISO8859EncodingFileReader(String filename) throws IOException { super(filename, TARGET_FORMAT); } diff --git a/core/src/main/java/de/neitzel/core/io/StringEncoder.java b/core/src/main/java/de/neitzel/core/io/StringEncoder.java index 4193bdc..723d27f 100644 --- a/core/src/main/java/de/neitzel/core/io/StringEncoder.java +++ b/core/src/main/java/de/neitzel/core/io/StringEncoder.java @@ -1,17 +1,33 @@ package de.neitzel.core.io; /** - * An encoder for Strings. - *

- * All characters with unicode number less than 32 or greater than 127 or 38 (Ampersend) - * will be encoded with &#number; with number as the decimal unicode number. + * Utility class for encoding and decoding strings. + * This class provides methods for transforming strings into encoded representations + * and decoding them back to the original representation. */ public class StringEncoder { /** - * Decodes the encoded String. - * @param data Encoded string. - * @return Decoded String. + * Private constructor to prevent instantiation of the utility class. + * This utility class is not meant to be instantiated, as it only provides + * static utility methods for array-related operations. + * + * @throws UnsupportedOperationException always, to indicate that this class + * should not be instantiated. + */ + private StringEncoder() { + throw new UnsupportedOperationException("Utility class"); + } + + /** + * Decodes a string containing encoded characters back to its original representation. + * Encoded characters are expected to be in the format {@code "&#;"}, where + * {@code } is a numeric representation of the character to decode. + * + * @param data the string to decode; may contain encoded characters or regular text. If null, an empty string is returned. + * @return the decoded string with all encoded characters replaced by their original representations. + * @throws IllegalArgumentException if the input string has encoding markup + * that is improperly formatted or incomplete. */ public static String decodeData(final String data) { if (data == null) return ""; @@ -40,9 +56,13 @@ public class StringEncoder { } /** - * Decode a single character. - * @param data String in the form &#xxx; with xxx a decimal number. - * @return The decoded character. + * Decodes a character from its numeric character reference representation. + * The input string must represent an encoded character in the format {@code "&#;"}. + * + * @param data the string containing the numeric character reference to decode. + * It must start with {@code "&#"} and end with {@code ";"}. + * @return the decoded character represented by the numeric character reference. + * @throws IllegalArgumentException if the input string does not follow the expected format. */ public static char decodeCharacter(final String data) { if (!data.startsWith("&#")) throw new IllegalArgumentException("Data does not start with &# (" + data + ")"); @@ -51,12 +71,13 @@ public class StringEncoder { } /** - * Encode data to a better String representation. - *

- * All Characters between from ascii 32 to 127 (except 38 / &) - * are replaced with a &#code; where code is the number of the character. - * @param data String that should be encoded. - * @return Encoded String. + * Encodes the provided string by converting characters outside the ASCII range (32-127) + * and the ampersand {@code "&"} character into their corresponding numeric character reference + * representation (e.g., {@code "&"}). + * + * @param data the input string to encode; if null, an empty string is returned + * @return an encoded string where non-ASCII and ampersand characters + * are replaced with numeric character references */ public static String encodeData(final String data) { if (data == null) return ""; diff --git a/core/src/main/java/de/neitzel/core/sound/ToneGenerator.java b/core/src/main/java/de/neitzel/core/sound/ToneGenerator.java index cab8df8..9e92c17 100644 --- a/core/src/main/java/de/neitzel/core/sound/ToneGenerator.java +++ b/core/src/main/java/de/neitzel/core/sound/ToneGenerator.java @@ -10,6 +10,18 @@ import javax.sound.sampled.SourceDataLine; * It allows playing tones based on frequency or predefined tone names. */ public class ToneGenerator { + /** + * Private constructor to prevent instantiation of the utility class. + * This utility class is not meant to be instantiated, as it only provides + * static utility methods for array-related operations. + * + * @throws UnsupportedOperationException always, to indicate that this class + * should not be instantiated. + */ + private ToneGenerator() { + throw new UnsupportedOperationException("Utility class"); + } + /** * Plays a tone based on a predefined tone name for a specified duration. * diff --git a/core/src/main/java/de/neitzel/core/sound/ToneTable.java b/core/src/main/java/de/neitzel/core/sound/ToneTable.java index a195658..e592ae0 100644 --- a/core/src/main/java/de/neitzel/core/sound/ToneTable.java +++ b/core/src/main/java/de/neitzel/core/sound/ToneTable.java @@ -13,6 +13,18 @@ import java.util.HashMap; * frequency information for specific tones. */ public class ToneTable { + /** + * Private constructor to prevent instantiation of the utility class. + * This utility class is not meant to be instantiated, as it only provides + * static utility methods for array-related operations. + * + * @throws UnsupportedOperationException always, to indicate that this class + * should not be instantiated. + */ + private ToneTable() { + throw new UnsupportedOperationException("Utility class"); + } + /** * A static map that associates written tone names with their corresponding frequencies in hertz (Hz). * The keys represent tone names (e.g., "C4", "D#5"), and the values are their respective frequencies. diff --git a/core/src/main/java/de/neitzel/core/sql/Query.java b/core/src/main/java/de/neitzel/core/sql/Query.java index ac86b59..f92d184 100644 --- a/core/src/main/java/de/neitzel/core/sql/Query.java +++ b/core/src/main/java/de/neitzel/core/sql/Query.java @@ -22,7 +22,6 @@ import java.util.stream.StreamSupport; * @param The type of the objects returned by the query. */ @Slf4j -@RequiredArgsConstructor public class Query { /** @@ -69,6 +68,15 @@ public class Query { */ private String queryText; + /** + * Constructs a new Query object with the given database connection. + * + * @param connection The Connection object used to interact with the database. + */ + public Query(Connection connection) { + this.connection = connection; + } + /** * Executes the given SQL query using the provided database connection. * diff --git a/core/src/main/java/de/neitzel/core/sql/TrimmingResultSet.java b/core/src/main/java/de/neitzel/core/sql/TrimmingResultSet.java index 7a0b55a..1297e67 100644 --- a/core/src/main/java/de/neitzel/core/sql/TrimmingResultSet.java +++ b/core/src/main/java/de/neitzel/core/sql/TrimmingResultSet.java @@ -18,7 +18,6 @@ import java.util.Map; * If any additional behaviors or transformations are applied, they are documented * in the respective overridden method descriptions. */ -@RequiredArgsConstructor public class TrimmingResultSet implements ResultSet { /** @@ -31,7 +30,16 @@ public class TrimmingResultSet implements ResultSet { * SQL query execution lifecycle. */ private final ResultSet resultSet; - + + /** + * Initializes a new instance of the TrimmingResultSet class, wrapping the provided ResultSet. + * + * @param resultSet the ResultSet to be wrapped and processed by this TrimmingResultSet instance + */ + public TrimmingResultSet(ResultSet resultSet) { + this.resultSet = resultSet; + } + /** * Retrieves the string value from the specified column index of the current row in the ResultSet. * The value is trimmed to remove leading and trailing whitespace. If the value is null, it returns null. diff --git a/core/src/main/java/de/neitzel/core/util/ArrayUtils.java b/core/src/main/java/de/neitzel/core/util/ArrayUtils.java index bbc0131..0abb26d 100644 --- a/core/src/main/java/de/neitzel/core/util/ArrayUtils.java +++ b/core/src/main/java/de/neitzel/core/util/ArrayUtils.java @@ -1,15 +1,30 @@ package de.neitzel.core.util; +import java.util.Objects; + /** - * Utility Class with static methods about arrays. + * Utility class providing helper methods for working with arrays. */ public class ArrayUtils { /** - * Checks if a given char is inside an array of chars. - * @param array Array of chars to seach in. - * @param ch Character to search. - * @return true if character was found, else false. + * Private constructor to prevent instantiation of the utility class. + * This utility class is not meant to be instantiated, as it only provides + * static utility methods for array-related operations. + * + * @throws UnsupportedOperationException always, to indicate that this class + * should not be instantiated. + */ + private ArrayUtils() { + throw new UnsupportedOperationException("Utility class"); + } + + /** + * Checks if the given character array contains the specified character. + * + * @param array the character array to be searched + * @param ch the character to search for in the array + * @return true if the character is found in the array, false otherwise */ public static boolean contains(char[] array, char ch) { for(int index=0; index < array.length; index++) { @@ -17,4 +32,47 @@ public class ArrayUtils { } return false; } + + /** + * Checks if the specified integer array contains the given integer value. + * + * @param array the array of integers to search + * @param ch the integer value to search for in the array + * @return true if the array contains the specified integer value, false otherwise + */ + public static boolean contains(int[] array, int ch) { + for(int index=0; index < array.length; index++) { + if (array[index] == ch) return true; + } + return false; + } + + /** + * Checks if the specified long array contains the given long value. + * + * @param array the array of long values to search + * @param ch the long value to search for in the array + * @return true if the array contains the specified long value, false otherwise + */ + public static boolean contains(long[] array, long ch) { + for(int index=0; index < array.length; index++) { + if (array[index] == ch) return true; + } + return false; + } + + /** + * Checks if the specified array contains the given element. + * + * @param array the array to be searched + * @param ch the element to search for in the array + * @param the type of the elements in the array + * @return true if the element is found in the array, false otherwise + */ + public static boolean contains(T[] array, T ch) { + for(int index=0; index < array.length; index++) { + if (Objects.equals(array[index], ch)) return true; + } + return false; + } } diff --git a/core/src/main/java/de/neitzel/core/util/EnumUtil.java b/core/src/main/java/de/neitzel/core/util/EnumUtil.java index 7cb9bbf..5b029d5 100644 --- a/core/src/main/java/de/neitzel/core/util/EnumUtil.java +++ b/core/src/main/java/de/neitzel/core/util/EnumUtil.java @@ -4,12 +4,30 @@ import java.util.ArrayList; import java.util.List; /** - * Enumeration Utilities + * Utility class for working with Enum types, providing methods to parse and generate + * patterns for Enum flags. */ public class EnumUtil { /** - * Creates a regular expression to match a comma separated list of Flags. - * @return Regular expression to match flags. + * Private constructor to prevent instantiation of the utility class. + * This utility class is not meant to be instantiated, as it only provides + * static utility methods for array-related operations. + * + * @throws UnsupportedOperationException always, to indicate that this class + * should not be instantiated. + */ + private EnumUtil() { + throw new UnsupportedOperationException("Utility class"); + } + + /** + * Generates a regular expression pattern that matches all possible case-insensitive representations + * of the enum constants within the specified Enum class. The pattern also includes optional delimiters + * such as commas, spaces, and empty values, enabling the matching of lists or sequences of flag values. + * + * @param The type of the Enum. + * @param clazz The Enum class for which the regular expression is to be generated. + * @return A String containing the regular expression pattern for matching the Enum's flag values. */ public static > String getFlagRegEx(Class clazz) { StringBuilder result = new StringBuilder(); @@ -33,9 +51,21 @@ public class EnumUtil { } /** - * Parse a list of comma separated flags into a List of RequestFlags. - * @param flags String with comma separated flags. - * @return List of RequestFlags. + * Parses a delimited string containing Enum constant names into a list of Enum constants. + * + * This method takes an Enum class and a string of flags, splits the string by commas + * or whitespace, and converts each substring into an Enum constant of the given class. + * The flag names are case-insensitive and will be converted to uppercase before matching + * to the Enum constants. + * + * @param The type of the Enum. + * @param clazz The Enum class to which the flags should be parsed. + * @param flags A string containing the delimited list of flag names to parse. + * Individual names can be separated by commas or whitespace. + * @return A list of Enum constants parsed from the input string. If the input string + * is null or empty, an empty list is returned. + * @throws IllegalArgumentException if any of the flag names do not match the constants in the given Enum class. + * @throws NullPointerException if the clazz parameter is null. */ public static > List parseFlags(final Class clazz, final String flags) { List result = new ArrayList<>(); diff --git a/core/src/main/java/de/neitzel/core/util/FileUtils.java b/core/src/main/java/de/neitzel/core/util/FileUtils.java index 63e6d3e..8606083 100644 --- a/core/src/main/java/de/neitzel/core/util/FileUtils.java +++ b/core/src/main/java/de/neitzel/core/util/FileUtils.java @@ -10,37 +10,65 @@ import java.text.SimpleDateFormat; import java.util.stream.Collectors; /** - * Utility Methods regarding files. + * Utility class for handling file operations, such as encoding checks, content reading/writing, + * path manipulations, and file conversions. */ @Slf4j public class FileUtils { + /** + * Private constructor to prevent instantiation of the utility class. + * This utility class is not meant to be instantiated, as it only provides + * static utility methods for array-related operations. + * + * @throws UnsupportedOperationException always, to indicate that this class + * should not be instantiated. + */ + private FileUtils() { + throw new UnsupportedOperationException("Utility class"); + } /** - * Date/Time format to add to request files. + * Defines a standardized timestamp format for debugging purposes, specifically used for naming + * or identifying files with precise timestamps. The format is "yyyy-MM-dd_HH_mm_ss_SSS", which + * includes: + * - Year in four digits (yyyy) + * - Month in two digits (MM) + * - Day of the month in two digits (dd) + * - Hour in 24-hour format with two digits (HH) + * - Minutes in two digits (mm) + * - Seconds in two digits (ss) + * - Milliseconds in three digits (SSS) + * + * This ensures timestamps are sortable and easily identifiable. */ public static final SimpleDateFormat DEBUG_FILE_TIMESTAMP_FORMAT = new SimpleDateFormat("yyyy-MM-dd_HH_mm_ss_SSS"); /** - * Default encoding used to check the File + * Default encoding used for string checks and validations in the application. + * + * This constant represents the `ISO-8859-15` encoding, which is a standardized + * character set encoding, commonly used in contexts where backward compatibility + * with `ISO-8859-1` is required, but with support for certain additional characters, + * such as the euro currency symbol (€). */ public static final String DEFAULT_CHECK_ENCODING = "ISO-8859-15"; /** - * Default Buffer size. + * Specifies the default buffer size used for data processing operations. + * + * This constant represents the size of the buffer in bytes, set to 1024, + * and is typically utilized in input/output operations to optimize performance + * by reducing the number of read/write calls. */ public static final int BUFFER_SIZE = 1024; /** - * Checks if a File is UTF-8 encoded. - *

- * This method checks a file for - * - first 3 bytes for UTF-8 BOM (0xEF 0xBB 0xBF) - * - Existence of 0xC2 / 0xC3 character. - *

- * @param file File to check. - * @param checkEncoding Encoding to use for the check, e.g. ISO-8859-15. - * @return true if an UTF-8 file is found, else false. - * @throws IOException IOException is thrown if the file could not be read. + * Determines whether the given file is encoded in UTF-8. + * + * @param file The file to be checked for UTF-8 encoding. + * @param checkEncoding The character encoding to use while checking the file content. + * @return true if the file is determined to be encoded in UTF-8; false otherwise. + * @throws IOException If an I/O error occurs while reading the file. */ public static boolean isUTF8(final File file, final String checkEncoding) throws IOException { @@ -69,15 +97,14 @@ public class FileUtils { } /** - * Checks if the File has a UTF-8 BOM. - *

- * This method checks a file for - * - first 3 bytes for UTF-8 BOM (0xEF 0xBB 0xBF) - * - Existence of 0xC2 / 0xC3 character. - *

- * @param file File to check. - * @return true if an UTF-8 BOM Header was found. - * @throws IOException IOException is thrown if the file could not be read. + * Checks if the provided file starts with a UTF-8 Byte Order Mark (BOM). + * + * This method reads the first character of the file using a reader that assumes + * UTF-8 encoding and checks if it matches the Unicode Byte Order Mark (U+FEFF). + * + * @param file The file to check for a UTF-8 BOM. Must not be null. + * @return true if the file starts with a UTF-8 BOM, false otherwise. + * @throws IOException If an input or output exception occurs while reading the file. */ public static boolean hasUTF8BOM(final File file) throws IOException { try (InputStreamReader reader = new InputStreamReader(new FileInputStream(file), StandardCharsets.UTF_8)) { @@ -89,27 +116,27 @@ public class FileUtils { } /** - * Checks if a File is UTF-8 encoded. - *

- * This method checks a file for - * - first 3 bytes for UTF-8 BOM (0xEF 0xBB 0xBF) - * - Existence of 0xC2 / 0xC3 character. - *

- * @param file File to check. - * @return true if an UTF-8 file is found, else false. - * @throws IOException IOException is thrown if the file could not be read. + * Determines if the content of the given file is encoded in UTF-8. + * + * @param file The file to check for UTF-8 encoding. Must not be null. + * @return true if the file content is in UTF-8 encoding; false otherwise. + * @throws IOException If an I/O error occurs while reading the file. */ public static boolean isUTF8(final File file) throws IOException { return isUTF8(file, DEFAULT_CHECK_ENCODING); } /** - * Converts the given Textfile inFile to the outFile using the given encodings. - * @param inFile File to read as UTF-8. - * @param sourceFormat Format of the source file. - * @param outFile File to write with ISO-8859-15 format. - * @param targetFormat Format of the target file. - * @throws IOException Thrown when files couldn't be read / written. + * Converts the content of a text file from one character encoding format to another. + * + * This method reads the input text file using the specified source encoding and writes + * the content to the output text file in the specified target encoding. + * + * @param inFile The input text file to be converted. Must not be null. + * @param sourceFormat The character encoding of the input file. Must not be null or empty. + * @param outFile The output text file to write the converted content to. Must not be null. + * @param targetFormat The character encoding to be used for the output file. Must not be null or empty. + * @throws IOException If an I/O error occurs during reading or writing. */ public static void convertTextFile(final File inFile, final String sourceFormat, final File outFile, final String targetFormat) throws IOException { char[] buffer = new char[BUFFER_SIZE]; @@ -142,48 +169,66 @@ public class FileUtils { } /** - * Creates a new InputStreamReader with the given format or UTF-8 if an UTF-8 file was recognized. - * @param filename Name of file to read. - * @return An InputStreamReader + * Creates a universal file reader for the specified file name. + * This method initializes and returns an InputStreamReader to read + * the content of the given file. + * + * @param filename The name or path of the file to be read. + * @return An InputStreamReader for reading the specified file. + * @throws IOException If an I/O error occurs while creating the file reader. */ public static InputStreamReader createUniversalFileReader(final String filename) throws IOException { return createUniversalFileReader(new File(filename)); } /** - * Creates a new InputStreamReader with the given format or UTF-8 if an UTF-8 file was recognized. - * @param filename Name of file to read. - * @param expectedFormat Expected format e.g. ISO-8859-15 - * @return An InputStreamReader + * Creates a universal file reader for the specified file and format. + * The method resolves the file using its name and the expected format, + * returning an InputStreamReader for reading the file contents. + * + * @param filename the name of the file to be read. + * @param expectedFormat the format expected for the file content. + * @return an InputStreamReader for the specified file and format. + * @throws IOException if an I/O error occurs while opening or reading the file. */ public static InputStreamReader createUniversalFileReader(final String filename, final String expectedFormat) throws IOException { return createUniversalFileReader(new File(filename), expectedFormat); } /** - * Creates a new InputStreamReader with the given format or UTF-8 if an UTF-8 file was recognized. - * @param file File to read. - * @return An InputStreamReader + * Creates a universal file reader for the specified file using the default encoding and configuration. + * + * @param file The file to be read. Must not be null. + * @return An InputStreamReader configured to read the specified file. + * @throws IOException If an I/O error occurs while creating the reader. */ public static InputStreamReader createUniversalFileReader(final File file) throws IOException { return createUniversalFileReader(file, DEFAULT_CHECK_ENCODING, true); } /** - * Creates a new InputStreamReader with the given format or UTF-8 if an UTF-8 file was recognized. - * @param file File to read. - * @param expectedFormat Expected format e.g. ISO-8859-15 - * @return An InputStreamReader + * Creates a universal file reader for the specified file with an expected format. + * This method wraps the given file in an InputStreamReader for consistent character stream manipulation. + * + * @param file The file to be read. Must not be null. + * @param expectedFormat The expected format of the file (e.g., encoding). Must not be null. + * @return An InputStreamReader for the specified file, allowing the caller to read the file + * with the desired format applied. + * @throws IOException If an I/O error occurs during the creation of the reader. */ public static InputStreamReader createUniversalFileReader(final File file, final String expectedFormat) throws IOException { return createUniversalFileReader(file, expectedFormat, true); } /** - * Creates a new InputStreamReader with the given format or UTF-8 if an UTF-8 file was recognized. - * @param file File to read. - * @param expectedFormat Expected format e.g. ISO-8859-15 - * @return An InputStreamReader + * Creates an InputStreamReader for reading a file, considering the specified encoding format + * and whether UTF-8 should be accepted. Handles potential BOM for UTF-8 encoded files. + * + * @param file The file to be read. + * @param expectedFormat The expected encoding format of the file. + * @param acceptUTF8 Indicates whether UTF-8 encoding should be accepted if detected. + * @return An InputStreamReader for the specified file and encoding. + * @throws IOException If there is an error accessing the file or reading its content. */ public static InputStreamReader createUniversalFileReader(final File file, final String expectedFormat, final boolean acceptUTF8) throws IOException { String encoding = acceptUTF8 && isUTF8(file, expectedFormat) @@ -201,9 +246,13 @@ public class FileUtils { } /** - * Gets the parent directory of a file name. - * @param filename Name of file. - * @return Parent folder. + * Retrieves the parent directory of the given file or directory path. + * + * If the given path does not have a parent directory, it defaults to returning the + * current directory represented by ".". + * + * @param filename The file or directory path for which the parent directory is to be retrieved. + * @return The parent directory of the given path, or "." if no parent directory exists. */ public static String getParentDirectory(final String filename) { File file = new File(filename); @@ -211,9 +260,10 @@ public class FileUtils { } /** - * Gets the core name of the file without path. - * @param filename Filename with path. - * @return Filename without path. + * Extracts the name of a file from the given file path. + * + * @param filename The full path or name of the file. Must not be null. + * @return The name of the file without any directory path. */ public static String getFilename(final String filename) { File file = new File(filename); @@ -221,10 +271,11 @@ public class FileUtils { } /** - * Reads the content of a file (With the correct encoding!). - * @param filename Name of file to read. - * @return Content of the file or null in case of an error. - * @throws IOException Throes an IOException if the file cannot be read. + * Reads the content of a file and returns it as a string, joining all lines with the system line separator. + * + * @param filename The name of the file to be read. + * @return A string containing the content of the file with all lines joined by the system line separator. + * @throws IOException If an I/O error occurs while reading the file. */ public static String readFileContent(final String filename) throws IOException { try (BufferedReader reader = new BufferedReader(createUniversalFileReader(filename))) { @@ -233,10 +284,11 @@ public class FileUtils { } /** - * Writes the content given to a file. - * @param path Path of the file to write. - * @param content Content to write. - * @throws IOException Thrown if the file could not be written. + * Writes the given content to the specified file path. If the file already exists, it will be overwritten. + * + * @param path The path of the file to write to. Must not be null and must be writable. + * @param content The content to be written to the file. Must not be null. + * @throws IOException If an I/O error occurs during writing to the file. */ public static void writeFile(final Path path, final String content) throws IOException { try (BufferedWriter writer = new BufferedWriter(new FileWriter(path.toFile()))) { diff --git a/core/src/main/java/de/neitzel/core/util/RegionalizationMessage.java b/core/src/main/java/de/neitzel/core/util/RegionalizationMessage.java index 5d2e5be..345ee10 100644 --- a/core/src/main/java/de/neitzel/core/util/RegionalizationMessage.java +++ b/core/src/main/java/de/neitzel/core/util/RegionalizationMessage.java @@ -4,34 +4,53 @@ import java.text.MessageFormat; import java.util.Locale; import java.util.ResourceBundle; +/** + * The RegionalizationMessage class provides functionality to retrieve + * localized messages from a resource bundle and format messages with parameters. + * It supports multiple constructors for initializing with specific locales if needed. + */ public class RegionalizationMessage { /** - * Resource Bundle to use for operations. + * The `res` variable holds a `ResourceBundle` instance, + * which is used to retrieve locale-specific objects and messages. + * It facilitates the process of internationalization by loading resources + * such as text and messages from specified bundles based on the provided locale. + * + * This variable is initialized in constructors of the `RegionalizationMessage` class + * and is used internally by various methods to fetch localized messages. */ private ResourceBundle res; /** - * Creates a new instance of RegionalizationMessage. - * @param source Source of messages. + * Constructs a new RegionalizationMessage instance using the specified resource bundle source. + * This constructor initializes the resource bundle with the given source name. + * + * @param source The base name of the resource bundle to load. + * This is typically a fully qualified class name or package name for the resource. */ public RegionalizationMessage(final String source) { res = ResourceBundle.getBundle(source); } /** - * Creates a new instance of RegionalizationMessage. - * @param source Source of messages. - * @param locale Locale to use. + * Constructs a RegionalizationMessage object to retrieve localized messages + * from a specified resource bundle using the given source and locale. + * + * @param source The base name of the resource bundle, a fully qualified class name. + * @param locale The Locale object specifying the desired language and region for localization. */ public RegionalizationMessage(final String source, final Locale locale) { res = ResourceBundle.getBundle(source, locale); } /** - * Gets the Message behind a key. - * @param key Key to look up. - * @return Message or null. + * Retrieves the localized message corresponding to the specified key from the resource bundle. + * If the key does not exist in the resource bundle, this method returns null. + * + * @param key The key for which the localized message needs to be retrieved. + * @return The localized message as a String if the key exists in the resource bundle; + * otherwise, null. */ public String getMessage(final String key) { if (!res.containsKey(key)) return null; @@ -39,10 +58,13 @@ public class RegionalizationMessage { } /** - * Gets the Message behind a key. - * @param key Key to look up. - * @param defaultMessage Default message to use if message is not available. - * @return Message from resource or default Message. + * Retrieves a localized message for the given key from the resource bundle. + * If the key is not found, the specified default message is returned. + * + * @param key The key to look up in the resource bundle. + * @param defaultMessage The default message to return if the key is not found. + * @return The localized message corresponding to the key, or the default message + * if the key does not exist in the resource bundle. */ public String getMessage(final String key, final String defaultMessage) { if (res.containsKey(key)) @@ -52,11 +74,14 @@ public class RegionalizationMessage { } /** - * Gets a formatted message. - * @param key key to look up message. - * @param defaultMessage Default message to use if message couldn't be loaded. - * @param params parameter to format the message. - * @return Formatted message. + * Retrieves a localized and formatted message from a resource bundle based on a key. + * If the key is not found in the resource bundle, a default message is used. + * The message supports parameter substitution using the supplied arguments. + * + * @param key The key used to retrieve the localized message from the resource bundle. + * @param defaultMessage The default message to be used if the key is not found in the resource bundle. + * @param params The parameters to substitute into the message placeholders. + * @return A formatted string containing the localized message with substituted parameters. */ public String getFormattedMessage(final String key, final String defaultMessage, final Object... params) { MessageFormat format = new MessageFormat(getMessage(key, defaultMessage)); diff --git a/core/src/main/java/de/neitzel/core/util/Strings.java b/core/src/main/java/de/neitzel/core/util/Strings.java index a1d2eff..6034981 100644 --- a/core/src/main/java/de/neitzel/core/util/Strings.java +++ b/core/src/main/java/de/neitzel/core/util/Strings.java @@ -5,25 +5,46 @@ import lombok.NonNull; import java.util.Map; /** - * Utility Methods for Strings + * Utility class providing common string manipulation methods. */ public class Strings { /** - * Environment variables of the system. + * Private constructor to prevent instantiation of the utility class. + * This utility class is not meant to be instantiated, as it only provides + * static utility methods for array-related operations. + * + * @throws UnsupportedOperationException always, to indicate that this class + * should not be instantiated. + */ + private Strings() { + throw new UnsupportedOperationException("Utility class"); + } + + /** + * A map that holds the system's environment variables. The keys represent + * environment variable names, and the values represent their corresponding + * values. It is initialized with the current system environment variables using + * {@link System#getenv()}. + * + * This variable provides access to the underlying system environment, which can + * be used for various purposes such as configuration, path resolution, or + * dynamic value substitution. + * + * Note: Modifications to this map will not affect the system environment, as it + * is a copy of the environment at the time of initialization. */ private static Map environmentVariables = System.getenv(); /** - * Expands environment Variables inside a string. - *

- * The environment variables should be given as ${variable}. - *

- *

- * Backslash inside variable values are replaced with slashes to avoid that they are seen as escape character. - * This makes the use for paths on windows possible but reduces the use with non paths in which you need a backslash. - *

- * @param text Test in which environment variables should be expanded. - * @return String with all environment variables expanded. + * Expands environment variable placeholders within the provided text. + * Placeholders in the format ${VARIABLE_NAME} are replaced with their + * corresponding values from the environment variables. + * + * @param text The input string containing environment variable placeholders. + * If null, the method returns null. + * @return A string with the placeholders replaced by their corresponding + * environment variable values. If no placeholders are found, + * the original string is returned. */ public static String expandEnvironmentVariables(String text) { if (text == null) return null; @@ -36,18 +57,23 @@ public class Strings { } /** - * Checks if the given String is null or empty. - * @param string String to check. - * @return true if given String is null or empty. + * Checks whether a given string is either null or empty. + * + * @param string the string to be checked for nullity or emptiness. + * @return true if the string is null or has a length of 0; false otherwise. */ public static boolean isNullOrEmpty(final String string) { return (string == null || string.length()==0); } /** - * Removes a leading / ending quote if there. - * @param value String to remove the quotes. - * @return Parameter string if it does not start / end with a quote, else string without leading/ending quote. + * Removes surrounding double quotes from the input string if they are present. + * Trims leading and trailing whitespaces from the input before processing. + * + * @param value The input string that might contain surrounding double quotes. + * The input cannot be null, and leading/trailing whitespaces will be ignored. + * @return A string with leading and trailing double quotes removed if present. + * Returns the original string if no surrounding double quotes are detected. */ public static String removeQuotes(final String value) { String trimmedValue = value.trim(); @@ -58,12 +84,15 @@ public class Strings { } /** - * Filters a given String and removes all illegal characters. - * @param value String value to filter all illegal characters from. - * @param illegalCharacters String with all Illegal Characters to filter out. - * @param replacement String to replace illegal characters with. - * @param combine Should multiple illegal characters that are together be replaced with one replacement string only? - * @return A new string where all illegal characters are replaced with the replacement string. + * Replaces illegal characters in a given string with a specified replacement string. + * Optionally, consecutive illegal characters can be combined into a single replacement. + * + * @param value The input string in which illegal characters are to be replaced. + * @param illegalCharacters A string specifying the set of illegal characters to be matched. + * @param replacement The string to replace each illegal character or group of characters. + * @param combine A boolean flag indicating whether consecutive illegal characters should be replaced + * with a single replacement string. If true, groups of illegal characters are combined. + * @return A new string with the illegal characters replaced by the provided replacement string. */ public static String replaceIllegalCharacters(final String value, final String illegalCharacters, final String replacement, final boolean combine) { String replacementRegex = "[" + illegalCharacters + "]" + (combine ? "+" : ""); @@ -71,15 +100,17 @@ public class Strings { } /** - * Filters a given String and removes all illegal characters. - *

- * All characters, that are not inside allowedCharacters, are illegal characters. - *

- * @param value String value to filter all illegal characters from. - * @param allowedCharacters String with all allowed Characters to filter out. - * @param replacement String to replace illegal characters with. - * @param combine Should multiple illegal characters that are together be replaced with one replacement string only? - * @return A new string where all illegal characters are replaced with the replacement string. + * Replaces characters in the input string that are not in the allowed characters set + * with a specified replacement string. Optionally combines consecutive non-allowed + * characters into a single replacement. + * + * @param value The input string to be processed. + * @param allowedCharacters A string containing the set of characters that are allowed. + * Any character not in this set will be replaced. + * @param replacement The string to replace non-allowed characters with. + * @param combine If true, consecutive non-allowed characters will be replaced with + * a single instance of the replacement string. + * @return A new string with non-allowed characters replaced according to the specified rules. */ public static String replaceNonAllowedCharacters(final String value, final String allowedCharacters, final String replacement, final boolean combine) { String replacementRegex = "[^" + allowedCharacters + "]" + (combine ? "+" : ""); @@ -87,9 +118,15 @@ public class Strings { } /** - * Gets the next Element which follows to the current element. - * @param element to get the precessor. - * @return The next element after this one. + * Increments a string value by modifying its last character, or leading characters if necessary. + * The increment follows these rules: + * - If the last character is a digit '9', it wraps to 'A'. + * - If the last character is 'Z', the preceding part of the string is recursively incremented, and '0' is appended. + * - If the string is empty, it returns "1". + * - For all other characters, increments the last character by one. + * + * @param element The string whose value is to be incremented. Must not be null. + * @return The incremented string value. If the input string is empty, returns "1". */ public static String increment(@NonNull final String element) { if (element.isEmpty()) return "1"; @@ -101,6 +138,17 @@ public class Strings { return firstPart + (char)(lastChar+1); } + /** + * Trims the input string to a specified maximum length, if necessary. + * If the input string's length is less than or equal to the specified max length, + * the string is returned unchanged. If the input string's length exceeds the max + * length, it is truncated to that length. + * + * @param original The original input string to be processed. If null, the method returns null. + * @param maxLength The maximum number of characters allowed in the resulting string. + * @return The original string if its length is less than or equal to maxLength, + * otherwise a truncated version of the string up to maxLength characters. + */ public static String limitCharNumber(final String original, final int maxLength) { if (original == null || original.length() <= maxLength) return original; diff --git a/core/src/main/java/de/neitzel/core/util/XmlUtils.java b/core/src/main/java/de/neitzel/core/util/XmlUtils.java index 973c4bb..5c35142 100644 --- a/core/src/main/java/de/neitzel/core/util/XmlUtils.java +++ b/core/src/main/java/de/neitzel/core/util/XmlUtils.java @@ -21,22 +21,39 @@ import java.time.format.DateTimeFormatter; import java.util.Date; /** - * Converter with helper functions to format XML. + * Utility class for handling common XML operations such as creating XML elements, + * formatting XML strings, and validating XML content. */ @Slf4j -public class XmlUtils { +public class XmlUtils { + /** + * Private constructor to prevent instantiation of the utility class. + * This utility class is not meant to be instantiated, as it only provides + * static utility methods for array-related operations. + * + * @throws UnsupportedOperationException always, to indicate that this class + * should not be instantiated. + */ + private XmlUtils() { + throw new UnsupportedOperationException("Utility class"); + } /** - * DateTimeFormatter instance to format a date for XML use (xs:date type). + * A {@link DateTimeFormatter} instance used for formatting or parsing dates in the "yyyy-MM-dd" pattern. + * + * This formatter adheres to the XML date format standard (ISO-8601). It can be used + * to ensure consistent date representations in XML or other similar text-based formats. + * + * Thread-safe and immutable, this formatter can be shared across multiple threads. */ public static final DateTimeFormatter XML_DATE_FORMATTER = DateTimeFormatter.ofPattern("yyyy-MM-dd"); /** - * Creates a new XML element to be used inside a document. + * Creates a new element in the provided XML document with the specified name. * - * @param doc XML Document to use. - * @param name Name of the Element. - * @return Created Element. + * @param doc The XML document in which the new element is to be created. Must not be null. + * @param name The name of the element to be created. Must not be null or empty. + * @return The newly created element with the given name. Never returns null. */ public static Element createElement(final Document doc, final String name) { log.debug("Creating a new element " + name); @@ -44,12 +61,14 @@ public class XmlUtils { } /** - * Creates a new XML element with text value to be used inside a document. + * Creates a new XML element with the specified name and value, appends the value + * as a text node to the element, and returns the resulting element. * - * @param doc XML Document to use. - * @param name Name of the Element. - * @param value Value of the Text Node. - * @return Created Element. + * @param doc the XML document to which the element belongs. Must not be null. + * @param name the name of the element to create. Must not be null. + * @param value the text value to be set as the content of the created element. + * If null, an empty string will be used as the content. + * @return the newly created XML element containing the specified value as a text node. */ public static Element createElement(final Document doc, final String name, final String value) { log.debug("Creating a new element " + name + " with value: " + value); @@ -62,24 +81,26 @@ public class XmlUtils { } /** - * Creates a new XML element with date value to be used inside a document. + * Creates an XML element with the specified name and value, formatted as a date string. + * The date value is converted to an XML-compatible string format using a predefined formatter. * - * @param doc XML Document to use. - * @param name Name of the Element. - * @param value Date to insert into node. - * @return Created Element. + * @param doc the XML document to which the element belongs; must not be null + * @param name the name of the element to be created; must not be null or empty + * @param value the date value to be assigned to the created element; must not be null + * @return the created XML element containing the specified name and formatted date value */ public static Element createElement(final Document doc, final String name, final Date value) { return createElement(doc, name, XML_DATE_FORMATTER.format(value.toInstant())); } /** - * Creates a new XML element with integer value to be used inside a document. + * Creates an XML element with the specified name and optional value. * - * @param doc XML Document to use. - * @param name Name of the Element. - * @param value Value of the Integer Node. - * @return Created Element. + * @param doc The Document object to which the element will belong. Must not be null. + * @param name The name of the element to be created. Must not be null or empty. + * @param value The optional value to be set as the text content of the element. If null, + * the element will have an empty text content. + * @return The newly created Element object with the specified name and value. */ public static Element createElement(final Document doc, final String name, final Integer value) { log.debug("Creating a new element " + name + " with value: " + value); @@ -92,12 +113,13 @@ public class XmlUtils { } /** - * Creates a new XML element to be used inside a document and adds it to the parent. + * Creates a new element with the specified name, appends it to the provided parent element, + * and returns the newly created element. * - * @param doc XML Document to use. - * @param name Name of the Element. - * @param parent Parent for the Element. - * @return Created Element. + * @param doc The Document to which the new element belongs. Must not be null. + * @param name The name of the new element to be created. Must not be null or empty. + * @param parent The parent element to which the new element will be appended. Must not be null. + * @return The newly created and appended Element object. */ public static Element createAndInsertElement(final Document doc, final String name, @NonNull final Element parent) { log.debug("Creating a new element " + name + " and adding it to a parent."); @@ -107,12 +129,14 @@ public class XmlUtils { } /** - * Creates a new XML element with text value And adds it to the parent. + * Creates a new XML element with a specified name and value, adds it to the specified parent element, + * and returns the created element. * - * @param name Name of the Element. - * @param value Value of the Text Node. - * @param parent Parent for the Element. - * @return Created Element. + * @param doc The XML document to which the new element belongs. Must not be null. + * @param name The name of the element to create. Must not be null. + * @param value The value to be set for the created element. Can be null if no value is required. + * @param parent The parent element to which the new element will be appended. Must not be null. + * @return The newly created and inserted element. */ public static Element createAndInsertElement(final Document doc, final String name, final String value, @NonNull final Element parent) { log.debug("Creating a new element " + name + " with value: " + value + " and adding it to a parent."); @@ -123,10 +147,14 @@ public class XmlUtils { /** - * Formats the XML from a given String with XML content. - * - * @param xmlStream String with XML content. - * @return Formated XML content or original content in case of an error. + * Formats a given XML string by applying proper indentation to enhance readability. + * The method uses a transformer to process the XML input, applying indentation + * with a four-space configuration. In case of an error, the original XML string + * is returned without any modifications. + * + * @param xmlStream The raw XML string to be formatted. Cannot be null. + * @return The formatted XML string with proper indentation. If an exception occurs + * during formatting, the original XML string is returned. */ public static String format(final String xmlStream) { log.debug("formatXML"); @@ -153,10 +181,13 @@ public class XmlUtils { } /** - * Formats the XML from a given XML Document. + * Formats a given XML Document into a human-readable string representation. + * The method applies indentation and specific output properties to the XML content. + * If an exception occurs during the transformation process, it logs the error + * and returns null. * - * @param doc XML Document to format. - * @return Formated XML content. + * @param doc The XML Document to be formatted. Must not be null. + * @return A formatted string representation of the XML document, or null if an error occurs during processing. */ public static String format(final Document doc) { try { @@ -184,9 +215,14 @@ public class XmlUtils { } /** - * Checks if the given xml string is valid XML - * @param xml XML String. - * @return true if xml is valid. + * Validates whether a given XML string is well-formed. + * This method attempts to parse the input XML string and checks + * if it can successfully create a valid DOM object from it. + * + * @param xml The XML string to be validated. Must not be null. + * If null or invalid, the method will return false. + * @return true if the XML string is well-formed and can be successfully parsed; + * false otherwise, such as in the case of invalid content or parsing errors. */ public static boolean checkXml(final String xml) { try { diff --git a/fx-example/pom.xml b/fx-example/pom.xml index f5b0b13..562daf0 100644 --- a/fx-example/pom.xml +++ b/fx-example/pom.xml @@ -43,160 +43,4 @@ - - - - - - image - - - image - - - - - - - org.apache.maven.plugins - maven-dependency-plugin - ${maven.dependency.plugin} - - - - copy-dependencies - package - - copy-dependencies - - - ${project.build.directory}/modules - runtime - false - false - true - - - - - - copy - install - - copy - - - ${project.build.directory}/modules - - - ${project.groupId} - ${project.artifactId} - ${project.version} - ${project.packaging} - ${project.build.finalName}.jar - - - true - - - - - - - com.github.akman - jpackage-maven-plugin - ${jpackage.maven.plugin} - - ${appName} - IMAGE - - - - - javafx\..* - - - - - - javafx.controls - javafx.graphics - javafx.fxml - javafx.web - - ${main.class} - ${project.build.directory}/modules - ${jar.filename}.jar - - - - install - - jpackage - - - - - - - - - - - fatjar - - - fatjar - - - - - - org.apache.maven.plugins - maven-shade-plugin - ${maven.shade.plugin} - - - package - - shade - - - - - true - full - - - - - ${main.class} - 1.0 - - - - - - *:* - - META-INF/MANIFEST.MF - **/module-info.class - META-INF/*.SF - META-INF/*.DSA - META-INF/*.RSA - - - - - - - - - diff --git a/log4j/src/main/java/de/neitzel/log4j/Log4jUtils.java b/log4j/src/main/java/de/neitzel/log4j/Log4jUtils.java index 4ab25e7..9b79868 100644 --- a/log4j/src/main/java/de/neitzel/log4j/Log4jUtils.java +++ b/log4j/src/main/java/de/neitzel/log4j/Log4jUtils.java @@ -6,40 +6,53 @@ import java.io.File; import java.net.URISyntaxException; /** - * Adds Utility Methods for log4j. + * Utility class for managing Log4j configurations. Provides methods to set up + * Log4j configurations from default files, resources, or command line arguments. */ public class Log4jUtils { /** - * Default Logfile that should be read. - * Must be a relative path that is checked from the current directory and also from the location of the jar file. + * The default path to the Log4j configuration file. + * This variable is used to specify the local file path for the Log4j configuration + * when no custom configuration is provided. */ public static final String DEFAULT_LOG4J_LOGFILE = "./log4j.properties"; /** - * Resource to use when no file is found. + * The default resource path to the Log4j configuration file included in the classpath. + * This path is used as a fallback when no other Log4j configuration is explicitly set. */ public static final String DEFAULT_LOG4J_RESOURCE = "/log4j.default.properties"; /** - * Checks if a log4j config file was set on command line with -Dlog4j.configuration - * @return true if log4j.configuration was set. + * Checks if the system property "log4j.configuration" is set. + * + * @return true if the "log4j.configuration" property is defined, false otherwise. */ public static boolean isLog4jConfigFileSet() { return System.getProperty("log4j.configuration") != null; } /** - * Uses the default configurations if no config file was set. + * Configures Log4j using default configuration settings. + * This method leverages a default configuration file path and a default resource path + * to set up Log4j logging if a configuration file is not already specified via + * a system property. If a valid configuration file or resource is found, it will be applied. + * + * Delegates to the overloaded {@code setLog4jConfiguration(String log4jConfigFile, String defaultResource)} + * method using predefined defaults. */ public static void setLog4jConfiguration() { setLog4jConfiguration(DEFAULT_LOG4J_LOGFILE, DEFAULT_LOG4J_RESOURCE); } /** - * Gets the file with path relative to the jar file. - * @param log4jConfigFile log4j config file. - * @return Path if possible or null. + * Constructs the absolute path to the specified Log4j configuration file located + * in the same directory as the JAR file of the application. + * + * @param log4jConfigFile The name of the Log4j configuration file. + * @return The absolute path to the specified Log4j configuration file if the + * path is successfully constructed; otherwise, returns null in case of an error. */ public static String getLog4jLogfileAtJar(final String log4jConfigFile) { try { @@ -50,13 +63,13 @@ public class Log4jUtils { } /** - * Uses the default configurations if no config file was set. - *

- * A log4j configuration can be set using -Dlog4j.configuration. If no configuration was set, - * we look for the log4jConfigFile. If it does not exist, we read the defaultResource. - *

- * @param log4jConfigFile Default file to look for. - * @param defaultResource Resource path to use if config file wasn't found. + * Sets the Log4j configuration using the specified configuration file or a default resource + * if the configuration file is not found. If a Log4j configuration is already set, the method + * does nothing. + * + * @param log4jConfigFile the path to the Log4j configuration file to be used. + * @param defaultResource the fallback resource to be used as the configuration if the file + * is not found or accessible. */ public static void setLog4jConfiguration(final String log4jConfigFile, final String defaultResource) { if (isLog4jConfigFileSet()) return; diff --git a/pom.xml b/pom.xml index 9a30a16..770d184 100644 --- a/pom.xml +++ b/pom.xml @@ -25,10 +25,10 @@ 21.0.3 - 24.1.0 - 5.10.2 - 1.18.32 - 5.12.0 + 26.0.2 + 5.12.1 + 1.18.38 + 5.16.1 0.10.2 2.0.17 @@ -145,6 +145,13 @@ test + + + org.slf4j + slf4j-simple + test + + org.jetbrains