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
To get rid of further IO boilerplate when the format library requires
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
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 Summary
ModifierConstructorDescriptionprotected
ConfigurationFormatFactory(Class<C> configClass, ConfigurationOptions options)
Creates from a config class and config options -
Method Summary
Modifier and TypeMethodDescriptionGets the configuration class this factory is forGets the comment header on the top level configuration.Gets the configuration options this factory usesload(InputStream inputStream)
Reads configuration data from an input streamload(InputStream inputStream, C auxiliaryEntries)
Reads configuration data from an input stream with the given auxiliary configuration instance.load(ReadableByteChannel readChannel)
Reads configuration data from a readable channelload(ReadableByteChannel readChannel, C auxiliaryEntries)
Reads configuration data from a readable channel with the given auxiliary configuration instance.Reads the default configuration data from annotations inConfDefault
If any config entry is missing a default value annotation, or the default values cannot be deserialised to the appropriate config value,IllDefinedConfigException
is thrownloadMap(InputStream inputStream)
Loads a map of config values from an input stream.loadMap(ReadableByteChannel readChannel)
Loads a map of config values from an input channel.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.boolean
Whether this implementation actively supports comments by recognisingCommentedWrapper
in config values.void
write(C configData, OutputStream outputStream)
Writes configuration data to an output streamvoid
write(C configData, WritableByteChannel writeChannel)
Writes configuration data to a writable byte channelabstract void
writeMap(Map<String,Object> config, OutputStream outputStream)
Writes a map of config values to an output streamabstract void
writeMap(Map<String,Object> config, WritableByteChannel writeChannel)
Writes a map of config values to an output channel
-
Constructor Details
-
ConfigurationFormatFactory
Creates from a config class and config options- Parameters:
configClass
- the config classoptions
- configuration options- Throws:
NullPointerException
- ifconfigClass
oroptions
is nullIllegalArgumentException
- ifconfigClass
is not an interfaceIllDefinedConfigException
- if the configuration entries defined in the config class are invalid
-
-
Method Details
-
getConfigClass
Description copied from interface:ConfigurationFactory
Gets the configuration class this factory is for- Specified by:
getConfigClass
in interfaceConfigurationFactory<C>
- Returns:
- the configuration class
-
getOptions
Description copied from interface:ConfigurationFactory
Gets the configuration options this factory uses- Specified by:
getOptions
in interfaceConfigurationFactory<C>
- Returns:
- the configuration options
-
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
Description copied from interface:ConfigurationFactory
Reads configuration data from a readable channel- Specified by:
load
in interfaceConfigurationFactory<C>
- Parameters:
readChannel
- the channel from which to read the data- Returns:
- the read config data
- Throws:
IOException
- if an I/O error occursInvalidConfigException
- if the configuration is invalid. Where possible, more specific subclasses are thrown
-
load
Description copied from interface:ConfigurationFactory
Reads configuration data from an input stream- Specified by:
load
in interfaceConfigurationFactory<C>
- Parameters:
inputStream
- the stream from which to read the data- Returns:
- the read config data
- Throws:
IOException
- if an I/O error occursInvalidConfigException
- if the configuration is invalid. Where possible, more specific subclasses are thrown
-
load
public final C load(ReadableByteChannel readChannel, C auxiliaryEntries) throws IOException, InvalidConfigExceptionDescription 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 implementsAuxiliaryKeys
, the caller can determine whether any of the auxiliary entries were used.- Specified by:
load
in interfaceConfigurationFactory<C>
- Parameters:
readChannel
- the channel from which to read the dataauxiliaryEntries
- the auxiliary configuration instance- Returns:
- the read config data
- Throws:
IOException
- if an I/O error occursInvalidConfigException
- if the configuration is invalid. Where possible, more specific subclasses are thrown
-
load
public final C load(InputStream inputStream, C auxiliaryEntries) throws IOException, InvalidConfigExceptionDescription 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 implementsAuxiliaryKeys
, the caller can determine whether any of the auxiliary entries were used.- Specified by:
load
in interfaceConfigurationFactory<C>
- Parameters:
inputStream
- the stream from which to read the dataauxiliaryEntries
- the auxiliary configuration instance- Returns:
- the read config data
- Throws:
IOException
- if an I/O error occursInvalidConfigException
- if the configuration is invalid. Where possible, more specific subclasses are thrown
-
loadDefaults
Description copied from interface:ConfigurationFactory
Reads the default configuration data from annotations inConfDefault
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 interfaceConfigurationFactory<C>
- Returns:
- the read config data
-
loadMap
public abstract Map<String,Object> loadMap(ReadableByteChannel readChannel) throws IOException, InvalidConfigExceptionLoads 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 occursInvalidConfigException
- if the configuration format dictates the data is not valid syntax. UsuallyConfigFormatSyntaxException
-
loadMap
public abstract Map<String,Object> loadMap(InputStream inputStream) throws IOException, InvalidConfigExceptionLoads 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 occursInvalidConfigException
- if the configuration format dictates the data is not valid syntax. UsuallyConfigFormatSyntaxException
-
write
Description copied from interface:ConfigurationFactory
Writes configuration data to a writable byte channel- Specified by:
write
in interfaceConfigurationFactory<C>
- Parameters:
configData
- the configuration datawriteChannel
- the channel to which to write the data- Throws:
IOException
- if an I/O error occurs
-
write
Description copied from interface:ConfigurationFactory
Writes configuration data to an output stream- Specified by:
write
in interfaceConfigurationFactory<C>
- Parameters:
configData
- the configuration dataoutputStream
- 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 IOExceptionWrites a map of config values to an output channel- Parameters:
config
- the hierarchical configuration mapwriteChannel
- 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 IOExceptionWrites a map of config values to an output stream- Parameters:
config
- the hierarchical configuration mapoutputStream
- 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 recognisingCommentedWrapper
in config values. It is insufficient for the underlying format to support comments; the implementation of this config factory must also recogniseCommentedWrapper
values. See thewriteMap
methods for more information.- Returns:
- true if comments supported by recognising
CommentedWrapper
, false otherwise
-
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
-