konrad/NeitzelLib
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Refactor utility classes and update dependencies.

Browse Source 
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.
This commit is contained in:
Konrad Neitzel 2025-04-03 20:15:18 +02:00
parent 8d01fd4935
commit b0beabf8b4
20 changed files with 1004 additions and 513 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

54
core/src/main/java/de/neitzel/core/commandline/ArgumentProvider.java
View File

@ -3,23 +3,43 @@ package de.neitzel.core.commandline;
import java.util.Iterator; 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<String> { public class ArgumentProvider implements Iterator<String> {
/** /**
* 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; 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; private int current = 0;
/** /**
* Creates a new instance of ArgumentProvider. * Creates an instance of the ArgumentProvider class to iterate over the given array of arguments.
* @param arguments List 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) { public ArgumentProvider(final String[] arguments) {
if (arguments == null) { if (arguments == null) {
@ -30,25 +50,29 @@ public class ArgumentProvider implements Iterator<String> {
} }
/** /**
* Checks if more arguments are available. * Checks if there are more arguments available to iterate over.
* @return True if more arguments are available else false. *
* @return true if there are additional arguments available; false otherwise.
*/ */
public boolean hasNext() { public boolean hasNext() {
return current < arguments.length; return current < arguments.length;
} }
/** /**
* Checks if count more arguments are available. * Determines if the specified number of additional arguments are available in the collection.
* @param count Number of arguments we want to get. *
* @return True if count more arguments are available else false. * @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) { public boolean hasNext(final int count) {
return current + count <= arguments.length; return current + count <= arguments.length;
} }
/** /**
* Get the next token. * Retrieves the next argument in the sequence.
* @return The next token or null if no more available. * 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() { public String next() {
if (!hasNext()) return null; if (!hasNext()) return null;
@ -59,8 +83,10 @@ public class ArgumentProvider implements Iterator<String> {
} }
/** /**
* Get the next token without removing it. * Returns the next argument in the sequence without advancing the iterator.
* @return The next token or null if no more available. * 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() { public String peek() {
if (!hasNext()) return null; if (!hasNext()) return null;

151
core/src/main/java/de/neitzel/core/commandline/Parameter.java
View File

@ -8,67 +8,184 @@ import java.util.List;
import java.util.function.Consumer; import java.util.function.Consumer;
/** /**
* A parameter on the command line. * The `Parameter` class defines a command-line parameter with associated metadata,
* <br> * such as constraints on the number of values it accepts, descriptions, and aliases.
* Each parameter has to start with either - or /! * 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 @Slf4j
@Builder @Builder
@Getter @Getter
@Setter @Setter
@AllArgsConstructor
@NoArgsConstructor
public class Parameter { 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<List<String>> callback, boolean isHelpCommand, boolean isDefaultParameter, List<String> 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; 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; 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; 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; 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; 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; 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<List<String>> callback; private Consumer<List<String>> 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; private boolean isHelpCommand;
/** /**
* Determines if this Parameter is the default parameter. * Indicates whether the parameter is designated as the default parameter.
* <br> *
* A default parameter must take at least one additional value. * 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; 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") @Singular("alias")
private List<String> aliasList; private List<String> aliasList;

117
core/src/main/java/de/neitzel/core/commandline/Parser.java
View File

@ -5,26 +5,76 @@ import lombok.extern.slf4j.Slf4j;
import java.util.*; import java.util.*;
/** /**
* A parser of the CommandLine. * The Parser class is responsible for parsing and handling command-line arguments.
* <br> * It allows for the registration of known parameters and provides mechanisms
* Parameter are defined. Each parameter will start with either - or /. * to validate and process command-line input.
*/ */
@Slf4j @Slf4j
public class Parser { 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<String, Parameter> parameters = new HashMap<>(); private Map<String, Parameter> 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; private Parameter defaultParameter = null;
/** /**
* Adds a parameter to the list of known parameters. * Constructs a new instance of the `Parser` class.
* @param parameter *
* 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) { public void addParameter(final Parameter parameter) {
// Add by name // Add by name
@ -48,13 +98,12 @@ public class Parser {
} }
/** /**
* Checks if param is a parameter. * Checks whether a given parameter string matches a valid parameter within the defined constraints.
* <br> *
* - When the parameter is known as a parameter, then it is true. * @param param the parameter string to be checked. This can either be a key defined in the `parameters` map
* - Everything that starts with a - must be a known parameter -> false * or a potential default parameter if it does not start with a dash ("-").
* - Parameter is not known and does not start with a -? -> Default parameter if available. * @return {@code true} if the parameter is a valid entry in the `parameters` map or matches the default parameter;
* @param param Parameter in lower case to check. * {@code false} otherwise, including when the parameter starts with a dash ("-").
* @return true if it is either a known parameter or an argument for the default parameter.
*/ */
protected boolean isParameter(final String param) { protected boolean isParameter(final String param) {
if (parameters.containsKey(param)) return true; if (parameters.containsKey(param)) return true;
@ -63,8 +112,15 @@ public class Parser {
} }
/** /**
* Parse the given commandline arguments. * Parses an array of command-line arguments and processes them as defined by the application's parameters.
* @param args Commandline Arguments to parse. *
* 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) { public void parse(final String[] args) {
ArgumentProvider provider = new ArgumentProvider(args); ArgumentProvider provider = new ArgumentProvider(args);
@ -96,11 +152,19 @@ public class Parser {
} }
/** /**
* Get the given optional data of a parameter- * Retrieves a list of options by consuming arguments from the provided {@link ArgumentProvider}
* @param provider Provider of token. * within the range specified by the minimum and maximum values.
* @param min Minimum number of elements to get. *
* @param max Maximum number of elements to get. * @param provider The source providing the command-line arguments. This object allows
* @return List of token of the Parameter. * 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<String> getOptions(ArgumentProvider provider, int min, int max) { private List<String> getOptions(ArgumentProvider provider, int min, int max) {
if (max < min) max = min; if (max < min) max = min;
@ -120,8 +184,15 @@ public class Parser {
} }
/** /**
* Callback for help command. * Handles the help command when invoked in the command-line interface, providing information about available parameters.
* @param arguments null for general help or name of a command. * 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<String> arguments) { public void helpCommandCallback(final List<String> arguments) {
if (arguments == null || arguments.size() == 0) { if (arguments == null || arguments.size() == 0) {

173
core/src/main/java/de/neitzel/core/config/Configuration.java
View File

@ -16,21 +16,49 @@ import java.util.Map;
import java.util.Properties; 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 @Slf4j
public class Configuration { 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 * Constructs a new Configuration instance with default properties.
* @param defaultValue Default value to return if key is not present. * This constructor initializes the Configuration object using an
* @param key Key of the property to get. * empty set of {@code Properties}.
* @return The value of the property if it exists or the default value. */
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) { protected boolean getBooleanProperty(final String key, final boolean defaultValue) {
if (!properties.containsKey(key)) return defaultValue; if (!properties.containsKey(key)) return defaultValue;
@ -38,10 +66,12 @@ public class Configuration {
} }
/** /**
* Gets a String property * Retrieves the value of the specified property as a trimmed string.
* @param key Key of the property to query. * If the property is not found, the default value is returned.
* @param defaultValue Default value to return if property not available. *
* @return The property if it exists, else the default value. * @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) { protected String getStringProperty(final String key, final String defaultValue) {
if (!properties.containsKey(key)) return defaultValue; if (!properties.containsKey(key)) return defaultValue;
@ -49,13 +79,13 @@ public class Configuration {
} }
/** /**
* Gets a String property with all environment variables replaced * Retrieves a string property value associated with the specified key, applies
* <p> * environment variable expansion on the value, and returns the processed result.
* Environment variable can be included with ${variable name}. *
* </p> * @param key the key identifying the property to retrieve.
* @param key Key of the property to query. * @param defaultValue the default value to use if the property is not found.
* @param defaultValue Default value to return if property not available. * @return the processed property value with expanded environment variables, or
* @return The property if it exists, else the default value. * the defaultValue if the property is not found.
*/ */
protected String getStringPropertyWithEnv(final String key, final String defaultValue) { protected String getStringPropertyWithEnv(final String key, final String defaultValue) {
String result = getStringProperty(key, defaultValue); String result = getStringProperty(key, defaultValue);
@ -63,26 +93,25 @@ public class Configuration {
} }
/** /**
* Gets a String property without quotes. * Retrieves the value of a string property associated with the specified key,
* <p> * removes any surrounding quotes from the value, and returns the resultant string.
* If the value is put in quotes, then the quote signs are replaced. *
* </p> * @param key the key associated with the desired property
* @param key Key of the property to query. * @param defaultValue the default value to return if the property is not found or is null
* @param defaultValue Default value to return if property not available. * @return the string property without surrounding quotes, or the defaultValue if the property is not found
* @return The property if it exists, else the default value (without leading/ending quote signs).
*/ */
protected String getStringPropertyWithoutQuotes(final String key, final String defaultValue) { protected String getStringPropertyWithoutQuotes(final String key, final String defaultValue) {
return Strings.removeQuotes(getStringProperty(key, defaultValue)); return Strings.removeQuotes(getStringProperty(key, defaultValue));
} }
/** /**
* Gets a String property without quotes. * Retrieves the string value of a configuration property identified by the given key,
* <p> * removes surrounding quotes if present, and expands any environment variables found
* If the value is put in quotes, then the quote signs are replaced. * within the string. If the property is not found, a default value is used.
* </p> *
* @param key Key of the property to query. * @param key the key identifying the configuration property
* @param defaultValue Default value to return if property not available. * @param defaultValue the default value to use if the property is not found
* @return The property if it exists, else the default value (without leading/ending quote signs). * @return the processed string property with quotes removed and environment variables expanded
*/ */
protected String getStringPropertyWithoutQuotesWithEnv(final String key, final String defaultValue) { protected String getStringPropertyWithoutQuotesWithEnv(final String key, final String defaultValue) {
String result = getStringPropertyWithoutQuotes(key, defaultValue); String result = getStringPropertyWithoutQuotes(key, defaultValue);
@ -90,12 +119,15 @@ public class Configuration {
} }
/** /**
* Gets an Integer property. * Retrieves the integer value for the specified property key. If the key does
* <br> * not exist in the properties or the value is null/empty, the provided default
* Supports null as value. * value is returned.
* @param defaultValue Default value to return if key is not present. *
* @param key Key of the property to get. * @param key the property key to retrieve the value for
* @return The value of the property if it exists or the default value. * @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) { protected Integer getIntegerProperty(final String key, final Integer defaultValue) {
if (!properties.containsKey(key)) return defaultValue; if (!properties.containsKey(key)) return defaultValue;
@ -104,9 +136,11 @@ public class Configuration {
} }
/** /**
* Sets an Integer property. * Sets an integer property in the properties object. If the provided value is null,
* @param key Key of the property to set. * an empty string will be stored as the property's value.
* @param value Value to set. *
* @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) { protected void setIntegerProperty(final String key, final Integer value) {
if (value == null) { if (value == null) {
@ -117,13 +151,14 @@ public class Configuration {
} }
/** /**
* Gets the property as LocalDate. * Retrieves a LocalDate value from the properties based on the provided key.
* <br> * If the key does not exist or the value is invalid, a default value is returned.
* An null value or an empty String is given as null. *
* @param key Key of the property. * @param key the key to look up the property in the properties map
* @param defaultValue default Value. * @param defaultValue the default LocalDate value to return if the key is not found
* @param formatString Format String to use. * @param formatString the format string to parse the LocalDate value
* @return The LocalDate stored the property or the default value if property unknown or couldn't be parsed. * @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) { protected LocalDate getLocalDateProperty(final String key, final LocalDate defaultValue, final String formatString) {
if (!properties.containsKey(key)) return defaultValue; if (!properties.containsKey(key)) return defaultValue;
@ -134,12 +169,12 @@ public class Configuration {
} }
/** /**
* Sets the LocalDate using the provided format String. * Sets a property with the given key and a formatted LocalDate value.
* <br> * If the provided value is null, the property will be set to an empty string.
* Null is allowed and is stored as empty string. *
* @param key Key of the property to set. * @param key the key of the property to set
* @param value Value to set. * @param value the LocalDate value to format and set as the property value
* @param formatString Format string to use. * @param formatString the pattern string used to format the LocalDate value
*/ */
protected void setLocalDateProperty(final String key, final LocalDate value, final String formatString) { protected void setLocalDateProperty(final String key, final LocalDate value, final String formatString) {
if (value == null) { if (value == null) {
@ -150,9 +185,11 @@ public class Configuration {
} }
/** /**
* Sets a property to a new value. * Sets a property with the specified key to the given value. If the value is null,
* @param key Key of property to set. * it defaults to an empty string. Logs the operation and updates the property.
* @param value New value of 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) { public void setProperty(final String key, final String value) {
String newValue = value == null ? "" : 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) { public void load(final String fileName) {
load(fileName, Charset.defaultCharset().name(), true); 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) { public void load(final String fileName, final String encoding, final boolean acceptUTF8) {
log.info("Reading Config: " + fileName + " with encoding: " + encoding + "accepting UTF-8: " + 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. * Merges the properties from the provided configuration into the current configuration.
* @param config Configuration to merge into this instance. *
* @param config the Configuration object whose properties will be merged into this instance
*/ */
public void merge(final Configuration config) { public void merge(final Configuration config) {
for(Map.Entry<Object, Object> entry: config.properties.entrySet()) { for(Map.Entry<Object, Object> entry: config.properties.entrySet()) {
@ -211,8 +257,9 @@ public class Configuration {
} }
/** /**
* Removes a key from the configuration. * Removes the specified key-value pair from the properties map if the key exists.
* @param key *
* @param key the key to be removed from the properties map
*/ */
public void remove(final String key){ public void remove(final String key){
if (properties.containsKey(key)) properties.remove(key); if (properties.containsKey(key)) properties.remove(key);

73
core/src/main/java/de/neitzel/core/io/ConvertedEncodingFileReader.java
View File

@ -8,21 +8,38 @@ import java.nio.charset.Charset;
import java.nio.charset.IllegalCharsetNameException; import java.nio.charset.IllegalCharsetNameException;
/** /**
* FileReader that converts an UTF-8 file to ISO-8859-15 if required. * The ConvertedEncodingFileReader class extends {@link InputStreamReader} to provide functionality
* <p> * for handling file encoding conversion transparently. If a file is detected to be in UTF-8 encoding,
* This FileReader checks, if the file to be read is an UTF-8 file. * this class converts it to the specified target encoding using a temporary file, then opens the reader
* If an UTF-8 encoding is found, a temporary file will be created with the content * with the converted encoding. If the file is already in the target encoding, it opens the reader directly.
* of the original File - just encoded in the new format. *
* </p> * This class is useful for applications needing to process text files in specific encodings and ensures
* <p> * encoding compatibility.
* This Reader is mainly tested ith ISO-8859-15 and UTF-8. Other formats are not really supported.
* </p>
*/ */
@Slf4j @Slf4j
public class ConvertedEncodingFileReader extends InputStreamReader { 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"; 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) { private static void setCheckEncoding(final String encoding) {
if (Charset.forName(encoding) != null) throw new IllegalCharsetNameException("Encoding " + encoding + " is not supported!"); 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. * Constructs a ConvertedEncodingFileReader for a specified file and target encoding format.
* @param file File to convert if required and open reader. * The class reads the provided file and ensures that its content is handled in the target encoding.
* @param targetFormat Target Format to use. * If the file is not already in the target encoding, it converts the file's encoding
* @throws IOException * 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 { public ConvertedEncodingFileReader(final File file, final String targetFormat) throws IOException {
super(createTargetFormatInputFileStream(file, targetFormat), targetFormat); super(createTargetFormatInputFileStream(file, targetFormat), targetFormat);
} }
/** /**
* Creates a new ISO8859ConvertedFileReader from a given File. * Constructs a ConvertedEncodingFileReader for reading a file with encoding conversion support.
* @param filename File to convert if required and open reader. * This constructor takes the file path as a string and ensures the file's encoding is either
* @throws IOException * 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 { public ConvertedEncodingFileReader(final String filename, final String targetFormat) throws IOException {
this(new File(filename), targetFormat); this(new File(filename), targetFormat);
} }
/** /**
* Creates an ISO8859-15 encoded InputFileStream on an file. * Creates an input file stream for a given file, converting its encoding if necessary.
* <p> * If the file is not in UTF-8 encoding, a direct {@link FileInputStream} is returned for the file.
* If the file is UTF-8 encoded, then it is converted to a temp file and the temp file will be opened. * If the file is in UTF-8 encoding, it is converted to the specified target format using a temporary file,
* </p> * and then an input stream for the temporary file is returned.
* @param file *
* @return The InputFileStream on the original file or the converted file in case of an UTF-8 file. * @param file the file for which the input stream is to be created
* @throws IOException * @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 { private static FileInputStream createTargetFormatInputFileStream(final File file, final String targetFormat) throws IOException {
if (!file.exists()) { if (!file.exists()) {

29
core/src/main/java/de/neitzel/core/io/ISO8859EncodingFileReader.java
View File

@ -3,14 +3,43 @@ package de.neitzel.core.io;
import java.io.File; import java.io.File;
import java.io.IOException; 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 { 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"; 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 { public ISO8859EncodingFileReader(File file) throws IOException {
super(file, TARGET_FORMAT); 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 { public ISO8859EncodingFileReader(String filename) throws IOException {
super(filename, TARGET_FORMAT); super(filename, TARGET_FORMAT);
} }

53
core/src/main/java/de/neitzel/core/io/StringEncoder.java
View File

@ -1,17 +1,33 @@
package de.neitzel.core.io; package de.neitzel.core.io;
/** /**
* An encoder for Strings. * Utility class for encoding and decoding strings.
* <p> * This class provides methods for transforming strings into encoded representations
* All characters with unicode number less than 32 or greater than 127 or 38 (Ampersend) * and decoding them back to the original representation.
* will be encoded with &#number; with number as the decimal unicode number.
*/ */
public class StringEncoder { public class StringEncoder {
/** /**
* Decodes the encoded String. * Private constructor to prevent instantiation of the utility class.
* @param data Encoded string. * This utility class is not meant to be instantiated, as it only provides
* @return Decoded String. * 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 "&amp;#<code>;<code>"}, where
* {@code <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) { public static String decodeData(final String data) {
if (data == null) return ""; if (data == null) return "";
@ -40,9 +56,13 @@ public class StringEncoder {
} }
/** /**
* Decode a single character. * Decodes a character from its numeric character reference representation.
* @param data String in the form &#xxx; with xxx a decimal number. * The input string must represent an encoded character in the format {@code "&#<code_point>;"}.
* @return The decoded character. *
* @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) { public static char decodeCharacter(final String data) {
if (!data.startsWith("&#")) throw new IllegalArgumentException("Data does not start with &# (" + 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. * Encodes the provided string by converting characters outside the ASCII range (32-127)
* <p> * and the ampersand {@code "&"} character into their corresponding numeric character reference
* All Characters between from ascii 32 to 127 (except 38 / &) * representation (e.g., {@code "&#38;"}).
* are replaced with a &#code; where code is the number of the character. *
* @param data String that should be encoded. * @param data the input string to encode; if null, an empty string is returned
* @return Encoded String. * @return an encoded string where non-ASCII and ampersand characters
* are replaced with numeric character references
*/ */
public static String encodeData(final String data) { public static String encodeData(final String data) {
if (data == null) return ""; if (data == null) return "";

12
core/src/main/java/de/neitzel/core/sound/ToneGenerator.java
View File

@ -10,6 +10,18 @@ import javax.sound.sampled.SourceDataLine;
* It allows playing tones based on frequency or predefined tone names. * It allows playing tones based on frequency or predefined tone names.
*/ */
public class ToneGenerator { 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. * Plays a tone based on a predefined tone name for a specified duration.
* *

12
core/src/main/java/de/neitzel/core/sound/ToneTable.java
View File

@ -13,6 +13,18 @@ import java.util.HashMap;
* frequency information for specific tones. * frequency information for specific tones.
*/ */
public class ToneTable { 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). * 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. * The keys represent tone names (e.g., "C4", "D#5"), and the values are their respective frequencies.

10
core/src/main/java/de/neitzel/core/sql/Query.java
View File

@ -22,7 +22,6 @@ import java.util.stream.StreamSupport;
* @param <T> The type of the objects returned by the query. * @param <T> The type of the objects returned by the query.
*/ */
@Slf4j @Slf4j
@RequiredArgsConstructor
public class Query<T> { public class Query<T> {
/** /**
@ -69,6 +68,15 @@ public class Query<T> {
*/ */
private String queryText; 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. * Executes the given SQL query using the provided database connection.
* *

10
core/src/main/java/de/neitzel/core/sql/TrimmingResultSet.java
View File

@ -18,7 +18,6 @@ import java.util.Map;
* If any additional behaviors or transformations are applied, they are documented * If any additional behaviors or transformations are applied, they are documented
* in the respective overridden method descriptions. * in the respective overridden method descriptions.
*/ */
@RequiredArgsConstructor
public class TrimmingResultSet implements ResultSet { public class TrimmingResultSet implements ResultSet {
/** /**
@ -32,6 +31,15 @@ public class TrimmingResultSet implements ResultSet {
*/ */
private final ResultSet resultSet; 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. * 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. * The value is trimmed to remove leading and trailing whitespace. If the value is null, it returns null.

68
core/src/main/java/de/neitzel/core/util/ArrayUtils.java
View File

@ -1,15 +1,30 @@
package de.neitzel.core.util; 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 { public class ArrayUtils {
/** /**
* Checks if a given char is inside an array of chars. * Private constructor to prevent instantiation of the utility class.
* @param array Array of chars to seach in. * This utility class is not meant to be instantiated, as it only provides
* @param ch Character to search. * static utility methods for array-related operations.
* @return true if character was found, else false. *
* @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) { public static boolean contains(char[] array, char ch) {
for(int index=0; index < array.length; index++) { for(int index=0; index < array.length; index++) {
@ -17,4 +32,47 @@ public class ArrayUtils {
} }
return false; 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 <T> the type of the elements in the array
* @return true if the element is found in the array, false otherwise
*/
public static <T> boolean contains(T[] array, T ch) {
for(int index=0; index < array.length; index++) {
if (Objects.equals(array[index], ch)) return true;
}
return false;
}
} }

42
core/src/main/java/de/neitzel/core/util/EnumUtil.java
View File

@ -4,12 +4,30 @@ import java.util.ArrayList;
import java.util.List; 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 { public class EnumUtil {
/** /**
* Creates a regular expression to match a comma separated list of Flags. * Private constructor to prevent instantiation of the utility class.
* @return Regular expression to match flags. * 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 <T> 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 <T extends Enum<T>> String getFlagRegEx(Class<T> clazz) { public static <T extends Enum<T>> String getFlagRegEx(Class<T> clazz) {
StringBuilder result = new StringBuilder(); StringBuilder result = new StringBuilder();
@ -33,9 +51,21 @@ public class EnumUtil {
} }
/** /**
* Parse a list of comma separated flags into a List of RequestFlags. * Parses a delimited string containing Enum constant names into a list of Enum constants.
* @param flags String with comma separated flags. *
* @return List of RequestFlags. * 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 <T> 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 <T extends Enum<T>> List<T> parseFlags(final Class<T> clazz, final String flags) { public static <T extends Enum<T>> List<T> parseFlags(final Class<T> clazz, final String flags) {
List<T> result = new ArrayList<>(); List<T> result = new ArrayList<>();

192
core/src/main/java/de/neitzel/core/util/FileUtils.java
View File

@ -10,37 +10,65 @@ import java.text.SimpleDateFormat;
import java.util.stream.Collectors; 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 @Slf4j
public class FileUtils { 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"); 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"; 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; public static final int BUFFER_SIZE = 1024;
/** /**
* Checks if a File is UTF-8 encoded. * Determines whether the given file is encoded in UTF-8.
* <p> *
* This method checks a file for * @param file The file to be checked for UTF-8 encoding.
* - first 3 bytes for UTF-8 BOM (0xEF 0xBB 0xBF) * @param checkEncoding The character encoding to use while checking the file content.
* - Existence of 0xC2 / 0xC3 character. * @return true if the file is determined to be encoded in UTF-8; false otherwise.
* </p> * @throws IOException If an I/O error occurs while reading the file.
* @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.
*/ */
public static boolean isUTF8(final File file, final String checkEncoding) throws IOException { 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. * Checks if the provided file starts with a UTF-8 Byte Order Mark (BOM).
* <p> *
* This method checks a file for * This method reads the first character of the file using a reader that assumes
* - first 3 bytes for UTF-8 BOM (0xEF 0xBB 0xBF) * UTF-8 encoding and checks if it matches the Unicode Byte Order Mark (U+FEFF).
* - Existence of 0xC2 / 0xC3 character. *
* </p> * @param file The file to check for a UTF-8 BOM. Must not be null.
* @param file File to check. * @return true if the file starts with a UTF-8 BOM, false otherwise.
* @return true if an UTF-8 BOM Header was found. * @throws IOException If an input or output exception occurs while reading the file.
* @throws IOException IOException is thrown if the file could not be read.
*/ */
public static boolean hasUTF8BOM(final File file) throws IOException { public static boolean hasUTF8BOM(final File file) throws IOException {
try (InputStreamReader reader = new InputStreamReader(new FileInputStream(file), StandardCharsets.UTF_8)) { 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. * Determines if the content of the given file is encoded in UTF-8.
* <p> *
* This method checks a file for * @param file The file to check for UTF-8 encoding. Must not be null.
* - first 3 bytes for UTF-8 BOM (0xEF 0xBB 0xBF) * @return true if the file content is in UTF-8 encoding; false otherwise.
* - Existence of 0xC2 / 0xC3 character. * @throws IOException If an I/O error occurs while reading the file.
* </p>
* @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.
*/ */
public static boolean isUTF8(final File file) throws IOException { public static boolean isUTF8(final File file) throws IOException {
return isUTF8(file, DEFAULT_CHECK_ENCODING); return isUTF8(file, DEFAULT_CHECK_ENCODING);
} }
/** /**
* Converts the given Textfile inFile to the outFile using the given encodings. * Converts the content of a text file from one character encoding format to another.
* @param inFile File to read as UTF-8. *
* @param sourceFormat Format of the source file. * This method reads the input text file using the specified source encoding and writes
* @param outFile File to write with ISO-8859-15 format. * the content to the output text file in the specified target encoding.
* @param targetFormat Format of the target file. *
* @throws IOException Thrown when files couldn't be read / written. * @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 { public static void convertTextFile(final File inFile, final String sourceFormat, final File outFile, final String targetFormat) throws IOException {
char[] buffer = new char[BUFFER_SIZE]; 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. * Creates a universal file reader for the specified file name.
* @param filename Name of file to read. * This method initializes and returns an InputStreamReader to read
* @return An InputStreamReader * 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 { public static InputStreamReader createUniversalFileReader(final String filename) throws IOException {
return createUniversalFileReader(new File(filename)); return createUniversalFileReader(new File(filename));
} }
/** /**
* Creates a new InputStreamReader with the given format or UTF-8 if an UTF-8 file was recognized. * Creates a universal file reader for the specified file and format.
* @param filename Name of file to read. * The method resolves the file using its name and the expected format,
* @param expectedFormat Expected format e.g. ISO-8859-15 * returning an InputStreamReader for reading the file contents.
* @return An InputStreamReader *
* @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 { public static InputStreamReader createUniversalFileReader(final String filename, final String expectedFormat) throws IOException {
return createUniversalFileReader(new File(filename), expectedFormat); return createUniversalFileReader(new File(filename), expectedFormat);
} }
/** /**
* Creates a new InputStreamReader with the given format or UTF-8 if an UTF-8 file was recognized. * Creates a universal file reader for the specified file using the default encoding and configuration.
* @param file File to read. *
* @return An InputStreamReader * @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 { public static InputStreamReader createUniversalFileReader(final File file) throws IOException {
return createUniversalFileReader(file, DEFAULT_CHECK_ENCODING, true); 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. * Creates a universal file reader for the specified file with an expected format.
* @param file File to read. * This method wraps the given file in an InputStreamReader for consistent character stream manipulation.
* @param expectedFormat Expected format e.g. ISO-8859-15 *
* @return An InputStreamReader * @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 { public static InputStreamReader createUniversalFileReader(final File file, final String expectedFormat) throws IOException {
return createUniversalFileReader(file, expectedFormat, true); return createUniversalFileReader(file, expectedFormat, true);
} }
/** /**
* Creates a new InputStreamReader with the given format or UTF-8 if an UTF-8 file was recognized. * Creates an InputStreamReader for reading a file, considering the specified encoding format
* @param file File to read. * and whether UTF-8 should be accepted. Handles potential BOM for UTF-8 encoded files.
* @param expectedFormat Expected format e.g. ISO-8859-15 *
* @return An InputStreamReader * @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 { public static InputStreamReader createUniversalFileReader(final File file, final String expectedFormat, final boolean acceptUTF8) throws IOException {
String encoding = acceptUTF8 && isUTF8(file, expectedFormat) String encoding = acceptUTF8 && isUTF8(file, expectedFormat)
@ -201,9 +246,13 @@ public class FileUtils {
} }
/** /**
* Gets the parent directory of a file name. * Retrieves the parent directory of the given file or directory path.
* @param filename Name of file. *
* @return Parent folder. * 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) { public static String getParentDirectory(final String filename) {
File file = new File(filename); File file = new File(filename);
@ -211,9 +260,10 @@ public class FileUtils {
} }
/** /**
* Gets the core name of the file without path. * Extracts the name of a file from the given file path.
* @param filename Filename with path. *
* @return Filename without 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) { public static String getFilename(final String filename) {
File file = new File(filename); File file = new File(filename);
@ -221,10 +271,11 @@ public class FileUtils {
} }
/** /**
* Reads the content of a file (With the correct encoding!). * Reads the content of a file and returns it as a string, joining all lines with the system line separator.
* @param filename Name of file to read. *
* @return Content of the file or null in case of an error. * @param filename The name of the file to be read.
* @throws IOException Throes an IOException if the file cannot 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 { public static String readFileContent(final String filename) throws IOException {
try (BufferedReader reader = new BufferedReader(createUniversalFileReader(filename))) { try (BufferedReader reader = new BufferedReader(createUniversalFileReader(filename))) {
@ -233,10 +284,11 @@ public class FileUtils {
} }
/** /**
* Writes the content given to a file. * Writes the given content to the specified file path. If the file already exists, it will be overwritten.
* @param path Path of the file to write. *
* @param content Content to write. * @param path The path of the file to write to. Must not be null and must be writable.
* @throws IOException Thrown if the file could not be written. * @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 { public static void writeFile(final Path path, final String content) throws IOException {
try (BufferedWriter writer = new BufferedWriter(new FileWriter(path.toFile()))) { try (BufferedWriter writer = new BufferedWriter(new FileWriter(path.toFile()))) {

61
core/src/main/java/de/neitzel/core/util/RegionalizationMessage.java
View File

@ -4,34 +4,53 @@ import java.text.MessageFormat;
import java.util.Locale; import java.util.Locale;
import java.util.ResourceBundle; 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 { 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; private ResourceBundle res;
/** /**
* Creates a new instance of RegionalizationMessage. * Constructs a new RegionalizationMessage instance using the specified resource bundle source.
* @param source Source of messages. * 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) { public RegionalizationMessage(final String source) {
res = ResourceBundle.getBundle(source); res = ResourceBundle.getBundle(source);
} }
/** /**
* Creates a new instance of RegionalizationMessage. * Constructs a RegionalizationMessage object to retrieve localized messages
* @param source Source of messages. * from a specified resource bundle using the given source and locale.
* @param locale Locale to use. *
* @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) { public RegionalizationMessage(final String source, final Locale locale) {
res = ResourceBundle.getBundle(source, locale); res = ResourceBundle.getBundle(source, locale);
} }
/** /**
* Gets the Message behind a key. * Retrieves the localized message corresponding to the specified key from the resource bundle.
* @param key Key to look up. * If the key does not exist in the resource bundle, this method returns null.
* @return Message or 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) { public String getMessage(final String key) {
if (!res.containsKey(key)) return null; if (!res.containsKey(key)) return null;
@ -39,10 +58,13 @@ public class RegionalizationMessage {
} }
/** /**
* Gets the Message behind a key. * Retrieves a localized message for the given key from the resource bundle.
* @param key Key to look up. * If the key is not found, the specified default message is returned.
* @param defaultMessage Default message to use if message is not available. *
* @return Message from resource or default Message. * @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) { public String getMessage(final String key, final String defaultMessage) {
if (res.containsKey(key)) if (res.containsKey(key))
@ -52,11 +74,14 @@ public class RegionalizationMessage {
} }
/** /**
* Gets a formatted message. * Retrieves a localized and formatted message from a resource bundle based on a key.
* @param key key to look up message. * If the key is not found in the resource bundle, a default message is used.
* @param defaultMessage Default message to use if message couldn't be loaded. * The message supports parameter substitution using the supplied arguments.
* @param params parameter to format the message. *
* @return Formatted message. * @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) { public String getFormattedMessage(final String key, final String defaultMessage, final Object... params) {
MessageFormat format = new MessageFormat(getMessage(key, defaultMessage)); MessageFormat format = new MessageFormat(getMessage(key, defaultMessage));

120
core/src/main/java/de/neitzel/core/util/Strings.java
View File

@ -5,25 +5,46 @@ import lombok.NonNull;
import java.util.Map; import java.util.Map;
/** /**
* Utility Methods for Strings * Utility class providing common string manipulation methods.
*/ */
public class Strings { 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<String, String> environmentVariables = System.getenv(); private static Map<String, String> environmentVariables = System.getenv();
/** /**
* Expands environment Variables inside a string. * Expands environment variable placeholders within the provided text.
* <p> * Placeholders in the format ${VARIABLE_NAME} are replaced with their
* The environment variables should be given as ${variable}. * corresponding values from the environment variables.
* </p> *
* <p> * @param text The input string containing environment variable placeholders.
* Backslash inside variable values are replaced with slashes to avoid that they are seen as escape character. * If null, the method returns null.
* This makes the use for paths on windows possible but reduces the use with non paths in which you need a backslash. * @return A string with the placeholders replaced by their corresponding
* </p> * environment variable values. If no placeholders are found,
* @param text Test in which environment variables should be expanded. * the original string is returned.
* @return String with all environment variables expanded.
*/ */
public static String expandEnvironmentVariables(String text) { public static String expandEnvironmentVariables(String text) {
if (text == null) return null; if (text == null) return null;
@ -36,18 +57,23 @@ public class Strings {
} }
/** /**
* Checks if the given String is null or empty. * Checks whether a given string is either null or empty.
* @param string String to check. *
* @return true if given String is 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) { public static boolean isNullOrEmpty(final String string) {
return (string == null || string.length()==0); return (string == null || string.length()==0);
} }
/** /**
* Removes a leading / ending quote if there. * Removes surrounding double quotes from the input string if they are present.
* @param value String to remove the quotes. * Trims leading and trailing whitespaces from the input before processing.
* @return Parameter string if it does not start / end with a quote, else string without leading/ending quote. *
* @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) { public static String removeQuotes(final String value) {
String trimmedValue = value.trim(); String trimmedValue = value.trim();
@ -58,12 +84,15 @@ public class Strings {
} }
/** /**
* Filters a given String and removes all illegal characters. * Replaces illegal characters in a given string with a specified replacement string.
* @param value String value to filter all illegal characters from. * Optionally, consecutive illegal characters can be combined into a single replacement.
* @param illegalCharacters String with all Illegal Characters to filter out. *
* @param replacement String to replace illegal characters with. * @param value The input string in which illegal characters are to be replaced.
* @param combine Should multiple illegal characters that are together be replaced with one replacement string only? * @param illegalCharacters A string specifying the set of illegal characters to be matched.
* @return A new string where all illegal characters are replaced with the replacement string. * @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) { public static String replaceIllegalCharacters(final String value, final String illegalCharacters, final String replacement, final boolean combine) {
String replacementRegex = "[" + illegalCharacters + "]" + (combine ? "+" : ""); String replacementRegex = "[" + illegalCharacters + "]" + (combine ? "+" : "");
@ -71,15 +100,17 @@ public class Strings {
} }
/** /**
* Filters a given String and removes all illegal characters. * Replaces characters in the input string that are not in the allowed characters set
* <p> * with a specified replacement string. Optionally combines consecutive non-allowed
* All characters, that are not inside allowedCharacters, are illegal characters. * characters into a single replacement.
* </p> *
* @param value String value to filter all illegal characters from. * @param value The input string to be processed.
* @param allowedCharacters String with all allowed Characters to filter out. * @param allowedCharacters A string containing the set of characters that are allowed.
* @param replacement String to replace illegal characters with. * Any character not in this set will be replaced.
* @param combine Should multiple illegal characters that are together be replaced with one replacement string only? * @param replacement The string to replace non-allowed characters with.
* @return A new string where all illegal characters are replaced with the replacement string. * @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) { public static String replaceNonAllowedCharacters(final String value, final String allowedCharacters, final String replacement, final boolean combine) {
String replacementRegex = "[^" + allowedCharacters + "]" + (combine ? "+" : ""); String replacementRegex = "[^" + allowedCharacters + "]" + (combine ? "+" : "");
@ -87,9 +118,15 @@ public class Strings {
} }
/** /**
* Gets the next Element which follows to the current element. * Increments a string value by modifying its last character, or leading characters if necessary.
* @param element to get the precessor. * The increment follows these rules:
* @return The next element after this one. * - 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) { public static String increment(@NonNull final String element) {
if (element.isEmpty()) return "1"; if (element.isEmpty()) return "1";
@ -101,6 +138,17 @@ public class Strings {
return firstPart + (char)(lastChar+1); 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) { public static String limitCharNumber(final String original, final int maxLength) {
if (original == null || original.length() <= maxLength) return original; if (original == null || original.length() <= maxLength) return original;

116
core/src/main/java/de/neitzel/core/util/XmlUtils.java
View File

@ -21,22 +21,39 @@ import java.time.format.DateTimeFormatter;
import java.util.Date; 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 @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"); 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 doc The XML document in which the new element is to be created. Must not be null.
* @param name Name of the Element. * @param name The name of the element to be created. Must not be null or empty.
* @return Created Element. * @return The newly created element with the given name. Never returns null.
*/ */
public static Element createElement(final Document doc, final String name) { public static Element createElement(final Document doc, final String name) {
log.debug("Creating a new element " + 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 doc the XML document to which the element belongs. Must not be null.
* @param name Name of the Element. * @param name the name of the element to create. Must not be null.
* @param value Value of the Text Node. * @param value the text value to be set as the content of the created element.
* @return 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) { public static Element createElement(final Document doc, final String name, final String value) {
log.debug("Creating a new element " + name + " with value: " + 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 doc the XML document to which the element belongs; must not be null
* @param name Name of the Element. * @param name the name of the element to be created; must not be null or empty
* @param value Date to insert into node. * @param value the date value to be assigned to the created element; must not be null
* @return Created Element. * @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) { public static Element createElement(final Document doc, final String name, final Date value) {
return createElement(doc, name, XML_DATE_FORMATTER.format(value.toInstant())); 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 doc The Document object to which the element will belong. Must not be null.
* @param name Name of the Element. * @param name The name of the element to be created. Must not be null or empty.
* @param value Value of the Integer Node. * @param value The optional value to be set as the text content of the element. If null,
* @return Created Element. * 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) { public static Element createElement(final Document doc, final String name, final Integer value) {
log.debug("Creating a new element " + name + " with value: " + 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 doc The Document to which the new element belongs. Must not be null.
* @param name Name of the Element. * @param name The name of the new element to be created. Must not be null or empty.
* @param parent Parent for the Element. * @param parent The parent element to which the new element will be appended. Must not be null.
* @return Created Element. * @return The newly created and appended Element object.
*/ */
public static Element createAndInsertElement(final Document doc, final String name, @NonNull final Element parent) { 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."); 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 doc The XML document to which the new element belongs. Must not be null.
* @param value Value of the Text Node. * @param name The name of the element to create. Must not be null.
* @param parent Parent for the Element. * @param value The value to be set for the created element. Can be null if no value is required.
* @return Created Element. * @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) { 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."); 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. * 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 String with XML content. * @param xmlStream The raw XML string to be formatted. Cannot be null.
* @return Formated XML content or original content in case of an error. * @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) { public static String format(final String xmlStream) {
log.debug("formatXML"); 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. * @param doc The XML Document to be formatted. Must not be null.
* @return Formated XML content. * @return A formatted string representation of the XML document, or null if an error occurs during processing.
*/ */
public static String format(final Document doc) { public static String format(final Document doc) {
try { try {
@ -184,9 +215,14 @@ public class XmlUtils {
} }
/** /**
* Checks if the given xml string is valid XML * Validates whether a given XML string is well-formed.
* @param xml XML String. * This method attempts to parse the input XML string and checks
* @return true if xml is valid. * 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) { public static boolean checkXml(final String xml) {
try { try {

156
fx-example/pom.xml
View File

@ -43,160 +43,4 @@
</plugin> </plugin>
</plugins> </plugins>
</build> </build>
<profiles>
<!-- Profile that adds JLink and JPackage runs.
Add -Pimage or -Dimage to use this profile.
-->
<profile>
<id>image</id>
<activation>
<property>
<name>image</name>
</property>
</activation>
<build>
<plugins>
<!-- Copy dependencies -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-dependency-plugin</artifactId>
<version>${maven.dependency.plugin}</version>
<executions>
<!-- erstmal Abhängigkeiten für den Class-Path kopieren -->
<execution>
<id>copy-dependencies</id>
<phase>package</phase>
<goals>
<goal>copy-dependencies</goal>
</goals>
<configuration>
<outputDirectory>${project.build.directory}/modules</outputDirectory>
<includeScope>runtime</includeScope>
<overWriteReleases>false</overWriteReleases>
<overWriteSnapshots>false</overWriteSnapshots>
<overWriteIfNewer>true</overWriteIfNewer>
</configuration>
</execution>
<!-- dazu noch das Projekt-JAR -->
<execution>
<id>copy</id>
<phase>install</phase>
<goals>
<goal>copy</goal>
</goals>
<configuration>
<outputDirectory>${project.build.directory}/modules</outputDirectory>
<artifactItems>
<artifactItem>
<groupId>${project.groupId}</groupId>
<artifactId>${project.artifactId}</artifactId>
<version>${project.version}</version>
<type>${project.packaging}</type>
<destFileName>${project.build.finalName}.jar</destFileName>
</artifactItem>
</artifactItems>
<overWriteIfNewer>true</overWriteIfNewer>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>com.github.akman</groupId>
<artifactId>jpackage-maven-plugin</artifactId>
<version>${jpackage.maven.plugin}</version>
<configuration>
<name>${appName}</name>
<type>IMAGE</type>
<modulepath>
<dependencysets>
<dependencyset>
<includenames>
<includename>javafx\..*</includename>
</includenames>
</dependencyset>
</dependencysets>
</modulepath>
<addmodules>
<addmodule>javafx.controls</addmodule>
<addmodule>javafx.graphics</addmodule>
<addmodule>javafx.fxml</addmodule>
<addmodule>javafx.web</addmodule>
</addmodules>
<mainclass>${main.class}</mainclass>
<input>${project.build.directory}/modules</input>
<mainjar>${jar.filename}.jar</mainjar>
</configuration>
<executions>
<execution>
<phase>install</phase>
<goals>
<goal>jpackage</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
</profile>
<!-- Profile to build a fat jar
Add -Pfatjar or -Dfatjar to use this profile.
-->
<profile>
<id>fatjar</id>
<activation>
<property>
<name>fatjar</name>
</property>
</activation>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-shade-plugin</artifactId>
<version>${maven.shade.plugin}</version>
<executions>
<execution>
<phase>package</phase>
<goals>
<goal>shade</goal>
</goals>
</execution>
</executions>
<configuration>
<shadedArtifactAttached>true</shadedArtifactAttached>
<shadedClassifierName>full</shadedClassifierName>
<transformers>
<transformer implementation="org.apache.maven.plugins.shade.resource.ServicesResourceTransformer"/>
<transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
<manifestEntries>
<Main-Class>${main.class}</Main-Class>
<Build-Version>1.0</Build-Version>
</manifestEntries>
</transformer>
</transformers>
<filters>
<filter>
<artifact>*:*</artifact>
<excludes>
<exclude>META-INF/MANIFEST.MF</exclude>
<exclude>**/module-info.class</exclude>
<exclude>META-INF/*.SF</exclude>
<exclude>META-INF/*.DSA</exclude>
<exclude>META-INF/*.RSA</exclude>
</excludes>
</filter>
</filters>
</configuration>
</plugin>
</plugins>
</build>
</profile>
</profiles>
</project> </project>

47
log4j/src/main/java/de/neitzel/log4j/Log4jUtils.java
View File

@ -6,40 +6,53 @@ import java.io.File;
import java.net.URISyntaxException; 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 { public class Log4jUtils {
/** /**
* Default Logfile that should be read. * The default path to the Log4j configuration file.
* Must be a relative path that is checked from the current directory and also from the location of the jar 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"; 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"; public static final String DEFAULT_LOG4J_RESOURCE = "/log4j.default.properties";
/** /**
* Checks if a log4j config file was set on command line with -Dlog4j.configuration * Checks if the system property "log4j.configuration" is set.
* @return true if log4j.configuration was set. *
* @return true if the "log4j.configuration" property is defined, false otherwise.
*/ */
public static boolean isLog4jConfigFileSet() { public static boolean isLog4jConfigFileSet() {
return System.getProperty("log4j.configuration") != null; 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() { public static void setLog4jConfiguration() {
setLog4jConfiguration(DEFAULT_LOG4J_LOGFILE, DEFAULT_LOG4J_RESOURCE); setLog4jConfiguration(DEFAULT_LOG4J_LOGFILE, DEFAULT_LOG4J_RESOURCE);
} }
/** /**
* Gets the file with path relative to the jar file. * Constructs the absolute path to the specified Log4j configuration file located
* @param log4jConfigFile log4j config file. * in the same directory as the JAR file of the application.
* @return Path if possible or null. *
* @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) { public static String getLog4jLogfileAtJar(final String log4jConfigFile) {
try { try {
@ -50,13 +63,13 @@ public class Log4jUtils {
} }
/** /**
* Uses the default configurations if no config file was set. * Sets the Log4j configuration using the specified configuration file or a default resource
* <p> * if the configuration file is not found. If a Log4j configuration is already set, the method
* A log4j configuration can be set using -Dlog4j.configuration. If no configuration was set, * does nothing.
* we look for the log4jConfigFile. If it does not exist, we read the defaultResource. *
* </p> * @param log4jConfigFile the path to the Log4j configuration file to be used.
* @param log4jConfigFile Default file to look for. * @param defaultResource the fallback resource to be used as the configuration if the file
* @param defaultResource Resource path to use if config file wasn't found. * is not found or accessible.
*/ */
public static void setLog4jConfiguration(final String log4jConfigFile, final String defaultResource) { public static void setLog4jConfiguration(final String log4jConfigFile, final String defaultResource) {
if (isLog4jConfigFileSet()) return; if (isLog4jConfigFileSet()) return;

15
pom.xml
View File

@ -25,10 +25,10 @@
<!-- Dependency versions --> <!-- Dependency versions -->
<javafx.version>21.0.3</javafx.version> <javafx.version>21.0.3</javafx.version>
<jetbrains.annotations.version>24.1.0</jetbrains.annotations.version> <jetbrains.annotations.version>26.0.2</jetbrains.annotations.version>
<junit.version>5.10.2</junit.version> <junit.version>5.12.1</junit.version>
<lombok.version>1.18.32</lombok.version> <lombok.version>1.18.38</lombok.version>
<mockito.version>5.12.0</mockito.version> <mockito.version>5.16.1</mockito.version>
<reflections.version>0.10.2</reflections.version> <reflections.version>0.10.2</reflections.version>
<slf4j.version>2.0.17</slf4j.version> <slf4j.version>2.0.17</slf4j.version>
@ -145,6 +145,13 @@
<scope>test</scope> <scope>test</scope>
</dependency> </dependency>
<!-- Logging implementation -->
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-simple</artifactId>
<scope>test</scope>
</dependency>
<!-- Dependency used for @NotNull / @Nullable --> <!-- Dependency used for @NotNull / @Nullable -->
<dependency> <dependency>
<groupId>org.jetbrains</groupId> <groupId>org.jetbrains</groupId>