[SDK-4644] Servlet Quickstart - Clarify that AuthenticationController should only be created once

articles/quickstart/webapp/java/_includes/_login.md

@@ -32,26 +32,47 @@ The project contains also four servlets:
 - `CallbackServlet.java`: The servlet captures requests to our Callback URL and processes the data to obtain the credentials. After a successful login, the credentials are then saved to the request's HttpSession.
 - `HomeServlet.java`: The servlet reads the previously saved tokens and shows them on the `home.jsp` resource.
 - `LogoutServlet.java`: Invoked when the user clicks the logout link. The servlet invalidates the user session and redirects the user to the login page, handled by the `LoginServlet`.
+- `AuthenticationControllerProvider`: Responsible to create and manage a single instance of the `AuthenticationController`
 
-Lastly, the project defines a helper class: the `AuthenticationControllerProvider.java` which will be in charge of creating new instances of `AuthenticationController`. Because this controller is very simple and doesn't keep any context it can be safely reused. You can also choose to create a new one every time it's needed.
+## Create the AuthenticationController
 
-## Trigger Authentication
+To enable users to authenticate, create an instance of the `AuthenticationController` provided by the `auth0-java-mvc-commons` SDK using the `domain`, `clientId`, and `clientSecret`.  The sample shows how to configure the component for use with tokens signed using the RS256 asymmetric signing algorithm, by specifying a `JwkProvider` to fetch the public key used to verify the token's signature. See the [jwks-rsa-java repository](https://github.com/auth0/jwks-rsa-java) to learn about additional configuration options. If you are using HS256, there is no need to configure the `JwkProvider`. 
 
-To enable users to authenticate, create an instance of the `AuthenticationController` provided by the `auth0-java-mvc-commons` SDK using the `domain`, `clientId`, and `clientSecret`.  The sample below shows how to configure the component for use with tokens signed using the RS256 asymmetric signing algorithm, by specifying a `JwkProvider` to fetch the public key used to verify the token's signature. See the [jwks-rsa-java repository](https://github.com/auth0/jwks-rsa-java) to learn about additional configuration options. If you are using HS256, there is no need to configure the `JwkProvider`. 
+:::note
+The `AuthenticationController` does not store any context, and is inteded to be reused. Unneccessary creation may result in additonal resources being created which could impact performance.
+:::
 
 ```java
-// src/main/java/com/auth0/example/AuthenticationControllerProvider.java
+class AuthenticationControllerProvider {
+
+    private AuthenticationControllerProvider() {}
+
+    private static AuthenticationController INSTANCE;
+
+    // if multiple threads may call this, synchronize this method and consider double locking
+    static AuthenticationController getInstance(ServletConfig config) throws UnsupportedEncodingException {
+        if (INSTANCE == null) {
+            String domain = config.getServletContext().getInitParameter("com.auth0.domain");
+            String clientId = config.getServletContext().getInitParameter("com.auth0.clientId");
+            String clientSecret = config.getServletContext().getInitParameter("com.auth0.clientSecret");
 
-String domain = getServletConfig().getServletContext().getInitParameter("com.auth0.domain");
-String clientId = getServletConfig().getServletContext().getInitParameter("com.auth0.clientId");
-String clientSecret = getServletConfig().getServletContext().getInitParameter("com.auth0.clientSecret");
+            if (domain == null || clientId == null || clientSecret == null) {
+                throw new IllegalArgumentException("Missing domain, clientId, or clientSecret. Did you update src/main/webapp/WEB-INF/web.xml?");
+            }
 
-JwkProvider jwkProvider = new JwkProviderBuilder(domain).build();
-AuthenticationController controller = AuthenticationController.newBuilder(domain, clientId, clientSecret)
-                .withJwkProvider(jwkProvider)
-                .build();
+            // JwkProvider required for RS256 tokens. If using HS256, do not use.
+            JwkProvider jwkProvider = new JwkProviderBuilder(domain).build();
+            INSTANCE = AuthenticationController.newBuilder(domain, clientId, clientSecret)
+                    .withJwkProvider(jwkProvider)
+                    .build();
+        }
+
+        return INSTANCE;
+    }
 ```
 
