Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Jetty/Feature/Jetty OSGi
Contents
Introduction
Jetty on OSGi consists of bootstrapping a standard jetty server from OSGi. It supports the deployment of traditional J2EE web-applications as well as web-applications contained inside an OSGi bundle (RFC66).
The goal of Jetty on OSGi is to offer a migration path for traditional J2EE applications to run inside an OSGi container. It favors J2EE applications currently deployed on jetty: developers and IT administrators familiar with a jetty deployment will found the same folder structure and configuration files.
Jetty-on-OSGi also provides an SDK for Eclipse-PDE that supports the development and debugging of a mix of traditional web-applications and web-applications contained in an OSGi bundle: Jetty on OSGi SDK for Eclipse PDE.
Feature
Jetty bootstrapping in OSGi
A single bundle 'org.eclipse.jetty.osgi.boot' acts as an alternative to Jetty's Start.jar. It wires up all the jetty jars that can be located. It locates the ${jetty.home} folder where the configuration files are located. It starts a jetty server according to these configuration files:
It locates a ${jetty.home} folder (or generate one by default) and starts a jetty server according to the jetty.xml file.
The classloader inside which the jetty server is executing is a mix of the OSGi classloader provided by the 'org.eclipse.jetty.osgi.boot' bundle and also the jars and folders found inside ${jetty.home}/lib/ext and ${jetty.home}/resources.
The jetty.xml provided by default in jetty will deploy all web-applications found inside the ${jetty.home}/webapps and will read the jetty context files found inside ${jetty.home/contexts}.
OSGi's HttpService via equinox servlet bridge
Equinox packages a servlet that supports HttpService. Jetty-OSGi is distributed with a bundle that deploys this servlet and hence provides an implementation of HttpService. The URL mapping to this servlet is "/*": it will catch any request not caught by other handlers.
Deployment of web-applications via OSGi
Support for RFC66
RFC66 standardize the format of a bundle that contains a web-application and its lifecycle. The basic use-case is this one: When a bundle is started and contains "WEB-INF/web.xml", an RFC66 implementation will deploy the web-application contained in that bundle. The RFc66 implementation reads the manifest headers of the bundle for non-default deployment parameters of that web-application.
Jetty-OSGi takes advantage of jetty's native web-app deployer and context deployers and exposes those as extensions to RFC66.
Manifest headers and access to OSGI in the servlet context
The mandatory manifest header of RFC66 is supported:
Web-ContextPath: /theContextPath
The default behavior when it is missing is also supported: the default context path is the symbolic name of the bundle that contains WEB-INF/web.xml.
The optional header "Jsp-ExtractLocation" is not supported currently.
A web-application deployed by OSGi contains a pointer to the org.osgi.BundleContext object as the attribute 'osgi-bundlecontext' of the servlet context.
Jetty-OSGi does not currently enforce that the WEB-INF/classes folder and the WEB-INF/lib/*.jar must be part of the Manifest entry "Bundle-Classpath". If they are not present, jetty-osgi will still load them in the classloader of the web-application.
"war" URL scheme
The "war" URL scheme specified by RFC66 support the installation of J2EE web archives - "war" files - into an OSGi environment. On the OSGi shell, it is possible to install a war file with a command like this one:
>install war:file://path/to/pet.war
The corresponding war file is transformed into a suitable OSGi bundle and installed on to the OSGi container.
The support for this protocol is mostly complete. The query string parameters that enable overriding the manifest headers and other settings have not been extensively tested.
Also RFC66 specifies a factory class that create URLs with the war scheme. This factory is not implemented currently. The factory is not specific to jetty so hopefully it will be packaged with the OSGi APIs.
The support for the war scheme is almost fully decoupled from jetty APIs. It could be used in any RFC66 implementation. It is in the bundle [http://github.com/intalio/hightide-on-osgi/tree/master/org.eclipse.jetty.osgi.boot.warurl