tamaya-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From anat...@apache.org
Subject incubator-tamaya git commit: TAMAYA-8: added/improved Javadocs.
Date Sat, 29 Nov 2014 21:30:28 GMT
Repository: incubator-tamaya
Updated Branches:
  refs/heads/master 6228b1719 -> 4b9e587f7


TAMAYA-8: added/improved Javadocs.


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

Branch: refs/heads/master
Commit: 4b9e587f7e7d8443fd0c6e175ff117fd34ab866b
Parents: 6228b17
Author: anatole <anatole@apache.org>
Authored: Sat Nov 29 22:30:18 2014 +0100
Committer: anatole <anatole@apache.org>
Committed: Sat Nov 29 22:30:18 2014 +0100

----------------------------------------------------------------------
 .../java/org/apache/tamaya/ConfigChangeSet.java |  2 +-
 .../main/java/org/apache/tamaya/MetaInfo.java   | 34 +++++++++++++++++++-
 .../java/org/apache/tamaya/PropertyAdapter.java |  6 ++--
 .../org/apache/tamaya/PropertyAdapters.java     |  2 +-
 .../tamaya/annot/ConfigChangeListener.java      |  3 +-
 .../tamaya/annot/ConfiguredProperties.java      |  2 +-
 .../org/apache/tamaya/annot/DefaultAreas.java   |  6 +++-
 .../org/apache/tamaya/annot/DefaultValue.java   |  4 ++-
 .../org/apache/tamaya/annot/LoadPolicy.java     |  3 +-
 .../org/apache/tamaya/annot/WithConfig.java     |  3 +-
 .../apache/tamaya/annot/WithConfigOperator.java |  4 ++-
 .../org/apache/tamaya/annot/WithLoadPolicy.java |  3 +-
 .../tamaya/annot/WithPropertyAdapter.java       |  4 ++-
 .../spi/ConfigurationManagerSingletonSpi.java   |  7 ++--
 .../apache/tamaya/spi/StagesSingletonSpi.java   |  2 +-
 15 files changed, 66 insertions(+), 19 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/4b9e587f/api/src/main/java/org/apache/tamaya/ConfigChangeSet.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/tamaya/ConfigChangeSet.java b/api/src/main/java/org/apache/tamaya/ConfigChangeSet.java
