Lates OASIS files for the annottaions, no changes just formating and javadoc

git-svn-id: http://svn.us.apache.org/repos/asf/tuscany@931880 13f79535-47bb-0310-9956-ffa450edef68

24 files changed, 247 insertions, 216 deletions

diff --git a/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/AllowsPassByReference.java b/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/AllowsPassByReference.java
index d394a64f91..3350e9413b 100644
--- a/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/AllowsPassByReference.java
+++ b/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/AllowsPassByReference.java
@@ -1,5 +1,5 @@
 /*
- * Copyright(C) OASIS(R) 2005,2009. All Rights Reserved.
+ * Copyright(C) OASIS(R) 2005,2010. All Rights Reserved.
  * OASIS trademark, IPR and other policies apply.
  */
 package org.oasisopen.sca.annotation;
@@ -9,19 +9,26 @@ import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.ElementType.PARAMETER;
 import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
-
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
 /**
- * Annotation on a service implementation class, on an individual method of a remotable service implementation, 
- * or on an individual reference which uses a remotable interface, where the reference is a field, a setter method, 
- * or a constructor parameter method.
- * The annotation indicates that that the parameters and return value may safely
- * be passed by reference. When the annotation is placed on a service implementation class or on a reference
- * it indicates that all declared methods support this optimization.
+ * The @AllowsPassByReference annotation is used on implementations
+ * of remotable interfaces to indicate that interactions with the
+ * service from a client within the same address space are allowed
+ * to use pass by reference data exchange semantics.
+ *
+ * The implementation promises that its by-value semantics will be
+ * maintained even if the parameters and return values are actually
+ * passed by-reference. This means that the service will not modify
+ * any operation input parameter or return value, even after returning
+ * from the operation.
+ *
+ * Either a whole class implementing a remotable service or an individual
+ * remotable service method implementation can be annotated using the
+ * {@literal @AllowsPassByReference} annotation.
  *
- * @version $Rev$ $Date$
+ * {@literal @AllowsPassByReference} has no attributes.
  */
 @Target({TYPE, METHOD, FIELD, PARAMETER})
 @Retention(RUNTIME)
diff --git a/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Authentication.java b/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Authentication.java
index 03a5a4ac5e..2b18388c8b 100644
--- a/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Authentication.java
+++ b/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Authentication.java
@@ -1,5 +1,5 @@
 /*
- * Copyright(C) OASIS(R) 2005,2009. All Rights Reserved.
+ * Copyright(C) OASIS(R) 2005,2010. All Rights Reserved.
  * OASIS trademark, IPR and other policies apply.
  */
 package org.oasisopen.sca.annotation;
