Holger's Java API

## com.antelmann
Class Settings

    java.lang.Object
      com.antelmann.Settings

    public final class Settings

extends Object

Settings provides access to several properties and resources that are used throughout the classes of this Antelmann.com framework.

The default settings are loaded from a well known location which denotes a file that is commonly distributed along with the antelmann.jar file. The default settings can be overwritten by simply altering the Properties returned by `getProperties()`, where a subsequent call to that method will reflect the changes (similar to `System.getProperties()`.

If the Settings are used in special environments (such as within an application server), you may need to manually use the `setClassLoader(ClassLoader)` method to specify a ClassLoader appropriate for the given context, before accessing any resources.

Since:
  3/24/2002
Author:
  Holger Antelmann

Field Summary
`static String` `CURRENT_DIRECTORY` denotes the property key used to keep track of the current directory that file dialogs should use
`static String` `DEFAULT_PROPERTY_FILE` denotes the relative location of the file for the default Properties, so that it can be found through the `ClassLoader`

Method Summary
`static void` `checkLicense(Object licensee)` calls `checkLicense(licensee, null)`
`static void` `checkLicense(Object licensee, Component c)` checks whether there is a valid license installed for accessing the given object - a convenience method normally used by an application to check whether access to an object is licensed.
`static Properties` `extractOptions(String[] args)` based on option key '-'; useful for command line options
`static String[]` `getAllValuesForProperty(String prefix)`
`static ClassLoader` `getClassLoader()` returns the ClassLoader currently used to locate resources
`static File` `getCurrentDirectory()` provides a current working directory that may be altered and may be null
`static LicenseHandler` `getLicenseHandler()` returns the LicenseHandler currently in place to react if a call to checkLicense(Object) fails initially.
`static Number` `getNumber(String key, Filter<? super Number> filter, Number defaultValue)`
`static Number` `getNumber(String key, Number defaultValue)`
`static Properties` `getOnlineProperties()` returns a fresh set of default Properties directly from the Antelmann.com website
`static Properties` `getProperties()` This method returns the current application properties; changes to the Properties will be reflected in subsequent calls to this method.
`static String` `getProperty(String key)` provides a shortcut for `getProperties().getPropterty(key)`
`static String` `getProperty(String key, String defaultValue)` This method will try to find the value for the given key and return it - or return the defaultValue if the property was not found or the default property file could not be opened
`static URL` `getResource(String resource)` This method encapsulates calls to the embedded ClassLoader to ease dealing with problems when not finding the resource.
`static void` `init(Properties newProperties)` initializes the properties to be used by Settings; all previously set properties are lost
`static void` `installLicense(License l)` installs the given license to the LicenseManager - a convenience method.
`static boolean` `isTrue(String key)`
`static boolean` `isValueTrue(Object value)`
`static void` `load(File fileProperties)` first, this method tries to initialize with the default properties, but even if that fails, the properties are loaded from the given location.
`static void` `load(Properties additionalProperties)` first, this method tries to initialize with the default properties, but even if that fails, the given properties are loaded into the current ones.
`static void` `load(URL urlProperties)` first, this method tries to initialize with the default properties, but even if that fails, the properties are loaded from the given location.
`static Properties` `loadCascadingBasedOnFileNameProperty(File file, String fileProperty)` the returned Properties are not automatically loaded into the properties of Settings
`static Object` `removeProperty(String key)`
`static void` `setClassLoader(ClassLoader cl)` sets the ClassLoader to be used in `getResource(String)`; by default, the ClassLoader of this Settings class is used
`static void` `setContextClassLoader()`
`static void` `setCurrentDirectory(File dir)` allows to alter the current working directory used in `getCurrentDirectory()`
`static void` `setLicenseHandler(LicenseHandler handler)` allows to react on failed license-checks by establishing a proper handler
`static Object` `setProperty(String key, String value)` sets a property within these settings
`static void` `setSystemClassLoader()` sets the class loader to be used to the system class loader

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### DEFAULT_PROPERTY_FILE

    public static final String DEFAULT_PROPERTY_FILE

  denotes the relative location of the file for the default Properties, so that it can be found through the `ClassLoader`

  See Also:
    Constant Field Values

### CURRENT_DIRECTORY

    public static final String CURRENT_DIRECTORY

  denotes the property key used to keep track of the current directory that file dialogs should use

  See Also:
    Constant Field Values

Method Detail

### getCurrentDirectory

    public static File getCurrentDirectory()

  provides a current working directory that may be altered and may be null

### setCurrentDirectory

    public static void setCurrentDirectory(File dir)

  allows to alter the current working directory used in `getCurrentDirectory()`

### setLicenseHandler

    public static void setLicenseHandler(LicenseHandler handler)

  allows to react on failed license-checks by establishing a proper handler

  See Also:
    `getLicenseHandler()`, `checkLicense(Object)`

### getLicenseHandler

    public static LicenseHandler getLicenseHandler()

  returns the LicenseHandler currently in place to react if a call to checkLicense(Object) fails initially.

  See Also:
    `checkLicense(Object)`, `setLicenseHandler(LicenseHandler)`

### checkLicense

    public static void checkLicense(Object licensee)
                             throws SecurityException

  calls `checkLicense(licensee, null)`

  Throws:
    `SecurityException`
  See Also:
    `checkLicense(Object, Component)`

### checkLicense

    public static void checkLicense(Object licensee,
                                    Component c)
                             throws SecurityException

  checks whether there is a valid license installed for accessing the given object - a convenience method normally used by an application to check whether access to an object is licensed. The method will only return normally if a valid license is available for the given licensee.

  By establishing a LicenseHandler, this method - in the event of the license check initially failing - will not immediately fail by throwing an exception, but will first try to e.g. obtain or renew a license through a call to the LicenseHander. After the LicenseHandler was called, the method will once again check with the LicenseManager, whether a valid license is present.

  Parameters:
    `licensee` - any object for wich a license is to be checked
    `c` - the parent component from where this call occurs (may be null). This component (if present) can be used by the LicenseHandler to show dialogs on top of the given component.
  Throws:
    `SecurityException` - if the license check failed; the exception cause will be a LicensingException
  See Also:
    `setLicenseHandler(LicenseHandler)`, `LicenseHandler`, `License`, `LicenseManager`, `LicensingException`

### installLicense

    public static void installLicense(License l)
                               throws SecurityException

  installs the given license to the LicenseManager - a convenience method.

  Throws:
    `SecurityException` - if the licenses could not be verified. The embedded cause will be a LicensingException
  See Also:
    `License`, `LicenseManager`, `LicensingException`

### setClassLoader

    public static void setClassLoader(ClassLoader cl)

  sets the ClassLoader to be used in `getResource(String)`; by default, the ClassLoader of this Settings class is used

  See Also:
    `getResource(String)`

### setSystemClassLoader

    public static void setSystemClassLoader()

  sets the class loader to be used to the system class loader

### setContextClassLoader

    public static void setContextClassLoader()

### getClassLoader

    public static ClassLoader getClassLoader()

  returns the ClassLoader currently used to locate resources

  See Also:
    `setClassLoader(ClassLoader)`

### getResource

    public static URL getResource(String resource)
                           throws ResourceNotFoundException

  This method encapsulates calls to the embedded ClassLoader to ease dealing with problems when not finding the resource. Instead of just returning null if a resource is not found, an exception is thrown (which is particularly helpful for image loading in swing). If you are working in special environments where the system class loader may not find the resource you are looking for, you need to set the class loader of this class to the one you need.

  Throws:
    `ResourceNotFoundException` - if the given resource could not be found
  See Also:
    `setClassLoader(ClassLoader)`

### init

    public static void init(Properties newProperties)

  initializes the properties to be used by Settings; all previously set properties are lost

### isTrue

    public static boolean isTrue(String key)

### isValueTrue

    public static boolean isValueTrue(Object value)

### getNumber

    public static Number getNumber(String key,
                                   Number defaultValue)

### getNumber

    public static Number getNumber(String key,
                                   Filter<? super Number> filter,
                                   Number defaultValue)

### getProperty

    public static String getProperty(String key,
                                     String defaultValue)

  This method will try to find the value for the given key and return it - or return the defaultValue if the property was not found or the default property file could not be opened

### getProperty

    public static String getProperty(String key)
                              throws ResourceNotFoundException

  provides a shortcut for `getProperties().getPropterty(key)`

  Throws:
    `ResourceNotFoundException` - if the property file could not be located
  See Also:
    `getProperties()`

### setProperty

    public static Object setProperty(String key,
                                     String value)

  sets a property within these settings

### removeProperty

    public static Object removeProperty(String key)

### getAllValuesForProperty

    public static String[] getAllValuesForProperty(String prefix)

### getProperties

    public static Properties getProperties()
                                    throws ResourceNotFoundException

  This method returns the current application properties; changes to the Properties will be reflected in subsequent calls to this method.

  Throws:
    `ResourceNotFoundException` - if the property file could not be located

### loadCascadingBasedOnFileNameProperty

    public static Properties loadCascadingBasedOnFileNameProperty(File file,
                                                                  String fileProperty)
                                                           throws IOException

  the returned Properties are not automatically loaded into the properties of Settings

  Throws:
    `IOException`

### load

    public static void load(File fileProperties)
                     throws IOException

  first, this method tries to initialize with the default properties, but even if that fails, the properties are loaded from the given location.

  Throws:
    `IOException`

### load

    public static void load(URL urlProperties)
                     throws IOException

  first, this method tries to initialize with the default properties, but even if that fails, the properties are loaded from the given location.

  Throws:
    `IOException`

### load

    public static void load(Properties additionalProperties)
                     throws IOException

  first, this method tries to initialize with the default properties, but even if that fails, the given properties are loaded into the current ones.

  Throws:
    `IOException`

### extractOptions

    public static Properties extractOptions(String[] args)

  based on option key '-'; useful for command line options

### getOnlineProperties

    public static Properties getOnlineProperties()

  returns a fresh set of default Properties directly from the Antelmann.com website

(c) Holger Antelmann since 2001- all rights reserved (contact: info@antelmann.com)
see www.antelmann.com/developer for further details and available downloads