1 files changed, 31 insertions, 11 deletions

diff --git a/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Property.java b/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Property.java
index 5905946627..6a8c8a0e04 100644
--- a/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Property.java
+++ b/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Property.java
@@ -1,6 +1,6 @@
 /*
- * Copyright(C) OASIS(R) 2005,2009. All Rights Reserved.
- * OASIS trademark, IPR and other policies apply.    
+ * Copyright(C) OASIS(R) 2005,2010. All Rights Reserved.
+ * OASIS trademark, IPR and other policies apply.
  */
 package org.oasisopen.sca.annotation;
 
@@ -8,31 +8,51 @@ import static java.lang.annotation.ElementType.FIELD;
 import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.ElementType.PARAMETER;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
-
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
 /**
- * Annotation used to indicate a constructor parameter, field or method that is
- * used to inject a configuration property value.
+ * The @Property annotation is used to denote a Java class field,
+ * a setter method, or a constructor parameter that is used to
+ * inject an SCA property value. The type of the property injected,
+ * which can be a simple Java type or a complex Java type, is defined
+ * by the type of the Java class field or the type of the input
+ * parameter of the setter method or constructor.
+ *
+ * The @Property annotation can be used on fields, on setter methods
+ * or on a constructor method parameter. However, the @Property annotation
+ * MUST NOT be used on a class field that is declared as final.
  *
- * @version $Rev$ $Date$
+ * Properties can also be injected via setter methods even when
+ * the @Property annotation is not present.  However, the @Property
+ * annotation must be used in order to inject a property onto a
+ * non-public field.  In the case where there is no @Property
+ * annotation, the name of the property is the same as the name of the
+ * field or setter.
+ *
+ * Where there is both a setter method and a field for a property, the
+ * setter method is used.
  */
 @Target({METHOD, FIELD, PARAMETER})
 @Retention(RUNTIME)
 public @interface Property {
+
     /**
-     * The name of the property. If not specified then the name will be derived
-     * from the annotated field or method.
+     * The name of the property.  For a field annotation, the default is
+     * the name of the field of the Java class.  For a setter method annotation,
+     * the default is the JavaBeans property name corresponding to the setter
+     * method name.  For a constructor parameter annotation, there is no
+     * default and the name attribute MUST be present.
      *
-     * @return the name of the property
+     * @return    the name of the property
      */
     String name() default "";
 
     /**
-     * Indicates whether a value for the property must be provided.
+     * Specifies whether injection is required, defaults to true. For a
+     * constructor parameter annotation, this attribute MUST have the value true.
      *
-     * @return true if a value must be provided
+     * @return    true if injection is required
      */
     boolean required() default true;
 }