Package space.arim.dazzleconf.factory

Class ConfigurationFormatFactory<C>

java.lang.Object
space.arim.dazzleconf.factory.ConfigurationFormatFactory<C>
Type Parameters:
C - the type of the configuration
All Implemented Interfaces:
ConfigurationFactory<C>
Direct Known Subclasses:
HumanReadableConfigurationFactory
public abstract class ConfigurationFormatFactory<C> extends Object implements ConfigurationFactory<C>
Abstract implementation of ConfigurationFactory which takes care of configuration loading from a map.

To get rid of further IO boilerplate when the format library requires Reader and Writer instances, see HumanReadableConfigurationFactory.

Hierarchical Maps
When a method in this class refers to a "hierarchical map", it is describing a map of keys and values, whose values may themselves contain further maps. This is the structure used with regards to nested configuration sections.

Comment wrappers
For implementations returning true in supportsCommentsThroughWrapper(), special treatment is required in the implementation of writeMap methods. Namely, configuration values may be commented or uncommented. If uncommented, they are a plain object. If commented, they are wrapped in CommentedWrapper, which includes the config value itself as well as the comments which are placed before it. As comments may apply to config sections, CommentWrapper may also wrap nested maps.
Author:
A248

  • Constructor Details

  • Method Details

    • getConfigClass

      public final Class<C> getConfigClass()
      Description copied from interface: ConfigurationFactory
      Gets the configuration class this factory is for
      Specified by:
      getConfigClass in interface ConfigurationFactory<C>
      Returns:
      the configuration class

    • getOptions

      public final ConfigurationOptions getOptions()
      Description copied from interface: ConfigurationFactory
      Gets the configuration options this factory uses
      Specified by:
      getOptions in interface ConfigurationFactory<C>
      Returns:
      the configuration options

    • getHeader

      public final List<String> getHeader()
      Gets the comment header on the top level configuration. This is the document wide comment header, at the top of the file.
      Returns:
      the top level comment header

    • load

      public final C load(ReadableByteChannel readChannel) throws IOException, InvalidConfigException
      Description copied from interface: ConfigurationFactory
      Reads configuration data from a readable channel
      Specified by:
      load in interface ConfigurationFactory<C>
      Parameters:
      readChannel - the channel from which to read the data
      Returns:
      the read config data
      Throws:
      IOException - if an I/O error occurs
      InvalidConfigException - if the configuration is invalid. Where possible, more specific subclasses are thrown

    • load

      public final C load(InputStream inputStream) throws IOException, InvalidConfigException
      Description copied from interface: ConfigurationFactory
      Reads configuration data from an input stream
      Specified by:
      load in interface ConfigurationFactory<C>
      Parameters:
      inputStream - the stream from which to read the data
      Returns:
      the read config data
      Throws:
      IOException - if an I/O error occurs
      InvalidConfigException - if the configuration is invalid. Where possible, more specific subclasses are thrown

    • load

      public final C load(ReadableByteChannel readChannel, C auxiliaryEntries) throws IOException, InvalidConfigException
      Description copied from interface: ConfigurationFactory
      Reads configuration data from a readable channel with the given auxiliary configuration instance. Any keys missing in the loaded config data will be supplanted by the config instance's corresponding entry.

      By checking if the returned configuration implements AuxiliaryKeys, the caller can determine whether any of the auxiliary entries were used.
      Specified by:
      load in interface ConfigurationFactory<C>
      Parameters:
      readChannel - the channel from which to read the data
      auxiliaryEntries - the auxiliary configuration instance
      Returns:
      the read config data
      Throws:
      IOException - if an I/O error occurs
      InvalidConfigException - if the configuration is invalid. Where possible, more specific subclasses are thrown

    • load

      public final C load(InputStream inputStream, C auxiliaryEntries) throws IOException, InvalidConfigException
      Description copied from interface: ConfigurationFactory
      Reads configuration data from an input stream with the given auxiliary configuration instance. Any keys missing in the loaded config data will be supplanted by the config instance's corresponding entry.

      By checking if the returned configuration implements AuxiliaryKeys, the caller can determine whether any of the auxiliary entries were used.
      Specified by:
      load in interface ConfigurationFactory<C>
      Parameters:
      inputStream - the stream from which to read the data
      auxiliaryEntries - the auxiliary configuration instance
      Returns:
      the read config data
      Throws:
      IOException - if an I/O error occurs
      InvalidConfigException - if the configuration is invalid. Where possible, more specific subclasses are thrown

    • loadDefaults

      public final C loadDefaults()
      Description copied from interface: ConfigurationFactory
      Reads the default configuration data from annotations in ConfDefault

      If any config entry is missing a default value annotation, or the default values cannot be deserialised to the appropriate config value, IllDefinedConfigException is thrown
      Specified by:
      loadDefaults in interface ConfigurationFactory<C>
      Returns:
      the read config data

    • loadMap

      public abstract Map<String,Object> loadMap(ReadableByteChannel readChannel) throws IOException, InvalidConfigException
      Loads a map of config values from an input channel.
      Parameters:
      readChannel - the channel from which to read
      Returns:
      the hierarchical configuration map
      Throws:
      IOException - if an I/O error occurs
      InvalidConfigException - if the configuration format dictates the data is not valid syntax. Usually ConfigFormatSyntaxException

    • loadMap

      public abstract Map<String,Object> loadMap(InputStream inputStream) throws IOException, InvalidConfigException
      Loads a map of config values from an input stream.
      Parameters:
      inputStream - the stream from which to read
      Returns:
      the hierarchical configuration map
      Throws:
      IOException - if an I/O error occurs
      InvalidConfigException - if the configuration format dictates the data is not valid syntax. Usually ConfigFormatSyntaxException

    • write

      public final void write(C configData, WritableByteChannel writeChannel) throws IOException
      Description copied from interface: ConfigurationFactory
      Writes configuration data to a writable byte channel
      Specified by:
      write in interface ConfigurationFactory<C>
      Parameters:
      configData - the configuration data
      writeChannel - the channel to which to write the data
      Throws:
      IOException - if an I/O error occurs

    • write

      public final void write(C configData, OutputStream outputStream) throws IOException
      Description copied from interface: ConfigurationFactory
      Writes configuration data to an output stream
      Specified by:
      write in interface ConfigurationFactory<C>
      Parameters:
      configData - the configuration data
      outputStream - the stream to which to write the data
      Throws:
      IOException - if an I/O error occurs

    • writeMap

      public abstract void writeMap(Map<String,Object> config, WritableByteChannel writeChannel) throws IOException
      Writes a map of config values to an output channel
      Parameters:
      config - the hierarchical configuration map
      writeChannel - the channel to which to write
      Throws:
      IOException - if an I/O error occurs

    • writeMap

      public abstract void writeMap(Map<String,Object> config, OutputStream outputStream) throws IOException
      Writes a map of config values to an output stream
      Parameters:
      config - the hierarchical configuration map
      outputStream - the stream to which to write
      Throws:
      IOException - if an I/O error occurs

    • supportsCommentsThroughWrapper

      public boolean supportsCommentsThroughWrapper()
      Whether this implementation actively supports comments by recognising CommentedWrapper in config values. It is insufficient for the underlying format to support comments; the implementation of this config factory must also recognise CommentedWrapper values. See the writeMap methods for more information.
      Returns:
      true if comments supported by recognising CommentedWrapper, false otherwise

    • pseudoCommentsSuffix

      public String pseudoCommentsSuffix()
      If the configuration format does not natively support comments, it is possible to attach a "comment" as a string value before the configuration entry which is to be commented, with the use of some key suffix.

      If this method returns a non empty string, this feature is enabled. For example, if this returns '-comment', using the Json configuration language, comments will be written as shown: 
         retries-comment: "determines the amount of retries"
   retries: 3
      Returns:
      an empty string if disabled, otherwise the suffix to append to form the keys of comments