Package org.apache.juneau.config

Class Config

java.lang.Object
org.apache.juneau.Context
org.apache.juneau.config.Config
All Implemented Interfaces:
ConfigEventListener
public class Config extends Context implements ConfigEventListener
Main configuration API class.
Notes:
  • This class is thread safe and reusable.
See Also:

  • Field Details

  • Constructor Details

  • Method Details

    • create

      public static Config.Builder create()
      Creates a new builder for this object.
      Returns:
      A new builder.

    • create

      public static Config.Builder create(String name)
      Same as create() but initializes the builder with the specified config name.
      Parameters:
      name - The configuration name.
      Returns:
      A new builder.

    • getCandidateSystemDefaultConfigNames

      public static List<String> getCandidateSystemDefaultConfigNames()
      Returns the list of candidate system default configuration file names.

      If the "juneau.configFile" system property is set, returns a singleton of that value.
      Otherwise, returns a list consisting of the following values:

      1. File with same name as jar file but with ".cfg" extension. (e.g. "myjar.cfg")
      2. Any file ending in ".cfg" in the home directory (names ordered alphabetically).
      3. "juneau.cfg"
      4. "default.cfg"
      5. "application.cfg"
      6. "app.cfg"
      7. "settings.cfg"
      8. "application.properties"

      Returns:
      A list of candidate file names.
      The returned list is modifiable.
      Each call constructs a new list.

    • getSystemDefault

      public static Config getSystemDefault()
      Returns the system default configuration.
      Returns:
      The system default configuration, or null if it doesn't exist.

    • setSystemDefault

      public static void setSystemDefault(Config systemDefault)
      Sets a system default configuration.
      Parameters:
      systemDefault - The new system default configuration.

    • addListener

      public Config addListener(ConfigEventListener listener)
      Add a listener to this config to react to modification events.

      Listeners should be removed using removeListener(ConfigEventListener).

      Parameters:
      listener - The new listener to add.
      Returns:
      This object.

    • applyMods

      public Config applyMods()
      Encodes and unencoded entries in this config.

      If any entries in the config are marked as encoded but not actually encoded, this will encode them.

      Returns:
      This object.
      Throws:
      UnsupportedOperationException - If configuration is read only.

    • close

      public void close()
      Closes this configuration object by unregistering it from the underlying config map.

    • commit

      public Config commit() throws IOException
      Commit the changes in this config to the store.
      Returns:
      This object.
      Throws:
      IOException - Thrown by underlying stream.
      UnsupportedOperationException - If configuration is read only.

    • copy

      public Config.Builder copy()
      Description copied from class: Context
      Creates a builder from this context object.

      Builders are used to define new contexts (e.g. serializers, parsers) based on existing configurations.

      Overrides:
      copy in class Context
      Returns:
      A new Builder object.

    • exists

      public boolean exists(String key)
      Returns true if this section contains the specified key and the key has a non-blank value.
      Parameters:
      key - The key.
      Returns:
      true if this section contains the specified key and the key has a non-blank value.

    • get

      public Entry get(String key)
      Gets the entry with the specified key.

      The key can be in one of the following formats...

      • "key" - A value in the default section (i.e. defined above any [section] header).
      • "section/key" - A value from the specified section.

      If entry does not exist, returns an empty Entry object.

      Parameters:
      key - The key.
      Returns:
      The entry bean, never null.

    • getKeys

      public Set<String> getKeys(String section)
      Returns the keys of the entries in the specified section.
      Parameters:
      section - The section name to write from.
      If empty, refers to the default section.
      Must not be null.
      Returns:
      An unmodifiable set of keys, or an empty set if the section doesn't exist.

    • getName

      public String getName()
      Returns the name associated with this config (usually a file name).
      Returns:
      The name associated with this config, or null if it has no name.

    • getSection

      public Section getSection(String name)
      Gets the section with the specified name.

      If section does not exist, returns an empty Section object.

      Parameters:
      name - The section name. null and blank refer to the default section.
      Returns:
      The section bean, never null.

    • getSectionNames

      public Set<String> getSectionNames()
      Returns the section names defined in this config.
      Returns:
      The section names defined in this config.

    • getString

      public String getString(String key)
      Gets the entry with the specified key.

      The key can be in one of the following formats...

      • "key" - A value in the default section (i.e. defined above any [section] header).
      • "section/key" - A value from the specified section.

      If entry does not exist, returns null.

      Notes:
      • This method is equivalent to calling get(key).orElse(null);.
      Parameters:
      key - The key.
      Returns:
      The entry value, or null if it doesn't exist.

    • load

      public Config load(Map<String,Map<String,Object>> m) throws SerializeException
      Loads the contents of the specified map of maps into this config.
      Parameters:
      m - The maps to load.
      Returns:
      This object.
      Throws:
      SerializeException - Value could not be serialized.

    • load

      public Config load(Reader contents, boolean synchronous) throws IOException, InterruptedException
      Overwrites the contents of the config file.
      Parameters:
      contents - The new contents of the config file.
      synchronous - Wait until the change has been persisted before returning this map.
      Returns:
      This object.
      Throws:
      IOException - Thrown by underlying stream.
      InterruptedException - Thread was interrupted.
      UnsupportedOperationException - If configuration is read only.

    • load

      public Config load(String contents, boolean synchronous) throws IOException, InterruptedException
      Overwrites the contents of the config file.
      Parameters:
      contents - The new contents of the config file.
      synchronous - Wait until the change has been persisted before returning this map.
      Returns:
      This object.
      Throws:
      IOException - Thrown by underlying stream.
      InterruptedException - Thread was interrupted.
      UnsupportedOperationException - If configuration is read only.

    • onConfigChange

      public void onConfigChange(ConfigEvents events)
      Description copied from interface: ConfigEventListener
      Gets called immediately after a config file has been loaded.
      Specified by:
      onConfigChange in interface ConfigEventListener
      Parameters:
      events - The change events.

    • remove

      public Config remove(String key)
      Removes an entry with the specified key.
      Parameters:
      key - The key.
      Returns:
      The previous value, or null if the section or key did not previously exist.
      Throws:
      UnsupportedOperationException - If configuration is read only.

    • removeImport

      public Config removeImport(String sectionName, String importName)
      Removes the import statement with the specified name from the specified section.
      Parameters:
      sectionName - The section name where to place the import statement.
      Must not be null.
      Use blank for the default section.
      importName - The import name.
      Must not be null.
      Returns:
      This object.
      Throws:
      UnsupportedOperationException - If configuration is read only.

    • removeListener

      public Config removeListener(ConfigEventListener listener)
      Removes a listener from this config.
      Parameters:
      listener - The listener to remove.
      Returns:
      This object.

    • removeSection

      public Config removeSection(String name)
      Removes the section with the specified name.
      Parameters:
      name - The name of the section to remove
      Returns:
      This object.
      Throws:
      UnsupportedOperationException - If configuration is read only.

    • resolving

      public Config resolving(VarResolverSession varSession)
      Creates a copy of this config using the specified var session for resolving variables.

      This creates a shallow copy of the config but replacing the variable resolver.

      Parameters:
      varSession - The var session used for resolving string variables.
      Returns:
      A new config object.

    • rollback

      public Config rollback()
      Does a rollback of any changes on this config currently in memory.
      Returns:
      This object.
      Throws:
      UnsupportedOperationException - If configuration is read only.

    • set

      public Config set(String key, Object value) throws SerializeException
      Adds or replaces an entry with the specified key with a POJO serialized to a string using the registered serializer.

      Equivalent to calling put(key, value, isEncoded(key)).

      Parameters:
      key - The key.
      value - The new value POJO.
      Returns:
      The previous value, or null if the section or key did not previously exist.
      Throws:
      SerializeException - If serializer could not serialize the value or if a serializer is not registered with this config file.
      UnsupportedOperationException - If configuration is read only.

    • set

      public Config set(String key, Object value, Serializer serializer) throws SerializeException
      Same as set(String, Object) but allows you to specify the serializer to use to serialize the value.
      Parameters:
      key - The key.
      value - The new value.
      serializer - The serializer to use for serializing the object. If null, then uses the predefined serializer on the config file.
      Returns:
      The previous value, or null if the section or key did not previously exist.
      Throws:
      SerializeException - If serializer could not serialize the value or if a serializer is not registered with this config file.
      UnsupportedOperationException - If configuration is read only.

    • set

      public Config set(String key, Object value, Serializer serializer, String modifiers, String comment, List<String> preLines) throws SerializeException
      Same as set(String, Object) but allows you to specify all aspects of a value.
      Parameters:
      key - The key.
      value - The new value.
      serializer - The serializer to use for serializing the object. If null, then uses the predefined serializer on the config file.
      modifiers - Optional modifiers to apply to the value.
      If null, then previous value will not be replaced.
      comment - Optional same-line comment to add to this value.
      If null, then previous value will not be replaced.
      preLines - Optional comment or blank lines to add before this entry.
      If null, then previous value will not be replaced.
      Returns:
      The previous value, or null if the section or key did not previously exist.
      Throws:
      SerializeException - If serializer could not serialize the value or if a serializer is not registered with this config file.
      UnsupportedOperationException - If configuration is read only.

    • set

      public Config set(String key, String value)
      Sets a value in this config.
      Parameters:
      key - The key.
      value - The value.
      Returns:
      This object.
      Throws:
      UnsupportedOperationException - If configuration is read only.

    • setImport

      public Config setImport(String sectionName, String importName, List<String> preLines)
      Creates the specified import statement if it doesn't exist.
      Parameters:
      sectionName - The section name where to place the import statement.
      Must not be null.
      Use blank for the default section.
      importName - The import name.
      Must not be null.
      preLines - Optional comment and blank lines to add immediately before the import statement.
      If null, previous pre-lines will not be replaced.
      Returns:
      The appended or existing import statement.
      Throws:
      UnsupportedOperationException - If configuration is read only.

    • setSection

      public Config setSection(String name, List<String> preLines)
      Creates the specified section if it doesn't exist.

      Returns the existing section if it already exists.

      Parameters:
      name - The section name.
      Must not be null.
      Use blank for the default section.
      preLines - Optional comment and blank lines to add immediately before the section.
      If null, previous pre-lines will not be replaced.
      Returns:
      The appended or existing section.
      Throws:
      UnsupportedOperationException - If configuration is read only.

    • setSection

      public Config setSection(String name, List<String> preLines, Map<String,Object> contents) throws SerializeException
      Creates the specified section if it doesn't exist.
      Parameters:
      name - The section name.
      Must not be null.
      Use blank for the default section.
      preLines - Optional comment and blank lines to add immediately before the section.
      If null, previous pre-lines will not be replaced.
      contents - Values to set in the new section.
      Can be null.
      Returns:
      The appended or existing section.
      Throws:
      SerializeException - Contents could not be serialized.
      UnsupportedOperationException - If configuration is read only.

    • setSystemProperties

      public Config setSystemProperties()
      Takes the settings defined in this configuration and sets them as system properties.
      Returns:
      This object.

    • toMap

      public JsonMap toMap()
      Returns the contents of this config as a simple map.
      Returns:
      The contents of this config as a simple map.

    • properties

      protected FluentMap<String,Object> properties()
      Description copied from class: Context
      Returns the properties on this bean as a map for debugging.
      Overrides:
      properties in class Context
      Returns:
      The properties on this bean as a map for debugging.

    • toString

      public String toString()
      Overrides:
      toString in class Context

    • writeTo

      public Writer writeTo(Writer w) throws IOException
      Saves this config file to the specified writer as an INI file.

      The writer will automatically be closed.

      Parameters:
      w - The writer to send the output to.
      Returns:
      This object.
      Throws:
      IOException - If a problem occurred trying to send contents to the writer.