Package org.apache.juneau.config

Class Config

java.lang.Object
org.apache.juneau.marshall.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.
      Must not be null.
      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. "juneau.cfg"
      3. "default.cfg"
      4. "application.cfg"
      5. "app.cfg"
      6. "settings.cfg"
      7. "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.

    • 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.
      Must not be null.
      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.
      Must not be null.
      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.
      Must not be null.
      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.
      Can be null (no-op).
      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.
      Must not be null.
      Returns:
      This object.
      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.

    • entry

      public EntryBuilder entry(String key)
      Returns a fluent builder for adding or updating the entry with the specified key.

      This is an ergonomic, self-documenting alternative to the set(String, Object, Serializer, String, List) overload. Rather than overloading a single call with several "leave-unchanged versus clear" sentinel conventions, each facet is expressed explicitly:

      Example:

      config.entry("MySection/myKey") .comment("My comment") .preLines(List.of("# A pre-line")) .set("My value");

      Parameters:
      key - The key.
      Must not be null.
      Returns:
      A new fluent entry builder, never null.

    • 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.
      Must not be null.
      value - The new value POJO.
      Returns:
      This object.
      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.
      Must not be null.
      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:
      This object.
      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 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.
      Must not be null.
      value - The new value.
      serializer - The serializer to use for serializing the object. If null, then uses the predefined serializer on the config file.
      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:
      This object.
      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.
      Must not be null.
      value - The value.
      Can be null (no-op if the entry does not already exist).
      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:
      This object.
      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:
      This object.
      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 (no additional values are set).
      Returns:
      This object.
      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.

      This is never called automatically; applications that want their config entries published as JVM-wide system properties must call it explicitly.

      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 using this config's ConfigFormat (INI, YAML, etc.).
      Parameters:
      w - The writer to send the output to.
      Must not be null.
      The writer is not closed by this method.
      Returns:
      The same writer passed in.
      Throws:
      IOException - If a problem occurred trying to send contents to the writer.

    • getRaw

      public String getRaw(String key)
      Returns the specified value as a string from the config file.

      Unlike getString(String), this method doesn't replace SVL variables.

      Values read through the other getters are resolved against the configured VarResolver, so a value that can be written by an untrusted party can pull in environment variables, system properties and other resolver content. Escape untrusted text before storing it in a config entry, or read it with this method.

      Parameters:
      key - The key.
      Returns:
      The value, or null if the section or value doesn't exist.