manual/src/main/asciidoc/user-guide/http.adoc

//
// Licensed 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.
//

==== Http Service

The Karaf http feature enables the Pax Web implementation of the OSGi HTTPService.

===== Installing the HTTP feature

----
root@karaf()> feature:install http
----

NB: the HTTP service will be actually bound only when at least one web application will use it.

If you want to test the HTTP service, you can install the `webconsole` feature:

----
root@karaf()> feature:install webconsole
----

Then, you can test the HTTP service by accessing the Apache Karaf WebConsole pointing your browser to [http://localhost:8181/system/console].

===== Configuring the HTTPService

By default the HTTPService listens on port 8181 you can change the port by creating a file `etc/org.ops4j.pax.web.cfg` with the following content:

----
org.osgi.service.http.port=8181
----

or by typing:
----
root@karaf> config:property-set -p org.ops4j.pax.web org.osgi.service.http.port 8181
----

If the http feature is already installed the change will take effect immediately.

===== Registering a servlet with the HttpService manually

See http://felix.apache.org/site/apache-felix-http-service.html.

===== Using the Pax Web whiteboard extender

The Pax Web whiteboard extender is an enhancement of the http feature. So use the following command to install:

----
root@karaf> feature:install http-whiteboard
----

The http://team.ops4j.org/wiki/display/ops4j/Pax+Web+Extender+-+Whiteboard[Pax Web whiteboard] extender listens to services
of interface type HttpServlet and Filter.
It will register each of these interfaces with the HttpService and remove them as soon as the service goes down.
So it is much more convenient than registering with the HttpService directly.

----
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">
    <service interface="javax.servlet.http.HttpServlet">
        <service-properties>
            <entry key="alias" value="/myservlet"/>
        </service-properties>
        <bean id="myServlet" class="com.example.MyServlet"/>
    </service>
</blueprint>
----

The above snippet publishes the Servlet MyServlet on http://localhost:8181/myServlet.

Please keep in mind that the Whiteboard pattern for Servlets is not standardized and only works with Pax Web.

For commands take a look at the command section in the link:webcontainer[webcontainer] chapter.