Merge pull request #127 from arjantijms/master

#124 Prepare Jakarta Security for Jakarta EE 8 Release

CONTRIBUTING.md

@@ -4,7 +4,7 @@ Thanks for your interest in this project.
 
 ## Project description
 
-The Java EE security provides a set of required security functionalities
+Jakarta Security provides a set of required security functionalities
 including authentication, authorization, data integrity, and transport security.
 
  * https://projects.eclipse.org/projects/ee4j.es

README.md

@@ -1,13 +1,13 @@
-# JSR-375 API Code Repository
+# Jakarta Security
 
-This repository contains the code for the Java EE Security API (JSR-375).
+This repository contains the code for Jakarta Security.
 
 [Online JavaDoc](https://javadoc.io/doc/javax.security.enterprise/javax.security.enterprise-api/)
 
 Building
 --------
 
-JSR 375 API can be built by executing the following from the project root:
+Jakarta Security can be built by executing the following from the project root:
 
 ``mvn clean package``
 
@@ -18,7 +18,7 @@ Making Changes
 
 To make changes, fork this repository, make your changes, and submit a pull request.
 
-About JSR-375
+About Jakarta Security
 -------------
 
-For more information about JSR-375, see the project web site at [https://javaee.github.io/security-spec/](https://javaee.github.io/security-spec/).
+For more information about Jakarta Security, see the project web site at [github.com/eclipse-ee4j/security-api](https://github.com/eclipse-ee4j/security-api).

pom.xml

@@ -31,8 +31,11 @@
     <version>1.0.2-SNAPSHOT</version>
     <packaging>bundle</packaging>
 
-    <name>Enterprise Security API</name>
-    <description>Security API for Java EE Applications</description>
+    <name>Jakarta Security</name>
+    <description>
+        Jakarta Security defines a standard for creating secure Jakarta EE applications in modern application paradigms.
+        It defines an overarching (end-user targeted) Security API for Jakarta EE Applications.
+    </description>
     <inceptionYear>2015</inceptionYear>
 
     <properties>
@@ -181,7 +184,7 @@
                         <Implementation-Version>${spec.implementation.version}</Implementation-Version>
                         <Specification-Version>${spec.specification.version}</Specification-Version>
                         <Bundle-Description>
-                            EE Security API ${spec.version} Specification
+                            Jakarta Security ${spec.version} Specification
                         </Bundle-Description>
                         <Specification-Vendor>Oracle Corporation</Specification-Vendor>
                         <Implementation-Vendor>${project.organization.name}</Implementation-Vendor>

src/main/java/javax/security/enterprise/AuthenticationException.java

@@ -23,9 +23,10 @@
 /**
  * A generic authentication exception.
  * 
- * This exception corresponds to the JASPIC (JSR 196) AuthException in that whenever a method
- * from the {@link HttpAuthenticationMechanism} throws this exception, the JASPIC bridge
- * has to throw an AuthException back to the JASPIC runtime wrapping this exception.
+ * This exception corresponds to the Jakarta Authentication <code>AuthException</code> in that whenever a 
+ * method from the {@link HttpAuthenticationMechanism} throws this exception, the Jakarta Authentication 
+ * bridge has to throw an <code>AuthException</code> back to the Jakarta Authentication runtime wrapping 
+ * this exception.
  *
  */
 public class AuthenticationException extends GeneralSecurityException {

src/main/java/javax/security/enterprise/AuthenticationStatus.java

@@ -26,7 +26,7 @@
  * 
  * <p>
  * For the result from {@link HttpAuthenticationMechanism#validateRequest(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, javax.security.enterprise.authentication.mechanism.http.HttpMessageContext)} 
- * an AuthenticationStatus must be transformed by the Java EE server into the corresponding JASPIC (JSR 196) AuthStatus
+ * an AuthenticationStatus must be transformed by the Jakarta EE server into the corresponding Jakarta Authentication <code>AuthStatus</code>
  * according to the following rules:
  * 
  * <ul>
@@ -37,21 +37,21 @@
  * </ul>
  * 
  * <p>
- * After the transformation as outlined above the transformed result has to be processed by the Java EE server as 
- * specified by the Servlet Container Profile of the JASPIC 1.1 spec (chapter 3).
+ * After the transformation as outlined above the transformed result has to be processed by the Jakarta EE server as 
+ * specified by the Servlet Container Profile of the Jakarta Authentication spec.
  * 
  * <p>
- * <b>Implementation note:</b> while the JASPIC Servlet Container Profile is the authoritative
+ * <b>Implementation note:</b> while the Jakarta Authentication Servlet Container Profile is the authoritative
  * source on how to process the <code>AuthStatus.SUCCESS</code> result and this specification puts no constraints 
- * of any kind on that, the expectation is that Java EE servers in practice will mainly look at the 
+ * of any kind on that, the expectation is that Jakarta EE servers in practice will mainly look at the 
  * result being <code>AuthStatus.SUCCESS</code> or not <code>AuthStatus.SUCCESS</code>. Simply said, if the result is 
  * <code>AuthStatus.SUCCESS</code> the authenticated identity (if any) must be set (established) for the current HTTP request, 
  * otherwise not.
  * 
  * <p>
  * The return value of {@link SecurityContext#authenticate(javax.servlet.http.HttpServletRequest, javax.servlet.http.HttpServletResponse, javax.security.enterprise.authentication.mechanism.http.AuthenticationParameters)}
  * , which is also of type AuthenticationStatus, strongly relates to the outcome of the <code>HttpAuthenticationMechanism#validateRequest</code>
- * method as described above, but must be transformed by the Java EE server from the corresponding outcome of the
+ * method as described above, but must be transformed by the Jakarta EE server from the corresponding outcome of the
  * {@link HttpServletRequest#authenticate(javax.servlet.http.HttpServletResponse)} call as follows:
  * 
  * <ul>
@@ -65,9 +65,9 @@
  * the value returned by <code>HttpAuthenticationMechanism#validateRequest</code>.
  * 
  * <p>
- * When a JASPIC ServerAuthModule (SAM) was used and an <code>HttpAuthenticationMechanism</code> was <em>not</em> used 
- * Java EE servers are encouraged, but not required, to set <code>[last status]</code> to the value returned by
- * <code>ServerAuthModule#validateRequest</code> transformed as follows:
+ * When a Jakarta Authentication ServerAuthModule (SAM) was used and an <code>HttpAuthenticationMechanism</code> 
+ * was <em>not</em> used Jakarta EE servers are encouraged, but not required, to set <code>[last status]</code> 
+ * to the value returned by <code>ServerAuthModule#validateRequest</code> transformed as follows:
  * 
  * <ul>
  *   <li> AuthStatus.SEND_CONTINUE to AuthenticationStatus.SEND_CONTINUE </li>
@@ -77,9 +77,9 @@
  * </ul>
  * 
  * <p>
- * When a Java EE Server proprietary identity store equivalent was used and an 
+ * When a Jakarta EE Server proprietary identity store equivalent was used and an 
  * <code>HttpAuthenticationMechanism</code> was <em>not</em> used 
- * Java EE servers are encouraged, but not required, to set <code>[last status]</code> to a value
+ * Jakarta EE servers are encouraged, but not required, to set <code>[last status]</code> to a value
  * that logically corresponds to the description of each enum constant of AuthenticationStatus. This outcome
  * should never be depended on by application code as being portable.
  * 
@@ -108,13 +108,13 @@ public enum AuthenticationStatus {
 
 	/**
 	 * The authentication mechanism was called and the caller was successfully authenticated. After the
-	 * Java EE server has processed this outcome, the caller principal is available.
+	 * Jakarta EE server has processed this outcome, the caller principal is available.
 	 */
 	SUCCESS,
 
 	/**
 	 * The authentication mechanism was called but the caller was <em>not</em> successfully authenticated and
-	 * therefor the caller principal will not be made available.
+	 * therefore the caller principal will not be made available.
 	 * <p>
 	 * Note that this status should be used to indicate a logical problem (such as a credential not matching or a caller
 	 * ID that can not be found). Exceptions should be used for system level problems (such as a database connection timing out).

src/main/java/javax/security/enterprise/SecurityContext.java

@@ -27,11 +27,11 @@
 
 /**
  * The SecurityContext provides an access point for programmatic security; an injectable type that is intended to be
- * used by application code to query and interact with the Java EE Security API.
+ * used by application code to query and interact with Jakarta Security.
  *
  * <p>
- * Unless otherwise indicated, this type must be usable in all Java EE containers, specifically the Servlet
- * and EJB containers.
+ * Unless otherwise indicated, this type must be usable in all Jakarta EE containers, specifically the Jakarta Servlet
+ * and Jakarta Enterprise Beans containers.
  *
  *
  */
@@ -69,14 +69,14 @@ public interface SecurityContext {
 	 * If the caller is not authenticated, this always returns <code>false</code>.
 	 *
 	 * <p>
-	 * This method <em>can not</em> be used to test for roles that are mapped to specific named Servlets or
-	 * named EJB beans. For a Servlet an example of this would be the <code>role-name</code> nested in a
+	 * This method <em>can not</em> be used to test for roles that are mapped to specific named Jakarta Servlets or
+	 * named Jakarta Enterprise Beans. For a Servlet an example of this would be the <code>role-name</code> nested in a
 	 * <code>security-role-ref</code> element nested in a <code>servlet</code> element in <code>web.xml</code>.
 	 *
 	 * <p>
-	 * Should code in either such Servlet or EJB bean wish to take such mapped (aka referenced, linked) roles into
-	 * account, the facilities for that specific container should be used instead. For instance for Servlet that would
-	 * be {@link HttpServletRequest#isUserInRole(String)} and for EJB beans that would be
+	 * Should code in either such Jakarta Servlet or Jakarta Enterprise Bean wish to take such mapped (aka referenced, linked) 
+	 * roles into account, the facilities for that specific container should be used instead. For instance for Servlet that 
+	 * would be {@link HttpServletRequest#isUserInRole(String)} and for Jakarta Enterprise Beans that would be
 	 * {@link SessionContext#isCallerInRole(String)}.
 	 *
 	 *

src/main/java/javax/security/enterprise/authentication/mechanism/http/AutoApplySession.java

@@ -32,10 +32,10 @@
  * and auto applies this for every request.
  *
  * <p>
- * See the JASPIC 1.1 specification section 3.8.4 for further details on <code>javax.servlet.http.registerSession</code>.
+ * See the Jakarta Authentication spec for further details on <code>javax.servlet.http.registerSession</code>.
  *
  * <p>
- * This support is provided via an implementation of an interceptor spec interceptor that conducts the
+ * This support is provided via an implementation of a Jakarta Interceptors interceptor that conducts the
  * necessary logic.
  *
  * <p>

src/main/java/javax/security/enterprise/authentication/mechanism/http/HttpAuthenticationMechanism.java

@@ -32,17 +32,18 @@
  * credentials in some way, using the HTTP protocol where necessary.
  * 
  * <p>
- * This is used to help in securing Servlet endpoints, including
- * endpoints that may be build on top of Servlet like JAX-RS endpoints and JSF views.
- * It specifically <b>is not</b> used for endpoints such as remote EJB beans or (JMS) message driven beans.
+ * This is used to help in securing Jakarta Servlet endpoints, including
+ * endpoints that may be build on top of Jakarta Servlets like Jakarta RESTful Web Services endpoints and 
+ * Jakarta Faces views. It specifically <b>is not</b> used for endpoints such as remote Jakarta Enterprise Beans
+ * or (Jakarta Messaging) message driven beans.
  * 
  * <p>
- * A <code>HttpAuthenticationMechanism</code> is essentially a Servlet specific and CDI enabled version of
- * the {@link ServerAuthModule} that adheres to the Servlet Container Profile. See the JASPIC spec for further
- * details on this.
+ * A <code>HttpAuthenticationMechanism</code> is essentially a Jakarta Servlet specific and CDI enabled version of
+ * the {@link ServerAuthModule} that adheres to the Servlet Container Profile. See the Jakarta Authentication spec for 
+ * further details on this.
  * 
  * <p>
- * Implementations of this class can notify the Servlet container about a successful authentication by using the
+ * Implementations of this class can notify the Jakarta Servlet container about a successful authentication by using the
  * {@link HttpMessageContext#notifyContainerAboutLogin(java.security.Principal, java.util.Set)} method.
  * 
  * <p>

src/main/java/javax/security/enterprise/authentication/mechanism/http/HttpMessageContext.java

@@ -39,9 +39,9 @@
 public interface HttpMessageContext {
 
     /**
-     * Checks if the currently requested resource is protected or not. A protected resource
-     * is a resource (e.g. a Servlet, JSF page, JSP page etc) for which a constraint has been defined
-     * in e.g. <code>web.xml</code>.
+     * Checks if the currently requested resource is protected or not. A protected resource is a resource (e.g. a Jakarta
+     * Servlet, Jakarta Faces page, Jakarta Server Pages page etc) for which a constraint has been defined in e.g.
+     * <code>web.xml</code>.
      * 
      * @return true if a protected resource was requested, false if a public resource was requested.
      */
@@ -79,8 +79,8 @@ public interface HttpMessageContext {
      * Convenience method to clean the subject associated with this context.
      * 
      * <p>
-     * Cleaning this subject is done as defined by the Servlet Container Profile of JASPIC
-     * (JSR 196) for the ServerAuthModule#cleanSubject method and the 
+     * Cleaning this subject is done as defined by the Servlet Container Profile of Jakarta Authentication
+     * for the ServerAuthModule#cleanSubject method and the 
      * {@link HttpAuthenticationMechanism#cleanSubject(HttpServletRequest, HttpServletResponse, HttpMessageContext)} 
      * method defined by this specification.
      */
@@ -94,8 +94,8 @@ public interface HttpMessageContext {
     AuthenticationParameters getAuthParameters();
 
     /**
-     * Returns the low level JSR 196 handler that the runtime provided when creating this {@link HttpMessageContext},
-     * and which this context uses to communicate the authentication details to the runtime.
+     * Returns the low level Jakarta Authentication handler that the runtime provided when creating this 
+     * {@link HttpMessageContext}, and which this context uses to communicate the authentication details to the runtime.
      * 
      * <p>
      * <em>Note:</em> This is a low level object that most higher level code would not need to use directly.
@@ -105,7 +105,7 @@ public interface HttpMessageContext {
     CallbackHandler getHandler();
 
     /**
-     * Returns the the low level JSR 196 message info instance for the current request.
+     * Returns the the low level Jakarta Authentication message info instance for the current request.
      * 
      * <p>
      * <em>Note:</em> This is a low level object that most higher level code would not need to use directly.
@@ -179,7 +179,7 @@ public interface HttpMessageContext {
     AuthenticationStatus redirect(String location);
 
     /**
-     * Forwards to another resource (servlet, JSP file, or HTML file) on the server.
+     * Forwards to another resource (Jakarta Servlet, Jakarta Server Pages file, or HTML file) on the server.
      * 
      * <p>
      * As a convenience this method returns SEND_CONTINUE, so this method can be used in
@@ -297,7 +297,7 @@ public interface HttpMessageContext {
      * Instructs the container to "do nothing".
      * 
      * <p>
-     * When intending to do nothing, a JSR 375 authentication mechanism has to indicate this
+     * When intending to do nothing, a Jakarta Security authentication mechanism has to indicate this
      * explicitly via its return value.
      * 
      * <p>

src/main/java/javax/security/enterprise/authentication/mechanism/http/LoginToContinue.java

@@ -157,7 +157,7 @@ public String errorPage() {
     boolean useForwardToLogin() default true;
 
     /**
-     * EL expression variant of <code>useForwardToLogin()</code>.
+     * Jakarta Expression Language expression variant of <code>useForwardToLogin()</code>.
      * The expression needs to evaluate to a boolean outcome. All named CDI beans are available
      * to the expression. If both this attribute and <code>useForwardToLogin()</code> are specified, this
      * attribute take precedence.