From bb9e16876e27d4450316233b2c50654817888f7e Mon Sep 17 00:00:00 2001 From: Rasmus Jokinen <146736881+51-code@users.noreply.github.com> Date: Tue, 21 Jan 2025 12:57:41 +0200 Subject: [PATCH 1/4] Add "How to implement" to README --- README.adoc | 61 ++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 56 insertions(+), 5 deletions(-) diff --git a/README.adoc b/README.adoc index 3a993e9..dd1df00 100644 --- a/README.adoc +++ b/README.adoc @@ -19,6 +19,12 @@ CNF-01 is a library that provides immutable configuration for Java projects. Imm . command line arguments (`ArgsConfiguration`) - Default configurations in case the provided configurations from a source are not found or are otherwise broken (`DefaultConfiguration`) +== A word about immutability + +Notable in CNF-01 is that the *configurations can not change after initialization*. + +For example, something might be added to the Java's System Properties even before calling `asMap()` on the `PropertiesConfiguration` object. However, this will not have effect on the `Configuration` object at all. *All the objects are immutable.* + == How to use // add instructions how people can start to use your project @@ -145,19 +151,64 @@ DefaultConfiguration defaultConfiguration = new DefaultConfiguration( Map result = defaultConfiguration.asMap(); ---- -=== Configuration objects in your project +== How to implement + +When implementing CNF-01 to a project, the point is to keep the main objects immutable and simple by moving the handling of configuration to their own objects. + +Follow these steps to implement CNF-01 in a Java project: + +* Identify the object that has to use configurations. +* You can define an interface for the factory objects that create the configured objects: + +[,java] +---- +public interface Factory { + public T object(); +} +---- + +* Create a Factory object for the object that has to use configurations. -The configuration Map from CNF-01 shouldn't be used directly in regular objects. It should only be passed to objects that are responsible for providing configured versions of other objects, in other words, Factories. The regular objects must not be configurable! +[,java] +---- +public final class ExampleFactory implements Factory { + + private final Map config; + + public ExampleFactory(final Map config) { + this.config = config; + } + + @Override + public Example object() { + // Parsing of values should be done here too if something else than String is needed + final String exampleType = config.get("example.type"); + final String exampleText = config.get("example.text"); + final Example example; -Small example with an `Example` object: + if (exampleType.equals("good")) { + example = new GoodExample(exampleText); + } else { + example = new BadExample(exampleText); + } + + return example; + } +} +---- + +* Utilize the Factory object to get properly initialized objects with the configuration options. [,java] ---- +PropertiesConfiguration config = new PropertiesConfiguration(); +Map configurationMap = config.asMap(); + ExampleFactory exampleFactory = new ExampleFactory(configurationMap); -Example example = exampleFactory.example(); +Example example = exampleFactory.object(); ---- -Here, the logic for instantiating an `Example` is in the `ExampleFactory` object, which receives the configuration map from CNF-01 as a parameter. This ensures that the main object `Example` is as clear as it can be. +* Create additional factories for other objects that require configurations. == Contributing From 19cd28885a4c95a7060f1123a199f9e1b72b114f Mon Sep 17 00:00:00 2001 From: Rasmus Jokinen <146736881+51-code@users.noreply.github.com> Date: Wed, 22 Jan 2025 08:00:21 +0200 Subject: [PATCH 2/4] Fix headings, add list continuation to code blocks --- README.adoc | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/README.adoc b/README.adoc index dd1df00..a9563f7 100644 --- a/README.adoc +++ b/README.adoc @@ -19,13 +19,13 @@ CNF-01 is a library that provides immutable configuration for Java projects. Imm . command line arguments (`ArgsConfiguration`) - Default configurations in case the provided configurations from a source are not found or are otherwise broken (`DefaultConfiguration`) -== A word about immutability +== A Word About Immutability Notable in CNF-01 is that the *configurations can not change after initialization*. For example, something might be added to the Java's System Properties even before calling `asMap()` on the `PropertiesConfiguration` object. However, this will not have effect on the `Configuration` object at all. *All the objects are immutable.* -== How to use +== How To Use // add instructions how people can start to use your project === Configuration @@ -94,7 +94,7 @@ try { Read Default Configuration section to see how default configurations can be used to avert the need for the try-catch. -=== Command line arguments +=== Command Line Arguments Command line arguments (or any `String[] args`) can be utilized as a configuration source with the `ArgsConfiguration` object. @@ -129,7 +129,7 @@ Configuration configuration = new EnvironmentConfiguration(); Map configMap = configuration.asMap(); ---- -=== Default configuration +=== Default Configuration Default configurations can be used in case the `asMap()` function throws `ConfigurationException`. If the function throws an exception, the defaults are used instead. Only `PathConfiguration` and `ArgsConfiguration` can currently throw an exception. @@ -151,7 +151,7 @@ DefaultConfiguration defaultConfiguration = new DefaultConfiguration( Map result = defaultConfiguration.asMap(); ---- -== How to implement +== How To Implement When implementing CNF-01 to a project, the point is to keep the main objects immutable and simple by moving the handling of configuration to their own objects. @@ -159,7 +159,7 @@ Follow these steps to implement CNF-01 in a Java project: * Identify the object that has to use configurations. * You can define an interface for the factory objects that create the configured objects: - ++ [,java] ---- public interface Factory { @@ -168,7 +168,7 @@ public interface Factory { ---- * Create a Factory object for the object that has to use configurations. - ++ [,java] ---- public final class ExampleFactory implements Factory { @@ -198,7 +198,7 @@ public final class ExampleFactory implements Factory { ---- * Utilize the Factory object to get properly initialized objects with the configuration options. - ++ [,java] ---- PropertiesConfiguration config = new PropertiesConfiguration(); From 3bee443f66feaf6486526e9d1af8dfcca591cabb Mon Sep 17 00:00:00 2001 From: Rasmus Jokinen <146736881+51-code@users.noreply.github.com> Date: Wed, 22 Jan 2025 08:03:53 +0200 Subject: [PATCH 3/4] Add empty line before code blocks --- README.adoc | 3 +++ 1 file changed, 3 insertions(+) diff --git a/README.adoc b/README.adoc index a9563f7..f8fca4a 100644 --- a/README.adoc +++ b/README.adoc @@ -160,6 +160,7 @@ Follow these steps to implement CNF-01 in a Java project: * Identify the object that has to use configurations. * You can define an interface for the factory objects that create the configured objects: + + [,java] ---- public interface Factory { @@ -169,6 +170,7 @@ public interface Factory { * Create a Factory object for the object that has to use configurations. + + [,java] ---- public final class ExampleFactory implements Factory { @@ -199,6 +201,7 @@ public final class ExampleFactory implements Factory { * Utilize the Factory object to get properly initialized objects with the configuration options. + + [,java] ---- PropertiesConfiguration config = new PropertiesConfiguration(); From 3f2d3e99d4add8e797c4668197748aed09acdab6 Mon Sep 17 00:00:00 2001 From: Rasmus Jokinen <146736881+51-code@users.noreply.github.com> Date: Tue, 28 Jan 2025 08:47:16 +0200 Subject: [PATCH 4/4] Move "How To Implement" to be before "How To Use" --- README.adoc | 124 ++++++++++++++++++++++++++-------------------------- 1 file changed, 62 insertions(+), 62 deletions(-) diff --git a/README.adoc b/README.adoc index f8fca4a..b88e5ec 100644 --- a/README.adoc +++ b/README.adoc @@ -25,6 +25,68 @@ Notable in CNF-01 is that the *configurations can not change after initializatio For example, something might be added to the Java's System Properties even before calling `asMap()` on the `PropertiesConfiguration` object. However, this will not have effect on the `Configuration` object at all. *All the objects are immutable.* +== How To Implement + +When implementing CNF-01 to a project, the point is to keep the main objects immutable and simple by moving the handling of configuration to their own objects. + +Follow these steps to implement CNF-01 in a Java project: + +* Identify the object that has to use configurations. +* You can define an interface for the factory objects that create the configured objects: ++ + +[,java] +---- +public interface Factory { + public T object(); +} +---- + +* Create a Factory object for the object that has to use configurations. ++ + +[,java] +---- +public final class ExampleFactory implements Factory { + + private final Map config; + + public ExampleFactory(final Map config) { + this.config = config; + } + + @Override + public Example object() { + // Parsing of values should be done here too if something else than String is needed + final String exampleType = config.get("example.type"); + final String exampleText = config.get("example.text"); + final Example example; + + if (exampleType.equals("good")) { + example = new GoodExample(exampleText); + } else { + example = new BadExample(exampleText); + } + + return example; + } +} +---- + +* Utilize the Factory object to get properly initialized objects with the configuration options. ++ + +[,java] +---- +PropertiesConfiguration config = new PropertiesConfiguration(); +Map configurationMap = config.asMap(); + +ExampleFactory exampleFactory = new ExampleFactory(configurationMap); +Example example = exampleFactory.object(); +---- + +* Create additional factories for other objects that require configurations. + == How To Use // add instructions how people can start to use your project @@ -151,68 +213,6 @@ DefaultConfiguration defaultConfiguration = new DefaultConfiguration( Map result = defaultConfiguration.asMap(); ---- -== How To Implement - -When implementing CNF-01 to a project, the point is to keep the main objects immutable and simple by moving the handling of configuration to their own objects. - -Follow these steps to implement CNF-01 in a Java project: - -* Identify the object that has to use configurations. -* You can define an interface for the factory objects that create the configured objects: -+ - -[,java] ----- -public interface Factory { - public T object(); -} ----- - -* Create a Factory object for the object that has to use configurations. -+ - -[,java] ----- -public final class ExampleFactory implements Factory { - - private final Map config; - - public ExampleFactory(final Map config) { - this.config = config; - } - - @Override - public Example object() { - // Parsing of values should be done here too if something else than String is needed - final String exampleType = config.get("example.type"); - final String exampleText = config.get("example.text"); - final Example example; - - if (exampleType.equals("good")) { - example = new GoodExample(exampleText); - } else { - example = new BadExample(exampleText); - } - - return example; - } -} ----- - -* Utilize the Factory object to get properly initialized objects with the configuration options. -+ - -[,java] ----- -PropertiesConfiguration config = new PropertiesConfiguration(); -Map configurationMap = config.asMap(); - -ExampleFactory exampleFactory = new ExampleFactory(configurationMap); -Example example = exampleFactory.object(); ----- - -* Create additional factories for other objects that require configurations. - == Contributing // Change the repository name in the issues link to match with your project's name