libraries/http/src/docs/http.txt

///////////////////////////////////////////////////////////////
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
///////////////////////////////////////////////////////////////

[[library-http, HTTP Library]]
= HTTP =

[devstatus]
--------------
source=libraries/http/dev-status.xml
--------------

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 <<library-servlet>>.

include::../../build/docs/buildinfo/artifact.txt[]

== Create an EventListenerService ==

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

[snippet,java]
----
source=libraries/http/src/test/java/org/qi4j/library/http/FooServletContextListenerService.java
tag=context-listener
----

== Create a ServletService ==

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

[snippet,java]
----
source=libraries/http/src/test/java/org/qi4j/library/http/HelloWorldServletService.java
tag=servletservice
----

== Create a FilterService ==

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

[snippet,java]
----
source=libraries/http/src/main/java/org/qi4j/library/http/UnitOfWorkFilterService.java
tag=filterservice
----

== Jetty Service ==

=== Assembly ===

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

[snippet,java]
----
source=libraries/http/src/test/java/org/qi4j/library/http/JettyServiceTest.java
tag=assembly
----

This library can be used alonside the JMX library, described in <<library-jmx>>. 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:

[snippet,java]
----
source=libraries/http/src/test/java/org/qi4j/library/http/JettyJMXStatisticsTest.java
tag=jmx
----

=== 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:

[snippet,java]
----
source=libraries/http/src/test/java/org/qi4j/library/http/SecureJettyServiceTest.java
tag=assemblyssl
----

=== 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:

[snippet,java]
----
source=libraries/http/src/test/java/org/qi4j/library/http/MutualSecureJettyServiceTest.java
tag=config
----

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