Update javadoc of RequestContextController with suggested usage

jakartaee · Sep 2, 2024 · ca235a4 · ca235a4
1 parent 778d0bf
commit ca235a4
Showing 1 changed file with 10 additions and 7 deletions.
diff --git a/api/src/main/java/jakarta/enterprise/context/control/RequestContextController.java b/api/src/main/java/jakarta/enterprise/context/control/RequestContextController.java
@@ -17,7 +17,7 @@
 import jakarta.enterprise.context.ContextNotActiveException;
 
 /**
- * The CDI container provides a built in instance of RequestContextController that is dependent scoped for the purposes
+ * The CDI container provides a built-in instance of {@code RequestContextController} that is dependent scoped for the purposes
  * of activating and deactivating. For example:
  *
  * <pre>
@@ -26,12 +26,15 @@
  *
  * public void doRequest(String body) {
  *     // activate request context
- *     requestContextController.activate();
- *
- *     // do work in a request context.
- *
- *     // deactivate the request context
- *     requestContextController.deactivate();
+ *     boolean activated = requestContextController.activate();
+ *     try {
+ *         // do work in a request context.
+ *     } finally {
+ *         // deactivate the request context if we activated it earlier
+ *         if (activated) {
+ *             requestContextController.deactivate();
+ *         }
+ *     }
  * }
  * </pre>
  *