From 53dfb44a8fb7fc0b13898bbffeffed9ffceaaf69 Mon Sep 17 00:00:00 2001 From: Pedro Igor Date: Wed, 31 May 2023 10:50:34 -0300 Subject: [PATCH] Migration guide for JAX-RS changes (#20659) Closes #keycloak/keycloak#15454 --- .../release_notes/topics/22_0_0.adoc | 16 +++++ .../topics/keycloak/changes-22_0_0.adoc | 72 +++++++++++++++++++ .../authorization/admin/PolicyService.java | 1 - .../resources/admin/UsersResource.java | 1 - 4 files changed, 88 insertions(+), 2 deletions(-) diff --git a/docs/documentation/release_notes/topics/22_0_0.adoc b/docs/documentation/release_notes/topics/22_0_0.adoc index 7e7473fe18..d43d5a5b7f 100644 --- a/docs/documentation/release_notes/topics/22_0_0.adoc +++ b/docs/documentation/release_notes/topics/22_0_0.adoc @@ -61,3 +61,19 @@ See the migration guide for more details. The `openshift-integration` preview feature was removed from Keycloak codebase into separate extension project. See the migration guide for more details. + += Context and dependency injection no longer enabled to JAX-RS Resources + +In order to provide a better runtime and leverage as much as possible the underlying stack, +all injection points for contextual data using the `javax.ws.rs.core.Context` annotation were removed. The expected improvement +in performance involves no longer creating proxies instances multiple times during the request lifecycle, and drastically reducing the amount of reflection code at runtime. + +If you are extending one of the following SPIs: + +* `PolicySpi` +* `AdminRealmResourceSpi` +* `IdentityProviderSpi` +* `RealmResourceSPI` + +See the link:{upgradingguide_link}[{upgradingguide_name}] for more details about how to +update your custom providers. \ No newline at end of file diff --git a/docs/documentation/upgrading/topics/keycloak/changes-22_0_0.adoc b/docs/documentation/upgrading/topics/keycloak/changes-22_0_0.adoc index a7cf5d6398..259b3b93ce 100644 --- a/docs/documentation/upgrading/topics/keycloak/changes-22_0_0.adoc +++ b/docs/documentation/upgrading/topics/keycloak/changes-22_0_0.adoc @@ -251,3 +251,75 @@ The removal of openshift-integration allows us to remove few thirdparty dependen any of these libraries as dependencies of your own providers deployed to Keycloak server, you may also need to copy those `jar` files explicitly to the Keycloak distribution `providers` directory as well. += Context and dependency injection no longer enabled to JAX-RS Resources + +In order to provide a better runtime and leverage as much as possible the underlying stack, +all injection points for contextual data using the `javax.ws.rs.core.Context` annotation were removed. The expected improvement +in performance involves no longer creating proxies instances multiple times during the request lifecycle, and drastically reducing the amount of reflection code at runtime. + +If you are extending one of the following SPIs: + +* `PolicySpi` +* `AdminRealmResourceSpi` +* `IdentityProviderSpi` +* `RealmResourceSPI` + +You should review your custom JAX-RS (sub)resources in order to obtain any contextual data as follows: + +[source,java] +---- +KeycloakSession session = org.keycloak.common.util.Resteasy.getContextData(KeycloakSession.class); +---- + +If you need access to the current request and response objects, you can now obtain their instances directly +from the `KeycloakSession`: + +[source,java] +---- +@Context +org.jboss.resteasy.spi.HttpRequest request; +@Context +org.jboss.resteasy.spi.HttpResponse response; +---- + +was replaced by: + +[source,java] +---- +KeycloakSession session = // obtain the session, which is usually available when creating a custom provider from a factory +KeycloakContext context = session.getContext(); + +HttpRequest request = context.getHttpRequest(); +HttpResponse response = context.getHttpResponse(); +---- + +In case you have no access to a `KeycloakSession` instance when invoking a JAX-RS resource method, you can obtain +contextual data from the JAX-RS runtime as follows: + +[source,java] +---- +KeycloakSession session = org.keycloak.common.util.Resteasy.getContextData(KeycloakSession.class); +---- + +Additional contextual data can be obtained from the runtime through the `KeycloakContext` instance: + +[source,java] +---- +KeycloakSession session = // obtain the session +KeycloakContext context = session.getContext(); +MyContextualObject myContextualObject = context.getContextObject(MyContextualObject.class); +---- + += Upgrading your custom JAX-RS resources + +If you are extending the server's REST APIs through the following SPIs: + +* `PolicySpi` +* `AdminRealmResourceSpi` +* `IdentityProviderSpi` +* `RealmResourceSPI` + +You need to add an empty `META-INF/beans.xml` to the JAR file where your custom providers are packaged. Otherwise, they are not recognized by the server +at runtime. + +You should also make sure your JAX-RS methods are declaring the expected media types for input and output by marking them with the `@Consumes` and `@Produces` annotations, respectively. \ No newline at end of file diff --git a/services/src/main/java/org/keycloak/authorization/admin/PolicyService.java b/services/src/main/java/org/keycloak/authorization/admin/PolicyService.java index 54847bf79b..2d4a620ec4 100644 --- a/services/src/main/java/org/keycloak/authorization/admin/PolicyService.java +++ b/services/src/main/java/org/keycloak/authorization/admin/PolicyService.java @@ -31,7 +31,6 @@ import jakarta.ws.rs.Path; import jakarta.ws.rs.PathParam; import jakarta.ws.rs.Produces; import jakarta.ws.rs.QueryParam; -import jakarta.ws.rs.core.Context; import jakarta.ws.rs.core.MediaType; import jakarta.ws.rs.core.Response; import jakarta.ws.rs.core.Response.Status; diff --git a/services/src/main/java/org/keycloak/services/resources/admin/UsersResource.java b/services/src/main/java/org/keycloak/services/resources/admin/UsersResource.java index e57335ae7b..c6f43f0511 100755 --- a/services/src/main/java/org/keycloak/services/resources/admin/UsersResource.java +++ b/services/src/main/java/org/keycloak/services/resources/admin/UsersResource.java @@ -51,7 +51,6 @@ import jakarta.ws.rs.Path; import jakarta.ws.rs.PathParam; import jakarta.ws.rs.Produces; import jakarta.ws.rs.QueryParam; -import jakarta.ws.rs.core.Context; import jakarta.ws.rs.core.HttpHeaders; import jakarta.ws.rs.core.MediaType; import jakarta.ws.rs.core.Response;