Add PropertyConfiguration class

Added PropertyConfiguration class, which provides for the loading of
properties into the fields of a subclass.  Annotations are used to
identify the field to be loaded and the name of the property from
which it is to be loaded.
Changed attribute "useDefault" to "emptyOk" so that it only has to
be specified when the default value is empty.
Reformatted a couple of files.
Added setAllFields() method.
Added getRawPropertyValue() method so subclasses can change how
values are extracted from the property set.
Added SpecPropertyConfiguration so controller or session names
may be embedded within property names.
Fixed some typos.
Refactored out generalizeType2().
Changed exception classes to take field name instead of Field object.
Modified getValue() to take the field name and class type instead of
Field object.
Removed or fixed comments in junit tests.
Added more junit tests.
Changed emptyOk attribute to accept, to facilitate adding other
options in the future.
Corrected comments on the isEmptyOk() methods.

Change-Id: I6b190fea687f87cf512fb3236bfcf40b7adc4566
Issue-ID: POLICY-577
Signed-off-by: Jim Hahn <jrh3@att.com>

1 files changed, 465 insertions, 0 deletions

diff --git a/utils/src/main/java/org/onap/policy/common/utils/properties/PropertyConfiguration.java b/utils/src/main/java/org/onap/policy/common/utils/properties/PropertyConfiguration.java
new file mode 100644
index 00000000..7253c746
--- /dev/null
+++ b/utils/src/main/java/org/onap/policy/common/utils/properties/PropertyConfiguration.java
@@ -0,0 +1,465 @@
+/*
+ * ============LICENSE_START=======================================================
+ * ONAP Policy Engine - Common Modules
+ * ================================================================================
+ * Copyright (C) 2018 AT&T Intellectual Property. All rights reserved.
+ * ================================================================================
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * 
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ * 
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * ============LICENSE_END=========================================================
+ */
+
+package org.onap.policy.common.utils.properties;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+import java.lang.reflect.Field;
+import java.lang.reflect.Modifier;
+import java.util.Properties;
+import org.onap.policy.common.utils.properties.exception.PropertyAccessException;
+import org.onap.policy.common.utils.properties.exception.PropertyException;
+import org.onap.policy.common.utils.properties.exception.PropertyInvalidException;
+import org.onap.policy.common.utils.properties.exception.PropertyMissingException;
+
+/**
+ * Configuration whose fields are initialized by reading from a set of {@link Properties},
+ * as directed by the {@link Property} annotations that appear on fields within the
+ * subclass.
+ * <p>
+ * It is possible that an invalid <i>defaultValue</i> is specified via the
+ * {@link Property} annotation. This could remain undetected until an optional property is
+ * left out of the {@link Properties}. Consequently, this class will always validate a
+ * {@link Property}'s default value, if the <i>defaultValue</i> is not empty or if
+ * <i>accept</i> includes the "empty" option.
+ */
+public class PropertyConfiguration {
+
+    /**
+     * The "empty" option that may appear within the {@link Property}'s <i>accept</i>
+     * attribute.
+     */
+    public static final String ACCEPT_EMPTY = "empty";
+
+    /**
+     * Constructs a configuration, without populating any fields; fields should be
+     * populated later by invoking {@link #setAllFields(Properties)}.
+     */
+    public PropertyConfiguration() {
+        super();
+    }
+
+    /**
+     * Initializes each "@Property" field with its value, as found in the properties.
+     * 
+     * @param props properties from which to extract the values
+     * @throws PropertyException if an error occurs
+     */
+    public PropertyConfiguration(Properties props) throws PropertyException {
+        setAllFields(props);
+    }
+
+    /**
+     * Walks the class hierarchy of "this" object, populating fields defined in each
+     * class, using values extracted from the given property set.
+     * 
+     * @param props properties from which to extract the values
+     * @throws PropertyException if an error occurs
+     */
+    public void setAllFields(Properties props) throws PropertyException {
+        Class<?> clazz = getClass();
+
+        while (clazz != PropertyConfiguration.class) {
+            for (Field field : clazz.getDeclaredFields()) {
+                setValue(field, props);
+            }
+
+            clazz = clazz.getSuperclass();
+        }
+    }
+
+    /**
+     * Sets a field's value, within an object, based on what's in the properties.
+     * 
+     * @param field field whose value is to be set
+     * @param props properties from which to get the value
+     * @return {@code true} if the property's value was set, {@code false} otherwise
+     * @throws PropertyException if an error occurs
+     */
+    protected boolean setValue(Field field, Properties props) throws PropertyException {
+        Property prop = field.getAnnotation(Property.class);
+        if (prop == null) {
+            return false;
+        }
+
+        checkModifiable(field, prop);
+
+        if (setValue(field, props, prop)) {
+            return true;
+        }
+
+        throw new PropertyAccessException(prop.name(), field.getName(), "unsupported field type");
+    }
+
+    /**
+     * Sets a field's value from a particular property.
+     * 
+     * @param field field whose value is to be set
+     * @param props properties from which to get the value
+     * @param prop property of interest
+     * @return {@code true} if the property's value was set, {@code false} otherwise
+     * @throws PropertyException if an error occurs
+     */
+    protected boolean setValue(Field field, Properties props, Property prop) throws PropertyException {
+
+        try {
+            Object val = getValue(field, props, prop);
+            if (val == null) {
+                return false;
+
+            } else {
+
+                /*
+                 * According to java docs & blogs, "field" is our own copy, so we're free
+                 * to change the flags without impacting the real permissions of the field
+                 * within the real class.
+                 */
+                field.setAccessible(true);
+
+                field.set(this, val);
+                return true;
+            }
+
+        } catch (IllegalArgumentException e) {
+            throw new PropertyInvalidException(prop.name(), field.getName(), e);
+
+        } catch (IllegalAccessException e) {
+            throw new PropertyAccessException(prop.name(), field.getName(), e);
+        }
+    }
+
+    /**
+     * Gets a property value, coercing it to the field's type.
+     * 
+     * @param field field whose value is to be set
+     * @param props properties from which to get the value
+     * @param prop property of interest
+     * @return the value extracted from the property, or {@code null} if the field type is
+     *         not supported
+     * @throws PropertyException if an error occurs
+     */
+    protected Object getValue(Field field, Properties props, Property prop) throws PropertyException {
+
+        Class<?> clazz = field.getType();
+        String fieldName = field.getName();
+
+        // can still add support for short, float, double, enum
+
+        if (clazz == String.class) {
+            return getStringValue(fieldName, props, prop);
+
+        } else if (clazz == Boolean.class || clazz == boolean.class) {
+            return getBooleanValue(fieldName, props, prop);
+
+        } else if (clazz == Integer.class || clazz == int.class) {
+            return getIntegerValue(fieldName, props, prop);
+
+        } else if (clazz == Long.class || clazz == long.class) {
+            return getLongValue(fieldName, props, prop);
+
+        } else {
+            return null;
+        }
+    }
+
+    /**
+     * Verifies that the field can be modified, i.e., it's neither <i>static</i>, nor
+     * <i>final</i>.
+     * 
+     * @param field field whose value is to be set
+     * @param prop property of interest
+     * @throws PropertyAccessException if the field is not modifiable
+     */
+    protected void checkModifiable(Field field, Property prop) throws PropertyAccessException {
+        int mod = field.getModifiers();
+
+        if (Modifier.isStatic(mod)) {
+            throw new PropertyAccessException(prop.name(), field.getName(), "'static' variable cannot be modified");
+        }
+
+        if (Modifier.isFinal(mod)) {
+            throw new PropertyAccessException(prop.name(), field.getName(), "'final' variable cannot be modified");
+        }
+    }
+
+    /**
+     * Gets a property value, coercing it to a String.
+     * 
+     * @param fieldName field whose value is to be set
+     * @param props properties from which to get the value
+     * @param prop property of interest
+     * @return the value extracted from the property
+     * @throws PropertyException if an error occurs
+     */
+    protected String getStringValue(String fieldName, Properties props, Property prop) throws PropertyException {
+
+        /*
+         * Note: the default value for a String type is always valid, thus no need to
+         * check it.
+         */
+
+        return getPropValue(fieldName, props, prop);
+    }
+
+    /**
+     * Gets a property value, coercing it to a Boolean.
+     * 
+     * @param fieldName field whose value is to be set
+     * @param props properties from which to get the value
+     * @param prop property of interest
+     * @return the value extracted from the property
+     * @throws PropertyException if an error occurs
+     */
+    protected Boolean getBooleanValue(String fieldName, Properties props, Property prop) throws PropertyException {
+        // validate the default value
+        checkDefaultValue(fieldName, prop, xxx -> makeBoolean(fieldName, prop, prop.defaultValue()));
+
+        return makeBoolean(fieldName, prop, getPropValue(fieldName, props, prop));
+    }
+
+    /**
+     * Gets a property value, coercing it to an Integer.
+     * 
+     * @param fieldName field whose value is to be set
+     * @param props properties from which to get the value
+     * @param prop property of interest
+     * @return the value extracted from the property
+     * @throws PropertyException if an error occurs
+     */
+    protected Integer getIntegerValue(String fieldName, Properties props, Property prop) throws PropertyException {
+        // validate the default value
+        checkDefaultValue(fieldName, prop, xxx -> makeInteger(fieldName, prop, prop.defaultValue()));
+
+        return makeInteger(fieldName, prop, getPropValue(fieldName, props, prop));
+    }
+
+    /**
+     * Gets a property value, coercing it to a Long.
+     * 
+     * @param fieldName field whose value is to be set
+     * @param props properties from which to get the value
+     * @param prop property of interest
+     * @return the value extracted from the property
+     * @throws PropertyException if an error occurs
+     */
+    protected Long getLongValue(String fieldName, Properties props, Property prop) throws PropertyException {
+        // validate the default value
+        checkDefaultValue(fieldName, prop, xxx -> makeLong(fieldName, prop, prop.defaultValue()));
+
+        return makeLong(fieldName, prop, getPropValue(fieldName, props, prop));
+    }
+
+    /**
+     * Gets a value from the property set.
+     * 
+     * @param fieldName field whose value is to be set
+     * @param props properties from which to get the value
+     * @param prop property of interest
+     * @return the value extracted from the property, or the <i>defaultValue</i> if the
+     *         value does not exist
+     * @throws PropertyMissingException if the property does not exist and the
+     *         <i>defaultValue</i> is empty and <i>emptyOk</i> is {@code false}
+     */
+    protected String getPropValue(String fieldName, Properties props, Property prop) throws PropertyMissingException {
+        String propnm = prop.name();
+
+        String val = getRawPropertyValue(props, propnm);
+        if (val != null && isEmptyOk(prop, val)) {
+            return val;
+        }
+
+        val = prop.defaultValue();
+        if (val != null && isEmptyOk(prop, val)) {
+            return val;
+        }
+
+        throw new PropertyMissingException(prop.name(), fieldName);
+    }
+
+    /**
+     * Gets the property value, straight from the property set.
+     * 
+     * @param props properties from which to get the value
+     * @param propnm name of the property of interest
+     * @return
+     */
+    protected String getRawPropertyValue(Properties props, String propnm) {
+        return props.getProperty(propnm);
+    }
+
+    /**
+     * Coerces a String value into a Boolean.
+     * 
+     * @param fieldName field whose value is to be set
+     * @param prop property of interest
+     * @param value value to be coerced
+     * @return the Boolean value represented by the String value
+     * @throws PropertyInvalidException if the value does not represent a valid Boolean
+     */
+    private Boolean makeBoolean(String fieldName, Property prop, String value) throws PropertyInvalidException {
+        if ("true".equals(value.toLowerCase())) {
+            return Boolean.TRUE;
+
+        } else if ("false".equals(value.toLowerCase())) {
+            return Boolean.FALSE;
+
+        } else {
+            throw new PropertyInvalidException(prop.name(), fieldName, "expecting 'true' or 'false'");
+        }
+    }
+
+    /**
+     * Coerces a String value into an Integer.
+     * 
+     * @param fieldName field whose value is to be set
+     * @param prop property of interest
+     * @param value value to be coerced
+     * @return the Integer value represented by the String value
+     * @throws PropertyInvalidException if the value does not represent a valid Integer
+     */
+    private Integer makeInteger(String fieldName, Property prop, String value) throws PropertyInvalidException {
+        try {
+            return Integer.valueOf(value);
+
+        } catch (NumberFormatException e) {
+            throw new PropertyInvalidException(prop.name(), fieldName, e);
+        }
+    }
+
+    /**
+     * Coerces a String value into a Long.
+     * 
+     * @param fieldName field whose value is to be set
+     * @param prop property of interest
+     * @param value value to be coerced
+     * @return the Long value represented by the String value
+     * @throws PropertyInvalidException if the value does not represent a valid Long
+     */
+    private Long makeLong(String fieldName, Property prop, String value) throws PropertyInvalidException {
+        try {
+            return Long.valueOf(value);
+
+        } catch (NumberFormatException e) {
+            throw new PropertyInvalidException(prop.name(), fieldName, e);
+        }
+    }
+
+    /**
+     * Applies a function to check a property's default value. If the function throws an
+     * exception about an invalid property, then it's re-thrown as an exception about an
+     * invalid <i>defaultValue</i>.
+     * 
+     * @param fieldName name of the field being checked
+     * @param prop property of interest
+     * @param func function to invoke to check the default value
+     */
+    private void checkDefaultValue(String fieldName, Property prop, CheckDefaultValueFunction func)
+                    throws PropertyInvalidException {
+
+        if (isEmptyOk(prop, prop.defaultValue())) {
+            try {
+                func.apply(null);
+
+            } catch (PropertyInvalidException ex) {
+                throw new PropertyInvalidException(ex.getPropertyName(), fieldName, "defaultValue is invalid",
+                                ex.getCause());
+            }
+        }
+    }
+
+    /**
+     * Determines if a value is OK, even if it's empty.
+     * 
+     * @param prop property specifying what's acceptable
+     * @param value value to be checked
+     * @return {@code true} if the value is not empty or empty is allowed, {@code false}
+     *         otherwise
+     */
+    protected boolean isEmptyOk(Property prop, String value) {
+        return !value.isEmpty() || isEmptyOk(prop);
+    }
+
+    /**
+     * Determines if a {@link Property}'s <i>accept</i> attribute includes the "empty"
+     * option.
+     * 
+     * @param prop property whose <i>accept</i> attribute is to be examined
+     * @return {@code true} if the <i>accept</i> attribute includes "empty"
+     */
+    protected boolean isEmptyOk(Property prop) {
+        for (String option : prop.accept().split(",")) {
+            if (ACCEPT_EMPTY.equals(option)) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    /**
+     * Functions to check a default value.
+     */
+    @FunctionalInterface
+    private static interface CheckDefaultValueFunction {
+
+        /**
+         * Checks the default value.
+         * 
+         * @param arg always {@code null}
+         * @throws PropertyInvalidException if an error occurs
+         */
+        public void apply(Void arg) throws PropertyInvalidException;
+    }
+
+    /**
+     * Annotation that declares a variable to be configured via {@link Properties}.
+     */
+    @Target(ElementType.FIELD)
+    @Retention(RetentionPolicy.RUNTIME)
+
+    protected static @interface Property {
+
+        /**
+         * Name of the property.
+         * 
+         * @return the property name
+         */
+        public String name();
+
+        /**
+         * Default value, used when the property does not exist.
+         * 
+         * @return the default value
+         */
+        public String defaultValue() default "";
+
+        /**
+         * Comma-separated options identifying what's acceptable. The word, "empty",
+         * indicates that an empty string, "", is an acceptable value.
+         * 
+         * @return options identifying what's acceptable
+         */
+        public String accept() default "";
+
+    }
+}