Merge pull request #36 from hankem/DoNotLogValue

@DoNotLogValue annotation to prevent values such as sensitive passwords from being logged

Author: wuan

README.md

@@ -1,84 +1,81 @@
 Java Config-Builder  [![Build Status](https://travis-ci.org/TNG/config-builder.svg?branch=master)](https://travis-ci.org/TNG/config-builder) [![Coverage Status](https://coveralls.io/repos/TNG/config-builder/badge.svg?branch=master&service=github)](https://coveralls.io/github/TNG/config-builder?branch=master) [![Dependency Status](https://www.versioneye.com/user/projects/56989a13af789b002e000b72/badge.svg?style=flat)](https://www.versioneye.com/user/projects/56989a13af789b002e000b72) [![MavenCentral](https://img.shields.io/maven-central/v/com.tngtech.java/config-builder.svg)](http://search.maven.org/#artifactdetails|com.tngtech.java|config-builder|1.3.1|jar) [![Stories in Ready](https://badge.waffle.io/TNG/config-builder.png?label=ready&title=Ready)](http://waffle.io/TNG/config-builder)
-==================
+===================
 
 #### Table of Contents
-[What It Is](#what-is-it)  
-[Motivation](#motivation)    
+[What It Is](#what-it-is)  
+[Motivation](#motivation)  
 [How To Build Your Config](#how-to-build-your-config)  
-[How To Merge With An Existing Config](#how-to-merge-with-an-existing-config)  
+[How To Import An Existing Config](#how-to-import-an-existing-config)  
 [Usage example](#usage-example)  
+[Presentation](#presentation)  
 [Java Doc](#java-doc)  
 
 What It Is
 ----------
+The Config-Builder makes use of annotations and reflections in order to build configured instances of custom classes.
 
-The ConfigBuilder makes use of annotations and reflections in order to build configured instances of custom classes. 
-
-Its features include   
+Its features include  
 1. defining default values and loading of values from properties files, system properties, the command line and others  
 2. configuring of not only String values, but fields of arbitrary types  
-3. configuring of collection fields   
-4. merging configs   
+3. configuring of collection fields  
+4. merging configs  
 5. JSR303 validation of the instances it builds.  
 
 Motivation
 ----------
-
-Many Java Projects include one or more classes that store configuration values and objects. Often, these come from
+Many Java projects include one or more classes that store configuration values and objects. These often come from
 properties files, system properties and environment variables or command line arguments, which requires the developer
 to implement the finding and loading of files, parsing the values etc. for every new project.
 
 This is is a time-consuming process, so why not spare this time and get started much faster? Although there are libraries
-that implement the loading of properties files and some possibilities of building configured objects e.g. in Spring, 
+that implement the loading of properties files and some possibilities of building configured objects e.g. in Spring,
 there hasn't been a really easy-yet-powerful solution so far.
 
-This is where the Config Builder comes in. It doesn't require any additional classes besides the config itself. 
-Instead of manually implementing the loading of values from files etc., building a config can now be easily done 
+This is where the Config-Builder comes in. It doesn't require any additional classes besides the config itself.
+Instead of manually implementing the loading of values from files etc., building a config can now be easily done
 by using annotations.
 
 How To Build Your Config
 ------------------------
-
-####1. Create your class:
+#### 1. Create your class:
 ```java
 public class Config {
     private String someNumber;
     private Collection<PidFix> stringCollection;
-    ...
+    // ...
 }
 ```
-####2. Annotate the class (configure the loading of properties files)
 
-If you want the ConfigBuilder to get values from properties files, 
-you can specify the files' basenames (no file extension or path) by 
-annotating your config class with the @PropertiesFiles annotation. 
-You can specify multiple basenames like this: 
+#### 2. Annotate the class (configure the loading of properties files)
+If you want the Config-Builder to get values from properties files,
+you can specify the files' basenames (no file extension or path) by
+annotating your config class with the `@PropertiesFiles` annotation.
+You can specify multiple basenames like this:
 ```java
 @PropertiesFiles({file1,file2,...})
 ```
 
-By default, properties files are loaded using the PropertyLoader's default config, which 
+By default, properties files are loaded using the `PropertyLoader`'s default config, which
 searches for files in the current directory, the ContextClassLoader and the user's home directory.
-You can manually specify the search locations by annotating your config class with the @PropertyLocations annotation, e.g.
+You can manually specify the search locations by annotating your config class with the `@PropertyLocations` annotation, e.g.
 ```java
 @PropertyLocations(directories = {"/home/user"}, resourcesForClasses={MyApp.class}, contextClassLoader = true)
 ```
 
-The PropertyLoader also searches for files with the default suffixes, i.e. the user name, local host names and 'override'.
-You can manually set the suffixes by annotating your config class with the @PropertySuffixes annotation like this:
+The `PropertyLoader` also searches for files with the default suffixes, i.e. the user name, local host names and 'override'.
+You can manually set the suffixes by annotating your config class with the `@PropertySuffixes` annotation like this:
 ```java
 @PropertySuffixes(extraSuffixes = {"tngtech","myname"}, hostNames = true)
 ```
 
-The default file extensions are .properties and .xml. You can replace the .properties file extension with your own
-by annotating your config class with 
+The default file extensions are `.properties` and `.xml`. You can replace the .properties file extension with your own
+by annotating your config class with
 ```java
 @PropertyExtension("fileextension")
 ```
 
-####3. Annotate the fields
-
-#####3.1 Get the String value
+#### 3. Annotate the fields
+##### 3.1 Get the String value
 There are five annotations that specify where the String value that configures a field comes from:
 ```java
 @DefaultValue("value")
@@ -89,61 +86,63 @@ There are five annotations that specify where the String value that configures a
 ```
 
 By default, when parsing the annotations, priority is as above, i.e. any value found on the command line overwrites a value found in properties, which in turn overwrites the environment variable value and so on.
-This order can be customized, see [4.](#4-change-the-order-in-which-annotations-are-processed-and-use-your-own-error-messages).
+This order can be customized, see [§5 (Change the order in which annotations are processed)](#5-change-the-order-in-which-annotations-are-processed).
 
-#####3.2 Transform it to any object or a collection
+##### 3.2 Transform it to any object or a collection
 Fields don't have to be Strings. You can configure collection fields or even any type you wish (or a collection of that type).
 
 Some simple transformers are included and used by default, e.g. a String will automatically be converted to an integer, a
 boolean value or even a collection as needed.
 
-If you need more complex transformers, you can also implement your own by extending the TypeTransformer class, and specifying them in the ```@TypeTransformers``` annotation.
- 
-Finally, the original value may not always be a String. To support this case, the annotation takes a list of possible transformers, and the one with the right 
-source and target types is automatically detected and used. 
- 
-####4. Add JSR validation annotations and/or define a custom validation method
+If you need more complex transformers, you can also implement your own by extending the `TypeTransformer` class, and specifying them in the `@TypeTransformers` annotation.
+
+Finally, the original value may not always be a String. To support this case, the annotation takes a list of possible transformers, and the one with the right
+source and target types is automatically detected and used.
 
+##### 3.3 Prevent sensitive data from being logged
+Resolved values are usually logged at debug level.
+If this is not desired, just add the `@DoNotLogValue` annotation to the field containing your sensitive data.
+
+#### 4. Add JSR validation annotations and/or define a custom validation method
 After an instance of your config is built, it is automatically validated. You can either use JSR validation annotations
-(@NotNull,...) or define a custom validation method:
+(`@NotNull`, ...) or define a custom validation method:
 
 ```java
 @Validation
 private void validate() {
-  <...>
+  // ...
 }
 ```
 
-####5. Change the order in which annotations are processed and use your own error messages
-
+#### 5. Change the order in which annotations are processed
 You can change the order in which annotations are processed globally or individually for each field.
-To specify a global order for parsing ValueExtractorAnnotation annotations, annotate the class with the
-@LoadingOrder annotation. To change the order for a certain field, annotate the field.
-The order may only contain ValueExtractorAnnotations, i.e. 
-CommandLineValue.class, PropertyValue.class and DefaultValue.class. Example:
+To specify a global order for parsing `ValueExtractorAnnotation` annotations, annotate the class with the
+`@LoadingOrder` annotation. To change the order for a certain field, annotate the field.
+The `@LoadingOrder` may only contain the following values:
 ```java
-@LoadingOrder({PropertyValue.class, EnvironmentVariableValue.class, SystemPropertyValue.class, CommandLineValue.class, DefaultValue.class})
+@LoadingOrder({PropertyValue.class, EnvironmentVariableValue.class, SystemPropertyValue.class, CommandLineValue.class, ImportedValue.class, DefaultValue.class})
 ```
 
-To specify your own error messages file (which is loaded by the PropertyLoader with the same settings as other the properties files), 
-annotate the class with the @ErrorMessageFile annotation:
+#### 6. Use your own error messages
+To specify your own error messages file (which is loaded by the `PropertyLoader` with the same settings as other the properties files),
+annotate the class with the `@ErrorMessageFile` annotation:
 ```java
 @ErrorMessageFile("myErrorMessages")
 ```
 
-####6. Build an instance of your class
+#### 7. Build an instance of your class
 ```java
-Config myConfig = new ConfigBuilder<Config>(Config.class).withCommandLineArgs(args).build();
+Config myConfig = ConfigBuilder.on(Config.class).withCommandLineArgs(args).build();
 ```
-How To Merge With An Existing Config
-------------------------------------
 
-If you already have an instance of your config class and want to only configure the fields which are not null, use
+How To Import An Existing Config
+--------------------------------
+If you already have an instance of your config class and want to only configure the fields which are not `null`, use
 ```java
-newConfig = new ConfigBuilder<Config>(Config.class).withCommandLineArgs(args).merge(existingConfig);
+Config newConfig = ConfigBuilder.on(Config.class).withCommandLineArgs(args).withImportedConfiguration(existingConfig).build();
 ```
-<b>Note that primitive type fields are always overwritten!</b>   
-Since primitive types can not be checked for 'null', it is not possible to check whether primitive fields of an existing config 
+<b>Note that primitive type fields are always overwritten!</b>  
+Since primitive types can not be checked for `null`, it is not possible to check whether primitive fields of an existing config
 have already been set. Hence, for the moment, primitives are always overwritten.
 
 Usage example
@@ -158,39 +157,40 @@ public class Config {
     public static class StringToPidFixTransformer extends TypeTransformer<String,PidFix> {
         @Override
         public PidFix transform(String input) {
-            <...>
+            // ...
         }
     }
-    
+
     @DefaultValue("false")      // values are automatically be converted to primitive types
     @CommandLineValue(shortOpt="t", longOpt="test", hasArg=false)     // this is a flag argument
     private boolean runInTestMode;
-    
+
     @DefaultValue("3")
     @CommandLineValue(shortOpt="rl", longOpt="runLevel", hasArg=true)
     private int runLevel;
-    
+
     @EnvironmentVariableValue("PATH")
     @PropertyValue("path")      // maps to the key "path" in the properties file
     private String path;
- 
+
     @SystemPropertyValue("user.name")       // maps to the field "user.name" in the system properties
     @NotEmpty("username.notEmpty")      // JSR-303 validation (Field should not be empty)
     private String userName;
- 
+
     @TypeTransformers(StringToPidFixTransformer.class)
     @CommandLineValue(shortOpt="pc", longOpt="pidFixCollection", hasArg=true)
     private Collection<PidFix> pidFixCollection;
-    
+
     @TypeTransformers(StringToPidFixTransformer.class)
     @CommandLineValue(shortOpt="p", longOpt="pidFix", hasArg=true)
     private PidFix pidFix;
- 
+
     @Validation
     private void validate() {
-        <...>
+        // ...
     }
-    ...
+
+    //...
 }
 ```
 To build a configured instance, simply call
@@ -199,12 +199,9 @@ Config myConfig = ConfigBuilder.on(Config.class).withCommandLineArgs(args).build
 ```
 
 Presentation
---------
-
+------------
 A sample presentation can be found at http://tng.github.io/config-builder
 
-
 Java Doc
 --------
-
 Full javadoc of the code can be found here http://tng.github.io/config-builder/javadoc

pom.xml

@@ -41,7 +41,7 @@
     </developers>
     <organization>
         <name>TNG Technology Consulting</name>
-        <url>http://www.tngtech.com/</url>
+        <url>https://www.tngtech.com/</url>
     </organization>
 
     <parent>
@@ -134,13 +134,11 @@
     </profiles>
 
     <dependencies>
-
         <dependency>
             <groupId>com.tngtech.java</groupId>
             <artifactId>property-loader</artifactId>
             <version>1.3.1</version>
         </dependency>
-
         <dependency>
             <groupId>junit</groupId>
             <artifactId>junit</artifactId>
@@ -156,13 +154,7 @@
         <dependency>
             <groupId>org.assertj</groupId>
             <artifactId>assertj-core</artifactId>
-            <version>2.5.0</version>
-            <scope>test</scope>
-        </dependency>
-        <dependency>
-            <groupId>org.unitils</groupId>
-            <artifactId>unitils-core</artifactId>
-            <version>3.4.6</version>
+            <version>2.6.0</version>
             <scope>test</scope>
         </dependency>
         <dependency>

src/main/java/com/tngtech/configbuilder/ConfigBuilder.java

@@ -5,7 +5,6 @@
 import com.tngtech.configbuilder.annotation.propertyloaderconfiguration.ErrorMessageFile;
 import com.tngtech.configbuilder.configuration.BuilderConfiguration;
 import com.tngtech.configbuilder.configuration.ErrorMessageSetup;
-import com.tngtech.configbuilder.util.ConfigBuilderFactory;
 import com.tngtech.configbuilder.util.*;
 import com.tngtech.propertyloader.PropertyLoader;
 import com.tngtech.propertyloader.impl.DefaultPropertyFilterContainer;

src/main/java/com/tngtech/configbuilder/annotation/configuration/DoNotLogValue.java

@@ -0,0 +1,17 @@
+package com.tngtech.configbuilder.annotation.configuration;
+
+import com.tngtech.configbuilder.ConfigBuilder;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * This annotation can be used to prevent a field's value from being logged
+ * when {@link ConfigBuilder#build(Object...)} builds a config instance.
+ */
+@Target(ElementType.FIELD)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface DoNotLogValue {
+}

src/main/java/com/tngtech/configbuilder/annotation/configuration/LoadingOrder.java

@@ -2,20 +2,25 @@
 
 import com.tngtech.configbuilder.annotation.valueextractor.CommandLineValue;
 import com.tngtech.configbuilder.annotation.valueextractor.DefaultValue;
+import com.tngtech.configbuilder.annotation.valueextractor.EnvironmentVariableValue;
+import com.tngtech.configbuilder.annotation.valueextractor.ImportedValue;
 import com.tngtech.configbuilder.annotation.valueextractor.PropertyValue;
+import com.tngtech.configbuilder.annotation.valueextractor.SystemPropertyValue;
+import com.tngtech.configbuilder.annotation.valueextractor.ValueExtractorAnnotation;
 
 import java.lang.annotation.*;
 
 /**
- * This annotation is used to specify the order in which the annotations CommandLineValue, PropertyValue and DefaultValue are processed.
+ * This annotation is used to specify the order in which the {@link ValueExtractorAnnotation} annotations
+ * {@link CommandLineValue}, {@link PropertyValue}, {@link EnvironmentVariableValue},
+ * {@link SystemPropertyValue}, {@link ImportedValue} and {@link DefaultValue} are processed.
  * It can specify the order for a certain field if placed on the field, or a global order if placed on the config class.
  * The annotations are processed top-down until a string value is found, i.e. the order is from the most important to the least important.
- * The order may only contain ValueExtractorAnnotations, i.e. CommandLineValue.class, PropertyValue.class and DefaultValue.class.<br>
+ * The {@code LoadingOrder} may only contain the aforementioned {@link ValueExtractorAnnotation} classes.<br>
  * <b>Usage:</b> <code>@LoadingOrder(value = {PropertyValue.class, CommandLineValue.class, DefaultValue.class})</code>
  */
 @Target({ElementType.TYPE, ElementType.FIELD})
 @Retention(RetentionPolicy.RUNTIME)
 public @interface LoadingOrder {
-    public Class<? extends Annotation>[] value() default {CommandLineValue.class, PropertyValue.class, DefaultValue.class};
-
+    Class<? extends Annotation>[] value() default {CommandLineValue.class, PropertyValue.class, DefaultValue.class};
 }

src/main/java/com/tngtech/configbuilder/annotation/configuration/PropertyNamePrefix.java

@@ -1,9 +1,5 @@
 package com.tngtech.configbuilder.annotation.configuration;
 
-import com.tngtech.configbuilder.annotation.valueextractor.CommandLineValue;
-import com.tngtech.configbuilder.annotation.valueextractor.DefaultValue;
-import com.tngtech.configbuilder.annotation.valueextractor.PropertyValue;
-
 import java.lang.annotation.*;
 
 /**
@@ -13,6 +9,5 @@
 @Target({ElementType.TYPE})
 @Retention(RetentionPolicy.RUNTIME)
 public @interface PropertyNamePrefix {
-    public String[] value() default {""};
-
+    String[] value() default {""};
 }

src/main/java/com/tngtech/configbuilder/annotation/propertyloaderconfiguration/PropertyExtension.java

@@ -13,5 +13,5 @@
 @Target(ElementType.TYPE)
 @Retention(RetentionPolicy.RUNTIME)
 public @interface PropertyExtension {
-    public String value();
+    String value();
 }