Migrating to Reststop 2

Motivation

The primary driver behind the changes in Reststop 2 was to remove the need of plugins to extend DefaultReststopPlugin.

In Reststop 2.0, plugins are instead annotated with @Plugin. They do not need to and will typically not extend any base class.

Where you in Reststop 1.x would addSomethingOfTypeX(..), in Reststop 2 you instead @Export a field of TypeX.

This removed the need to extend and maintain a parent plugin class. It also allows Reststop to statically determine service dependencies between plugins and start them in the correct dependency order. Another benefit is that plugins may now export any combination of services, this used to be problematic because of Java's single parent inheritance.

New in Reststop 2 is that your plugin constructor may now inject Collection<T>. Similarly, you may @Export a Collection<T> (useful in cases where the actual number of exported instances must be determined at runtime.

With the removal of DefaultReststopPlugin and its constructor, we also removed the ability to inject configuration to @Config annotated fields. @Config is now injected using plugin constructor injection.

How do I migrate my plugins to Reststop 2?

When upgrading you plugins you need to be aware of the following changes:

• The interface ReststopPlugin and the class DefaultReststopPlugin have been removed
• Uses of DefaultReststopPlugin.addServletFilter(..) to expose a Filter should be replaced by an @Export'ed field of type Filter
• The Reststop interface methods createServletFilter, createFilter, createServletConfig, createFilterConfig and newFilterChain should be replaced with similar methods found in new interface ServletBuilder. The hello-world integration test has an example of using ServletBuilder.
• DefaultReststopPlugin.addPluginListener should be replaced with an @Export of fields of type PluginListener.
• The remaining methods non-servlet related methods from Reststop were only used by the development plugin of Reststop have been folded into core.
• Any @Config annotated fields must be replaced with @Config annotated constructor parameters
• The reststop-cxf-plugin is now split into reststop-cxf-plugin and the new reststop-cxf-deploy-plugin which does endpoint deployment. If you are using reststop-cxf-plugin, you need to add reststop-cxf-deploy-plugin
• The reststop-jersey-plugin is now split into reststop-jersey-plugin and the new reststop-jersey-deploy-plugin which does application deployment. If you are using reststop-jersey-plugin, you need to add reststop-jersey-deploy-plugin
• reststop-maven-plugin:scan-plugins has been replaced by a compile time annotation processor. This means that reststop-annotation-processor must be added as a compile time dependency in the pom.xml. You must also remove the goal scan-plugins from your maven config.

Plugin using V2 API

import org.kantega.reststop.api.Export;
import org.kantega.reststop.api.Plugin;
import org.kantega.reststop.jaxrsapi.ApplicationBuilder;
import javax.ws.rs.core.Application;

@Plugin
public class HelloworldJaxRsPlugin  {

     @Export
     private final Application helloApp;

     public HelloworldJaxRsPlugin(@Config String configParam,
             ApplicationBuilder applicationBuilder) {

             helloApp = applicationBuilder.application()
                .singleton(new HelloWorldRootResource())
                .singleton(new HelloworldResource())
                .resource(ValidationMessageFeature.class)
                .build();
    }
}

Plugin using DefaultJaxRsPlugin

V1 API:

public class RestPlugin extends DefaultJaxRsPlugin {

    public RestPlugin(BlogDao blogDao, BlogPostDao blogPostDao, BlogPostCommentDao blogPostCommentDao, 
         MetricRegistry metricRegistry) {
        addJaxRsSingletonResource(new BlogsResource(blogDao, blogPostDao, blogPostCommentDao, metricRegistry));
    }
}

V2 API:

@Plugin
public class RestPlugin  {

    @Export
    private final Application metricsApp;

    public RestPlugin(BlogDao blogDao, BlogPostDao blogPostDao, BlogPostCommentDao blogPostCommentDao, 
             MetricRegistry metricRegistry, ApplicationBuilder applicationBuilder) {

        metricsApp = applicationBuilder.application()
                .singleton(new BlogsResource(blogDao, blogPostDao, blogPostCommentDao, metricRegistry))
                .build();
    }
}