tamaya-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From anat...@apache.org
Subject [01/27] incubator-tamaya git commit: TAMAYA-37: Added PropertyFilter
Date Sat, 03 Jan 2015 11:59:10 GMT
Repository: incubator-tamaya
Updated Branches:
  refs/heads/master 0791e8713 -> 95885781e


TAMAYA-37: Added PropertyFilter


Project: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/commit/cdb4d13d
Tree: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/tree/cdb4d13d
Diff: http://git-wip-us.apache.org/repos/asf/incubator-tamaya/diff/cdb4d13d

Branch: refs/heads/master
Commit: cdb4d13d39bee53220f740226ff42efeba609f4a
Parents: 0791e87
Author: anatole <anatole@apache.org>
Authored: Fri Jan 2 11:15:38 2015 +0100
Committer: anatole <anatole@apache.org>
Committed: Fri Jan 2 11:15:38 2015 +0100

----------------------------------------------------------------------
 .../apache/tamaya/spi/ConfigurationContext.java | 64 +++++++++++++++++---
 .../org/apache/tamaya/spi/PropertyFilter.java   | 53 ++++++++++++++++
 2 files changed, 108 insertions(+), 9 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/cdb4d13d/api/src/main/java/org/apache/tamaya/spi/ConfigurationContext.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/tamaya/spi/ConfigurationContext.java b/api/src/main/java/org/apache/tamaya/spi/ConfigurationContext.java
index 370683d..3dc0daa 100644
--- a/api/src/main/java/org/apache/tamaya/spi/ConfigurationContext.java
+++ b/api/src/main/java/org/apache/tamaya/spi/ConfigurationContext.java
@@ -21,6 +21,7 @@ package org.apache.tamaya.spi;
 
 import java.util.List;
 import java.util.Map;
+import java.util.function.UnaryOperator;
 
 /**
  * Central SPI for programmatically dealing with the setup of the configuration system.
@@ -38,12 +39,14 @@ public interface ConfigurationContext {
     void addPropertySources(PropertySource... propertySourcesToAdd);
 
     /**
-     * This method returns the list of registered PropertySources ordered via their ordinal.
+     * This method returns the current list of registered PropertySources ordered via their
ordinal.
      * PropertySources with a lower ordinal come first. The PropertySource with the
      * highest ordinal comes last.
      * If two PropertySources have the same ordinal number they will get sorted
      * using their class name just to ensure the user at least gets the same ordering
      * after a JVM restart.
+     * PropertySources are loaded when this method is called the first time, which basically
is
+     * when the first time configuration is accessed.
      *
      * @return sorted list of registered PropertySources
      */
