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;
/**
* 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> {
/**
* List of Arguments (from command line)
* A String array representing the command-line arguments provided to the application.
* This array holds each tokenized element of the command-line input for further parsing
* and processing by the application logic. It is used within the {@code ArgumentProvider}
* class to iterate through and retrieve arguments systematically.
*/
private String[] arguments;
/**
* Current element we work on.
* Tracks the current position within an array of arguments.
*
* This variable is used to index into the arguments array, enabling
* sequential access to command-line tokens. It is incremented as arguments
* are processed or retrieved using methods such as {@code next()} or {@code peek()}
* in the {@link ArgumentProvider} class.
*
* Its value starts at 0 and increases until it reaches the length of
* the provided arguments array, at which point iteration ends.
*/
private int current = 0;
/**
* Creates a new instance of ArgumentProvider.
* @param arguments List of Arguments.
* Creates an instance of the ArgumentProvider class to iterate over the given array of arguments.
* If the provided array is null, it initializes the arguments with an empty array.
*
* @param arguments The array of command-line arguments to be iterated over.
* If null, it defaults to an empty array.
*/
public ArgumentProvider(final String[] arguments) {
if (arguments == null) {
@ -30,25 +50,29 @@ public class ArgumentProvider implements Iterator<String> {
}
/**
* Checks if more arguments are available.
* @return True if more arguments are available else false.
* Checks if there are more arguments available to iterate over.
*
* @return true if there are additional arguments available; false otherwise.
*/
public boolean hasNext() {
return current < arguments.length;
}
/**
* Checks if count more arguments are available.
* @param count Number of arguments we want to get.
* @return True if count more arguments are available else false.
* Determines if the specified number of additional arguments are available in the collection.
*
* @param count the number of additional arguments to check for availability
* @return true if there are at least the specified number of arguments available, otherwise false
*/
public boolean hasNext(final int count) {
return current + count <= arguments.length;
}
/**
* Get the next token.
* @return The next token or null if no more available.
* Retrieves the next argument in the sequence.
* If no more arguments are available, returns {@code null}.
*
* @return the next argument as a {@code String}, or {@code null} if no further arguments are available
*/
public String next() {
if (!hasNext()) return null;
@ -59,8 +83,10 @@ public class ArgumentProvider implements Iterator<String> {
}
/**
* Get the next token without removing it.
* @return The next token or null if no more available.
* Returns the next argument in the sequence without advancing the iterator.
* If there are no more arguments available, this method returns null.
*
* @return the next argument in the sequence or null if no arguments are available
*/
public String peek() {
if (!hasNext()) return null;

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;
/**
* A parameter on the command line.
* <br>
* Each parameter has to start with either - or /!
* The `Parameter` class defines a command-line parameter with associated metadata,
* such as constraints on the number of values it accepts, descriptions, and aliases.
* It also allows specifying callbacks to handle parameter processing.
*
* This class is intended to be used as part of a command-line parser, enabling
* structured handling of arguments provided via the command line.
*/
@Slf4j
@Builder
@Getter
@Setter
@AllArgsConstructor
@NoArgsConstructor
public class Parameter {
/**
* Name of the parameter.
* Represents a command-line parameter definition within the application.
*
* This class encapsulates the metadata and configuration of a command-line parameter,
* including its name, aliases, descriptions, value constraints, and behavior. Instances
* of this class are used to define and manage the parameters that the `Parser` class
* recognizes and processes.
*
* A parameter can be configured as a default parameter or as a help command. The default
* parameter serves as a catch-all for unmatched command-line inputs, while the help
* command provides usage information for users.
*/
public Parameter() {
}
/**
* Constructs a new Parameter with the given attributes.
*
* @param name The name of the parameter.
* @param minNumberValues The minimum number of values allowed for this parameter.
* @param maxNumberValues The maximum number of values allowed for this parameter.
* @param multipleEntries Indicates whether multiple entries are allowed for this parameter.
* @param shortDescription A brief description of the parameter.
* @param longDescription A detailed description of the parameter.
* @param callback A consumer function that processes a list of values associated with this parameter.
* @param isHelpCommand Indicates whether this parameter represents a help command.
* @param isDefaultParameter Indicates whether this parameter is the default parameter.
* @param aliasList A list of aliases for this parameter.
*/
public Parameter(String name, int minNumberValues, int maxNumberValues, boolean multipleEntries, String shortDescription, String longDescription, Consumer<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;
/**
* Min number of values given.
* Specifies the minimum number of values required for this parameter.
*
* This variable enforces a constraint on the number of arguments that must
* be provided for the parameter during command-line parsing. If the number of
* provided arguments is less than this value, an exception will be thrown during parsing.
*
* It is primarily used in validation logic within the command-line parser
* to ensure the required input is received for proper processing of the parameter.
*/
private int minNumberValues;
/**
* Max number of values given.
* Specifies the maximum number of values that the corresponding parameter can accept.
*
* This field is used to validate and enforce constraints during command-line parsing.
* If more values than specified are provided for a parameter, the parser throws an exception
* to indicate a violation of this constraint.
*
* A value of 0 implies that the parameter does not support any values, while a positive
* value indicates the exact maximum limit of acceptable values.
*/
private int maxNumberValues;
/**
* Defines if the parameter can be given multiple times.
* Indicates whether the parameter allows multiple entries.
*
* If set to {@code true}, the parameter can be specified multiple times
* on the command-line. This allows the association of multiple values
* or options with the same parameter name.
*
* If set to {@code false}, the parameter can be specified only once
* during command-line parsing.
*/
private boolean multipleEntries;
/**
* Short description of the parameter.
* A concise, human-readable description of the parameter's purpose and functionality.
*
* This description provides a brief summary to help users understand the
* essential role of the parameter within the command-line parser. It is typically
* displayed in usage instructions, help messages, or command summaries.
*/
private String shortDescription;
/**
* Long description of the parameter.
* A detailed, extended description of the parameter's purpose and usage.
*
* This description provides deeper context about what the parameter represents,
* how it fits into the overall command-line application, and any nuances
* associated with its use. It is displayed when help or additional documentation
* for a specific parameter is requested.
*/
private String longDescription;
/**
* Callback wenn der Parameter gefunden wurde.
* A callback function that processes a list of string arguments for a specific parameter.
* The callback is invoked during command-line parsing when a parameter is recognized,
* passing the associated values of the parameter for further processing.
*
* The provided {@link Consumer} implementation defines the logic to
* handle or validate the values supplied for a command-line parameter. The values
* passed are determined based on the parameter's configuration (e.g., minimum and
* maximum number of associated values).
*
* This field is typically set for the `Parameter` class to enable custom handling
* of parameter-specific logic, such as invoking a help command or performing
* business logic with the values parsed from the command-line arguments.
*/
private Consumer<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;
/**
* Determines if this Parameter is the default parameter.
* <br>
* A default parameter must take at least one additional value.
* Indicates whether the parameter is designated as the default parameter.
*
* The default parameter is a special type of parameter that can accept arguments
* without an explicit prefix or identifier. It is used when a provided command-line
* argument does not match any defined parameter and does not start with a special
* character (e.g., '-') typically used to denote named parameters.
*
* If this field is set to {@code true}, the parameter is treated as the default
* parameter. Only one parameter can be assigned this role within the parser.
* Attempting to assign multiple default parameters or a default parameter without
* accepting values (both `minNumberValues` and `maxNumberValues` set to 0) will
* result in an exception during configuration.
*
* This property is utilized during the parsing process to determine whether an
* unmatched argument should be handled as a default parameter value, simplifying
* the handling of positional arguments or other unnamed input data.
*/
private boolean isDefaultParameter;
/**
* List of aliases.
* A list of alias names associated with a parameter.
*
* This variable holds alternative names that can be used
* to reference the parameter in command-line input. Each alias
* functions as an equivalent to the primary parameter name.
* Aliases are case-insensitive when used within the command-line parser.
*
* The aliases associated with a parameter allow greater flexibility
* and user convenience when specifying parameters during command-line execution.
*/
@Singular("alias")
private List<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.*;
/**
* A parser of the CommandLine.
* <br>
* Parameter are defined. Each parameter will start with either - or /.
* The Parser class is responsible for parsing and handling command-line arguments.
* It allows for the registration of known parameters and provides mechanisms
* to validate and process command-line input.
*/
@Slf4j
public class Parser {
/**
* Parameters known by the CommandLineParser.
* A map to store parameters where the key is a string representing
* the parameter name and the value is the corresponding {@link Parameter} object.
*
* This map serves as a registry for defining, organizing, and accessing
* command-line parameters. Each entry holds a parameter's metadata and
* its associated configuration to facilitate effective command-line parsing.
*
* Key considerations:
* - The key represents the primary name of the parameter.
* - The value, encapsulated as a {@link Parameter} object, includes
* details such as descriptions, value constraints, aliases, and processing logic.
*/
private Map<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;
/**
* Adds a parameter to the list of known parameters.
* @param parameter
* Constructs a new instance of the `Parser` class.
*
* The `Parser` class is responsible for parsing and processing
* command-line arguments. It interprets input data based on defined
* parameters and provides structured access to arguments, enabling
* streamlined application configuration and execution.
*
* This constructor initializes the parser without any predefined
* configuration or parameters. Users can define parameters,
* add handlers, and parse command-line arguments using available
* methods in the class.
*/
public Parser() {
}
/**
* Adds a new parameter to the internal parameter map. The method registers the parameter
* using its primary name and all specified aliases (case-insensitive). It also sets up
* specific behaviors for help and default parameters based on the parameter's configuration.
*
* @param parameter the Parameter object to be added. It contains the primary name, aliases,
* and other metadata such as whether it is a help command or default parameter.
* The parameter must fulfill specific constraints if defined as the default
* parameter (e.g., accepting values).
*
* @throws IllegalArgumentException if the parameter is defined as a default parameter and
* does not accept values (both minNumberValues and maxNumberValues
* are set to 0).
*/
public void addParameter(final Parameter parameter) {
// Add by name
@ -48,13 +98,12 @@ public class Parser {
}
/**
* Checks if param is a parameter.
* <br>
* - When the parameter is known as a parameter, then it is true.
* - Everything that starts with a - must be a known parameter -> false
* - Parameter is not known and does not start with a -? -> Default parameter if available.
* @param param Parameter in lower case to check.
* @return true if it is either a known parameter or an argument for the default parameter.
* Checks whether a given parameter string matches a valid parameter within the defined constraints.
*
* @param param the parameter string to be checked. This can either be a key defined in the `parameters` map
* or a potential default parameter if it does not start with a dash ("-").
* @return {@code true} if the parameter is a valid entry in the `parameters` map or matches the default parameter;
* {@code false} otherwise, including when the parameter starts with a dash ("-").
*/
protected boolean isParameter(final String param) {
if (parameters.containsKey(param)) return true;
@ -63,8 +112,15 @@ public class Parser {
}
/**
* Parse the given commandline arguments.
* @param args Commandline Arguments to parse.
* Parses an array of command-line arguments and processes them as defined by the application's parameters.
*
* The method iteratively checks each argument in the provided array, validates it against
* the registered parameters, and invokes the corresponding processing callback if applicable.
* Unrecognized parameters or missing required values will result in an {@code IllegalArgumentException}.
*
* @param args the array of command-line arguments to be parsed and processed. Each element in this
* array represents a single input argument provided to the application. The format and
* content of the arguments are expected to conform to the application's parameter definitions.
*/
public void parse(final String[] args) {
ArgumentProvider provider = new ArgumentProvider(args);
@ -96,11 +152,19 @@ public class Parser {
}
/**
* Get the given optional data of a parameter-
* @param provider Provider of token.
* @param min Minimum number of elements to get.
* @param max Maximum number of elements to get.
* @return List of token of the Parameter.
* Retrieves a list of options by consuming arguments from the provided {@link ArgumentProvider}
* within the range specified by the minimum and maximum values.
*
* @param provider The source providing the command-line arguments. This object allows
* retrieving and examining argument strings in sequence.
* @param min The minimum number of arguments to be retrieved. If fewer arguments
* are available, no arguments will be added to the result.
* @param max The maximum number of arguments to be retrieved. If `max` is smaller
* than `min`, it will be adjusted to match `min`. Only up to `max`
* arguments will be added to the result.
* @return A list of argument strings, containing up to `max` elements and at least `min`
* elements if sufficient arguments are available. The list will not include
* arguments already recognized in the `parameters` map.
*/
private List<String> getOptions(ArgumentProvider provider, int min, int max) {
if (max < min) max = min;
@ -120,8 +184,15 @@ public class Parser {
}
/**
* Callback for help command.
* @param arguments null for general help or name of a command.
* Handles the help command when invoked in the command-line interface, providing information about available parameters.
* If no arguments are provided, it lists all possible parameters and their short descriptions.
* If specific arguments are supplied, it provides the detailed description of the corresponding parameter.
* In case an unknown parameter is specified, it indicates so to the user.
*
* @param arguments a list of strings representing the user-provided arguments. If empty or {@code null},
* the method lists all available parameters with their short descriptions. If a parameter name
* is provided in the list, its detailed information is displayed. If an unrecognized parameter
* is provided, a corresponding message is shown.
*/
public void helpCommandCallback(final List<String> arguments) {
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;
/**
* Base class for a simple configuration.
* Provides a utility class for managing configuration properties in an
* application. This class allows loading properties from files, accessing
* values with various types including environment variable substitution,
* and updating properties.
*/
@Slf4j
public class Configuration {
/**
* Properties with configuration data.
* A {@link Properties} object that stores a set of key-value pairs.
* This variable can be used to manage configuration settings or other
* collections of properties within the application.
*
* It provides methods to load, retrieve, and modify properties
* as necessary for the application's requirements.
*/
private Properties properties = new Properties();
private final Properties properties;
/**
* Gets a boolean property
* @param defaultValue Default value to return if key is not present.
* @param key Key of the property to get.
* @return The value of the property if it exists or the default value.
* Constructs a new Configuration instance with default properties.
* This constructor initializes the Configuration object using an
* empty set of {@code Properties}.
*/
public Configuration() {
this(new Properties());
}
/**
* Constructs a new Configuration instance using the provided properties.
*
* @param properties the Properties object containing configuration key-value pairs
*/
public Configuration(Properties properties) {
this.properties = properties;
}
/**
* Retrieves a boolean property value associated with the specified key. If the key does not exist in the properties,
* the provided default value is returned. The method also supports interpreting specific string values as true.
*
* @param key the key used to retrieve the boolean property
* @param defaultValue the default value returned if the key is not found in the properties
* @return the boolean value associated with the key, or the defaultValue if the key does not exist
*/
protected boolean getBooleanProperty(final String key, final boolean defaultValue) {
if (!properties.containsKey(key)) return defaultValue;
@ -38,10 +66,12 @@ public class Configuration {
}
/**
* Gets a String property
* @param key Key of the property to query.
* @param defaultValue Default value to return if property not available.
* @return The property if it exists, else the default value.
* Retrieves the value of the specified property as a trimmed string.
* If the property is not found, the default value is returned.
*
* @param key the key of the property to retrieve
* @param defaultValue the default value to return if the property is not found
* @return the trimmed string value of the property, or the default value if the property is not found
*/
protected String getStringProperty(final String key, final String defaultValue) {
if (!properties.containsKey(key)) return defaultValue;
@ -49,13 +79,13 @@ public class Configuration {
}
/**
* Gets a String property with all environment variables replaced
* <p>
* Environment variable can be included with ${variable name}.
* </p>
* @param key Key of the property to query.
* @param defaultValue Default value to return if property not available.
* @return The property if it exists, else the default value.
* Retrieves a string property value associated with the specified key, applies
* environment variable expansion on the value, and returns the processed result.
*
* @param key the key identifying the property to retrieve.
* @param defaultValue the default value to use if the property is not found.
* @return the processed property value with expanded environment variables, or
* the defaultValue if the property is not found.
*/
protected String getStringPropertyWithEnv(final String key, final String defaultValue) {
String result = getStringProperty(key, defaultValue);
@ -63,26 +93,25 @@ public class Configuration {
}
/**
* Gets a String property without quotes.
* <p>
* If the value is put in quotes, then the quote signs are replaced.
* </p>
* @param key Key of the property to query.
* @param defaultValue Default value to return if property not available.
* @return The property if it exists, else the default value (without leading/ending quote signs).
* Retrieves the value of a string property associated with the specified key,
* removes any surrounding quotes from the value, and returns the resultant string.
*
* @param key the key associated with the desired property
* @param defaultValue the default value to return if the property is not found or is null
* @return the string property without surrounding quotes, or the defaultValue if the property is not found
*/
protected String getStringPropertyWithoutQuotes(final String key, final String defaultValue) {
return Strings.removeQuotes(getStringProperty(key, defaultValue));
}
/**
* Gets a String property without quotes.
* <p>
* If the value is put in quotes, then the quote signs are replaced.
* </p>
* @param key Key of the property to query.
* @param defaultValue Default value to return if property not available.
* @return The property if it exists, else the default value (without leading/ending quote signs).
* Retrieves the string value of a configuration property identified by the given key,
* removes surrounding quotes if present, and expands any environment variables found
* within the string. If the property is not found, a default value is used.
*
* @param key the key identifying the configuration property
* @param defaultValue the default value to use if the property is not found
* @return the processed string property with quotes removed and environment variables expanded
*/
protected String getStringPropertyWithoutQuotesWithEnv(final String key, final String defaultValue) {
String result = getStringPropertyWithoutQuotes(key, defaultValue);
@ -90,12 +119,15 @@ public class Configuration {
}
/**
* Gets an Integer property.
* <br>
* Supports null as value.
* @param defaultValue Default value to return if key is not present.
* @param key Key of the property to get.
* @return The value of the property if it exists or the default value.
* Retrieves the integer value for the specified property key. If the key does
* not exist in the properties or the value is null/empty, the provided default
* value is returned.
*
* @param key the property key to retrieve the value for
* @param defaultValue the default value to return if the key is not present
* or the value is null/empty
* @return the integer value associated with the key, or the defaultValue if
* the key does not exist or its value is null/empty
*/
protected Integer getIntegerProperty(final String key, final Integer defaultValue) {
if (!properties.containsKey(key)) return defaultValue;
@ -104,9 +136,11 @@ public class Configuration {
}
/**
* Sets an Integer property.
* @param key Key of the property to set.
* @param value Value to set.
* Sets an integer property in the properties object. If the provided value is null,
* an empty string will be stored as the property's value.
*
* @param key the key under which the property will be stored
* @param value the integer value to be stored; if null, an empty string will be used
*/
protected void setIntegerProperty(final String key, final Integer value) {
if (value == null) {
@ -117,13 +151,14 @@ public class Configuration {
}
/**
* Gets the property as LocalDate.
* <br>
* An null value or an empty String is given as null.
* @param key Key of the property.
* @param defaultValue default Value.
* @param formatString Format String to use.
* @return The LocalDate stored the property or the default value if property unknown or couldn't be parsed.
* Retrieves a LocalDate value from the properties based on the provided key.
* If the key does not exist or the value is invalid, a default value is returned.
*
* @param key the key to look up the property in the properties map
* @param defaultValue the default LocalDate value to return if the key is not found
* @param formatString the format string to parse the LocalDate value
* @return the LocalDate value from the properties if available and valid,
* otherwise the defaultValue
*/
protected LocalDate getLocalDateProperty(final String key, final LocalDate defaultValue, final String formatString) {
if (!properties.containsKey(key)) return defaultValue;
@ -134,12 +169,12 @@ public class Configuration {
}
/**
* Sets the LocalDate using the provided format String.
* <br>
* Null is allowed and is stored as empty string.
* @param key Key of the property to set.
* @param value Value to set.
* @param formatString Format string to use.
* Sets a property with the given key and a formatted LocalDate value.
* If the provided value is null, the property will be set to an empty string.
*
* @param key the key of the property to set
* @param value the LocalDate value to format and set as the property value
* @param formatString the pattern string used to format the LocalDate value
*/
protected void setLocalDateProperty(final String key, final LocalDate value, final String formatString) {
if (value == null) {
@ -150,9 +185,11 @@ public class Configuration {
}
/**
* Sets a property to a new value.
* @param key Key of property to set.
* @param value New value of property.
* Sets a property with the specified key to the given value. If the value is null,
* it defaults to an empty string. Logs the operation and updates the property.
*
* @param key the key of the property to be set
* @param value the value to be associated with the specified key; defaults to an empty string if null
*/
public void setProperty(final String key, final String value) {
String newValue = value == null ? "" : value;
@ -161,14 +198,22 @@ public class Configuration {
}
/**
* Loads the configuration of the file.
* Loads the content of the specified file using the provided file name.
*
* @param fileName the name of the file to be loaded
*/
public void load(final String fileName) {
load(fileName, Charset.defaultCharset().name(), true);
}
/**
* Loads the configuration of the file.
* Loads the configuration from a specified file. If the file does not exist in the
* specified location, it attempts to find the file alongside the JAR file of the application.
* Reads the configuration with the provided encoding and an option to accept UTF-8 encoding.
*
* @param fileName the name of the configuration file to be loaded
* @param encoding the encoding format to be used while reading the configuration file
* @param acceptUTF8 a boolean flag indicating whether to accept UTF-8 encoding
*/
public void load(final String fileName, final String encoding, final boolean acceptUTF8) {
log.info("Reading Config: " + fileName + " with encoding: " + encoding + "accepting UTF-8: " + acceptUTF8);
@ -201,8 +246,9 @@ public class Configuration {
}
/**
* Insert the configuration settings of the given config.
* @param config Configuration to merge into this instance.
* Merges the properties from the provided configuration into the current configuration.
*
* @param config the Configuration object whose properties will be merged into this instance
*/
public void merge(final Configuration config) {
for(Map.Entry<Object, Object> entry: config.properties.entrySet()) {
@ -211,8 +257,9 @@ public class Configuration {
}
/**
* Removes a key from the configuration.
* @param key
* Removes the specified key-value pair from the properties map if the key exists.
*
* @param key the key to be removed from the properties map
*/
public void remove(final String key){
if (properties.containsKey(key)) properties.remove(key);

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

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.IOException;
/**
* The ISO8859EncodingFileReader class extends the ConvertedEncodingFileReader to provide
* file reading functionality with specific encoding support for ISO-8859-15.
* This class ensures that the file content is either read directly in the ISO-8859-15 encoding
* or converted transparently to this encoding if needed.
*/
public class ISO8859EncodingFileReader extends ConvertedEncodingFileReader {
/**
* Represents the target encoding format used by the ISO8859EncodingFileReader class.
* The TARGET_FORMAT is set to "ISO-8859-15", which specifies an encoding standard
* that is a variant of ISO-8859-1, adding the Euro symbol and other additional characters.
* This constant is used to indicate the desired character encoding for reading file content.
*/
private static final String TARGET_FORMAT = "ISO-8859-15";
/**
* Constructs an instance of ISO8859EncodingFileReader to read the provided file
* while ensuring the encoding is set to ISO-8859-15. If the file is not in the
* target encoding, this method transparently converts the file content to match
* the encoding before reading.
*
* @param file The file to be read. Must exist and be accessible.
* @throws IOException If the file does not exist, is inaccessible, or an error
* occurs during the encoding conversion process.
*/
public ISO8859EncodingFileReader(File file) throws IOException {
super(file, TARGET_FORMAT);
}
/**
* Constructs an ISO8859EncodingFileReader for reading a file with encoding conversion
* to the ISO-8859-15 format. This constructor accepts the file path as a string.
*
* @param filename the path to the file to be read
* @throws IOException if an I/O error occurs while accessing or reading the specified file
*/
public ISO8859EncodingFileReader(String filename) throws IOException {
super(filename, TARGET_FORMAT);
}

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

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

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.
*/
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.
*

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.
*/
public class ToneTable {
/**
* Private constructor to prevent instantiation of the utility class.
* This utility class is not meant to be instantiated, as it only provides
* static utility methods for array-related operations.
*
* @throws UnsupportedOperationException always, to indicate that this class
* should not be instantiated.
*/
private ToneTable() {
throw new UnsupportedOperationException("Utility class");
}
/**
* A static map that associates written tone names with their corresponding frequencies in hertz (Hz).
* The keys represent tone names (e.g., "C4", "D#5"), and the values are their respective frequencies.

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.
*/
@Slf4j
@RequiredArgsConstructor
public class Query<T> {
/**
@ -69,6 +68,15 @@ public class Query<T> {
*/
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.
*

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
* in the respective overridden method descriptions.
*/
@RequiredArgsConstructor
public class TrimmingResultSet implements ResultSet {
/**
@ -32,6 +31,15 @@ public class TrimmingResultSet implements 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.
* 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;
import java.util.Objects;
/**
* Utility Class with static methods about arrays.
* Utility class providing helper methods for working with arrays.
*/
public class ArrayUtils {
/**
* Checks if a given char is inside an array of chars.
* @param array Array of chars to seach in.
* @param ch Character to search.
* @return true if character was found, else false.
* Private constructor to prevent instantiation of the utility class.
* This utility class is not meant to be instantiated, as it only provides
* static utility methods for array-related operations.
*
* @throws UnsupportedOperationException always, to indicate that this class
* should not be instantiated.
*/
private ArrayUtils() {
throw new UnsupportedOperationException("Utility class");
}
/**
* Checks if the given character array contains the specified character.
*
* @param array the character array to be searched
* @param ch the character to search for in the array
* @return true if the character is found in the array, false otherwise
*/
public static boolean contains(char[] array, char ch) {
for(int index=0; index < array.length; index++) {
@ -17,4 +32,47 @@ public class ArrayUtils {
}
return false;
}
/**
* Checks if the specified integer array contains the given integer value.
*
* @param array the array of integers to search
* @param ch the integer value to search for in the array
* @return true if the array contains the specified integer value, false otherwise
*/
public static boolean contains(int[] array, int ch) {
for(int index=0; index < array.length; index++) {
if (array[index] == ch) return true;
}
return false;
}
/**
* Checks if the specified long array contains the given long value.
*
* @param array the array of long values to search
* @param ch the long value to search for in the array
* @return true if the array contains the specified long value, false otherwise
*/
public static boolean contains(long[] array, long ch) {
for(int index=0; index < array.length; index++) {
if (array[index] == ch) return true;
}
return false;
}
/**
* Checks if the specified array contains the given element.
*
* @param array the array to be searched
* @param ch the element to search for in the array
* @param <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;
/**
* Enumeration Utilities
* Utility class for working with Enum types, providing methods to parse and generate
* patterns for Enum flags.
*/
public class EnumUtil {
/**
* Creates a regular expression to match a comma separated list of Flags.
* @return Regular expression to match flags.
* Private constructor to prevent instantiation of the utility class.
* This utility class is not meant to be instantiated, as it only provides
* static utility methods for array-related operations.
*
* @throws UnsupportedOperationException always, to indicate that this class
* should not be instantiated.
*/
private EnumUtil() {
throw new UnsupportedOperationException("Utility class");
}
/**
* Generates a regular expression pattern that matches all possible case-insensitive representations
* of the enum constants within the specified Enum class. The pattern also includes optional delimiters
* such as commas, spaces, and empty values, enabling the matching of lists or sequences of flag values.
*
* @param <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) {
StringBuilder result = new StringBuilder();
@ -33,9 +51,21 @@ public class EnumUtil {
}
/**
* Parse a list of comma separated flags into a List of RequestFlags.
* @param flags String with comma separated flags.
* @return List of RequestFlags.
* Parses a delimited string containing Enum constant names into a list of Enum constants.
*
* This method takes an Enum class and a string of flags, splits the string by commas
* or whitespace, and converts each substring into an Enum constant of the given class.
* The flag names are case-insensitive and will be converted to uppercase before matching
* to the Enum constants.
*
* @param <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) {
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;
/**
* Utility Methods regarding files.
* Utility class for handling file operations, such as encoding checks, content reading/writing,
* path manipulations, and file conversions.
*/
@Slf4j
public class FileUtils {
/**
* Private constructor to prevent instantiation of the utility class.
* This utility class is not meant to be instantiated, as it only provides
* static utility methods for array-related operations.
*
* @throws UnsupportedOperationException always, to indicate that this class
* should not be instantiated.
*/
private FileUtils() {
throw new UnsupportedOperationException("Utility class");
}
/**
* Date/Time format to add to request files.
* Defines a standardized timestamp format for debugging purposes, specifically used for naming
* or identifying files with precise timestamps. The format is "yyyy-MM-dd_HH_mm_ss_SSS", which
* includes:
* - Year in four digits (yyyy)
* - Month in two digits (MM)
* - Day of the month in two digits (dd)
* - Hour in 24-hour format with two digits (HH)
* - Minutes in two digits (mm)
* - Seconds in two digits (ss)
* - Milliseconds in three digits (SSS)
*
* This ensures timestamps are sortable and easily identifiable.
*/
public static final SimpleDateFormat DEBUG_FILE_TIMESTAMP_FORMAT = new SimpleDateFormat("yyyy-MM-dd_HH_mm_ss_SSS");
/**
* Default encoding used to check the File
* Default encoding used for string checks and validations in the application.
*
* This constant represents the `ISO-8859-15` encoding, which is a standardized
* character set encoding, commonly used in contexts where backward compatibility
* with `ISO-8859-1` is required, but with support for certain additional characters,
* such as the euro currency symbol (€).
*/
public static final String DEFAULT_CHECK_ENCODING = "ISO-8859-15";
/**
* Default Buffer size.
* Specifies the default buffer size used for data processing operations.
*
* This constant represents the size of the buffer in bytes, set to 1024,
* and is typically utilized in input/output operations to optimize performance
* by reducing the number of read/write calls.
*/
public static final int BUFFER_SIZE = 1024;
/**
* Checks if a File is UTF-8 encoded.
* <p>
* This method checks a file for
* - first 3 bytes for UTF-8 BOM (0xEF 0xBB 0xBF)
* - Existence of 0xC2 / 0xC3 character.
* </p>
* @param file File to check.
* @param checkEncoding Encoding to use for the check, e.g. ISO-8859-15.
* @return true if an UTF-8 file is found, else false.
* @throws IOException IOException is thrown if the file could not be read.
* Determines whether the given file is encoded in UTF-8.
*
* @param file The file to be checked for UTF-8 encoding.
* @param checkEncoding The character encoding to use while checking the file content.
* @return true if the file is determined to be encoded in UTF-8; false otherwise.
* @throws IOException If an I/O error occurs while reading the file.
*/
public static boolean isUTF8(final File file, final String checkEncoding) throws IOException {
@ -69,15 +97,14 @@ public class FileUtils {
}
/**
* Checks if the File has a UTF-8 BOM.
* <p>
* This method checks a file for
* - first 3 bytes for UTF-8 BOM (0xEF 0xBB 0xBF)
* - Existence of 0xC2 / 0xC3 character.
* </p>
* @param file File to check.
* @return true if an UTF-8 BOM Header was found.
* @throws IOException IOException is thrown if the file could not be read.
* Checks if the provided file starts with a UTF-8 Byte Order Mark (BOM).
*
* This method reads the first character of the file using a reader that assumes
* UTF-8 encoding and checks if it matches the Unicode Byte Order Mark (U+FEFF).
*
* @param file The file to check for a UTF-8 BOM. Must not be null.
* @return true if the file starts with a UTF-8 BOM, false otherwise.
* @throws IOException If an input or output exception occurs while reading the file.
*/
public static boolean hasUTF8BOM(final File file) throws IOException {
try (InputStreamReader reader = new InputStreamReader(new FileInputStream(file), StandardCharsets.UTF_8)) {
@ -89,27 +116,27 @@ public class FileUtils {
}
/**
* Checks if a File is UTF-8 encoded.
* <p>
* This method checks a file for
* - first 3 bytes for UTF-8 BOM (0xEF 0xBB 0xBF)
* - Existence of 0xC2 / 0xC3 character.
* </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.
* Determines if the content of the given file is encoded in UTF-8.
*
* @param file The file to check for UTF-8 encoding. Must not be null.
* @return true if the file content is in UTF-8 encoding; false otherwise.
* @throws IOException If an I/O error occurs while reading the file.
*/
public static boolean isUTF8(final File file) throws IOException {
return isUTF8(file, DEFAULT_CHECK_ENCODING);
}
/**
* Converts the given Textfile inFile to the outFile using the given encodings.
* @param inFile File to read as UTF-8.
* @param sourceFormat Format of the source file.
* @param outFile File to write with ISO-8859-15 format.
* @param targetFormat Format of the target file.
* @throws IOException Thrown when files couldn't be read / written.
* Converts the content of a text file from one character encoding format to another.
*
* This method reads the input text file using the specified source encoding and writes
* the content to the output text file in the specified target encoding.
*
* @param inFile The input text file to be converted. Must not be null.
* @param sourceFormat The character encoding of the input file. Must not be null or empty.
* @param outFile The output text file to write the converted content to. Must not be null.
* @param targetFormat The character encoding to be used for the output file. Must not be null or empty.
* @throws IOException If an I/O error occurs during reading or writing.
*/
public static void convertTextFile(final File inFile, final String sourceFormat, final File outFile, final String targetFormat) throws IOException {
char[] buffer = new char[BUFFER_SIZE];
@ -142,48 +169,66 @@ public class FileUtils {
}
/**
* Creates a new InputStreamReader with the given format or UTF-8 if an UTF-8 file was recognized.
* @param filename Name of file to read.
* @return An InputStreamReader
* Creates a universal file reader for the specified file name.
* This method initializes and returns an InputStreamReader to read
* the content of the given file.
*
* @param filename The name or path of the file to be read.
* @return An InputStreamReader for reading the specified file.
* @throws IOException If an I/O error occurs while creating the file reader.
*/
public static InputStreamReader createUniversalFileReader(final String filename) throws IOException {
return createUniversalFileReader(new File(filename));
}
/**
* Creates a new InputStreamReader with the given format or UTF-8 if an UTF-8 file was recognized.
* @param filename Name of file to read.
* @param expectedFormat Expected format e.g. ISO-8859-15
* @return An InputStreamReader
* Creates a universal file reader for the specified file and format.
* The method resolves the file using its name and the expected format,
* returning an InputStreamReader for reading the file contents.
*
* @param filename the name of the file to be read.
* @param expectedFormat the format expected for the file content.
* @return an InputStreamReader for the specified file and format.
* @throws IOException if an I/O error occurs while opening or reading the file.
*/
public static InputStreamReader createUniversalFileReader(final String filename, final String expectedFormat) throws IOException {
return createUniversalFileReader(new File(filename), expectedFormat);
}
/**
* Creates a new InputStreamReader with the given format or UTF-8 if an UTF-8 file was recognized.
* @param file File to read.
* @return An InputStreamReader
* Creates a universal file reader for the specified file using the default encoding and configuration.
*
* @param file The file to be read. Must not be null.
* @return An InputStreamReader configured to read the specified file.
* @throws IOException If an I/O error occurs while creating the reader.
*/
public static InputStreamReader createUniversalFileReader(final File file) throws IOException {
return createUniversalFileReader(file, DEFAULT_CHECK_ENCODING, true);
}
/**
* Creates a new InputStreamReader with the given format or UTF-8 if an UTF-8 file was recognized.
* @param file File to read.
* @param expectedFormat Expected format e.g. ISO-8859-15
* @return An InputStreamReader
* Creates a universal file reader for the specified file with an expected format.
* This method wraps the given file in an InputStreamReader for consistent character stream manipulation.
*
* @param file The file to be read. Must not be null.
* @param expectedFormat The expected format of the file (e.g., encoding). Must not be null.
* @return An InputStreamReader for the specified file, allowing the caller to read the file
* with the desired format applied.
* @throws IOException If an I/O error occurs during the creation of the reader.
*/
public static InputStreamReader createUniversalFileReader(final File file, final String expectedFormat) throws IOException {
return createUniversalFileReader(file, expectedFormat, true);
}
/**
* Creates a new InputStreamReader with the given format or UTF-8 if an UTF-8 file was recognized.
* @param file File to read.
* @param expectedFormat Expected format e.g. ISO-8859-15
* @return An InputStreamReader
* Creates an InputStreamReader for reading a file, considering the specified encoding format
* and whether UTF-8 should be accepted. Handles potential BOM for UTF-8 encoded files.
*
* @param file The file to be read.
* @param expectedFormat The expected encoding format of the file.
* @param acceptUTF8 Indicates whether UTF-8 encoding should be accepted if detected.
* @return An InputStreamReader for the specified file and encoding.
* @throws IOException If there is an error accessing the file or reading its content.
*/
public static InputStreamReader createUniversalFileReader(final File file, final String expectedFormat, final boolean acceptUTF8) throws IOException {
String encoding = acceptUTF8 && isUTF8(file, expectedFormat)
@ -201,9 +246,13 @@ public class FileUtils {
}
/**
* Gets the parent directory of a file name.
* @param filename Name of file.
* @return Parent folder.
* Retrieves the parent directory of the given file or directory path.
*
* If the given path does not have a parent directory, it defaults to returning the
* current directory represented by ".".
*
* @param filename The file or directory path for which the parent directory is to be retrieved.
* @return The parent directory of the given path, or "." if no parent directory exists.
*/
public static String getParentDirectory(final String filename) {
File file = new File(filename);
@ -211,9 +260,10 @@ public class FileUtils {
}
/**
* Gets the core name of the file without path.
* @param filename Filename with path.
* @return Filename without path.
* Extracts the name of a file from the given file path.
*
* @param filename The full path or name of the file. Must not be null.
* @return The name of the file without any directory path.
*/
public static String getFilename(final String filename) {
File file = new File(filename);
@ -221,10 +271,11 @@ public class FileUtils {
}
/**
* Reads the content of a file (With the correct encoding!).
* @param filename Name of file to read.
* @return Content of the file or null in case of an error.
* @throws IOException Throes an IOException if the file cannot be read.
* Reads the content of a file and returns it as a string, joining all lines with the system line separator.
*
* @param filename The name of the file to be read.
* @return A string containing the content of the file with all lines joined by the system line separator.
* @throws IOException If an I/O error occurs while reading the file.
*/
public static String readFileContent(final String filename) throws IOException {
try (BufferedReader reader = new BufferedReader(createUniversalFileReader(filename))) {
@ -233,10 +284,11 @@ public class FileUtils {
}
/**
* Writes the content given to a file.
* @param path Path of the file to write.
* @param content Content to write.
* @throws IOException Thrown if the file could not be written.
* Writes the given content to the specified file path. If the file already exists, it will be overwritten.
*
* @param path The path of the file to write to. Must not be null and must be writable.
* @param content The content to be written to the file. Must not be null.
* @throws IOException If an I/O error occurs during writing to the file.
*/
public static void writeFile(final Path path, final String content) throws IOException {
try (BufferedWriter writer = new BufferedWriter(new FileWriter(path.toFile()))) {

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.ResourceBundle;
/**
* The RegionalizationMessage class provides functionality to retrieve
* localized messages from a resource bundle and format messages with parameters.
* It supports multiple constructors for initializing with specific locales if needed.
*/
public class RegionalizationMessage {
/**
* Resource Bundle to use for operations.
* The `res` variable holds a `ResourceBundle` instance,
* which is used to retrieve locale-specific objects and messages.
* It facilitates the process of internationalization by loading resources
* such as text and messages from specified bundles based on the provided locale.
*
* This variable is initialized in constructors of the `RegionalizationMessage` class
* and is used internally by various methods to fetch localized messages.
*/
private ResourceBundle res;
/**
* Creates a new instance of RegionalizationMessage.
* @param source Source of messages.
* Constructs a new RegionalizationMessage instance using the specified resource bundle source.
* This constructor initializes the resource bundle with the given source name.
*
* @param source The base name of the resource bundle to load.
* This is typically a fully qualified class name or package name for the resource.
*/
public RegionalizationMessage(final String source) {
res = ResourceBundle.getBundle(source);
}
/**
* Creates a new instance of RegionalizationMessage.
* @param source Source of messages.
* @param locale Locale to use.
* Constructs a RegionalizationMessage object to retrieve localized messages
* from a specified resource bundle using the given source and locale.
*
* @param source The base name of the resource bundle, a fully qualified class name.
* @param locale The Locale object specifying the desired language and region for localization.
*/
public RegionalizationMessage(final String source, final Locale locale) {
res = ResourceBundle.getBundle(source, locale);
}
/**
* Gets the Message behind a key.
* @param key Key to look up.
* @return Message or null.
* Retrieves the localized message corresponding to the specified key from the resource bundle.
* If the key does not exist in the resource bundle, this method returns null.
*
* @param key The key for which the localized message needs to be retrieved.
* @return The localized message as a String if the key exists in the resource bundle;
* otherwise, null.
*/
public String getMessage(final String key) {
if (!res.containsKey(key)) return null;
@ -39,10 +58,13 @@ public class RegionalizationMessage {
}
/**
* Gets the Message behind a key.
* @param key Key to look up.
* @param defaultMessage Default message to use if message is not available.
* @return Message from resource or default Message.
* Retrieves a localized message for the given key from the resource bundle.
* If the key is not found, the specified default message is returned.
*
* @param key The key to look up in the resource bundle.
* @param defaultMessage The default message to return if the key is not found.
* @return The localized message corresponding to the key, or the default message
* if the key does not exist in the resource bundle.
*/
public String getMessage(final String key, final String defaultMessage) {
if (res.containsKey(key))
@ -52,11 +74,14 @@ public class RegionalizationMessage {
}
/**
* Gets a formatted message.
* @param key key to look up message.
* @param defaultMessage Default message to use if message couldn't be loaded.
* @param params parameter to format the message.
* @return Formatted message.
* Retrieves a localized and formatted message from a resource bundle based on a key.
* If the key is not found in the resource bundle, a default message is used.
* The message supports parameter substitution using the supplied arguments.
*
* @param key The key used to retrieve the localized message from the resource bundle.
* @param defaultMessage The default message to be used if the key is not found in the resource bundle.
* @param params The parameters to substitute into the message placeholders.
* @return A formatted string containing the localized message with substituted parameters.
*/
public String getFormattedMessage(final String key, final String defaultMessage, final Object... params) {
MessageFormat format = new MessageFormat(getMessage(key, defaultMessage));

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

@ -5,25 +5,46 @@ import lombok.NonNull;
import java.util.Map;
/**
* Utility Methods for Strings
* Utility class providing common string manipulation methods.
*/
public class Strings {
/**
* Environment variables of the system.
* Private constructor to prevent instantiation of the utility class.
* This utility class is not meant to be instantiated, as it only provides
* static utility methods for array-related operations.
*
* @throws UnsupportedOperationException always, to indicate that this class
* should not be instantiated.
*/
private Strings() {
throw new UnsupportedOperationException("Utility class");
}
/**
* A map that holds the system's environment variables. The keys represent
* environment variable names, and the values represent their corresponding
* values. It is initialized with the current system environment variables using
* {@link System#getenv()}.
*
* This variable provides access to the underlying system environment, which can
* be used for various purposes such as configuration, path resolution, or
* dynamic value substitution.
*
* Note: Modifications to this map will not affect the system environment, as it
* is a copy of the environment at the time of initialization.
*/
private static Map<String, String> environmentVariables = System.getenv();
/**
* Expands environment Variables inside a string.
* <p>
* The environment variables should be given as ${variable}.
* </p>
* <p>
* Backslash inside variable values are replaced with slashes to avoid that they are seen as escape character.
* This makes the use for paths on windows possible but reduces the use with non paths in which you need a backslash.
* </p>
* @param text Test in which environment variables should be expanded.
* @return String with all environment variables expanded.
* Expands environment variable placeholders within the provided text.
* Placeholders in the format ${VARIABLE_NAME} are replaced with their
* corresponding values from the environment variables.
*
* @param text The input string containing environment variable placeholders.
* If null, the method returns null.
* @return A string with the placeholders replaced by their corresponding
* environment variable values. If no placeholders are found,
* the original string is returned.
*/
public static String expandEnvironmentVariables(String text) {
if (text == null) return null;
@ -36,18 +57,23 @@ public class Strings {
}
/**
* Checks if the given String is null or empty.
* @param string String to check.
* @return true if given String is null or empty.
* Checks whether a given string is either null or empty.
*
* @param string the string to be checked for nullity or emptiness.
* @return true if the string is null or has a length of 0; false otherwise.
*/
public static boolean isNullOrEmpty(final String string) {
return (string == null || string.length()==0);
}
/**
* Removes a leading / ending quote if there.
* @param value String to remove the quotes.
* @return Parameter string if it does not start / end with a quote, else string without leading/ending quote.
* Removes surrounding double quotes from the input string if they are present.
* Trims leading and trailing whitespaces from the input before processing.
*
* @param value The input string that might contain surrounding double quotes.
* The input cannot be null, and leading/trailing whitespaces will be ignored.
* @return A string with leading and trailing double quotes removed if present.
* Returns the original string if no surrounding double quotes are detected.
*/
public static String removeQuotes(final String value) {
String trimmedValue = value.trim();
@ -58,12 +84,15 @@ public class Strings {
}
/**
* Filters a given String and removes all illegal characters.
* @param value String value to filter all illegal characters from.
* @param illegalCharacters String with all Illegal Characters to filter out.
* @param replacement String to replace illegal characters with.
* @param combine Should multiple illegal characters that are together be replaced with one replacement string only?
* @return A new string where all illegal characters are replaced with the replacement string.
* Replaces illegal characters in a given string with a specified replacement string.
* Optionally, consecutive illegal characters can be combined into a single replacement.
*
* @param value The input string in which illegal characters are to be replaced.
* @param illegalCharacters A string specifying the set of illegal characters to be matched.
* @param replacement The string to replace each illegal character or group of characters.
* @param combine A boolean flag indicating whether consecutive illegal characters should be replaced
* with a single replacement string. If true, groups of illegal characters are combined.
* @return A new string with the illegal characters replaced by the provided replacement string.
*/
public static String replaceIllegalCharacters(final String value, final String illegalCharacters, final String replacement, final boolean combine) {
String replacementRegex = "[" + illegalCharacters + "]" + (combine ? "+" : "");
@ -71,15 +100,17 @@ public class Strings {
}
/**
* Filters a given String and removes all illegal characters.
* <p>
* All characters, that are not inside allowedCharacters, are illegal characters.
* </p>
* @param value String value to filter all illegal characters from.
* @param allowedCharacters String with all allowed Characters to filter out.
* @param replacement String to replace illegal characters with.
* @param combine Should multiple illegal characters that are together be replaced with one replacement string only?
* @return A new string where all illegal characters are replaced with the replacement string.
* Replaces characters in the input string that are not in the allowed characters set
* with a specified replacement string. Optionally combines consecutive non-allowed
* characters into a single replacement.
*
* @param value The input string to be processed.
* @param allowedCharacters A string containing the set of characters that are allowed.
* Any character not in this set will be replaced.
* @param replacement The string to replace non-allowed characters with.
* @param combine If true, consecutive non-allowed characters will be replaced with
* a single instance of the replacement string.
* @return A new string with non-allowed characters replaced according to the specified rules.
*/
public static String replaceNonAllowedCharacters(final String value, final String allowedCharacters, final String replacement, final boolean combine) {
String replacementRegex = "[^" + allowedCharacters + "]" + (combine ? "+" : "");
@ -87,9 +118,15 @@ public class Strings {
}
/**
* Gets the next Element which follows to the current element.
* @param element to get the precessor.
* @return The next element after this one.
* Increments a string value by modifying its last character, or leading characters if necessary.
* The increment follows these rules:
* - If the last character is a digit '9', it wraps to 'A'.
* - If the last character is 'Z', the preceding part of the string is recursively incremented, and '0' is appended.
* - If the string is empty, it returns "1".
* - For all other characters, increments the last character by one.
*
* @param element The string whose value is to be incremented. Must not be null.
* @return The incremented string value. If the input string is empty, returns "1".
*/
public static String increment(@NonNull final String element) {
if (element.isEmpty()) return "1";
@ -101,6 +138,17 @@ public class Strings {
return firstPart + (char)(lastChar+1);
}
/**
* Trims the input string to a specified maximum length, if necessary.
* If the input string's length is less than or equal to the specified max length,
* the string is returned unchanged. If the input string's length exceeds the max
* length, it is truncated to that length.
*
* @param original The original input string to be processed. If null, the method returns null.
* @param maxLength The maximum number of characters allowed in the resulting string.
* @return The original string if its length is less than or equal to maxLength,
* otherwise a truncated version of the string up to maxLength characters.
*/
public static String limitCharNumber(final String original, final int maxLength) {
if (original == null || original.length() <= maxLength) return original;

118
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;
/**
* Converter with helper functions to format XML.
* Utility class for handling common XML operations such as creating XML elements,
* formatting XML strings, and validating XML content.
*/
@Slf4j
public class XmlUtils {
public class XmlUtils {
/**
* Private constructor to prevent instantiation of the utility class.
* This utility class is not meant to be instantiated, as it only provides
* static utility methods for array-related operations.
*
* @throws UnsupportedOperationException always, to indicate that this class
* should not be instantiated.
*/
private XmlUtils() {
throw new UnsupportedOperationException("Utility class");
}
/**
* DateTimeFormatter instance to format a date for XML use (xs:date type).
* A {@link DateTimeFormatter} instance used for formatting or parsing dates in the "yyyy-MM-dd" pattern.
*
* This formatter adheres to the XML date format standard (ISO-8601). It can be used
* to ensure consistent date representations in XML or other similar text-based formats.
*
* Thread-safe and immutable, this formatter can be shared across multiple threads.
*/
public static final DateTimeFormatter XML_DATE_FORMATTER = DateTimeFormatter.ofPattern("yyyy-MM-dd");
/**
* Creates a new XML element to be used inside a document.
* Creates a new element in the provided XML document with the specified name.
*
* @param doc XML Document to use.
* @param name Name of the Element.
* @return Created Element.
* @param doc The XML document in which the new element is to be created. Must not be null.
* @param name The name of the element to be created. Must not be null or empty.
* @return The newly created element with the given name. Never returns null.
*/
public static Element createElement(final Document doc, final String name) {
log.debug("Creating a new element " + name);
@ -44,12 +61,14 @@ public class XmlUtils {
}
/**
* Creates a new XML element with text value to be used inside a document.
* Creates a new XML element with the specified name and value, appends the value
* as a text node to the element, and returns the resulting element.
*
* @param doc XML Document to use.
* @param name Name of the Element.
* @param value Value of the Text Node.
* @return Created Element.
* @param doc the XML document to which the element belongs. Must not be null.
* @param name the name of the element to create. Must not be null.
* @param value the text value to be set as the content of the created element.
* If null, an empty string will be used as the content.
* @return the newly created XML element containing the specified value as a text node.
*/
public static Element createElement(final Document doc, final String name, final String value) {
log.debug("Creating a new element " + name + " with value: " + value);
@ -62,24 +81,26 @@ public class XmlUtils {
}
/**
* Creates a new XML element with date value to be used inside a document.
* Creates an XML element with the specified name and value, formatted as a date string.
* The date value is converted to an XML-compatible string format using a predefined formatter.
*
* @param doc XML Document to use.
* @param name Name of the Element.
* @param value Date to insert into node.
* @return Created Element.
* @param doc the XML document to which the element belongs; must not be null
* @param name the name of the element to be created; must not be null or empty
* @param value the date value to be assigned to the created element; must not be null
* @return the created XML element containing the specified name and formatted date value
*/
public static Element createElement(final Document doc, final String name, final Date value) {
return createElement(doc, name, XML_DATE_FORMATTER.format(value.toInstant()));
}
/**
* Creates a new XML element with integer value to be used inside a document.
* Creates an XML element with the specified name and optional value.
*
* @param doc XML Document to use.
* @param name Name of the Element.
* @param value Value of the Integer Node.
* @return Created Element.
* @param doc The Document object to which the element will belong. Must not be null.
* @param name The name of the element to be created. Must not be null or empty.
* @param value The optional value to be set as the text content of the element. If null,
* the element will have an empty text content.
* @return The newly created Element object with the specified name and value.
*/
public static Element createElement(final Document doc, final String name, final Integer value) {
log.debug("Creating a new element " + name + " with value: " + value);
@ -92,12 +113,13 @@ public class XmlUtils {
}
/**
* Creates a new XML element to be used inside a document and adds it to the parent.
* Creates a new element with the specified name, appends it to the provided parent element,
* and returns the newly created element.
*
* @param doc XML Document to use.
* @param name Name of the Element.
* @param parent Parent for the Element.
* @return Created Element.
* @param doc The Document to which the new element belongs. Must not be null.
* @param name The name of the new element to be created. Must not be null or empty.
* @param parent The parent element to which the new element will be appended. Must not be null.
* @return The newly created and appended Element object.
*/
public static Element createAndInsertElement(final Document doc, final String name, @NonNull final Element parent) {
log.debug("Creating a new element " + name + " and adding it to a parent.");
@ -107,12 +129,14 @@ public class XmlUtils {
}
/**
* Creates a new XML element with text value And adds it to the parent.
* Creates a new XML element with a specified name and value, adds it to the specified parent element,
* and returns the created element.
*
* @param name Name of the Element.
* @param value Value of the Text Node.
* @param parent Parent for the Element.
* @return Created Element.
* @param doc The XML document to which the new element belongs. Must not be null.
* @param name The name of the element to create. Must not be null.
* @param value The value to be set for the created element. Can be null if no value is required.
* @param parent The parent element to which the new element will be appended. Must not be null.
* @return The newly created and inserted element.
*/
public static Element createAndInsertElement(final Document doc, final String name, final String value, @NonNull final Element parent) {
log.debug("Creating a new element " + name + " with value: " + value + " and adding it to a parent.");
@ -123,10 +147,14 @@ public class XmlUtils {
/**
* Formats the XML from a given String with XML content.
* 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.
* @return Formated XML content or original content in case of an error.
* @param xmlStream The raw XML string to be formatted. Cannot be null.
* @return The formatted XML string with proper indentation. If an exception occurs
* during formatting, the original XML string is returned.
*/
public static String format(final String xmlStream) {
log.debug("formatXML");
@ -153,10 +181,13 @@ public class XmlUtils {
}
/**
* Formats the XML from a given XML Document.
* Formats a given XML Document into a human-readable string representation.
* The method applies indentation and specific output properties to the XML content.
* If an exception occurs during the transformation process, it logs the error
* and returns null.
*
* @param doc XML Document to format.
* @return Formated XML content.
* @param doc The XML Document to be formatted. Must not be null.
* @return A formatted string representation of the XML document, or null if an error occurs during processing.
*/
public static String format(final Document doc) {
try {
@ -184,9 +215,14 @@ public class XmlUtils {
}
/**
* Checks if the given xml string is valid XML
* @param xml XML String.
* @return true if xml is valid.
* Validates whether a given XML string is well-formed.
* This method attempts to parse the input XML string and checks
* if it can successfully create a valid DOM object from it.
*
* @param xml The XML string to be validated. Must not be null.
* If null or invalid, the method will return false.
* @return true if the XML string is well-formed and can be successfully parsed;
* false otherwise, such as in the case of invalid content or parsing errors.
*/
public static boolean checkXml(final String xml) {
try {

156
fx-example/pom.xml
View File

@ -43,160 +43,4 @@
</plugin>
</plugins>
</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>

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

@ -6,40 +6,53 @@ import java.io.File;
import java.net.URISyntaxException;
/**
* Adds Utility Methods for log4j.
* Utility class for managing Log4j configurations. Provides methods to set up
* Log4j configurations from default files, resources, or command line arguments.
*/
public class Log4jUtils {
/**
* Default Logfile that should be read.
* Must be a relative path that is checked from the current directory and also from the location of the jar file.
* The default path to the Log4j configuration file.
* This variable is used to specify the local file path for the Log4j configuration
* when no custom configuration is provided.
*/
public static final String DEFAULT_LOG4J_LOGFILE = "./log4j.properties";
/**
* Resource to use when no file is found.
* The default resource path to the Log4j configuration file included in the classpath.
* This path is used as a fallback when no other Log4j configuration is explicitly set.
*/
public static final String DEFAULT_LOG4J_RESOURCE = "/log4j.default.properties";
/**
* Checks if a log4j config file was set on command line with -Dlog4j.configuration
* @return true if log4j.configuration was set.
* Checks if the system property "log4j.configuration" is set.
*
* @return true if the "log4j.configuration" property is defined, false otherwise.
*/
public static boolean isLog4jConfigFileSet() {
return System.getProperty("log4j.configuration") != null;
}
/**
* Uses the default configurations if no config file was set.
* Configures Log4j using default configuration settings.
* This method leverages a default configuration file path and a default resource path
* to set up Log4j logging if a configuration file is not already specified via
* a system property. If a valid configuration file or resource is found, it will be applied.
*
* Delegates to the overloaded {@code setLog4jConfiguration(String log4jConfigFile, String defaultResource)}
* method using predefined defaults.
*/
public static void setLog4jConfiguration() {
setLog4jConfiguration(DEFAULT_LOG4J_LOGFILE, DEFAULT_LOG4J_RESOURCE);
}
/**
* Gets the file with path relative to the jar file.
* @param log4jConfigFile log4j config file.
* @return Path if possible or null.
* Constructs the absolute path to the specified Log4j configuration file located
* in the same directory as the JAR file of the application.
*
* @param log4jConfigFile The name of the Log4j configuration file.
* @return The absolute path to the specified Log4j configuration file if the
* path is successfully constructed; otherwise, returns null in case of an error.
*/
public static String getLog4jLogfileAtJar(final String log4jConfigFile) {
try {
@ -50,13 +63,13 @@ public class Log4jUtils {
}
/**
* Uses the default configurations if no config file was set.
* <p>
* A log4j configuration can be set using -Dlog4j.configuration. If no configuration was set,
* we look for the log4jConfigFile. If it does not exist, we read the defaultResource.
* </p>
* @param log4jConfigFile Default file to look for.
* @param defaultResource Resource path to use if config file wasn't found.
* Sets the Log4j configuration using the specified configuration file or a default resource
* if the configuration file is not found. If a Log4j configuration is already set, the method
* does nothing.
*
* @param log4jConfigFile the path to the Log4j configuration file to be used.
* @param defaultResource the fallback resource to be used as the configuration if the file
* is not found or accessible.
*/
public static void setLog4jConfiguration(final String log4jConfigFile, final String defaultResource) {
if (isLog4jConfigFileSet()) return;

15
pom.xml
View File

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