Merge pull request #60 from jamezp/integration-updates

Update source files to use more modern approaches to creating instanc…

Author: jamezp

README.adoc

@@ -63,7 +63,7 @@ You need to use the `GuiceResteasyBootstrapServletContextListener` as follows
     <servlet>
         <servlet-name>Resteasy</servlet-name>
         <servlet-class>
-            org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher
+            org.jboss.resteasy.plugins.server.servlet.HttpServlet30Dispatcher
         </servlet-class>
     </servlet>
 
@@ -79,31 +79,61 @@ You need to use the `GuiceResteasyBootstrapServletContextListener` as follows
 Also notice that there is a `resteasy.guice.modules` context-param.
 This can take a comma delimited list of class names that are Guice Modules.
 
+== Registering resources and providers
+
+Guice does not scan the classpath, so RESTEasy Guice can only see what your modules explicitly bind.
+Every `@Path` root resource and every `@Provider` must be bound in one of your modules; an unbound resource is simply not registered and its endpoints return `404`.
+
+[source,java]
+----
+public class MyModule implements Module {
+    @Override
+    public void configure(final Binder binder) {
+        binder.bind(HelloResource.class);              // a @Path resource
+        binder.bind(MyExceptionMapper.class);          // an @Provider
+        binder.bind(GreetingService.class).to(GreetingServiceImpl.class);
+    }
+}
+----
+
+Resources are instantiated by Guice, so constructor injection uses Guice bindings.
+This means the Jakarta REST `@Context` annotation cannot be used on a constructor parameter — RESTEasy performs `@Context` injection on fields and setters only, after Guice has created the instance.
+To inject the request-scoped context objects (`UriInfo`, `HttpHeaders`, etc.) through a constructor, install the `RequestScopeModule` (see below) and use a plain `@Inject` constructor.
+
 == Request Scope
 
-Add the `RequestScopeModule` to your modules to allow objects to be scoped to the HTTP request by adding the `@RequestScoped` annotation to your fields in resource classes.
-All the objects injectable via the `@Context` annotation are  also injectable, except `ServletConfig` and `ServletContext`.
-Note that `RequestScopeModule` will already be added if any of your modules extends `com.google.inject.servlet.ServletModule`.
-In such cases you should not add it again to avoid injector creation errors.
+Add the `RequestScopeModule` to your modules to make the Jakarta REST context objects injectable with a plain Guice `@Inject`, bound to the current HTTP request.
+The following types are bound: `UriInfo`, `HttpHeaders`, `Request`, `SecurityContext`, `HttpServletRequest`, and `HttpServletResponse` (`ServletConfig` and `ServletContext` are not bound).
 
 [source,java]
 ----
 
 import jakarta.inject.Inject;