@@ -63,33 +66,76 @@ public interface ConfigurationContext {
      * <p>
      * This method returns the Map of registered PropertyConverters
      * per type.
+     * The List for each type is ordered via their {@link javax.annotation.Priority} and
+     * cladd name. Refer also to {@link #getPropertyConverters()}.
+     * </p>
+     * <p>
+     * A simplified scenario could be like:
+     * <pre>
+     *  {
+     *      Date.class -> {StandardDateConverter, TimezoneDateConverter, MyCustomDateConverter
}
+     *      Boolean.class -> {StandardBooleanConverter, FrenchBooleanConverter}
+     *      Integer.class -> {DynamicDefaultConverter}
+     *  }
+     * </pre>
+     * </p>
+     *
+     * @return map with sorted list of registered PropertySources per type.
+     */
+    Map<Class<?>, List<PropertyConverter<?>>> getPropertyConverters();
+
+    /**
+     * <p>
+     * This method returns the registered PropertyConverters for a given type.
      * The List for each type is ordered via their {@link javax.annotation.Priority}.
      * </p>
      *
      * <p>
-     * PropertyConverters with a lower Priority come first. The PropertyConverter with the
-     * highest Priority comes last.
+     * PropertyConverters with a higher Priority come first. The PropertyConverter with the
+     * lowest Priority comes last.
      * If two PropertyConverter have the same ordinal number they will get sorted
      * using their class name just to ensure the user at least gets the same ordering
      * after a JVM restart.
      * </p>
      *
      * <p>
+     * Additionally if a PropertyProvider is accessed, which is not registered the implementation
+     * should try to figure out, if there could be a default implementation as follows:
+     * <ol>
+     *     <le>Look for static factory methods: {@code of(String), valueOf(String),
getInstance(String),
+     *     instanceOf(String), fomr(String)}</le>
+     *     <le>Look for a matching constructor: {@code T(String)}.</le>
+     * </ol>
+     * If a correspoding factory method or constructor could be found, a corresponding
+     * PropertyConverter should be created and registered automatically for the given
+     * type.
+     * </p>
+     *
+     * <p>
      * The scenario could be like:
      * <pre>
      *  {
-     *      Date.class -> {StandardDateConverter, TimezoneDateConverter, MyCustomDateConverter
}
+     *      Date.class -> {MyCustomDateConverter,StandardDateConverter, TimezoneDateConverter}
      *      Boolean.class -> {StandardBooleanConverter, FrenchBooleanConverter}
+     *      Integer.class -> {DynamicDefaultConverter}
      *  }
      * </pre>
      * </p>
      *
-     * TODO: we need to define in which order the converters will be used later!
+     * <p>
+     * The converters returned for a type should be used as a chain, whereas the result of
the
+     * first converter that is able to convert the configured value, is taken as the chain's
result.
+     * No more converters are called after a converter has successfully converted the input
into
+     * the required target type.
+     * </p>
      *
-     * @return map with sorted list of registered PropertySources per type.
+     * @return a sorted list of registered PropertySources per type.
      */
-    Map<Class<?>, List<PropertyConverter<?>>> getPropertyConverters();
+    <T> List<PropertyConverter<T>> getPropertyConverters(Class<T>
type);
 
-
-    //X TODO add a way to manage and use PropertyFilters
+    /**
+     * Access the current PropertyFilter instances.
+     * @return the list of registered PropertyFilters, never null.
+     */
+    List<PropertyFilter> getPropertyFilters();
 }

http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/cdb4d13d/api/src/main/java/org/apache/tamaya/spi/PropertyFilter.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/tamaya/spi/PropertyFilter.java b/api/src/main/java/org/apache/tamaya/spi/PropertyFilter.java
new file mode 100644
index 0000000..7479008
--- /dev/null
+++ b/api/src/main/java/org/apache/tamaya/spi/PropertyFilter.java
@@ -0,0 +1,53 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you 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.
+ */
+package org.apache.tamaya.spi;
+
+
+import java.util.Map;
+
+/**
+ * <p>Interface for filtering the current map of properties during the evaluation of
the chain of PropertySources.
+ * Filters can be registered using the {@link org.apache.tamaya.spi.ServiceContext}. The
ordinal
+ * hereby is defined by the corresponding {@code @Priority} annotation.</p>
+ * <p>Filters </p>
+ */
+public interface PropertyFilter<T>{
+
+    /**
+     * <p>Maps the current {@code valueToBeFiltered} value to a new value. The resulting
value will be used as the result
+     * passed to the user.</p>
+     * <p>If a filter is currently not available, it should just pass the input map
to the method's
+     * output.</p>
+     * <p>Returning {@code null} will remove the entry and Optional.empty() will be
returned to the user.</p>
+     * <h3>Implementation specification</h3>
+     * Implementations of this class must be
+     * <ul>
+     *     <li>reentrant</li>
+     *     <li>thread-safe</li>
+     * </ul>
+     *
+     * @param key the key accessed, not null.
+     * @param valueToBeFiltered the value to be filtered, not null.
+     * @param currentMap the current input property map, not null. Can be used for resolution
of the filtered value
+     *                   or as datasource for additional meta-information, such as categories,
sensitivity etc.
+     * @return the filtered map, never null.
+     */
+    String filterProperty(String key, String valueToBeFiltered, Map<String,String>
currentMap);
+
+}


Mime
View raw message