Add common parameter handling

This common module is proposed to handle all parameters and properties
for the ONAP Policy Framework in a common way.

Parameters and Properties:
- are validated once when they are loaded and need not be checked again
  in classes that use them
- are available for lookup in a parameter service, they need not be passed
  in constructors and method arguments
- are input using a single implementiation of input method only
  (JSON/YAML/Java properties/REST)
- are defined in a schema and the schema is used for validation as much
  as possible

Issue-ID: POLICY-922
Change-Id: I1fac88b9e952b6b5fcbea04319cb4294a9653327
Signed-off-by: liamfallon <liam.fallon@ericsson.com>

6 files changed, 428 insertions, 0 deletions

diff --git a/common-parameters/src/main/java/org/onap/policy/common/parameters/AbstractParameters.java b/common-parameters/src/main/java/org/onap/policy/common/parameters/AbstractParameters.java
new file mode 100644
index 00000000..5430dfeb
--- /dev/null
+++ b/common-parameters/src/main/java/org/onap/policy/common/parameters/AbstractParameters.java
@@ -0,0 +1,47 @@
+package org.onap.policy.common.parameters;
+/*
+ * ============LICENSE_START=======================================================
+ *  Copyright (C) 2018 Ericsson. 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.
+ * 
+ * SPDX-License-Identifier: Apache-2.0
+ * ============LICENSE_END=========================================================
+ */
+
+/**
+ * This class defines an abstract parameter interface that acts as a base interface for all parameters in the ONAP
+ * Policy Framework. All parameter POJOs are subclass of the abstract parameter class and can be used with the
+ * {@link ParameterService}.
+ *
+ * @author Liam Fallon (liam.fallon@ericsson.com)
+ */
+public interface AbstractParameters {
+    /**
+     * Gets the parameter class.
+     *
+     * @return the parameter class
+     */
+    default Class<? extends AbstractParameters> getParameterClass() {
+        return this.getClass();
+    }
+
+    /**
+     * Gets the parameter class name.
+     *
+     * @return the parameter class name
+     */
+    default String getParameterClassName() {
+        return this.getClass().getCanonicalName();
+    }
+}
diff --git a/common-parameters/src/main/java/org/onap/policy/common/parameters/ParameterException.java b/common-parameters/src/main/java/org/onap/policy/common/parameters/ParameterException.java
new file mode 100644
index 00000000..129d5390
--- /dev/null
+++ b/common-parameters/src/main/java/org/onap/policy/common/parameters/ParameterException.java
@@ -0,0 +1,112 @@
+/*-
+ * ============LICENSE_START=======================================================
+ *  Copyright (C) 2018 Ericsson. 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.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ * ============LICENSE_END=========================================================
+ */
+
+package org.onap.policy.common.parameters;
+
+/**
+ * Exception thrown oon parameter reading, validation, and check errors.
+ *
+ * @author Liam Fallon (liam.fallon@ericsson.com)
+ */
+public class ParameterException extends Exception {
+    private static final long serialVersionUID = -8507246953751956974L;
+
+    // The object on which the exception was thrown
+    private final transient Object object;
+
+    /**
+     * Instantiates a new parameter exception.
+     *
+     * @param message the message on the exception
+     */
+    public ParameterException(final String message) {
+        this(message, null);
+    }
+
+    /**
+     * Instantiates a new parameter exception.
+     *
+     * @param message the message on the exception
+     * @param object the object that the exception was thrown on
+     */
+    public ParameterException(final String message, final Object object) {
+        super(message);
+        this.object = object;
+    }
+
+    /**
+     * Instantiates a new parameter exception.
+     *
+     * @param message the message on the exception
+     * @param e the exception that caused this parameter exception
+     */
+    public ParameterException(final String message, final Exception e) {
+        this(message, e, null);
+    }
+
+    /**
+     * Instantiates a new parameter exception.
+     *
+     * @param message the message on the exception
+     * @param e the exception that caused this parameter exception
+     * @param object the object that the exception was thrown on
+     */
+    public ParameterException(final String message, final Exception e, final Object object) {
+        super(message, e);
+        this.object = object;
+    }
+
+    /**
+     * Get the message from this exception and its causes.
+     *
+     * @return the cascaded messages from this exception and the exceptions that caused it
+     */
+    public String getCascadedMessage() {
+        return buildCascadedMessage(this);
+    }
+
+    /**
+     * Build a cascaded message from an exception and all its nested exceptions
+     * 
+     * @param throwable the top level exception
+     * @return cascaded message string
+     */
+    public static String buildCascadedMessage(Throwable throwable) {
+        final StringBuilder builder = new StringBuilder();
+        builder.append(throwable.getMessage());
+
+        for (Throwable t = throwable; t != null; t = t.getCause()) {
+            builder.append("\ncaused by: ");
+            builder.append(t.getMessage());
+        }
+
+        return builder.toString();
+    }
+
+    /**
+     *
+     * Get the object on which the exception was thrown.
+     *
+     * @return The object on which the exception was thrown
+     */
+    public Object getObject() {
+        return object;
+    }
+}
diff --git a/common-parameters/src/main/java/org/onap/policy/common/parameters/ParameterRuntimeException.java b/common-parameters/src/main/java/org/onap/policy/common/parameters/ParameterRuntimeException.java
new file mode 100644
index 00000000..4b7d5874
--- /dev/null
+++ b/common-parameters/src/main/java/org/onap/policy/common/parameters/ParameterRuntimeException.java
@@ -0,0 +1,93 @@
+/*-
+ * ============LICENSE_START=======================================================
+ *  Copyright (C) 2018 Ericsson. 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.
+ * 
+ * SPDX-License-Identifier: Apache-2.0
+ * ============LICENSE_END=========================================================
+ */
+
+package org.onap.policy.common.parameters;
+
+/**
+ * A run time exception thrown on parameter validations.
+ *
+ * @author Liam Fallon (liam.fallon@ericsson.com)
+ */
+public class ParameterRuntimeException extends RuntimeException {
+    private static final long serialVersionUID = -8507246953751956974L;
+
+    // The object on which the exception was thrown
+    private final transient Object object;
+
+    /**
+     * Instantiates a new parameter runtime exception.
+     *
+     * @param message the message on the exception
+     */
+    public ParameterRuntimeException(final String message) {
+        this(message, null);
+    }
+
+    /**
+     * Instantiates a new parameter runtime exception.
+     *
+     * @param message the message on the exception
+     * @param object the object that the exception was thrown on
+     */
+    public ParameterRuntimeException(final String message, final Object object) {
+        super(message);
+        this.object = object;
+    }
+
+    /**
+     * Instantiates a new parameter runtime exception.
+     *
+     * @param message the message on the exception
+     * @param e the exception that caused this parameter exception
+     */
+    public ParameterRuntimeException(final String message, final Exception e) {
+        this(message, e, null);
+    }
+
+    /**
+     * Instantiates a new parameter runtime exception.
+     *
+     * @param message the message on the exception
+     * @param e the exception that caused this parameter exception
+     * @param object the object that the exception was thrown on
+     */
+    public ParameterRuntimeException(final String message, final Exception e, final Object object) {
+        super(message, e);
+        this.object = object;
+    }
+
+    /**
+     * Get the message from this exception and its causes.
+     *
+     * @return the message of this exception and all the exceptions that caused this exception
+     */
+    public String getCascadedMessage() {
+        return ParameterException.buildCascadedMessage(this);
+    }
+
+    /**
+     * Get the object on which the exception was thrown.
+     *
+     * @return The object
+     */
+    public Object getObject() {
+        return object;
+    }
+}
diff --git a/common-parameters/src/main/java/org/onap/policy/common/parameters/ParameterService.java b/common-parameters/src/main/java/org/onap/policy/common/parameters/ParameterService.java
new file mode 100644
index 00000000..f411937d
--- /dev/null
+++ b/common-parameters/src/main/java/org/onap/policy/common/parameters/ParameterService.java
@@ -0,0 +1,114 @@
+package org.onap.policy.common.parameters;
+/*
+ * ============LICENSE_START=======================================================
+ *  Copyright (C) 2018 Ericsson. 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.
+ * 
+ * SPDX-License-Identifier: Apache-2.0
+ * ============LICENSE_END=========================================================
+ */
+
+import java.util.Map;
+import java.util.Map.Entry;
+import java.util.Set;
+import java.util.concurrent.ConcurrentHashMap;
+
+/**
+ * The parameter service makes ONAP PF parameters available to all classes in a JVM.
+ *
+ * The reason for having a parameter service is to avoid having to pass parameters down long call chains in modules such
+ * as PDPs and editors. The parameter service makes correct and verified parameters available statically.
+ *
+ * The parameter service must be used with care because changing a parameter set anywhere in a JVM will affect all users
+ * of those parameters anywhere in the JVM.
+ *
+ * @author Liam Fallon (liam.fallon@ericsson.com)
+ */
+public abstract class ParameterService {
+    // The map holding the parameters
+    private static Map<Class<? extends AbstractParameters>, AbstractParameters> parameterMap = new ConcurrentHashMap<>();
+
+    /**
+     * This class is an abstract static class that cannot be extended.
+     */
+    private ParameterService() {
+    }
+
+    /**
+     * Register parameters with the parameter service.
+     *
+     * @param <P> the generic type
+     * @param parametersClass the class of the parameter, used to index the parameter
+     * @param parameters the parameters
+     */
+    public static <P extends AbstractParameters> void registerParameters(final P parameters) {
+        parameterMap.put(parameters.getClass(), parameters);
+    }
+
+    /**
+     * Remove parameters from the parameter service.
+     *
+     * @param <P> the generic type
+     * @param parametersClass the class of the parameter, used to index the parameter
+     */
+    public static <P extends AbstractParameters> void deregisterParameters(final Class<P> parametersClass) {
+        parameterMap.remove(parametersClass);
+    }
+
+    /**
+     * Get parameters from the parameter service.
+     *
+     * @param <P> the generic type
+     * @param parametersClass the class of the parameter, used to index the parameter
+     * @return The parameter
+     */
+    @SuppressWarnings("unchecked")
+    public static <P extends AbstractParameters> P getParameters(final Class<P> parametersClass) {
+        final P parameter = (P) parameterMap.get(parametersClass);
+
+        if (parameter == null) {
+            throw new ParameterRuntimeException(
+                            "Parameters for " + parametersClass.getCanonicalName() + " not found in parameter service");
+        }
+
+        return parameter;
+    }
+
+    /**
+     * Check if parameters is defined on the parameter service.
+     *
+     * @param <P> the generic type
+     * @param parametersClass the class of the parameter, used to index the parameter
+     * @return true if the parameter is defined
+     */
+    public static <P extends AbstractParameters> boolean existsParameters(final Class<P> parametersClass) {
+        return parameterMap.get(parametersClass) != null;
+    }
+
+    /**
+     * Get all the entries in the parameters map.
+     *
+     * @return The entries
+     */
+    public static Set<Entry<Class<? extends AbstractParameters>, AbstractParameters>> getAll() {
+        return parameterMap.entrySet();
+    }
+
+    /**
+     * Clear all parameters in the parameter service.
+     */
+    public static void clear() {
+        parameterMap.clear();
+    }
+}
diff --git a/common-parameters/src/main/java/org/onap/policy/common/parameters/ParameterValidator.java b/common-parameters/src/main/java/org/onap/policy/common/parameters/ParameterValidator.java
new file mode 100644
index 00000000..0d718267
--- /dev/null
+++ b/common-parameters/src/main/java/org/onap/policy/common/parameters/ParameterValidator.java
@@ -0,0 +1,36 @@
+/*-
+ * ============LICENSE_START=======================================================
+ *  Copyright (C) 2018 Ericsson. 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.
+ * 
+ * SPDX-License-Identifier: Apache-2.0
+ * ============LICENSE_END=========================================================
+ */
+
+package org.onap.policy.common.parameters;
+
+/**
+ * This interface is implemented by ONAP PF parameter classes so that they can be validated.
+ *
+ * @author Liam Fallon (liam.fallon@ericsson.com)
+ */
+public interface ParameterValidator {
+    /**
+     * Validate a parameter java bean, if the parameter bean is valid, an empty string is returned,
+     * otherwise the string gives details of the invalid parameters.
+     *
+     * @return the string with validation errors
+     */
+    String validate();
+}
diff --git a/common-parameters/src/main/java/org/onap/policy/common/parameters/package-info.java b/common-parameters/src/main/java/org/onap/policy/common/parameters/package-info.java
new file mode 100644
index 00000000..7ee1f833
--- /dev/null
+++ b/common-parameters/src/main/java/org/onap/policy/common/parameters/package-info.java
@@ -0,0 +1,26 @@
+/*-
+ * ============LICENSE_START=======================================================
+ *  Copyright (C) 2018 Ericsson. 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.
+ * 
+ * SPDX-License-Identifier: Apache-2.0
+ * ============LICENSE_END=========================================================
+ */
+
+/**
+ * Provides a common parameter service for the ONAP Policy Framework.
+ *
+ * @author Liam Fallon (liam.fallon@ericsson.com)
+ */
+package org.onap.policy.common.parameters;