### HTTP

code

docs

tests

The HTTP library provides a Jetty based embedded HTTP service with support for easy event listeners, servlets and filters assembly as Services.

It’s an easy way to embedd a servlet container and reuse everything that can be run in it (JAX-*, Restlet, Wicket, Vaadin, GWT etc..). If instead you want to run a Zest™ Application in a servlet container, see Servlet Library.

Table 33. Artifact

Group ID | Artifact ID | Version
--- | --- | ---
org.qi4j.library | org.qi4j.library.http | 2.1

#### Create an EventListenerService

EventListeners in HttpService are assembled as Services, so one have to declare a ServiceComposite like this:

    @Mixins( FooServletContextListener.class )
    public interface FooServletContextListenerService
            extends ServletContextListener, ServiceComposite
    {
    }

#### Create a ServletService

Servlets in HttpService are assembled as Services, so one have to declare a ServiceComposite like this:

    @Mixins( HelloWorldServlet.class )
    public interface HelloWorldServletService
            extends Servlet, ServiceComposite
    {
    }

#### Create a FilterService

It’s the same for Filters. As an example here is the bundled UnitOfWorkFilterService declaration:

    @Mixins( UnitOfWorkFilter.class )
    public interface UnitOfWorkFilterService extends Filter, ServiceComposite
    {
    }

#### Jetty Service

##### Assembly

The HTTP library provide a JettyServiceAssembler and a fluent API to easily assemble Servlets and Filters.

    // Assemble the JettyService
    new JettyServiceAssembler().withConfig( configModule, Visibility.layer ).assemble( module );

    // Set HTTP port as JettyConfiguration default
    JettyConfiguration config = configModule.forMixin( JettyConfiguration.class ).declareDefaults();
    config.hostName().set( "127.0.0.1" );
    config.port().set( HTTP_PORT );

    // Serve /helloWorld with HelloWorldServletService
    addServlets( serve( "/helloWorld" ).with( HelloWorldServletService.class ) ).to( module );

    // Filter requests on /* through provided UnitOfWorkFilterService
    addFilters( filter( "/*" ).through( UnitOfWorkFilterService.class ).on( REQUEST ) ).to( module );

This library can be used alonside the JMX library, described in JMX Library. If it is visible and that you enable Jetty statistics configuration property they will be automatically exposed through JMX.

Here is a simple example from the unit tests showing what’s necessary but inside a simple Module for the sake of clarity:

    new JettyServiceAssembler().withConfig( configModule, Visibility.layer ).assemble( module );
    new JMXAssembler().assemble( module ); // Assemble both JettyService and JMX

    JettyConfiguration config = configModule.forMixin( JettyConfiguration.class ).declareDefaults();
    config.hostName().set( "127.0.0.1" );
    config.port().set( 8441 );
    config.statistics().set( Boolean.TRUE ); // Set statistics default to TRUE in configuration

    // Hello world servlet related assembly
    addServlets( serve( "/hello" ).with( HelloWorldServletService.class ) ).to( module );

##### Configuration

Underlying Jetty engine configuration is exposed as a Zest™ Service Configuration. The only one that is mandatory is the port.

See org.qi4j.library.http.JettyConfiguration for a reference of all available configuration properties.

#### Secure Jetty Service

The HTTP library provides a second HttpService that brings SSL support.

##### Assembly

Simply change from JettyServiceAssembler to SecureJettyServiceAssembler:

    new SecureJettyServiceAssembler().withConfig( configModule, Visibility.layer ).assemble( module );
    [...snip...]

    addServlets( serve( "/hello" ).with( HelloWorldServletService.class ) ).to( module );
    addFilters( filter( "/*" ).through( UnitOfWorkFilterService.class ).on( REQUEST ) ).to( module );

##### Configuration

You must at least configure a KeyStore using the three related properties. All the other ones have sensible defaults.

If you want, or need, to do client certificate authentication you’ll need to configure at least a "trust store", a KeyStore that contains your trusted trust anchors.

Here is some code that set HTTP port a well as a KeyStore and a TrustStore as SecureJettyConfiguration default during assembly:

    SecureJettyConfiguration config = configModule.forMixin( SecureJettyConfiguration.class ).declareDefaults();
    config.hostName().set( "127.0.0.1" );
    config.port().set( HTTPS_PORT );

    config.keystorePath().set( SERVER_KEYSTORE_PATH );
    config.keystoreType().set( "JCEKS" );
    config.keystorePassword().set( KS_PASSWORD );

    config.truststorePath().set( TRUSTSTORE_PATH );
    config.truststoreType().set( "JCEKS" );
    config.truststorePassword().set( KS_PASSWORD );

    config.wantClientAuth().set( Boolean.TRUE );

See org.qi4j.library.http.SecureJettyConfiguration for a reference of all available configuration properties.