index 11bff0b..76a7cea 100644
--- a/api/src/main/java/org/apache/tamaya/ConfigChangeSet.java
+++ b/api/src/main/java/org/apache/tamaya/ConfigChangeSet.java
@@ -59,7 +59,7 @@ public final class ConfigChangeSet {
 
     /**
      * Get the underlying property provider/configuration.
-     * @return the underlying property provider/configuration, never null, unless for {@link
EMPTY_CHANGESET}.
+     * @return the underlying property provider/configuration, never null.
      */
     public PropertyProvider getPropertyProvider(){
         return this.propertyProvider;

http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/4b9e587f/api/src/main/java/org/apache/tamaya/MetaInfo.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/tamaya/MetaInfo.java b/api/src/main/java/org/apache/tamaya/MetaInfo.java
index 0ca0044..3d20723 100644
--- a/api/src/main/java/org/apache/tamaya/MetaInfo.java
+++ b/api/src/main/java/org/apache/tamaya/MetaInfo.java
@@ -25,32 +25,59 @@ import java.util.*;
  * configuration or some if its entries.
  */
 public final class MetaInfo{
-
+    /** The key used for storing the data owner. */
     private static final String OWNER_KEY = "_owner";
+    /** The meta information data. */
     private final Map<String, String> metaInfo = new HashMap<>();
 
+    /**
+     * Constructor, used from the builder.
+     * @param builder the builder, not null.
+     */
     MetaInfo(MetaInfoBuilder builder){
         Objects.requireNonNull(builder);
         this.metaInfo.putAll(builder.map);
     }
 
+    /**
+     * Returns a new instance of this class, adding only a general information property.
+     * @param info the info property, not null.
+     * @return a new instance of this class, never null.
+     */
     public static MetaInfo of(String info){
         return MetaInfoBuilder.of(info).build();
     }
 
+    /**
+     * Access a meta data property.
+     * @param key the property key, not null.
+     * @return the corresponding property value, or null.
+     */
     public String get(String key){
         return this.metaInfo.get(key);
 
     }
 
+    /**
+     * Get the information about the data owner.
+     * @return the data owner info, or null.
+     */
     public String getOwnerInfo(){
         return this.metaInfo.get(OWNER_KEY);
     }
 
+    /**
+     * @see java.util.Map#keySet()
+     * @return the key set.
+     */
     public Set<String> keySet(){
         return this.metaInfo.keySet();
     }
 
+    /**
+     * Access the meta info as map.
+     * @return the corresponding map, never null.
+     */
     public Map<? extends String,? extends String> toMap(){
         return Collections.unmodifiableMap(this.metaInfo);
     }
@@ -68,6 +95,11 @@ public final class MetaInfo{
         return b.toString();
     }
 
+    /**
+     * Helper method to escape "=\\[]".
+     * @param val the input value, not null.
+     * @return the escaped String, not null.
+     */
     static String escape(String val){
         return val.replaceAll("=", "\\\\=").replaceAll("\\[", "\\\\[").replaceAll("]", "\\\\]").replaceAll("\\,",
"\\\\,");
     }

http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/4b9e587f/api/src/main/java/org/apache/tamaya/PropertyAdapter.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/tamaya/PropertyAdapter.java b/api/src/main/java/org/apache/tamaya/PropertyAdapter.java
index 9423e03..8a238b4 100644
--- a/api/src/main/java/org/apache/tamaya/PropertyAdapter.java
+++ b/api/src/main/java/org/apache/tamaya/PropertyAdapter.java
@@ -21,14 +21,16 @@ package org.apache.tamaya;
 
 /**
  * Interface for an adapter that converts a configured String into something else.
+ * This is typically used for implementing type conversion from String to a certain target
+ * type of the configured property.
  */
 @FunctionalInterface
 public interface PropertyAdapter<T>{
 
     /**
      * Adapt the given configuration value to the required target type.
-     * @param value
-     * @return
+     * @param value the configuration value
+     * @return adapted value
      */
     T adapt(String value);
 

http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/4b9e587f/api/src/main/java/org/apache/tamaya/PropertyAdapters.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/tamaya/PropertyAdapters.java b/api/src/main/java/org/apache/tamaya/PropertyAdapters.java
index 2103f60..d967e3f 100644
--- a/api/src/main/java/org/apache/tamaya/PropertyAdapters.java
+++ b/api/src/main/java/org/apache/tamaya/PropertyAdapters.java
@@ -24,7 +24,7 @@ import org.apache.tamaya.spi.PropertyAdaptersSingletonSpi;
 import java.util.Optional;
 
 /**
- * Singleton accessor that provides {@link PropertyAdapter} instance, usable for converting
String
+ * Singleton manager that provides {@link PropertyAdapter} instance, usable for converting
String
  * based configuration entries into any other target types.
  */
 public final class PropertyAdapters{

http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/4b9e587f/api/src/main/java/org/apache/tamaya/annot/ConfigChangeListener.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/tamaya/annot/ConfigChangeListener.java b/api/src/main/java/org/apache/tamaya/annot/ConfigChangeListener.java
index dcf895e..e745a10 100644
--- a/api/src/main/java/org/apache/tamaya/annot/ConfigChangeListener.java
+++ b/api/src/main/java/org/apache/tamaya/annot/ConfigChangeListener.java
@@ -27,7 +27,8 @@ import java.lang.annotation.Target;
  * Annotation to annotate a method on a class to be informed on config changes.
  * The exact behaviour, when configuration change events are sent can be configured
  * on each configured property/method by adding the {@link org.apache.tamaya.annot.WithLoadPolicy}
- * annotation.
+ * annotation. By default listeners are only informed about changes that are affecting configured
+ * values of the containing class/instance.
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(value = { ElementType.METHOD })

http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/4b9e587f/api/src/main/java/org/apache/tamaya/annot/ConfiguredProperties.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/tamaya/annot/ConfiguredProperties.java b/api/src/main/java/org/apache/tamaya/annot/ConfiguredProperties.java
index f97b63b..fd8c057 100644
--- a/api/src/main/java/org/apache/tamaya/annot/ConfiguredProperties.java
+++ b/api/src/main/java/org/apache/tamaya/annot/ConfiguredProperties.java
@@ -24,7 +24,7 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * Annotation to enable injection of multiple {@link org.apache.tamaya.annot.ConfiguredProperty}
+ * Annotation container to enable injection of multiple {@link org.apache.tamaya.annot.ConfiguredProperty}
  * annotations. Hereby the ordering of annotations imply the defaulting. The first value
that
  * could be resolved successfully in the chain of annotations will be used.
  */

http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/4b9e587f/api/src/main/java/org/apache/tamaya/annot/DefaultAreas.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/tamaya/annot/DefaultAreas.java b/api/src/main/java/org/apache/tamaya/annot/DefaultAreas.java
index bb4fba5..5dc4566 100644
--- a/api/src/main/java/org/apache/tamaya/annot/DefaultAreas.java
+++ b/api/src/main/java/org/apache/tamaya/annot/DefaultAreas.java
@@ -24,7 +24,11 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * Annotation to control injection and resolution of a configured bean.
+ * Annotation to control injection and resolution of a configured bean. The configuration
keys
+ * to be resolved are basically determined by the {@link org.apache.tamaya.annot.ConfiguredProperty}
+ * annotation(s). Nevertheless these annotations can also have relative key names. This annotation
allows
+ * to define a configuration area that is prefixed to all relative configuration keys within
the
+ * corresponding class/template interface.
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(value = { ElementType.TYPE })

http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/4b9e587f/api/src/main/java/org/apache/tamaya/annot/DefaultValue.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/tamaya/annot/DefaultValue.java b/api/src/main/java/org/apache/tamaya/annot/DefaultValue.java
index f9b9586..6c818f2 100644
--- a/api/src/main/java/org/apache/tamaya/annot/DefaultValue.java
+++ b/api/src/main/java/org/apache/tamaya/annot/DefaultValue.java
@@ -24,7 +24,9 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * Annotation to enable injection of a configured property.
+ * Annotation to define a default value to be returned, when no configured value could be
+ * determined for a property/template accessor. The value hereby can also contain a
+ * dynamic expression that is evaluated by the configuration system.
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(value = { ElementType.FIELD, ElementType.METHOD })

http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/4b9e587f/api/src/main/java/org/apache/tamaya/annot/LoadPolicy.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/tamaya/annot/LoadPolicy.java b/api/src/main/java/org/apache/tamaya/annot/LoadPolicy.java
index f159432..ebc7ebe 100644
--- a/api/src/main/java/org/apache/tamaya/annot/LoadPolicy.java
+++ b/api/src/main/java/org/apache/tamaya/annot/LoadPolicy.java
@@ -20,7 +20,8 @@ package org.apache.tamaya.annot;
 
 /**
  * Available policies that describe how changes affecting configured values are published/reinjected.
- * Created by Anatole on 10.10.2014.
+ * The policy also affects the cases were any configured listeners/listener methods are called
for
+ * propagation of configuration changes.
  */
 public enum LoadPolicy {
     /**

http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/4b9e587f/api/src/main/java/org/apache/tamaya/annot/WithConfig.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/tamaya/annot/WithConfig.java b/api/src/main/java/org/apache/tamaya/annot/WithConfig.java
index 0cd40a3..1e4ac3d 100644
--- a/api/src/main/java/org/apache/tamaya/annot/WithConfig.java
+++ b/api/src/main/java/org/apache/tamaya/annot/WithConfig.java
@@ -25,7 +25,8 @@ import java.lang.annotation.Target;
 
 /**
  * Annotation to reference an explicit {@link org.apache.tamaya.Configuration} to be used
to
- * resolve the required properties.
+ * resolve the required properties. the configured value is passed to {@code Configuration.of(String)}
+ * to evaluate the required configuration required.
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(value = { ElementType.TYPE, ElementType.FIELD, ElementType.METHOD })

http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/4b9e587f/api/src/main/java/org/apache/tamaya/annot/WithConfigOperator.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/tamaya/annot/WithConfigOperator.java b/api/src/main/java/org/apache/tamaya/annot/WithConfigOperator.java
index a4e39d6..582a0da 100644
--- a/api/src/main/java/org/apache/tamaya/annot/WithConfigOperator.java
+++ b/api/src/main/java/org/apache/tamaya/annot/WithConfigOperator.java
@@ -26,7 +26,9 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * Annotation to define an adapter to be used before injecting a configured value.
+ * Annotation to define an configuration operator to be used before accessing a configured
value.
+ * This allows filtering of configuration, e.g. for realizing views or ensuring security
+ * constraints.
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(value = { ElementType.FIELD, ElementType.METHOD, ElementType.TYPE })

http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/4b9e587f/api/src/main/java/org/apache/tamaya/annot/WithLoadPolicy.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/tamaya/annot/WithLoadPolicy.java b/api/src/main/java/org/apache/tamaya/annot/WithLoadPolicy.java
index 786293b..9a1a40c 100644
--- a/api/src/main/java/org/apache/tamaya/annot/WithLoadPolicy.java
+++ b/api/src/main/java/org/apache/tamaya/annot/WithLoadPolicy.java
@@ -24,7 +24,8 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * Annotation to define how config changes are handled in general for a type or per property.
+ * Annotation to define how config changes are handled for a type or per property/template
method.
+ * @see org.apache.tamaya.annot.LoadPolicy
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(value = { ElementType.FIELD, ElementType.METHOD, ElementType.TYPE })

http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/4b9e587f/api/src/main/java/org/apache/tamaya/annot/WithPropertyAdapter.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/tamaya/annot/WithPropertyAdapter.java b/api/src/main/java/org/apache/tamaya/annot/WithPropertyAdapter.java
index b01dff1..f7e060e 100644
--- a/api/src/main/java/org/apache/tamaya/annot/WithPropertyAdapter.java
+++ b/api/src/main/java/org/apache/tamaya/annot/WithPropertyAdapter.java
@@ -26,7 +26,9 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
 /**
- * Annotation to define an adapter to be used before injecting a configured value.
+ * Annotation to define a type adapter to be used before injecting a configured value.
+ * This will override any other adapter for performing the type conversion before
+ * injecting the field value.
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(value = { ElementType.FIELD, ElementType.METHOD })

http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/4b9e587f/api/src/main/java/org/apache/tamaya/spi/ConfigurationManagerSingletonSpi.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/tamaya/spi/ConfigurationManagerSingletonSpi.java
b/api/src/main/java/org/apache/tamaya/spi/ConfigurationManagerSingletonSpi.java
index 2b796f9..8e777ef 100644
--- a/api/src/main/java/org/apache/tamaya/spi/ConfigurationManagerSingletonSpi.java
+++ b/api/src/main/java/org/apache/tamaya/spi/ConfigurationManagerSingletonSpi.java
@@ -25,10 +25,10 @@ import java.beans.PropertyChangeListener;
 /**
  * Manager for {@link org.apache.tamaya.Configuration} instances. Implementations must register
an instance
  * using the {@link Bootstrap} mechanism in place (by default this is based on the {@link
java.util.ServiceLoader}.
- * The {@link org.javaconfig.ConfigurationManager} Singleton in the API delegates its corresponding
calls to the
+ * The {@link org.apache.tamaya.ConfigurationManager} Singleton in the API delegates its
corresponding calls to the
  * instance returned by the current bootstrap service in place.
  *
- * @see org.javaconfig.ConfigurationManager
+ * @see org.apache.tamaya.ConfigurationManager
  * @see Bootstrap
  */
 public interface ConfigurationManagerSingletonSpi{
@@ -64,8 +64,7 @@ public interface ConfigurationManagerSingletonSpi{
      * entries.
      *
      * @param instance the instance with configuration annotations, not null.
-     * @return the corresponding typed Configuration instance, never null.
-     * @throws org.apache.tamaya.ConfigException if the configuration could not be resolved.
+     * @throws org.apache.tamaya.ConfigException if any required configuration could not
be resolved/injected.
      */
     void configure(Object instance);
 

http://git-wip-us.apache.org/repos/asf/incubator-tamaya/blob/4b9e587f/api/src/main/java/org/apache/tamaya/spi/StagesSingletonSpi.java
----------------------------------------------------------------------
diff --git a/api/src/main/java/org/apache/tamaya/spi/StagesSingletonSpi.java b/api/src/main/java/org/apache/tamaya/spi/StagesSingletonSpi.java
index 450ed24..a2d6be0 100644
--- a/api/src/main/java/org/apache/tamaya/spi/StagesSingletonSpi.java
+++ b/api/src/main/java/org/apache/tamaya/spi/StagesSingletonSpi.java
@@ -23,7 +23,7 @@ import org.apache.tamaya.Stage;
 import java.util.Collection;
 
 /**
- * Spi o be registered using the Bootstrap mechanism for backing up the {@link org.javaconfig.Stages}
singleton.
+ * Spi to be registered using the Bootstrap mechanism for backing up the {@link org.apache.tamaya.Stages}
singleton.
  * This SPI is loaded on boot time.
  */
 public interface StagesSingletonSpi {


Mime
View raw message