General description of EL support in all annotations

src/main/java/javax/security/enterprise/package-info.java

@@ -39,11 +39,62 @@
  */
 
 /**
- * The main Java EE Security API package. This package
- * contains classes and interfaces that span authentication, 
+ * The main Java EE Security API package. This package contains classes and interfaces that span authentication, 
  * authorization and identity concerns.
+ * 
+ * <h2>EL Support in annotations</h2>
+ * 
+ * This specification supports the use of expression language 3.0 in annotations. This is described in more detail below:
+ * 
+ * <h3>...Definition annotations</h3>
+ * 
+ * The Java EE Security API features several annotations ending on <code>Definition</code> which when used make CDI
+ * beans available. For completeness, this concerns the following annotations:
+ * 
+ *  <ul>
+ *  <li>{@link javax.security.enterprise.identitystore.DatabaseIdentityStoreDefinition}</li>
+ *  <li>{@link javax.security.enterprise.identitystore.LdapIdentityStoreDefinition}</li>
+ *  <li>{@link javax.security.enterprise.authentication.mechanism.http.BasicAuthenticationMechanismDefinition}</li>
+ *  <li>{@link javax.security.enterprise.authentication.mechanism.http.CustomFormAuthenticationMechanismDefinition}</li>
+ *  <li>{@link javax.security.enterprise.authentication.mechanism.http.FormAuthenticationMechanismDefinition}</li>
+ *  </ul>
+ *  
+ * For all attributes of type <code>String</code> on these annotations expression language 3.0 expressions can be used.  
+ * All named CDI beans are available to that expression as well as the default classes as specified by EL 3.0 for the
+ * {@link ELProcessor}.
+ * 
+ * <p>
+ * Expressions can be either immediate (<code>${}</code> syntax), or deferred (<code>#{}</code> syntax). Immediate
+ * expressions are evaluated once when the bean instance corresponding to the "...Definition" annotation is actually created. 
+ * Since such beans are application scoped, that means once for the entire application. Deferred expressions are evaluated in
+ * each request where the security runtime needs to use the value of these attributes.
+ * 
+ * <p>
+ * Attributes that are documented as being EL alternatives to non-<code>String</code> type
+ * attributes (attributes of which the name ends on <code>Expression</code>, hereafter called EL alternative attribute) 
+ * MUST evaluate to the same type as the attribute they are an alternative to. If the EL alternative attribute has a 
+ * non empty value, it takes precedence over the attribute which it is an alternative to.  
+ * 
+ * <p>
+ * The EL alternative attribute MUST contain a valid EL expression. Attributes of type string that are not EL alternative
+ * attributes can contain either an expression or a string value that is not an expression.
+ * 
+ * <h3>Interceptor annotations</h3>
+ * 
+ * The Java EE Security API features several annotations with attributes that denote interceptor spec interceptors. 
+ * For completeness, this concerns the following annotations:
+ * 
+ * <ul>
+ * <li>{@link javax.security.enterprise.authentication.mechanism.http.LoginToContinue}</li>
+ * <li>{@link javax.security.enterprise.authentication.mechanism.http.RememberMe}</li>
+ * </ul>
+ * 
+ * <p>
+ * Expression language is supported for these annotations as well, but in a slightly different way.
+ * See the javadoc of both these annotations for how the expression language support differs.
  *
  * @version 1.0
  */
 package javax.security.enterprise;
 
+import javax.el.ELProcessor;