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 Polygene™ Application in a servlet container, see Servlet Library.

Table 27. Artifact

Group ID	Artifact ID	Version
org.apache.polygene.libraries	org.apache.polygene.library.http	3.0.0

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
{
}

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( httpPort );

// 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( FreePortFinder.findFreePortOnLoopback() );
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 Polygene™ Service Configuration. The only one that is mandatory is the port.

See org.apache.polygene.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( httpsPort );

config.keystorePath().set( getKeyStoreFile( SERVER_KEYSTORE_FILENAME ).getAbsolutePath() );
config.keystoreType().set( "JCEKS" );
config.keystorePassword().set( KS_PASSWORD );

config.truststorePath().set( getKeyStoreFile( TRUSTSTORE_FILENAME ).getAbsolutePath() );
config.truststoreType().set( "JCEKS" );
config.truststorePassword().set( KS_PASSWORD );

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

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