org.refcodes.configuration.ext.runtime.RuntimePropertiesSugar Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of refcodes-configuration-ext-runtime Show documentation
Show all versions of refcodes-configuration-ext-runtime Show documentation
Artefact for providing predefined configuration compositions common for
everyday application setups.
// /////////////////////////////////////////////////////////////////////////////
// REFCODES.ORG
// /////////////////////////////////////////////////////////////////////////////
// This code is copyright (c) by Siegfried Steiner, Munich, Germany and licensed
// under the following (see "http://en.wikipedia.org/wiki/Multi-licensing")
// licenses:
// -----------------------------------------------------------------------------
// GNU General Public License, v3.0 ("http://www.gnu.org/licenses/gpl-3.0.html")
// -----------------------------------------------------------------------------
// Apache License, v2.0 ("http://www.apache.org/licenses/LICENSE-2.0")
// -----------------------------------------------------------------------------
// Please contact the copyright holding author(s) of the software artifacts in
// question for licensing issues not being covered by the above listed licenses,
// also regarding commercial licensing models or regarding the compatibility
// with other open source licenses.
// /////////////////////////////////////////////////////////////////////////////
package org.refcodes.configuration.ext.runtime;
import java.io.File;
import java.io.IOException;
import java.io.InputStream;
import java.net.URL;
import java.text.ParseException;
import org.refcodes.configuration.Properties;
import org.refcodes.configuration.PropertiesSugar;
import org.refcodes.console.AmbiguousArgsException;
import org.refcodes.console.Condition;
import org.refcodes.console.ParseArgsException;
import org.refcodes.console.SuperfluousArgsException;
import org.refcodes.console.UnknownArgsException;
import org.refcodes.runtime.ConfigLocator;
import org.refcodes.runtime.SystemContext;
/**
* Declarative syntactic sugar which may be statically imported in order to
* allow declarative definitions for the construction of
* {@link RuntimeProperties} (and the like).
*/
public class RuntimePropertiesSugar extends PropertiesSugar {
// /////////////////////////////////////////////////////////////////////////
// STATICS:
// /////////////////////////////////////////////////////////////////////////
// /////////////////////////////////////////////////////////////////////////
// CONSTANTS:
// /////////////////////////////////////////////////////////////////////////
// /////////////////////////////////////////////////////////////////////////
// VARIABLES:
// /////////////////////////////////////////////////////////////////////////
// /////////////////////////////////////////////////////////////////////////
// CONSTRUCTORS:
// /////////////////////////////////////////////////////////////////////////
// /////////////////////////////////////////////////////////////////////////
// INJECTION:
// /////////////////////////////////////////////////////////////////////////
// /////////////////////////////////////////////////////////////////////////
// METHODS:
// /////////////////////////////////////////////////////////////////////////
// /////////////////////////////////////////////////////////////////////////
// JAVA PROPERTIES:
// /////////////////////////////////////////////////////////////////////////
/**
* Factory method to conveniently create a pre-configured
* {@link RuntimeProperties} instance. Constructs a
* {@link RuntimeProperties} instance with no {@link Condition} for parsing
* command line arguments. As no syntax notation is required by the
* constructor (no root {@link Condition}), no syntax validation is done.
* Therefore the properties are heuristically determined from the provided
* command line arguments when invoking {@link #withArgs(String[])}.
*
* @return The accordingly constructed {@link RuntimeProperties} instance.
*/
public static RuntimeProperties fromRuntimeProperties() {
return new RuntimePropertiesImpl();
}
/**
* Factory method to conveniently create a pre-configured
* {@link RuntimeProperties} instance. Constructs a
* {@link RuntimeProperties} instance with no {@link Condition} for parsing
* command line arguments: As no syntax notation is required by the
* constructor (no root {@link Condition}), no syntax validation is done.
* Therefore the properties are heuristically determined from the provided
* command line arguments.
*
* @param aArgs The command line arguments to be evaluated.
*
* @return The accordingly constructed {@link RuntimeProperties} instance.
*/
public static RuntimeProperties withArgs( String[] aArgs ) {
return new RuntimePropertiesImpl( aArgs );
}
/**
* Factory method to conveniently create a pre-configured
* {@link RuntimeProperties} instance. Constructs a
* {@link RuntimeProperties} instance with the given {@link Condition}
* representing the syntax to be used to parse command line arguments.
* Provide command line arguments via
* {@link RuntimeProperties#evalArgs(String[])} (and the like methods).
*
* @param aRootCondition The root condition being the node from which
* parsing the command line arguments starts. Parse the command line
* arguments via {@link RuntimeProperties#evalArgs(String[])}.
*
* @return The accordingly constructed {@link RuntimeProperties} instance.
*/
public static RuntimeProperties withRootCondition( Condition aRootCondition ) {
return new RuntimePropertiesImpl( aRootCondition );
}
/**
* Factory method to conveniently create a pre-configured
* {@link RuntimeProperties} instance. Constructs the
* {@link RuntimeProperties} with the given obfuscation mode
*
* @param aMode The {@link SystemContext} specifies which level of
* obfuscation is to be used when encountering upon obfuscated
* properties: E.g. obfuscation may be bound to the host, the
* "secret" used for obfuscation being the same for all applications
* on the same host or obfuscation may be bound to the application,
* being different for different applications on the same host.
*
* @return The accordingly constructed {@link RuntimeProperties} instance.
*/
public static RuntimeProperties withObfuscationMode( SystemContext aMode ) {
return new RuntimePropertiesImpl( aMode );
}
/**
* Factory method to conveniently create a pre-configured
* {@link RuntimeProperties} instance. Constructs a
* {@link RuntimeProperties} instance with a custom secret for obfuscation.
*
* @param aSecret The secret to be used when encountering upon obfuscated
* properties.
*
* @return The accordingly constructed {@link RuntimeProperties} instance.
*/
public static RuntimeProperties withSecret( String aSecret ) {
return new RuntimePropertiesImpl( aSecret );
}
/**
* Factory method to conveniently create a pre-configured
* {@link RuntimeProperties} instance. Loads a properties file from the file
* directly or (if not found) from first folder containing such a file as of
* the specification for the method {@link ConfigLocator#getFolders()}.
*
* @param aFile The file of the properties to load.
*
* @return The {@link RuntimeProperties} instance as of the builder pattern
* for chained method calls.
*
* @throws IOException thrown in case accessing or processing the properties
* file failed.
*
* @throws ParseException Signals that an error has been reached
* unexpectedly while parsing the data to be loaded.
*/
public static RuntimeProperties withFile( File aFile ) throws IOException, ParseException {
return fromRuntimeProperties().withFile( aFile );
}
/**
* Factory method to conveniently create a pre-configured
* {@link RuntimeProperties} instance. Reads the properties from the given
* {@link InputStream}.
*
* @param aInputStream The {@link InputStream} from which to read the
* properties.
*
* @return The {@link RuntimeProperties} instance as of the builder pattern
* for chained method calls.
*
* @throws IOException thrown in case accessing or processing the properties
* file failed.
*
* @throws ParseException Signals that an error has been reached
* unexpectedly while parsing the data to be loaded.
*/
public static RuntimeProperties withInputStream( InputStream aInputStream ) throws IOException, ParseException {
return fromRuntimeProperties().withInputStream( aInputStream );
}
/**
* Factory method to conveniently create a pre-configured
* {@link RuntimeProperties} instance. Loads a properties file from the file
* directly or (if not found) from first folder containing such a file as of
* the specification for the method {@link ConfigLocator#getFolders()}.
*
* @param aFilePath The file of the properties file to load.
*
* @return The {@link RuntimeProperties} instance as of the builder pattern
* for chained method calls.
*
* @throws IOException thrown in case accessing or processing the properties
* file failed.
*
* @throws ParseException Signals that an error has been reached
* unexpectedly while parsing the data to be loaded.
*/
public static RuntimeProperties withFilePath( String aFilePath ) throws IOException, ParseException {
return fromRuntimeProperties().withFilePath( aFilePath );
}
/**
* Factory method to conveniently create a pre-configured
* {@link RuntimeProperties} instance. Loads the properties from the given
* {@link URL}.
*
* @param aUrl The {@link URL} from which to read the properties.
*
* @return The {@link RuntimeProperties} instance as of the builder pattern
* for chained method calls.
*
* @throws IOException thrown in case accessing or processing the properties
* file failed.
*
* @throws ParseException Signals that an error has been reached
* unexpectedly while parsing the data to be loaded.
*/
public static RuntimeProperties withUrl( URL aUrl ) throws IOException, ParseException {
return fromRuntimeProperties().withUrl( aUrl );
}
/**
* Factory method to conveniently create a pre-configured
* {@link RuntimeProperties} instance. Evaluates the provided command line
* arguments and adds them with their according properties representation
*
* @param aArgs The command line arguments to be evaluated.
*
* @return The {@link RuntimeProperties} instance of the builder pattern to
* chain further method calls.
*
* @throws UnknownArgsException Thrown in case not one command line argument
* matched regarding the provided args vs. the expected args.
* @throws AmbiguousArgsException Thrown in case at least one command line
* argument is ambiguous regarding expected args vs. provided args.
* @throws SuperfluousArgsException Thrown in case there were arguments
* found not being used (superfluous arguments).
* @throws ParseArgsException Thrown in case the provided command line
* arguments do not respect the required syntax or cannot be
* converted to the required type
*/
public static RuntimeProperties withParseArgs( String[] aArgs ) throws UnknownArgsException, AmbiguousArgsException, SuperfluousArgsException, ParseArgsException {
return fromRuntimeProperties().withParseArgs( aArgs );
}
/**
* Factory method to conveniently create a pre-configured
* {@link RuntimeProperties} instance. A hook for you to provide
* {@link Properties} programmatically. The later you add
* {@link Properties}, the lower their precedence.
*
* @param aProperties The {@link Properties} to be added.
*
* @return The {@link RuntimeProperties} instance of the builder pattern to
* chain further method calls.
*/
public static RuntimeProperties withProperties( Properties aProperties ) {
return fromRuntimeProperties().withProperties( aProperties );
}
// /////////////////////////////////////////////////////////////////////////
// HOOKS:
// /////////////////////////////////////////////////////////////////////////
// /////////////////////////////////////////////////////////////////////////
// HELPER:
// /////////////////////////////////////////////////////////////////////////
// /////////////////////////////////////////////////////////////////////////
// INNER CLASSES:
// /////////////////////////////////////////////////////////////////////////
}