@@ -16,37 +16,33 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
 /**
- * Annotation denoting the intent that service operations require authentication.
- * <p/>
- * Applied to the injection site (field, method or constructor parameter) for a reference,
- * it indicates that all invocations through that reference require authentication.
- * <p/>
- * Applied to a interface method on a service contract, it indicates that all invocations
- * of that service operation require authentication; applied to the type of a service contract,
- * it indicates that all service operations on that interface require authentication.
- * <p/>
- * Applied to a method on an implementation class, it indicates that all invocations that
- * are dispatched to that implementation method (through any service) require authentication.
- * Applied to a interface implemented by an implementation class, it indicates that all
- * invocations that are dispatched to the implementation method for that interface operation
- * require authentication.
- * <p/>
- * Applied to an implementation class, it indicates that all invocations of that implementation
- * and that all invocations made by that implementation require authentication.
- *
- * @version $Rev$ $Date$
+ * The @Authentication annotation is used to indicate that the
+ * invocation requires authentication.
  */
 @Inherited
 @Target({TYPE, FIELD, METHOD, PARAMETER})
 @Retention(RUNTIME)
 @Intent(Authentication.AUTHENTICATION)
 public @interface Authentication {
+	/**
+	 * The serialized QName of the authentication policy intent,
+	 * for use with the SCA @Requires annotation.
+	 */
     String AUTHENTICATION = SCA_PREFIX + "authentication";
+    /**
+	 * The serialized QName of the authentication.message policy
+	 * intent, for use with the SCA @Requires annotation.
+	 */
     String AUTHENTICATION_MESSAGE = AUTHENTICATION + ".message";
+    /**
+	 * The serialized QName of the authentication.transport policy
+	 * intent, for use with the SCA @Requires annotation.
+	 */
     String AUTHENTICATION_TRANSPORT = AUTHENTICATION + ".transport";
 
     /**
-     * List of authentication qualifiers (such as "message" or "transport").
+     * List of authentication qualifiers (such as "message" 
+     * or "transport").
      *
      * @return authentication qualifiers
      */
diff --git a/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Authorization.java b/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Authorization.java
index 76fcd866ae..6893f6196a 100644
--- a/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Authorization.java
+++ b/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Authorization.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;
 
@@ -17,14 +17,16 @@ import java.lang.annotation.Target;
 
 /**
  * The @Authorization annotation is used to indicate that
- * an authorization policy is required - for a method, for an implementation class, for a reference
- * (either injected as a method parameter or injected into a field)
+ * an authorization policy is required.
  */
 @Inherited
 @Target({TYPE, FIELD, METHOD, PARAMETER})
 @Retention(RUNTIME)
 @Intent(Authorization.AUTHORIZATION)
 public @interface Authorization {
+	/**
+	 * The serialized QName of the authorization policy intent,
+	 * for use with the SCA @Requires annotation.
+	 */
     String AUTHORIZATION = SCA_PREFIX + "authorization";
 }
-
diff --git a/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Callback.java b/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Callback.java
index 03598e10d0..cc68baaba9 100644
--- a/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Callback.java
+++ b/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Callback.java
@@ -1,5 +1,5 @@
 /*
- * Copyright(C) OASIS(R) 2005,2009. All Rights Reserved.
+ * Copyright(C) OASIS(R) 2005, 2010. All Rights Reserved.
  * OASIS trademark, IPR and other policies apply.
  */
 package org.oasisopen.sca.annotation;
@@ -8,29 +8,22 @@ import static java.lang.annotation.ElementType.FIELD;
 import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
-
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
 /**
- * When placed on a service interface, this annotation specifies the interface
- * to be used for callbacks.
- * <p/>
- * When placed on a method or field, this annotation denotes the injection
- * site to be used for a callback reference.
- * <p/>
- * There is a error in the 1.00 draft spec in the declaration of this interface.
- * The form defined here is a proposed correction for that error.
- *
- * @version $Rev$ $Date$
+ * The @Callback annotation is used to annotate a service interface
+ * with a callback interface, which takes the Java Class object of
+ * the callback interface as a parameter.  
  */
 @Target({TYPE, METHOD, FIELD})
 @Retention(RUNTIME)
 public @interface Callback {
+
     /**
-     * The Class of the associated callback interface.
+     * The name of a Java class file containing the callback interface.
      *
-     * @return the associated callback interface
+     * @return    the callback interface
      */
     Class<?> value() default Void.class;
 }
diff --git a/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/ComponentName.java b/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/ComponentName.java
index 7debe2ba89..5ea768a9ca 100644
--- a/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/ComponentName.java
+++ b/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/ComponentName.java
@@ -1,5 +1,5 @@
 /*
- * Copyright(C) OASIS(R) 2005,2009. All Rights Reserved.
+ * Copyright(C) OASIS(R) 2005,2010. All Rights Reserved.
  * OASIS trademark, IPR and other policies apply.
  */
 package org.oasisopen.sca.annotation;
@@ -7,16 +7,15 @@ package org.oasisopen.sca.annotation;
 import static java.lang.annotation.ElementType.FIELD;
 import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
-
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
 /**
- * Annotation used to indicate a field or method that is used to inject the component's name.
- *
- * @version $Rev$ $Date$
+ * The @ComponentName annotation is used to denote a Java class field
+ * or setter method that is used to inject the component name.
  */
 @Target({METHOD, FIELD})
 @Retention(RUNTIME)
 public @interface ComponentName {
+
 }
diff --git a/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Confidentiality.java b/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Confidentiality.java
index 5481a988b6..df5c3c502e 100644
--- a/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Confidentiality.java
+++ b/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Confidentiality.java
@@ -1,5 +1,5 @@
 /*
- * Copyright(C) OASIS(R) 2005,2009. All Rights Reserved.
+ * Copyright(C) OASIS(R) 2005,2010. All Rights Reserved.
  * OASIS trademark, IPR and other policies apply.
  */
 package org.oasisopen.sca.annotation;
@@ -16,33 +16,28 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
 /**
- * Annotation denoting the intent that service operations require confidentiality.
- * <p/>
- * Applied to the injection site (field, method or constructor parameter) for a reference,
- * it indicates that all invocations through that reference require confidentiality.
- * <p/>
- * Applied to a interface method on a service contract, it indicates that all invocations
- * of that service operation require confidentiality; applied to the type of a service contract,
- * it indicates that all service operations on that interface require confidentiality.
- * <p/>
- * Applied to a method on an implementation class, it indicates that all invocations that
- * are dispatched to that implementation method (through any service) require confidentiality.
- * Applied to a interface implemented by an implementation class, it indicates that all
- * invocations that are dispatched to the implementation method for that interface operation
- * require confidentiality.
- * <p/>
- * Applied to an implementation class, it indicates that all invocations of that implementation
- * and that all invocations made by that implementation require confidentiality.
- *
- * @version $Rev$ $Date$
+ * The @Confidentiality annotation is used to indicate that the
+ * invocation requires confidentiality.
  */
 @Inherited
 @Target({TYPE, FIELD, METHOD, PARAMETER})
 @Retention(RUNTIME)
 @Intent(Confidentiality.CONFIDENTIALITY)
 public @interface Confidentiality {
+	/**
+	 * The serialized QName of the confidentiality policy intent,
+	 * for use with the SCA @Requires annotation.
+	 */
     String CONFIDENTIALITY = SCA_PREFIX + "confidentiality";
+    /**
+	 * The serialized QName of the confidentiality.message policy intent,
+	 * for use with the SCA @Requires annotation.
+	 */
     String CONFIDENTIALITY_MESSAGE = CONFIDENTIALITY + ".message";
+    /**
+	 * The serialized QName of the confidentiality.transport policy intent,
+	 * for use with the SCA @Requires annotation.
+	 */
     String CONFIDENTIALITY_TRANSPORT = CONFIDENTIALITY + ".transport";
 
     /**
diff --git a/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Constructor.java b/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Constructor.java
index c1c99de683..0b068febd3 100644
--- a/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Constructor.java
+++ b/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Constructor.java
@@ -1,22 +1,23 @@
 /*
- * Copyright(C) OASIS(R) 2005,2009. All Rights Reserved.
+ * Copyright(C) OASIS(R) 2005,2010. All Rights Reserved.
  * OASIS trademark, IPR and other policies apply.
  */
 package org.oasisopen.sca.annotation;
 
 import static java.lang.annotation.ElementType.CONSTRUCTOR;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
-
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
 /**
- * Used to indicate the constructor the runtime is to use when instantiating a component implementation instance
- *
- * @version $Rev$ $Date$
+ * The @Constructor annotation is used to mark a particular
+ * constructor to use when instantiating a Java component
+ * implementation. If this constructor has parameters, each
+ * of these parameters MUST have either a @Property annotation
+ * or a @Reference annotation.
  */
 @Target(CONSTRUCTOR)
 @Retention(RUNTIME)
 public @interface Constructor {
-    String[] value() default "";
+
 }
diff --git a/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Context.java b/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Context.java
index fce0334792..90cf9b81ce 100644
--- a/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Context.java
+++ b/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Context.java
@@ -1,5 +1,5 @@
 /*
- * Copyright(C) OASIS(R) 2005,2009. All Rights Reserved.
+ * Copyright(C) OASIS(R) 2005,2010. All Rights Reserved.
  * OASIS trademark, IPR and other policies apply.
  */
 package org.oasisopen.sca.annotation;
@@ -7,19 +7,20 @@ package org.oasisopen.sca.annotation;
 import static java.lang.annotation.ElementType.FIELD;
 import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
-
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
 /**
- * Annotation used to indicate a field or setter method that is used to inject an SCA context.
- * The type of context injected is determined by the type of the field or the parameter
- * to the setter method and is typically a ComponentContext or RequestContext.
+ * The @Context annotation is used to denote a Java class field
+ * or a setter method that is used to inject a composite context
+ * for the component. The type of context to be injected is defined
+ * by the type of the Java class field or type of the setter method
+ * input argument; the type is either ComponentContext or RequestContext.
  *
- * @version $Rev$ $Date$
+ * The @Context annotation has no attributes.
  */
 @Target({METHOD, FIELD})
 @Retention(RUNTIME)
 public @interface Context {
+    
 }
-
diff --git a/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Destroy.java b/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Destroy.java
index f9c6505648..b4d3cd4369 100644
--- a/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Destroy.java
+++ b/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Destroy.java
@@ -1,22 +1,22 @@
 /*
- * Copyright(C) OASIS(R) 2005,2009. All Rights Reserved.
+ * Copyright(C) OASIS(R) 2005,2010. All Rights Reserved.
  * OASIS trademark, IPR and other policies apply.
  */
 package org.oasisopen.sca.annotation;
 
 import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
-
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
 /**
- * Annotation used to indicate a method that will be called by the container when the
- * scope defined for the local service ends.
- *
- * @version $Rev$ $Date$
+ * The @Destroy annotation is used to denote a single Java class method
+ * that will be called when the scope defined for the implementation
+ * class ends. The method MAY have any access modifier and MUST have a
+ * void return type and no arguments.
  */
 @Target(METHOD)
 @Retention(RUNTIME)
 public @interface Destroy {
+
 }
diff --git a/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/EagerInit.java b/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/EagerInit.java
index a8e415a00b..e4cd03ea4b 100644
--- a/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/EagerInit.java
+++ b/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/EagerInit.java
@@ -1,21 +1,21 @@
 /*
- * Copyright(C) OASIS(R) 2005,2009. All Rights Reserved.
+ * Copyright(C) OASIS(R) 2005,2010. All Rights Reserved.
  * OASIS trademark, IPR and other policies apply.
  */
 package org.oasisopen.sca.annotation;
 
 import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
-
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
 /**
- * Annotation used to indicate an instance should be eagerly initialized.
- *
- * @version $Rev$ $Date$
+ * The @EagerInit annotation is used to annotate the Java class of a
+ * COMPOSITE scoped implementation for eager initialization. When marked
+ * for eager initialization, the composite scoped instance is created
+ * when its containing component is started.
  */
-@Target({TYPE})
+@Target(TYPE)
 @Retention(RUNTIME)
 public @interface EagerInit {
 
diff --git a/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Init.java b/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Init.java
index b8b38a1088..b4b420c175 100644
--- a/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Init.java
+++ b/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Init.java
@@ -1,23 +1,22 @@
 /*
- * Copyright(C) OASIS(R) 2005,2009. All Rights Reserved.
+ * Copyright(C) OASIS(R) 2005,2010. All Rights Reserved.
  * OASIS trademark, IPR and other policies apply.
  */
 package org.oasisopen.sca.annotation;
 
 import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
-
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
 /**
- * Annotation used to indicate a method that will be called by the container when the scope defined for the local
- * service begins.
- *
- * @version $Rev$ $Date$
+ * The @Init annotation is used to denote a single Java class method
+ * that is called when the scope defined for the implementation class
+ * starts. The method MAY have any access modifier and MUST have a
+ * void return type and no arguments.
  */
 @Target(METHOD)
 @Retention(RUNTIME)
 public @interface Init {
-
+       
 }
diff --git a/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Integrity.java b/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Integrity.java
index 8b59edeafe..e9918533d9 100644
--- a/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Integrity.java
+++ b/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Integrity.java
@@ -1,5 +1,5 @@
 /*
- * Copyright(C) OASIS(R) 2005,2009. All Rights Reserved.
+ * Copyright(C) OASIS(R) 2005,2010. All Rights Reserved.
  * OASIS trademark, IPR and other policies apply.
  */
 package org.oasisopen.sca.annotation;
@@ -16,33 +16,29 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
 /**
- * Annotation denoting the intent that service operations require integrity.
- * <p/>
- * Applied to the injection site (field, method or constructor parameter) for a reference,
- * it indicates that all invocations through that reference require integrity.
- * <p/>
- * Applied to a interface method on a service contract, it indicates that all invocations
- * of that service operation require integrity; applied to the type of a service contract,
- * it indicates that all service operations on that interface require integrity.
- * <p/>
- * Applied to a method on an implementation class, it indicates that all invocations that
- * are dispatched to that implementation method (through any service) require integrity.
- * Applied to a interface implemented by an implementation class, it indicates that all
- * invocations that are dispatched to the implementation method for that interface operation
- * require integrity.
- * <p/>
- * Applied to an implementation class, it indicates that all invocations of that implementation
- * and that all invocations made by that implementation require integrity.
- *
- * @version $Rev$ $Date$
+ * The @Integrity annotation is used to indicate that the invocation
+ * requires integrity (ie no tampering of the messages between client
+ * and service).
  */
 @Inherited
 @Target({TYPE, FIELD, METHOD, PARAMETER})
 @Retention(RUNTIME)
 @Intent(Integrity.INTEGRITY)
 public @interface Integrity {
+	/**
+	 * The serialized QName of the integrity policy intent,
+	 * for use with the SCA @Requires annotation.
+	 */
     String INTEGRITY = SCA_PREFIX + "integrity";
+    /**
+	 * The serialized QName of the integrity.message policy intent,
+	 * for use with the SCA @Requires annotation.
+	 */
     String INTEGRITY_MESSAGE = INTEGRITY + ".message";
+    /**
+	 * The serialized QName of the integrity.transport policy intent,
+	 * for use with the SCA @Requires annotation.
+	 */
     String INTEGRITY_TRANSPORT = INTEGRITY + ".transport";
 
     /**
diff --git a/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Intent.java b/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Intent.java
index 54a1935859..593ae56e67 100644
--- a/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Intent.java
+++ b/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Intent.java
@@ -1,44 +1,37 @@
 /*
- * Copyright(C) OASIS(R) 2005,2009. All Rights Reserved.
+ * Copyright(C) OASIS(R) 2005,2010. All Rights Reserved.
  * OASIS trademark, IPR and other policies apply.
  */
 package org.oasisopen.sca.annotation;
 
 import static java.lang.annotation.ElementType.ANNOTATION_TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
-
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
 /**
- * Annotation that can be applied to annotations that describe SCA intents.
- * Adding this annotation allows SCA runtimes to automatically detect user-defined intents.
- * <p/>
- * Applications must specify a value, a pairing of targetNamespace and localPort, or both.
- * If both value and pairing are supplied they must define the name qualified name.
- *
- * @version $Rev$ $Date$
+ * The @Intent annotation is used for the creation of new annotations
+ * for specific intents.  It is not expected that the @Intent annotation
+ * will be used in application code.
  */
 @Target({ANNOTATION_TYPE})
 @Retention(RUNTIME)
 public @interface Intent {
     /**
-     * The qualified name of the intent, in the form defined by {@link javax.xml.namespace.QName#toString}.
-     *
+     * The qualified name of the intent, in the form defined by 
+     * javax.xml.namespace.QName.toString().
      * @return the qualified name of the intent
      */
     String value() default "";
 
     /**
      * The XML namespace for the intent.
-     *
      * @return the XML namespace for the intent
      */
     String targetNamespace() default "";
 
     /**
      * The name of the intent within its namespace.
-     *
      * @return name of the intent within its namespace
      */
     String localPart() default "";
diff --git a/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/ManagedSharedTransaction.java b/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/ManagedSharedTransaction.java
index b12050a3e3..ba6b086756 100644
--- a/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/ManagedSharedTransaction.java
+++ b/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/ManagedSharedTransaction.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;
 
@@ -24,6 +24,9 @@ import java.lang.annotation.Target;
 @Retention(RUNTIME)
 @Intent(ManagedSharedTransaction.MANAGEDSHAREDTRANSACTION)
 public @interface ManagedSharedTransaction {
+	/**
+	 * The serialized QName of the managedSharedTransaction policy intent,
+	 * for use with the SCA @Requires annotation.
+	 */
     String MANAGEDSHAREDTRANSACTION = SCA_PREFIX + "managedSharedTransaction";
-}
-
+}
\ No newline at end of file
diff --git a/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/ManagedTransaction.java b/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/ManagedTransaction.java
index 7115e8a5e9..6fca1ab5df 100644
--- a/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/ManagedTransaction.java
+++ b/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/ManagedTransaction.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;
 
@@ -24,8 +24,20 @@ import java.lang.annotation.Target;
 @Retention(RUNTIME)
 @Intent(ManagedTransaction.MANAGEDTRANSACTION)
 public @interface ManagedTransaction {
+	/**
+	 * The serialized QName of the managedTransaction policy intent,
+	 * for use with the SCA @Requires annotation.
+	 */
     String MANAGEDTRANSACTION = SCA_PREFIX + "managedTransaction";
+    /**
+	 * The serialized QName of the managedTransaction.local policy intent,
+	 * for use with the SCA @Requires annotation.
+	 */
     String MANAGEDTRANSACTION_MESSAGE = MANAGEDTRANSACTION + ".local";
+    /**
+	 * The serialized QName of the managedTransaction.global policy intent,
+	 * for use with the SCA @Requires annotation.
+	 */
     String MANAGEDTRANSACTION_TRANSPORT = MANAGEDTRANSACTION + ".global";
 
     /**
@@ -36,5 +48,3 @@ public @interface ManagedTransaction {
     @Qualifier
     String[] value() default "";
 }
-
-
diff --git a/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/MutualAuthentication.java b/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/MutualAuthentication.java
index d0825cd8e3..9a4bf86053 100644
--- a/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/MutualAuthentication.java
+++ b/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/MutualAuthentication.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;
 
@@ -24,7 +24,9 @@ import java.lang.annotation.Target;
 @Retention(RUNTIME)
 @Intent(MutualAuthentication.MUTUALAUTHENTICATION)
 public @interface MutualAuthentication {
+	/**
+	 * The serialized QName of the mutualAuthentication policy intent,
+	 * for use with the SCA @Requires annotation.
+	 */
     String MUTUALAUTHENTICATION = SCA_PREFIX + "mutualAuthentication";
 }
-
-
diff --git a/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/OneWay.java b/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/OneWay.java
index 700e71990c..1fbf83458e 100644
--- a/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/OneWay.java
+++ b/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/OneWay.java
@@ -1,22 +1,23 @@
 /*
- * Copyright(C) OASIS(R) 2005,2009. All Rights Reserved.
+ * Copyright(C) OASIS(R) 2005,2010. All Rights Reserved.
  * OASIS trademark, IPR and other policies apply.
  */
 package org.oasisopen.sca.annotation;
 
 import static java.lang.annotation.ElementType.METHOD;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
-
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
 /**
- * Annotation on a method that indicates that the method is non-blocking and communication
- * with the service provider may use buffer the requests and send them at some later time.
+ * The @OneWay annotation is used on a Java interface or class method
+ * to indicate that invocations will be dispatched in a non-blocking
+ * fashion as described in the section on Asynchronous Programming.
  *
- * @version $Rev$ $Date$
+ * The @OneWay annotation has no attributes.
  */
-@Target({METHOD})
+@Target(METHOD)
 @Retention(RUNTIME)
 public @interface OneWay {
+
 }
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;
 }
diff --git a/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Qualifier.java b/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Qualifier.java
index 97204fdf32..dd002d27c7 100644
--- a/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Qualifier.java
+++ b/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Qualifier.java
@@ -1,5 +1,5 @@
 /*
- * Copyright(C) OASIS(R) 2005,2009. All Rights Reserved.
+ * Copyright(C) OASIS(R) 2005,2010. All Rights Reserved.
  * OASIS trademark, IPR and other policies apply.
  */
 package org.oasisopen.sca.annotation;
@@ -11,12 +11,14 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
 /**
- * Annotation that can be applied to an attribute of an @Intent annotation to indicate the
- * attribute provides qualifiers for the intent.
- * 
- * @version $Rev$ $Date$
+ * The @Qualifier annotation is applied to an attribute of a
+ * specific intent annotation definition, defined using the @Intent
+ * annotation, to indicate that the attribute provides qualifiers
+ * for the intent. The @Qualifier annotation MUST be used in a
+ * specific intent annotation definition where the intent has qualifiers.
  */
 @Target(METHOD)
 @Retention(RUNTIME)
 public @interface Qualifier {
+
 }
diff --git a/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Reference.java b/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Reference.java
index 8f7d6b2043..4dbf9412fc 100644
--- a/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Reference.java
+++ b/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Reference.java
@@ -1,5 +1,5 @@
 /*
- * Copyright(C) OASIS(R) 2005,2009. All Rights Reserved.
+ * Copyright(C) OASIS(R) 2005,2010. All Rights Reserved.
  * OASIS trademark, IPR and other policies apply.
  */
 package org.oasisopen.sca.annotation;
@@ -8,30 +8,49 @@ 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 reference.
+ * The @Reference annotation type is used to annotate a Java class field,
+ * a setter method, or a constructor parameter that is used to inject a
+ * service that resolves the reference. The interface of the service
+ * injected is defined by the type of the Java class field or the type
+ * of the input parameter of the setter method or constructor.
+ *
+ * The @Reference annotation MUST NOT be used on a class field that is
+ * declared as final.
+ *
+ * References can also be injected via setter methods even when
+ * the @Reference annotation is not present.  However, the @Reference
+ * annotation must be used in order to inject a reference onto a non-public
+ * field.  In the case where there is no @Reference annotation, the name
+ * of the reference is the same as the name of the field or setter.
  *
- * @version $Rev$ $Date$
+ * Where there is both a setter method and a field for a reference, the
+ * setter method is used.
  */
 @Target({METHOD, FIELD, PARAMETER})
 @Retention(RUNTIME)
 public @interface Reference {
+
     /**
-     * The name of the reference. If not specified then the name will be derived from the annotated field or method.
+     * The name of the reference. 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 reference
+     * @return    the name of the reference
      */
     String name() default "";
 
     /**
-     * Indicates if a reference must be specified.
+     * Specifies whether injection of service or services is required.
+     * Defaults to true. For a constructor parameter annotation, this
+     * attribute MUST have the value true.
      *
-     * @return true if a reference must be specified
+     * @return    true if injection is required
      */
     boolean required() default true;
 }
-
diff --git a/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Remotable.java b/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Remotable.java
index 3f7ac2623a..50f3557bed 100644
--- a/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Remotable.java
+++ b/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Remotable.java
@@ -1,23 +1,23 @@
 /*
- * Copyright(C) OASIS(R) 2005,2009. All Rights Reserved.
+ * Copyright(C) OASIS(R) 2005,2010. All Rights Reserved.
  * OASIS trademark, IPR and other policies apply.
  */
 package org.oasisopen.sca.annotation;
 
 import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
-
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
 /**
- * Annotation used to indicate a Java interface as remotable.
- * Remotable interfaces use pass-by-value semantics, can be published as entry points
- * and used for external services.
+ * The @Remotable annotation is used to specify a Java service
+ * interface as remotable. A remotable service can be published
+ * externally as a service and must be translatable into a WSDL portType.
  *
- * @version $Rev$ $Date$
+ * The @Remotable annotation has no attributes.
  */
 @Target(TYPE)
 @Retention(RUNTIME)
 public @interface Remotable {
+
 }
diff --git a/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Requires.java b/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Requires.java
index 8c9101b2b4..b5d485e016 100644
--- a/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Requires.java
+++ b/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Requires.java
@@ -1,5 +1,5 @@
 /*
- * Copyright(C) OASIS(R) 2005,2009. All Rights Reserved.
+ * Copyright(C) OASIS(R) 2005,2010. All Rights Reserved.
  * OASIS trademark, IPR and other policies apply.
  */
 package org.oasisopen.sca.annotation;
@@ -15,20 +15,9 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
 /**
- * Annotation that allows the attachment of any intent to a Java Class or interface or to members of that
- * class such as methods, fields or constructor parameters.
- * <p/>
- * Intents are specified as XML QNames in the representation defined by
- * {@link javax.xml.namespace.QName#toString()}. Intents may be qualified with one or more
- * suffixes separated by a "." such as:
- * <ul>
- * <li>{http://docs.oasis-open.org/ns/opencsa/sca/200912}confidentiality</li>
- * <li>{http://docs.oasis-open.org/ns/opencsa/sca/200912}confidentiality.message</li>
- * </ul>
- * This annotation supports general purpose intents specified as strings.  Users may also define
- * specific intents using the {@link @org.oasisopen.sca.annotation.Intent} annotation.
- *
- * @version $Rev$ $Date$
+ * The @Requires annotation supports general purpose intents
+ * specified as strings. Users can also define specific intent
+ * annotations using the @Intent annotation.
  */
 @Inherited
 @Retention(RUNTIME)
diff --git a/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Scope.java b/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Scope.java
index 8f9a13430e..087f589168 100644
--- a/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Scope.java
+++ b/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Scope.java
@@ -1,31 +1,34 @@
 /*
- * Copyright(C) OASIS(R) 2005,2009. All Rights Reserved.
+ * Copyright(C) OASIS(R) 2005,2010. All Rights Reserved.
  * OASIS trademark, IPR and other policies apply.
  */
 package org.oasisopen.sca.annotation;
 
 import static java.lang.annotation.ElementType.TYPE;
 import static java.lang.annotation.RetentionPolicy.RUNTIME;
-
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
 /**
- * Annotation used to indicate a scoped service.
- * <p/>
- * The spec refers to but does not describe an eager() attribute; this is an error in the draft.
- *
- * @version $Rev$ $Date$
+ * The @Scope annotation MUST only be used on a service's implementation
+ * class. It is an error to use this annotation on an interface.
  */
 @Target(TYPE)
 @Retention(RUNTIME)
 public @interface Scope {
+
     /**
-     * The name of the scope. Values currently defined by the specification are:
-     * <ul>
-     * <li>STATELESS (default)</li>
-     * <li>COMPOSITE</li>
-     * </ul>
+     * The name of the scope.
+     *
+     * For 'STATELESS' implementations, a different implementation
+     * instance can be used to service each request. Implementation
+     * instances can be newly created or be drawn from a pool of instances.
+     *
+     * SCA defines the following scope names, but others can be defined
+     * by particular Java-based implementation types:
+     *  STATELESS
+     *  COMPOSITE
+     * The default value is STATELESS.
      *
      * @return the name of the scope
      */
diff --git a/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Service.java b/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Service.java
index a60754762e..5c2600ff12 100644
--- a/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Service.java
+++ b/sca-java-2.x/trunk/modules/sca-api/src/main/java/org/oasisopen/sca/annotation/Service.java
@@ -1,5 +1,5 @@
 /*
- * Copyright(C) OASIS(R) 2005,2009. All Rights Reserved.
+ * Copyright(C) OASIS(R) 2005,2010. All Rights Reserved.
  * OASIS trademark, IPR and other policies apply.
  */
 package org.oasisopen.sca.annotation;