Add docs, upgrade guide, upgrade.md

hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/changelog/7_0_0/2082-jakarta-api-changes.yaml

@@ -0,0 +1,4 @@
+---
+type: fix
+issue: 5452
+title: "Swapped from using `javax.*` to `jakarta.*` packages. This is a breaking change for a large majority of people who write custom code against HAPI-FHIR. Please see [the migration guide](/docs/interceptors/jakarta_upgrade.md) for more information."

hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/changelog/7_0_0/upgrade.md

@@ -0,0 +1 @@
+This release contains a large breaking change for authors of interceptors. Internally, HAPI-FHIR has swapped from using `javax.*` to `jakarta.*` packages. Please see [the migration guide](/docs/interceptors/jakarta_upgrade.md) for more information.  Without manual intervention, the majority of interceptors will fail at runtime unless they are upgraded.

hapi-fhir-docs/src/main/resources/ca/uhn/hapi/fhir/docs/files.properties

@@ -105,6 +105,7 @@ page.interceptors.built_in_client_interceptors=Built-In Client Interceptors
 page.interceptors.server_interceptors=Server Interceptors
 page.interceptors.server_pointcuts=Server Pointcuts
 page.interceptors.built_in_server_interceptors=Built-In Server Interceptors
+page.interceptors.jakarta_upgrade=7.0.0 Migration Guide
 
 section.security.title=Security
 page.security.introduction=Introduction

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

@@ -0,0 +1,78 @@
+# 7.0.0 Interceptor Upgrade Guide
+
+As of HAPI-FHIR 7.0.0, dependency on the `javax.*` packages has now changed to instead use the `jakarta.*` packages. This is a breaking change for any users who have written their own interceptors, as the package names of the interfaces have changed.
+
+In order to upgrade your interceptors, you will need to change, at a minimum, the imports in your affected interceptor implementations. For example, if you have an interceptor that uses imports such as `javax.servlet.http.HttpServletRequest`, you will need to change these to `jakarta.servlet.http.HttpServletRequest`. The following is an example of a migration of an interceptor.
+
+## Example
+
+### Old Server Interceptor
+
+```java
+package com.example;
+
+import ca.uhn.fhir.interceptor.api.Hook;
+import ca.uhn.fhir.interceptor.api.Pointcut;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.beans.factory.annotation.Autowired;
+
+import javax.servlet.http.HttpServletRequest;
+import javax.servlet.http.HttpServletResponse;
+import java.util.Iterator;
+import java.util.function.Supplier;
+
+public class SampleInteceptor{
+
+    private static final Logger ourLog = LoggerFactory.getLogger(SampleInteceptor.class);
+    
+	@Hook(Pointcut.SERVER_INCOMING_REQUEST_PRE_PROCESSED)
+	public boolean serverIncomingRequestPreProcessed(HttpServletRequest theHttpServletRequest, HttpServletResponse theHttpServletResponse) {
+		ourLog.info("I'm an interceptor!");
+		return true;
+	}
+}
+```
+
+## New Server Interceptor
+
+```java
+package com.example;
+
+import ca.uhn.fhir.interceptor.api.Hook;
+import ca.uhn.fhir.interceptor.api.Pointcut;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.beans.factory.annotation.Autowired;
+
+import jakarta.servlet.http.HttpServletRequest;
+import jakarta.servlet.http.HttpServletResponse;
+import java.util.Iterator;
+import java.util.function.Supplier;
+
+public class SampleInteceptor{
+
+    private static final Logger ourLog = LoggerFactory.getLogger(SampleInteceptor.class);
+    
+	@Hook(Pointcut.SERVER_INCOMING_REQUEST_PRE_PROCESSED)
+	public boolean serverIncomingRequestPreProcessed(HttpServletRequest theHttpServletRequest, HttpServletResponse theHttpServletResponse) {
+		ourLog.info("I'm an interceptor!");
+		return true;
+	}
+}
+```
+
+You'll note that there is only one very subtle difference between these two versions, and that is the change from: 
+
+```java
+import javax.servlet.http.HttpServletRequest;
+import javax.servlet.http.HttpServletResponse;
+```
+
+to:
+
+```java
+import jakarta.servlet.http.HttpServletRequest;
+import jakarta.servlet.http.HttpServletResponse;
+```
+