Home

Awesome

vertx-jersey

Allows creating JAX-RS Jersey resources in vert.x.

Build Status Maven Central

Getting started

Add the vertx-jersey dependency to your project

<dependency>
    <groupId>com.englishtown.vertx</groupId>
    <artifactId>vertx-jersey</artifactId>
    <version>4.7.0</version>
</dependency>

See maven-simplest for getting started. There are additional example modules covering: injection, filters, serialization, swagger etc.

Version Matrix

vertx-jerseyjerseyvert.x
4.7.02.25.13.5.0
4.6.02.25.13.4.2
4.5.02.23.13.3.0
4.4.22.233.2.1
4.3.02.22.13.2.0
4.2.02.223.1.0
4.0.02.183.0.0
3.0.1 (vertx-mod-jersey)2.112.x

There are multiple ways to start the Jersey Server:

1. Run vertx-jersey as a service

Running as a service is probably the easiest way to get started.

From the command line:

vertx run service:com.englishtown.vertx:vertx-jersey:4.7.0 -conf config.json

Programmatically:

vertx.deployVerticle("service:com.englishtown.vertx:vertx-jersey:4.7.0", config);

See the maven-service example.

NOTE: When running as a service, vertx-hk2 must be on the class path.

2. Run the verticle

Rather than running as a service, you can run the JerseyVerticle from the command line:

vertx run java-hk2:com.englishtown.vertx.jersey.JerseyVerticle -conf config.json
vertx run java-guice:com.englishtown.vertx.jersey.JerseyVerticle -conf config.json

Or programmatically

vertx.deployVerticle("java-hk2:com.englishtown.vertx.jersey.JerseyVerticle", config);
vertx.deployVerticle("java-guice:com.englishtown.vertx.jersey.JerseyVerticle", config);

This assumes you have vertx-hk2 or vertx-guice on the class path as well as vertx-jersey and all its dependencies.

3. Create JerseyServer yourself

You can also skip the JerseyVerticle and instantiate the JerseyServer yourself. It is easiest to use DI for this, but it can also be done manually.

Configuration

The vertx-jersey configuration is as follows:

{
    "host": "<host>",
    "port": <port>,
    "ssl": <ssl>,
    "base_path": "<base_path>",
    "packages": ["<packages>"],
    "components": ["<components>"],
    "instances": ["<instances>"],
    "properties": {"<properties>"},
    "compression_supported": <compression_supported>,
    "jks_options": <jks_options>,
    "receive_buffer_size": <receive_buffer_size>,
    "max_body_size": <max_body_size>,
    "backlog_size": <backlog_sze>
}

You must configure at least one package or component.

You can also group the jersey configuration under a jersey json field:

{
    "jersey": {
        "host": "<host>",
        "packages": "<packages>"
        ....
    }
}

Examples

Simple
{
    "resources": ["com.englishtown.vertx.jersey.resources"]
}
All settings
{
    "host": "localhost",
    "port": 8080,
    "base_path": "/rest",
    "resources": ["com.englishtown.vertx.jersey.resources", "com.englishtown.vertx.jersey.resources2"],
    "features": ["org.glassfish.jersey.jackson.JacksonFeature"],
    "binders": ["com.englishtown.vertx.jersey.AppBinder"]
}

Vertx Resource Injection

The javax.ws.rs.core.Context annotation can be used to inject vert.x objects into a resource constructor, field, or method parameter. Supported vert.x objects include

To inject custom objects, you must provide one or more binders in the configuration. See the injection example projects.

Dependency Injection

The JerseyVerticle requires dependency injection. Guice and HK2 binders are provided:

See the examples directory for runnable hk2 and guice samples.

vertx-guice

If using vertx-guice, ensure the vertx-guice jar is on the class path so vert.x registers the GuiceVerticleFactory.

Note: The Guice Multibindings extension is required.

vertx-mod-hk2

If using vertx-hk2, ensure the vertx-hk2 jar is on the class path so vert.x registers the HK2VerticleFactory.

Note: if you are using vertx-mod-hk2, ensure you are using 1.7.0 or higher.

Example Resource Method

@GET
@Produces(MediaType.APPLICATION_JSON)
public void getQuery(
        @Suspended final AsyncResponse response,
        @Context ContainerRequest jerseyRequest,
        @Context HttpServerRequest vertxRequest,
        @Context Vertx vertx) {

    vertx.runOnLoop(new Handler<Void>() {
        @Override
        public void handle(Void aVoid) {
            response.resume("Hello World!");
        }
    });
}

Promises

The promises package provides when.java wrappers to create a JerseyServer. You must provide the when.java dependency.

Example

The following example assumes a com.englishtown.vertx.jersey.promises.WhenJerseyServer instance has been injected using the com.englishtown.vertx.hk2.WhenHK2JerseyBinder with vertx-hk2 module.


    @Override
    public void start(Future<Void> startedResult) throws Exception {

        JsonObject jerseyConfig = vertx.getOrCreateContext().config().getJsonObject("jersey");

        jerseyServer.createServer(jerseyConfig)
                .then(server -> {
                    startedResult.complete();
                    return null;
                })
                .otherwise(t -> {
                    startedResult.fail(t);
                    return null;
                });

    }