-import jakarta.servlet.http.HttpServletRequest;
-import jakarta.ws.rs.core.Context;
+import jakarta.ws.rs.GET;
+import jakarta.ws.rs.Path;
+import jakarta.ws.rs.core.UriInfo;
+
+@Path("example")
+public class ExampleResource {
+    private final UriInfo uriInfo;
 
-import dev.resteasy.guice.RequestScoped;
+    @Inject
+    public ExampleResource(final UriInfo uriInfo) {
+        this.uriInfo = uriInfo;
+    }
 
-public class MyClass {
-    @Inject @RequestScoped @Context
-    private HttpRequest request;
+    @GET
+    public String get() {
+        return uriInfo.getRequestUri().toString();
+    }
 }
 ----
 
+The scope is also available directly as the `dev.resteasy.guice.RequestScoped` annotation for binding your own request-scoped objects.
+
 == Binding Jakarta REST utilities
 
-Add the `JaxrsModule` to bind `jakarta.ws.rs.ext.RuntimeDelegate`, `jakarta.ws.rs.core.Response.ResponseBuilder`, `jakarta.ws.rs.core.UriBuilder`, `jakarta.ws.rs.core.Variant.VariantListBuilder` and `org.jboss.resteasy.client.jaxrs.ClientHttpEngine`.
+Add the `JaxrsModule` to bind the Jakarta REST utility factories so they can be injected: `jakarta.ws.rs.ext.RuntimeDelegate`, `jakarta.ws.rs.core.Response.ResponseBuilder`, `jakarta.ws.rs.core.UriBuilder`, and `jakarta.ws.rs.core.Variant.VariantListBuilder`.
 
 == Configuring Stage
 
@@ -135,7 +165,7 @@ If this value is not specified, RESTEasy uses whatever Guice's default is.
     <servlet>
         <servlet-name>Resteasy</servlet-name>
         <servlet-class>
-            org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher
+            org.jboss.resteasy.plugins.server.servlet.HttpServlet30Dispatcher
         </servlet-class>
     </servlet>
 
@@ -235,13 +265,11 @@ Once everything is setup, you simply need to run the `./release.sh` script. Ther
 
 By default the release version cannot contain `SNAPSHOT` and the development version, must container `SNAPSHOT`.
 
-[source,bash]
-----
 .Example Command
+[source,bash]
 ----
 ./release -r 1.0.0.Final -d 1.0.1.Final-SNAPSHOT
 ----
-----
 
 === Supported Arguments
 

pom.xml

@@ -71,11 +71,12 @@
         <!-- Check to see if it can be removed when updating Guice. -->
         <version.com.google.guava.guava>33.7.1-jre</version.com.google.guava.guava>
         <version.com.google.inject.guice>7.0.0</version.com.google.inject.guice>
+        <version.org.eclipse.jetty>12.1.12</version.org.eclipse.jetty>
         <version.org.jboss.logging>3.6.3.Final</version.org.jboss.logging>
         <version.org.jboss.logging.jboss-logging-tools>3.0.4.Final</version.org.jboss.logging.jboss-logging-tools>
         <version.org.jboss.logmanager>3.2.2.Final</version.org.jboss.logmanager>
         <version.org.jboss.resteasy>7.0.3.Final</version.org.jboss.resteasy>
-        <version.dev.resteasy.netty>1.0.0.Final</version.dev.resteasy.netty>
+        <version.org.jboss.slf4j>2.1.0.Final</version.org.jboss.slf4j>
         <version.org.junit>6.1.3</version.org.junit>
 
         <!-- Plugins versions -->
@@ -118,17 +119,18 @@
                 <scope>import</scope>
             </dependency>
             <dependency>
-                <groupId>dev.resteasy.netty</groupId>
-                <artifactId>resteasy-netty-bom</artifactId>
-                <version>${version.dev.resteasy.netty}</version>
+                <groupId>org.eclipse.jetty</groupId>
+                <artifactId>jetty-bom</artifactId>
+                <version>${version.org.eclipse.jetty}</version>
                 <type>pom</type>
                 <scope>import</scope>
             </dependency>
-            <!-- This is a typo in the BOM of the resteasy-netty-bom where there is no resteasy-netty-embedded-server -->
             <dependency>
-                <groupId>dev.resteasy.netty</groupId>
-                <artifactId>resteasy-embedded-server</artifactId>
-                <version>${version.dev.resteasy.netty}</version>
+                <groupId>org.eclipse.jetty.ee11</groupId>
+                <artifactId>jetty-ee11-bom</artifactId>
+                <version>${version.org.eclipse.jetty}</version>
+                <type>pom</type>
+                <scope>import</scope>
             </dependency>
             <dependency>
                 <groupId>org.junit</groupId>
@@ -189,12 +191,14 @@
 
         <!-- Test dependencies -->
         <dependency>
-            <groupId>dev.resteasy.netty</groupId>
-            <artifactId>resteasy-reactor-netty-client</artifactId>
+            <groupId>org.eclipse.jetty</groupId>
+            <artifactId>jetty-server</artifactId>
+            <scope>test</scope>
         </dependency>
         <dependency>
-            <groupId>dev.resteasy.netty</groupId>
-            <artifactId>resteasy-embedded-server</artifactId>
+            <groupId>org.eclipse.jetty.ee11</groupId>
+            <artifactId>jetty-ee11-servlet</artifactId>
+            <scope>test</scope>
         </dependency>
         <dependency>
             <groupId>org.junit.jupiter</groupId>
@@ -208,6 +212,12 @@
             <version>${version.org.jboss.logmanager}</version>
             <scope>test</scope>
         </dependency>
+        <dependency>
+            <groupId>org.jboss.slf4j</groupId>
+            <artifactId>slf4j-jboss-logmanager</artifactId>
+            <version>${version.org.jboss.slf4j}</version>
+            <scope>test</scope>
+        </dependency>
     </dependencies>
 
     <build>

src/main/java/dev/resteasy/guice/GuiceResourceFactory.java

@@ -15,6 +15,11 @@
 
 import com.google.inject.Provider;
 
+/**
+ * A RESTEasy {@link ResourceFactory} backed by a Guice {@link Provider}. Each request obtains a fresh resource
+ * instance from {@link Provider#get()} (so the resource's Guice scope governs its lifecycle) and then runs
+ * RESTEasy property injection ({@code @Context} fields and setters) on it.
+ */
 public class GuiceResourceFactory implements ResourceFactory {
 
     private final Provider<?> provider;
@@ -26,27 +31,31 @@ public GuiceResourceFactory(final Provider<?> provider, final Class<?> scannable
         this.scannableClass = scannableClass;
     }
 
+    @Override
     public Class<?> getScannableClass() {
         return scannableClass;
     }
 
-    public void registered(ResteasyProviderFactory factory) {
+    @Override
+    public void registered(final ResteasyProviderFactory factory) {
         propertyInjector = factory.getInjectorFactory().createPropertyInjector(scannableClass, factory);
     }
 
     @Override
     public Object createResource(final HttpRequest request, final HttpResponse response,
             final ResteasyProviderFactory factory) {
         final Object resource = provider.get();
-        CompletionStage<Void> propertyStage = propertyInjector.inject(request, response, resource, true);
+        final CompletionStage<Void> propertyStage = propertyInjector.inject(request, response, resource, true);
         return propertyStage == null ? resource
                 : propertyStage
                         .thenApply(v -> resource);
     }
 
+    @Override
     public void requestFinished(final HttpRequest request, final HttpResponse response, final Object resource) {
     }
 
+    @Override
     public void unregistered() {
     }
 }

src/main/java/dev/resteasy/guice/GuiceResteasyBootstrapServletContextListener.java

@@ -31,6 +31,22 @@
 import com.google.inject.Module;
 import com.google.inject.Stage;
 
+/**
+ * A {@link ServletContextListener} that bootstraps RESTEasy with Guice. Register it in {@code web.xml} (or an
+ * equivalent programmatic servlet setup) alongside the RESTEasy dispatcher servlet.
+ * <p>
+ * On {@link #contextInitialized(ServletContextEvent) context initialization} it builds a Guice {@link Injector}
+ * from the configured {@link Module}s and hands it to a {@link ModuleProcessor}, which registers every bound
+ * {@code @Path} root resource and {@code @Provider} type with RESTEasy. Modules are, by default, taken from the
+ * comma-separated {@code resteasy.guice.modules} context-param and instantiated with their no-arg constructor;
+ * the Guice {@link Stage} may be set with the {@code resteasy.guice.stage} context-param.
+ * <p>
+ * The behavior can be customized by subclassing and overriding {@link #getModules(ServletContext)},
+ * {@link #getStage(ServletContext)}, or {@link #withInjector(Injector)}; register the subclass as the listener.
+ * If a parent {@link Injector} is available via {@link Inject field injection}, a child injector is created from
+ * it instead. No-arg {@link PostConstruct} and {@link PreDestroy} methods on module instances are invoked on
+ * context initialization and destruction, respectively.
+ */
 public class GuiceResteasyBootstrapServletContextListener extends ResteasyBootstrap implements ServletContextListener {
 
     private List<? extends Module> modules;
@@ -71,18 +87,20 @@ public void contextInitialized(final ServletContextEvent event) {
     }
 
     /**
-     * Override this method to interact with the {@link Injector} after it has been created. The default is no-op.
+     * Override this method to interact with the {@link Injector} after it has been created. The default is a no-op.
      *
-     * @param injector
+     * @param injector the fully-created injector for this deployment
      */
     protected void withInjector(Injector injector) {
     }
 
     /**
-     * Override this method to set the Stage. By default it is taken from resteasy.guice.stage context param.
+     * Override this method to set the Guice {@link Stage}. By default, it is taken from the
+     * {@code resteasy.guice.stage} context-param, or {@code null} (Guice's own default) if that is not set.
+     *
+     * @param context the servlet context for this deployment
      *
-     * @param context
-     * @return Guice Stage
+     * @return the Guice {@link Stage} to create the injector with, or {@code null} to use Guice's default
      */
     protected Stage getStage(ServletContext context) {
         final String stageAsString = context.getInitParameter("resteasy.guice.stage");
@@ -97,27 +115,29 @@ protected Stage getStage(ServletContext context) {
     }
 
     /**
-     * Override this method to instantiate your {@link Module}s yourself.
+     * Override this method to instantiate your {@link Module}s yourself, for example when a module needs
+     * constructor arguments. The default reads the comma-separated {@code resteasy.guice.modules} context-param
+     * and instantiates each listed class with its no-arg constructor.
+     *
+     * @param context the servlet context for this deployment
      *
-     * @param context
-     * @return
+     * @return the modules to build the injector from; never {@code null}
      */
     protected List<? extends Module> getModules(final ServletContext context) {
-        final List<Module> result = new ArrayList<Module>();
+        final List<Module> result = new ArrayList<>();
         final String modulesString = context.getInitParameter("resteasy.guice.modules");
         if (modulesString != null) {
             final String[] moduleStrings = modulesString.trim().split(",");
             for (final String moduleString : moduleStrings) {
                 try {
                     LogMessages.LOGGER.info(Messages.MESSAGES.foundModule(moduleString));
                     final Class<?> clazz = Thread.currentThread().getContextClassLoader().loadClass(moduleString.trim());
-                    final Module module = (Module) clazz.newInstance();
+                    final Module module = (Module) clazz.getDeclaredConstructor().newInstance();
                     result.add(module);
-                } catch (ClassNotFoundException | IllegalAccessException | InstantiationException e) {
+                } catch (ReflectiveOperationException e) {
                     throw new RuntimeException(e);
                 }
             }
-
         }
         return result;
     }
@@ -128,9 +148,9 @@ public void contextDestroyed(final ServletContextEvent event) {
     }
 
     private void triggerAnnotatedMethods(final Class<? extends Annotation> annotationClass) {
-        for (Module module : this.modules) {
+        for (final Module module : this.modules) {
             final Method[] methods = module.getClass().getMethods();
-            for (Method method : methods) {
+            for (final Method method : methods) {
                 if (method.isAnnotationPresent(annotationClass)) {
                     if (method.getParameterTypes().length > 0) {
                         LogMessages.LOGGER.warn(Messages.MESSAGES.cannotExecute(module.getClass().getSimpleName(),
@@ -139,10 +159,7 @@ private void triggerAnnotatedMethods(final Class<? extends Annotation> annotatio
                     }
                     try {
                         method.invoke(module);
-                    } catch (InvocationTargetException ex) {
-                        LogMessages.LOGGER
-                                .warn(Messages.MESSAGES.problemRunningAnnotationMethod(annotationClass.getSimpleName()), ex);
-                    } catch (IllegalAccessException ex) {
+                    } catch (InvocationTargetException | IllegalAccessException ex) {
                         LogMessages.LOGGER
                                 .warn(Messages.MESSAGES.problemRunningAnnotationMethod(annotationClass.getSimpleName()), ex);
                     }

src/main/java/dev/resteasy/guice/ModuleProcessor.java

@@ -21,6 +21,13 @@
 import com.google.inject.Binding;
 import com.google.inject.Injector;
 
+/**
+ * Registers the Guice-managed Jakarta REST components of an {@link Injector} with RESTEasy. It walks the
+ * injector's explicit bindings and, for each bound type, registers root resources (types recognized by
+ * {@link GetRestful#isRootResource(Class)}) with the {@link Registry} and {@code @Provider}-annotated types with
+ * the {@link ResteasyProviderFactory}. Because it scans only explicit bindings, every resource and provider must
+ * be bound in a Guice {@link com.google.inject.Module}; Guice's just-in-time bindings are not discovered.
+ */
 public class ModuleProcessor {
 
     private final Registry registry;
@@ -31,8 +38,13 @@ public ModuleProcessor(final Registry registry, final ResteasyProviderFactory pr
         this.providerFactory = providerFactory;
     }
 
+    /**
+     * Registers the root resources and providers bound in the given injector with RESTEasy.
+     *
+     * @param injector the injector whose bindings should be registered
+     */
     public void processInjector(final Injector injector) {
-        List<Binding<?>> rootResourceBindings = new ArrayList<Binding<?>>();
+        final List<Binding<?>> rootResourceBindings = new ArrayList<>();
         for (final Binding<?> binding : injector.getBindings().values()) {
             final Class<?> type = binding.getKey().getTypeLiteral().getRawType();
             if (type != null) {
@@ -46,8 +58,8 @@ public void processInjector(final Injector injector) {
                 }
             }
         }
-        for (Binding<?> binding : rootResourceBindings) {
-            Class<?> beanClass = (Class<?>) binding.getKey().getTypeLiteral().getType();
+        for (final Binding<?> binding : rootResourceBindings) {
+            final Class<?> beanClass = (Class<?>) binding.getKey().getTypeLiteral().getType();
             final ResourceFactory resourceFactory = new GuiceResourceFactory(binding.getProvider(), beanClass);
             LogMessages.LOGGER.info(Messages.MESSAGES.registeringFactory(beanClass.getName()));
             registry.addResourceFactory(resourceFactory);

src/main/java/dev/resteasy/guice/_private/Messages.java

@@ -14,7 +14,6 @@
 @MessageBundle(projectCode = "RESTEASY-GUICE")
 public interface Messages {
     Messages MESSAGES = org.jboss.logging.Messages.getBundle(MethodHandles.lookup(), Messages.class);
-    int BASE = 11000;
 
     @Message(id = 100, value = "Cannot execute expected module {0}''s @{1} method {2} because it has unexpected parameters: skipping.", format = Format.MESSAGE_FORMAT)
     String cannotExecute(String className, String annotation, String methodName);

src/main/java/dev/resteasy/guice/ext/JaxrsModule.java

@@ -18,6 +18,7 @@
 
 public class JaxrsModule implements Module {
 
+    @Override
     public void configure(final Binder binder) {
         binder.bind(ClientHttpEngine.class).to(ApacheHttpClient43Engine.class);
         binder.bind(RuntimeDelegate.class).toInstance(RuntimeDelegate.getInstance());