+## Trigger Authentication
+
 To enable users to login, your application will redirect them to the [Universal Login](https://auth0.com/docs/universal-login) page. Using the `AuthenticationController` instance, you can generate the redirect URL by calling the `buildAuthorizeUrl(HttpServletRequest request, HttpServletResponse response, String redirectUrl)` method. The redirect URL must be the URL that was added to the **Allowed Callback URLs** of your Auth0 Application.
 
 ```java

articles/quickstart/webapp/java/files/authentication-controller-provider.md

@@ -3,18 +3,31 @@ name: AuthenticationControllerProvider.java
 language: java
 ---
 ```java
-public abstract class AuthenticationControllerProvider {
+class AuthenticationControllerProvider {
 
-    public static AuthenticationController getInstance(ServletConfig config) throws UnsupportedEncodingException {
-        String domain = config.getServletContext().getInitParameter("com.auth0.domain");
-        String clientId = config.getServletContext().getInitParameter("com.auth0.clientId");
-        String clientSecret = config.getServletContext().getInitParameter("com.auth0.clientSecret");
+    private AuthenticationControllerProvider() {}
 
-        // JwkProvider required for RS256 tokens. If using HS256, do not use.
-        JwkProvider jwkProvider = new JwkProviderBuilder(domain).build();
-        return AuthenticationController.newBuilder(domain, clientId, clientSecret)
-                .withJwkProvider(jwkProvider)
-                .build();
+    private static AuthenticationController INSTANCE;
+
+    // if multiple threads may call this, synchronize this method and consider double locking
+    static AuthenticationController getInstance(ServletConfig config) throws UnsupportedEncodingException {
+        if (INSTANCE == null) {
+            String domain = config.getServletContext().getInitParameter("com.auth0.domain");
+            String clientId = config.getServletContext().getInitParameter("com.auth0.clientId");
+            String clientSecret = config.getServletContext().getInitParameter("com.auth0.clientSecret");
+
+            if (domain == null || clientId == null || clientSecret == null) {
+                throw new IllegalArgumentException("Missing domain, clientId, or clientSecret. Did you update src/main/webapp/WEB-INF/web.xml?");
+            }
+
+            // JwkProvider required for RS256 tokens. If using HS256, do not use.
+            JwkProvider jwkProvider = new JwkProviderBuilder(domain).build();
+            INSTANCE = AuthenticationController.newBuilder(domain, clientId, clientSecret)
+                    .withJwkProvider(jwkProvider)
+                    .build();
+        }
+
+        return INSTANCE;
     }
 }
 ```

articles/quickstart/webapp/java/interactive.md

@@ -107,13 +107,16 @@ The project contains also four servlets:
 - `CallbackServlet.java`: The servlet captures requests to our Callback URL and processes the data to obtain the credentials. After a successful login, the credentials are then saved to the request's HttpSession.
 - `HomeServlet.java`: The servlet reads the previously saved tokens and shows them on the `home.jsp` resource.
 - `LogoutServlet.java`: Invoked when the user clicks the logout link. The servlet invalidates the user session and redirects the user to the login page, handled by the `LoginServlet`.
-
-Lastly, the project defines a helper class: the `AuthenticationControllerProvider.java` which will be in charge of creating new instances of `AuthenticationController`. Because this controller is very simple and doesn't keep any context it can be safely reused. You can also choose to create a new one every time it's needed.
-
-## Trigger Authentication {{{ data-action=code data-code="AuthenticationControllerProvider.java#4:12" }}}
+- `AuthenticationControllerProvider`: Responsible to create and manage a single instance of the `AuthenticationController`
+
+## Create the AuthenticationController {{{ data-action=code data-code="AuthenticationControllerProvider.java#6-32 }}}
 
 To enable users to authenticate, create an instance of the `AuthenticationController` provided by the `auth0-java-mvc-commons` SDK using the `domain`, `clientId`, and `clientSecret`.  The sample shows how to configure the component for use with tokens signed using the RS256 asymmetric signing algorithm, by specifying a `JwkProvider` to fetch the public key used to verify the token's signature. See the [jwks-rsa-java repository](https://github.com/auth0/jwks-rsa-java) to learn about additional configuration options. If you are using HS256, there is no need to configure the `JwkProvider`. 
 
+:::note
+The `AuthenticationController` does not store any context, and is inteded to be reused. Unneccessary creation may result in additonal resources being created which could impact performance.
+:::
+
 ## Login Redirection {{{ data-action=code data-code="LoginServlet.java#21:23" }}}
 
 To enable users to log in, your application will redirect them to the [Universal Login](https://auth0.com/docs/universal-login) page. Using the `AuthenticationController` instance, you can generate the redirect URL by calling the `buildAuthorizeUrl(HttpServletRequest request, HttpServletResponse response, String redirectUrl)` method. The redirect URL must be the URL that was added to the **Allowed Callback URLs** of your Auth0 application.