replace non-servlet usages of request details get/set attribute with getUserData (#7068)

* move three keys that were in request details attributes to user data

* updated cdr side

* cleanup

* inconsequential change to force CI

* final fixme

* final fixme

* change log

* cleanup

* make RequestDetails thread-safe

* fix test regressions

* claude review

* claude review

* claude review

* spotless

* fix test

---------

Co-authored-by: Ken Stevens <[email protected]>

Author: fil512

hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/changelog/8_4_0/7068-request-details.yaml

@@ -0,0 +1,6 @@
+---
+type: change
+issue: 7068
+title: "RequestDetails.getAttribute() and RequestDetails.setAttribute() have been deprecated. Users are encouraged to 
+use getUserData() to share data. If Servlet Attributes are required, users can use the new getServletAttribute()
+and setServletAttribute() methods available on ServletRequestDetails."

hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/interceptors/interceptors.md

@@ -47,3 +47,29 @@ The following example shows an exception handling interceptor which overrides th
 {{snippet:classpath:/ca/uhn/hapi/fhir/docs/RequestExceptionInterceptor.java|interceptor}}
 ```
 
+## Working with RequestDetails in Interceptors
+
+Many interceptor hook methods receive a [RequestDetails](/hapi-fhir/apidocs/hapi-fhir-server/ca/uhn/fhir/rest/api/server/RequestDetails.html) parameter which provides access to request context information. When working with RequestDetails in interceptors:
+
+* **Use `getUserData()`** to pass information between different interceptor methods and hook points. This is the recommended approach for most interceptor use cases.
+
+* **For servlet attributes** (used for communication between servlet filters), use the `getServletAttribute()` and `setServletAttribute()` methods available on servlet-based RequestDetails implementations.
+
+```java
+@Hook(Pointcut.SERVER_INCOMING_REQUEST_PRE_HANDLED)
+public void preHandle(RequestDetails theRequestDetails) {
+    // Store data for use in later interceptor methods
+    theRequestDetails.getUserData().put("START_TIME", System.currentTimeMillis());
+}
+
+@Hook(Pointcut.SERVER_OUTGOING_RESPONSE)
+public void postHandle(RequestDetails theRequestDetails) {
+    // Retrieve data stored in earlier interceptor method
+    Long startTime = (Long) theRequestDetails.getUserData().get("START_TIME");
+    if (startTime != null) {
+        long duration = System.currentTimeMillis() - startTime;
+        // Log or process the duration...
+    }
+}
+```
+

hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/server_plain/resource_providers.md

@@ -72,6 +72,47 @@ In some cases, it may be useful to have access to the underlying HttpServletRequ
 {{snippet:classpath:/ca/uhn/hapi/fhir/docs/RestfulPatientResourceProviderMore.java|underlyingReq}}
 ```
 
+## Accessing RequestDetails
+
+Many server methods can accept a parameter of type [RequestDetails](/hapi-fhir/apidocs/hapi-fhir-server/ca/uhn/fhir/rest/api/server/RequestDetails.html), which provides access to request context information including headers, parameters, and user data. RequestDetails is commonly used in multitenancy scenarios, interceptors, and custom server logic.
+
+```java
+@Read()
+public Patient read(@IdParam IdType theId, RequestDetails theRequestDetails) {
+    // Access tenant information
+    String tenantId = theRequestDetails.getTenantId();
+    
+    // Access user data (for passing information between interceptors)
+    Map<Object, Object> userData = theRequestDetails.getUserData();
+    
+    // Access headers
+    String authHeader = theRequestDetails.getHeader("Authorization");
+    
+    // Your implementation here...
+    return patient;
+}
+```
+
+### RequestDetails Best Practices
+
+When working with RequestDetails, it's important to understand the distinction between different types of data storage:
+
+* **User Data** - Use `RequestDetails.getUserData()` to pass information between interceptor methods. This is the recommended approach for most use cases involving interceptors, security, and custom business logic.
+
+* **Servlet Attributes** - For servlet-specific request attributes (used for communication between servlet filters), use the `getServletAttribute()` and `setServletAttribute()` methods available on servlet-based RequestDetails implementations.
+
+```java
+// Recommended: Use getUserData() to pass values between different interceptors
+theRequestDetails.getUserData().put("CUSTOM_KEY_A", someValue);
+theRequestDetails.getUserData().get("CUSTOM_KEY_A");
+
+// To retrieve servlet attributes you can use
+if (theRequestDetails instanceof ServletRequestDetails) {
+    ServletRequestDetails servletDetails = (ServletRequestDetails) theRequestDetails;
+    Object value = servletDetails.getServletAttribute("SERVLET_ATTR");
+}
+```
+
 <a name="exceptions"/>
 
 # REST Exception/Error Handling

hapi-fhir-jaxrsserver-base/src/main/java/ca/uhn/fhir/jaxrs/server/util/JaxRsRequest.java

@@ -27,6 +27,7 @@
 import ca.uhn.fhir.rest.api.Constants;
 import ca.uhn.fhir.rest.api.RequestTypeEnum;
 import ca.uhn.fhir.rest.api.RestOperationTypeEnum;
+import ca.uhn.fhir.rest.api.server.IHasServletAttributes;
 import ca.uhn.fhir.rest.api.server.IRestfulResponse;
 import ca.uhn.fhir.rest.api.server.RequestDetails;
 import ca.uhn.fhir.rest.server.exceptions.InvalidRequestException;
@@ -36,7 +37,6 @@
 import jakarta.ws.rs.core.MediaType;
 import org.apache.commons.lang3.StringUtils;
 
-import java.io.IOException;
 import java.io.InputStream;
 import java.io.Reader;
 import java.nio.charset.Charset;
@@ -50,7 +50,7 @@
  *
  * @author Peter Van Houte | [email protected] | Agfa Healthcare
  */
-public class JaxRsRequest extends RequestDetails {
+public class JaxRsRequest extends RequestDetails implements IHasServletAttributes {
 
 	private HttpHeaders myHeaders;
 	private String myResourceString;
@@ -127,24 +127,60 @@ public void setHeaders(String theName, List<String> theValue) {
 		throw new UnsupportedOperationException(Msg.code(2500) + "Headers can not be modified in JAX-RS");
 	}
 
+	/**
+	 * Gets an attribute from the servlet request. Attributes are used for interacting with servlet request
+	 * attributes to communicate between servlet filters. These methods should not be used to pass information
+	 * between interceptor methods. Use {@link #getUserData()} instead to pass information
+	 * between interceptor methods.
+	 *
+	 * @param theAttributeName The attribute name
+	 * @return The attribute value, or null if the attribute is not set
+	 */
 	@Override
-	public Object getAttribute(String theAttributeName) {
+	public Object getServletAttribute(String theAttributeName) {
 		return myAttributes.get(theAttributeName);
 	}
 
+	/**
+	 * Sets an attribute on the servlet request. Attributes are used for interacting with servlet request
+	 * attributes to communicate between servlet filters. These methods should not be used to pass information
+	 * between interceptor methods. Use {@link #getUserData()} instead to pass information
+	 * between interceptor methods.
+	 *
+	 * @param theAttributeName The attribute name
+	 * @param theAttributeValue The attribute value
+	 */
 	@Override
-	public void setAttribute(String theAttributeName, Object theAttributeValue) {
+	public void setServletAttribute(String theAttributeName, Object theAttributeValue) {
 		myAttributes.put(theAttributeName, theAttributeValue);
 	}
 
+	/**
+	 * @deprecated Use {@link #getUserData()}. If servlet attributes are truly required, then use {@link IHasServletAttributes#getServletAttribute(String)}.
+	 */
+	@Deprecated
+	@Override
+	public Object getAttribute(String theAttributeName) {
+		return getServletAttribute(theAttributeName);
+	}
+
+	/**
+	 * @deprecated Use {@link #getUserData()}. If servlet attributes are truly required, then use {@link IHasServletAttributes#setServletAttribute(String, Object)}.
+	 */
+	@Deprecated
+	@Override
+	public void setAttribute(String theAttributeName, Object theAttributeValue) {
+		setServletAttribute(theAttributeName, theAttributeValue);
+	}
+
 	@Override
 	public InputStream getInputStream() {
 		// not yet implemented
 		throw new UnsupportedOperationException(Msg.code(599));
 	}
 
 	@Override
-	public Reader getReader() throws IOException {
+	public Reader getReader() {
 		// not yet implemented
 		throw new UnsupportedOperationException(Msg.code(600));
 	}
@@ -181,13 +217,14 @@ public String getServerBaseForRequest() {
 	 */
 	public static class Builder {
 		private final String myResourceName;
+		private final RequestTypeEnum myRequestType;
+		private final String myRequestUrl;
+		private final RestOperationTypeEnum myRestOperation;
+		private final AbstractJaxRsProvider myServer;
+
+		private String myResource;
 		private String myCompartment;
 		private String myId;
-		private RequestTypeEnum myRequestType;
-		private String myRequestUrl;
-		private String myResource;
-		private RestOperationTypeEnum myRestOperation;
-		private AbstractJaxRsProvider myServer;
 		private String myVersion;
 
 		/**
@@ -196,7 +233,7 @@ public static class Builder {
 		 * @param theServer        the server
 		 * @param theRequestType   the request type
 		 * @param theRestOperation the rest operation
-		 * @param theRequestUrl
+		 * @param theRequestUrl    the request url
 		 */
 		public Builder(
 				AbstractJaxRsProvider theServer,

hapi-fhir-server/src/main/java/ca/uhn/fhir/rest/api/server/IHasServletAttributes.java

@@ -0,0 +1,45 @@
+/*
+ * #%L
+ * HAPI FHIR - Server Framework
+ * %%
+ * Copyright (C) 2014 - 2025 Smile CDR, Inc.
+ * %%
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ * #L%
+ */
+package ca.uhn.fhir.rest.api.server;
+
+public interface IHasServletAttributes {
+
+	/**
+	 * Gets an attribute from the servlet request. Attributes are used for interacting with servlet request
+	 * attributes to communicate between servlet filters. These methods should not be used to pass information
+	 * between interceptor methods. Use {@link RequestDetails#getUserData()} instead to pass information
+	 * between interceptor methods.
+	 *
+	 * @param theAttributeName The attribute name
+	 * @return The attribute value, or null if the attribute is not set
+	 */
+	Object getServletAttribute(String theAttributeName);
+
+	/**
+	 * Sets an attribute on the servlet request. Attributes are used for interacting with servlet request
+	 * attributes to communicate between servlet filters. These methods should not be used to pass information
+	 * between interceptor methods. Use {@link RequestDetails#getUserData()} instead to pass information
+	 * between interceptor methods.
+	 *
+	 * @param theAttributeName The attribute name
+	 * @param theAttributeValue The attribute value
+	 */
+	void setServletAttribute(String theAttributeName, Object theAttributeValue);
+}

hapi-fhir-server/src/main/java/ca/uhn/fhir/rest/api/server/RequestDetails.java

@@ -31,12 +31,15 @@
 import ca.uhn.fhir.rest.server.interceptor.IServerInterceptor;
 import ca.uhn.fhir.util.StopWatch;
 import ca.uhn.fhir.util.UrlUtil;
+import jakarta.annotation.Nonnull;
 import jakarta.servlet.http.HttpServletRequest;
 import jakarta.servlet.http.HttpServletResponse;
 import org.apache.commons.lang3.ArrayUtils;
 import org.apache.commons.lang3.Validate;
 import org.hl7.fhir.instance.model.api.IBaseResource;
 import org.hl7.fhir.instance.model.api.IIdType;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 
 import java.io.IOException;
 import java.io.InputStream;
@@ -54,11 +57,14 @@
 import static org.apache.commons.lang3.StringUtils.isBlank;
 
 public abstract class RequestDetails {
-
+	private static final Logger ourLog = LoggerFactory.getLogger(RequestDetails.class);
 	public static final byte[] BAD_STREAM_PLACEHOLDER =
 			(Msg.code(2543) + "PLACEHOLDER WHEN READING FROM BAD STREAM").getBytes(StandardCharsets.UTF_8);
+
 	private final StopWatch myRequestStopwatch;
-	private IInterceptorBroadcaster myInterceptorBroadcaster;
+	private final IInterceptorBroadcaster myInterceptorBroadcaster;
+	private final Map<Object, Object> myUserData = new UserDataMap();
+
 	private String myTenantId;
 	private String myCompartmentName;
 	private String myCompleteUrl;
@@ -76,7 +82,6 @@ public abstract class RequestDetails {
 	private String mySecondaryOperation;
 	private boolean mySubRequest;
 	private Map<String, List<String>> myUnqualifiedToQualifiedNames;
-	private Map<Object, Object> myUserData;
 	private IBaseResource myResource;
 	private String myRequestId;
 	private String myTransactionGuid;
@@ -116,11 +121,14 @@ public RequestDetails(RequestDetails theRequestDetails) {
 		mySecondaryOperation = theRequestDetails.getSecondaryOperation();
 		mySubRequest = theRequestDetails.isSubRequest();
 		myUnqualifiedToQualifiedNames = theRequestDetails.getUnqualifiedToQualifiedNames();
-		myUserData = theRequestDetails.getUserData();
+		myUserData.putAll(theRequestDetails.getUserData());
 		myResource = theRequestDetails.getResource();
 		myRequestId = theRequestDetails.getRequestId();
 		myTransactionGuid = theRequestDetails.getTransactionGuid();
 		myFixedConditionalUrl = theRequestDetails.getFixedConditionalUrl();
+		myRewriteHistory = theRequestDetails.isRewriteHistory();
+		myMaxRetries = theRequestDetails.getMaxRetries();
+		myRetry = theRequestDetails.isRetry();
 	}
 
 	public String getFixedConditionalUrl() {
@@ -259,7 +267,7 @@ public void setFhirServerBase(String theFhirServerBase) {
 	/**
 	 * Adds a new header
 	 *
-	 * @param theName The header name
+	 * @param theName  The header name
 	 * @param theValue The header value
 	 * @since 7.2.0
 	 */
@@ -268,7 +276,7 @@ public void setFhirServerBase(String theFhirServerBase) {
 	/**
 	 * Replaces any existing header(s) with the given name using a List of new header values
 	 *
-	 * @param theName The header name
+	 * @param theName  The header name
 	 * @param theValue The header value
 	 * @since 7.2.0
 	 */
@@ -283,18 +291,27 @@ public void setId(IIdType theId) {
 	}
 
 	/**
-	 * Returns the attribute map for this request. Attributes are a place for user-supplied
-	 * objects of any type to be attached to an individual request. They can be used to pass information
-	 * between interceptor methods.
+	 * @deprecated Use {@link #getUserData()}. If servlet attributes are truly required, then use {@link IHasServletAttributes#getServletAttribute(String)}.
 	 */
-	public abstract Object getAttribute(String theAttributeName);
+	@Deprecated
+	public Object getAttribute(String theAttributeName) {
+		ourLog.error(
+				"{} is not a servlet request. Unable to get attribute {}",
+				getClass().getName(),
+				theAttributeName);
+		return null;
+	}
 
 	/**
-	 * Returns the attribute map for this request. Attributes are a place for user-supplied
-	 * objects of any type to be attached to an individual request. They can be used to pass information
-	 * between interceptor methods.
+	 * @deprecated Use {@link #getUserData()}. If servlet attributes are truly required, then use {@link IHasServletAttributes#setServletAttribute(String, Object)}.
 	 */
-	public abstract void setAttribute(String theAttributeName, Object theAttributeValue);
+	@Deprecated
+	public void setAttribute(String theAttributeName, Object theAttributeValue) {
+		ourLog.error(
+				"{} is not a servlet request. Unable to set attribute {}",
+				getClass().getName(),
+				theAttributeName);
+	}
 
 	/**
 	 * Retrieves the body of the request as binary data. Either this method or {@link #getReader} may be called to read
@@ -374,7 +391,7 @@ public String getRequestPath() {
 	}
 
 	public void setRequestPath(String theRequestPath) {
-		assert theRequestPath.length() == 0 || theRequestPath.charAt(0) != '/';
+		assert theRequestPath.isEmpty() || theRequestPath.charAt(0) != '/';
 		myRequestPath = theRequestPath;
 	}
 
@@ -488,11 +505,14 @@ public Map<String, List<String>> getUnqualifiedToQualifiedNames() {
 	 * to a later hook method on the {@link ca.uhn.fhir.interceptor.api.Pointcut#SERVER_OUTGOING_RESPONSE}
 	 * pointcut.
 	 * </p>
+	 * <p>
+	 * This method should be used to pass information between interceptor methods. For servlet-specific
+	 * request attributes used to communicate between servlet filters, use {@link IHasServletAttributes}
+	 * methods available on implementations that support them.
+	 * </p>
 	 */
+	@Nonnull
 	public Map<Object, Object> getUserData() {
-		if (myUserData == null) {
-			myUserData = new HashMap<>();
-		}
 		return myUserData;
 	}
 
@@ -545,7 +565,6 @@ public final synchronized byte[] loadRequestContents() {
 					myRequestContents = BAD_STREAM_PLACEHOLDER;
 				}
 			}
-			assert myRequestContents != null : "We must not re-read the stream.";
 		}
 		return getRequestContentsIfLoaded();
 	}