You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@karaf.apache.org by gg...@apache.org on 2022/03/30 10:56:27 UTC
[karaf] 03/03: [KARAF-7406] Update Karaf 4.4 manual to show new features of Pax Web 8
This is an automated email from the ASF dual-hosted git repository.
ggrzybek pushed a commit to branch KARAF-7392
in repository https://gitbox.apache.org/repos/asf/karaf.git
commit 122d1bb75526ce9d2216c1e4b411b369e950dc20
Author: Grzegorz Grzybek <gr...@gmail.com>
AuthorDate: Wed Mar 30 12:53:25 2022 +0200
[KARAF-7406] Update Karaf 4.4 manual to show new features of Pax Web 8
---
manual/src/main/asciidoc/user-guide/console.adoc | 8 +-
manual/src/main/asciidoc/user-guide/http.adoc | 69 +++-
manual/src/main/asciidoc/user-guide/kar.adoc | 49 +--
.../src/main/asciidoc/user-guide/provisioning.adoc | 98 +++---
manual/src/main/asciidoc/user-guide/urls.adoc | 2 +-
.../src/main/asciidoc/user-guide/webcontainer.adoc | 361 +++++++++++++--------
.../web/management/internal/WebMBeanImpl.java | 11 +-
7 files changed, 390 insertions(+), 208 deletions(-)
diff --git a/manual/src/main/asciidoc/user-guide/console.adoc b/manual/src/main/asciidoc/user-guide/console.adoc
index 08fe392..22e1a9c 100644
--- a/manual/src/main/asciidoc/user-guide/console.adoc
+++ b/manual/src/main/asciidoc/user-guide/console.adoc
@@ -288,11 +288,9 @@ Like on most Unix environments, the Karaf console supports some key bindings:
You can pipe the output of one command as input to another one. It's a pipe, using the | character:
----
-karaf@root()> feature:list |grep -i war
-pax-war | 4.1.4 | | Uninstalled | org.ops4j.pax.web-4.1.4 | Provide support of a full WebContainer
-pax-war-tomcat | 4.1.4 | | Uninstalled | org.ops4j.pax.web-4.1.4 |
-war | 4.0.0 | | Uninstalled | standard-4.0.0 | Turn Karaf as a full WebContainer
-blueprint-web | 4.0.0 | | Uninstalled | standard-4.0.0 | Provides an OSGI-aware Servlet ContextListener fo
+karaf@root()> feature:list | grep -i felix
+felix-httplite │ 0.1.6 │ │ Uninstalled │ standard-4.4.0 │ Felix Httplite HTTP Service
+felix-http │ 4.1.12 │ │ Uninstalled │ standard-4.4.0 │ Felix HTTP Service
----
===== Grep, more, find, ...
diff --git a/manual/src/main/asciidoc/user-guide/http.adoc b/manual/src/main/asciidoc/user-guide/http.adoc
index d48b4f8..50de469 100644
--- a/manual/src/main/asciidoc/user-guide/http.adoc
+++ b/manual/src/main/asciidoc/user-guide/http.adoc
@@ -14,22 +14,26 @@
==== Http Service
-Apache Karaf supports several Http Services:
+_Http Service_ should mean an implementation of OSGi CMPN Chapter 102 "Http Service" specification.
-* `http` feature installs Http Service powered by Pax Web
-* `felix-http` feature installs Http Service powered by Apache Felix HTTP
+Apache Karaf supports several Http Service implementations:
+
+* `http` feature installs Http Service implementation powered by Pax Web
+* `felix-http` feature installs Http Service implementation powered by Apache Felix HTTP
+
+NOTE: Felix HTTP implementation is also an implementation of OSGi CMPN Chapter 140 "Whiteboard Service" specification.
+
+NOTE: Pax Web also contains implementations of OSGi CMPN Chapter 140 "Whiteboard Service" and OSGi CMPN Chapter 128 "Web Applications" specification, but these are installed using additional features.
===== Installing the Http Service
-If you want to use Pax Web Http Service, you have to install the `http` feature:
+If you want to use Pax Web Http Service implementation, you have to install 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 use Apache Felix Http Service, you have to install `felix-http` feature:
+If you want to use Apache Felix Http Service implementation, you have to install `felix-http` feature:
----
root@karaf()> feature:install felix-http
@@ -43,6 +47,57 @@ 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].
+====== More information about Pax Web implementation
+
+Pax Web 8 itself contains properly defined and tested Karaf features. However Karaf was always providing own web-related features in `org.apache.karaf.features/standard` feature repository.
+
+For completeness, here's a full list of features provided by Pax Web:
+
+.Core features
+
+* `pax-web-specs` - several API related bundles that can be used (or can be treated as reference) when the runtime (like Karaf) doesn't provide necessary APIs (servlet API, EL API, Annotation API)
+* `pax-web-core` - fundamental Pax Web API/SPI bundles which don't register any OSGi services
+
+.Runtime features
+
+Pax Web in all versions (and in particular in version 8) was always aiming to provide support for all major web container technologies. That's why there are 3 sets of features for Jetty, Tomcat and Undertow support. These features only install relevant web container bundles without any bundles specific to OSGi CMPN specifications.
+
+* Jetty
+** `pax-web-jetty` - required `org.eclipse.jetty` bundles with Servlet API bundle
+** `pax-web-jetty-websockets` - required `org.eclipse.jetty.websocket` bundles with WebSocket API bundle
+** `pax-web-jetty-http2` - required `org.eclipse.jetty.http2` bundles
+** `pax-web-jetty-http2-jdk8` - optional Jetty ALPN bundles when running on JDK8
+** `pax-web-jetty-http2-jdk9` - optional Jetty ALPN bundles when running on JDK9+
+* Tomcat
+** `pax-web-tomcat` - required Tomcat bundles (repackaged `org.apache.tomcat` libraries), including HTTP/2 support
+** `pax-web-tomcat-websockets` required Tomcat bundles for WebSocket support (repackaged `org.apache.tomcat` libraries)
+* Undertow
+** `pax-web-undertow` - required Undertow bundles, including HTTP/2 support
+** `pax-web-undertow-websockets` - required Undertow bundles for WebSocket support
+
+.OSGi CMPN Http Service features
+
+* `pax-web-http-jetty` - implementation of OSGi CMPN Chapter 102 "Http Service" specification based on Jetty 9.4
+* `pax-web-http-tomcat` - implementation of OSGi CMPN Chapter 102 "Http Service" specification based on Tomcat 9.0
+* `pax-web-http-undertow` - implementation of OSGi CMPN Chapter 102 "Http Service" specification based on Undertow 2.2
+
+.Additional features
+
+* `pax-web-jsp` - support for Java Server Pages (not mentioned in OSGi CMPN specifications)
+* `pax-web-whiteboard` - support for OSGi CMPN Chapter 140 "Whiteboard Service" specification
+* `pax-web-war` - support for OSGi CMPN Chapter 128 "Web Applications" specification (WABs and WARs)
+* `pax-web-karaf` - Karaf commands implemented by Pax Web itself
+
+====== Additional features that include Pax Web features
+
+Karaf itself provides more features than just `felix-http` and `http`. Simply because there are many Pax Web features, there's support for more web containers and there are more technologies to cover (like websockets and JSPs), but also because of some kind of backward compatibility, here's a list of Pax Web related features defined in Karaf:
+
+* `http` - the _main_ feature mentioned at the start of this chapter. This feature only includes `pax-web-http` feature, also defined in Karaf
+* `pax-web-http` - includes `pax-web-http-jetty` feature from Pax Web and also Http JMX and WebConsole bundles from Karaf
+* `pax-web-http-whiteboard` and `http-whiteboard` (its alias) - include `pax-web-http-jetty`, `pax-web-whiteboard` and `pax-web-websockets` features from Pax Web
+* `pax-web-http-war` and `war` (its alias) - include `pax-web-http-jetty`, `pax-web-war`, `pax-web-jsp` and `pax-web-websockets` features from Pax Web
+* `jetty` - includes `pax-web-jetty`, so it's only used to install Jetty bundles. This feature is used as feature-dependency of many CXF and Camel features.
+
===== 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` (if you use the Pax Web Http Service) with the following content:
diff --git a/manual/src/main/asciidoc/user-guide/kar.adoc b/manual/src/main/asciidoc/user-guide/kar.adoc
index 3d40718..cebfcd9 100644
--- a/manual/src/main/asciidoc/user-guide/kar.adoc
+++ b/manual/src/main/asciidoc/user-guide/kar.adoc
@@ -173,26 +173,36 @@ The `feature:repo-list` command gives you the list of registered features reposi
karaf@root()> feature:repo-list
Repository | URL
-------------------------------------------------------------------------------------------------------
-standard-4.0.0 | mvn:org.apache.karaf.features/standard/4.0.0/xml/features
-enterprise-4.0.0 | mvn:org.apache.karaf.features/enterprise/4.0.0/xml/features
-spring-4.0.0 | mvn:org.apache.karaf.features/spring/4.0.0/xml/features
-org.ops4j.pax.web-4.1.4 | mvn:org.ops4j.pax.web/pax-web-features/4.1.4/xml/features
+standard-4.4.0 | mvn:org.apache.karaf.features/standard/4.4.0/xml/features
+enterprise-4.4.0 | mvn:org.apache.karaf.features/enterprise/4.4.0/xml/features
+spring-4.4.0 | mvn:org.apache.karaf.features/spring/4.4.0/xml/features
+org.ops4j.pax.web-8.0.2 | mvn:org.ops4j.pax.web/pax-web-features/8.0.2/xml/features
----
You can use one of these features repositories to create the kar file:
----
-karaf@root()> kar:create org.ops4j.pax.web-4.1.4
-Adding feature pax-jetty
-Adding feature pax-http-whiteboard
-Adding feature pax-war
-Adding feature pax-http-tomcat
-Adding feature pax-war-tomcat
-Adding feature pax-http
-Adding feature pax-http-jetty
-Adding feature pax-jsf-support
-Adding feature pax-jetty-spdy
-Kar file created : /home/jbonofre/Downloads/apache-karaf-4.0.0/data/kar/org.ops4j.pax.web-4.1.4.kar
+karaf@root()> kar:create org.ops4j.pax.web-8.0.2
+Adding feature pax-web-karaf
+Adding feature pax-web-core
+Adding feature pax-web-http-tomcat
+Adding feature pax-web-websockets
+Adding feature pax-web-jetty
+Adding feature pax-web-undertow
+Adding feature pax-web-jetty-http2
+Adding feature pax-web-http-undertow
+Adding feature pax-web-whiteboard
+Adding feature pax-web-tomcat-websockets
+Adding feature pax-web-jsp
+Adding feature pax-web-undertow-websockets
+Adding feature pax-web-war
+Adding feature pax-web-jetty-websockets
+Adding feature pax-web-tomcat
+Adding feature pax-web-jetty-http2-jdk8
+Adding feature pax-web-http-jetty
+Adding feature pax-web-jetty-http2-jdk9
+Adding feature pax-web-specs
+Kar file created : /data/servers/apache-karaf-4.4.0-SNAPSHOT/data/kar/org.ops4j.pax.web-8.0.2.kar
----
You can see that the KAR file has been created in the `KARAF_DATA/kar` folder.
@@ -202,10 +212,11 @@ By default, the `kar:create` command creates a KAR file, packaging all features
You can provide the list of features that you want to package into the KAR file:
----
-karaf@root()> kar:create org.ops4j.pax.web-4.1.4 pax-jetty pax-tomcat
-Adding feature pax-jetty
-Adding feature pax-tomcat
-Kar file created : /opt/apache-karaf-4.1.4/data/kar/org.ops4j.pax.web-4.1.4.kar
+karaf@root()> kar:create org.ops4j.pax.web-8.0.2 pax-web-http-jetty pax-web-jetty
+Adding feature pax-web-core
+Adding feature pax-web-jetty
+Adding feature pax-web-http-jetty
+Kar file created : /data/servers/apache-karaf-4.4.0-SNAPSHOT/data/kar/org.ops4j.pax.web-8.0.2.kar
----
===== `kar:install`
diff --git a/manual/src/main/asciidoc/user-guide/provisioning.adoc b/manual/src/main/asciidoc/user-guide/provisioning.adoc
index c5a30cb..3c781d8 100644
--- a/manual/src/main/asciidoc/user-guide/provisioning.adoc
+++ b/manual/src/main/asciidoc/user-guide/provisioning.adoc
@@ -508,13 +508,21 @@ The `feature:repo-list` command lists all registered feature repositories:
----
karaf@root()> feature:repo-list
-Repository | URL
+Repository | URL
--------------------------------------------------------------------------------------
-org.ops4j.pax.cdi-0.12.0 | mvn:org.ops4j.pax.cdi/pax-cdi-features/0.12.0/xml/features
-org.ops4j.pax.web-4.1.4 | mvn:org.ops4j.pax.web/pax-web-features/4.1.4/xml/features
-standard-4.0.0 | mvn:org.apache.karaf.features/standard/4.0.0/xml/features
-enterprise-4.0.0 | mvn:org.apache.karaf.features/enterprise/4.0.0/xml/features
-spring-4.0.0 | mvn:org.apache.karaf.features/spring/4.0.0/xml/features
+pax-jms-1.1.0 │ mvn:org.ops4j.pax.jms/pax-jms-features/1.1.0/xml/features
+standard-4.4.0 │ mvn:org.apache.karaf.features/standard/4.4.0/xml/features
+org.ops4j.pax.jdbc-1.5.0 │ mvn:org.ops4j.pax.jdbc/pax-jdbc-features/1.5.0/xml/features
+aries-jpa-2.7.3 │ mvn:org.apache.aries.jpa/jpa-features/2.7.3/xml/features
+framework-4.4.0 │ mvn:org.apache.karaf.features/framework/4.4.0/xml/features
+org.ops4j.pax.web-8.0.2 │ mvn:org.ops4j.pax.web/pax-web-features/8.0.2/xml/features
+pax-transx-0.5.0 │ mvn:org.ops4j.pax.transx/pax-transx-features/0.5.0/xml/features
+openjpa-3.2.0 │ mvn:org.apache.openjpa/openjpa-features/3.2.0/xml/features
+specs-4.4.0 │ mvn:org.apache.karaf.features/specs/4.4.0/xml/features
+hibernate-validator-osgi-features │ mvn:org.hibernate.validator/hibernate-validator-osgi-karaf-features/7.0.1.Final/xml/features
+spring-4.4.0 │ mvn:org.apache.karaf.features/spring/4.4.0/xml/features
+enterprise-4.4.0 │ mvn:org.apache.karaf.features/enterprise/4.4.0/xml/features
+org.ops4j.pax.cdi-1.1.4 │ mvn:org.ops4j.pax.cdi/pax-cdi-features/1.1.4/xml/features
----
Each repository has a name and the URL to the features XML.
@@ -527,13 +535,21 @@ so update the features definition), you can use the `-r` option:
karaf@root()> feature:repo-list -r
Reloading all repositories from their urls
-Repository | URL
+Repository | URL
--------------------------------------------------------------------------------------
-org.ops4j.pax.cdi-0.12.0 | mvn:org.ops4j.pax.cdi/pax-cdi-features/0.12.0/xml/features
-org.ops4j.pax.web-4.1.4 | mvn:org.ops4j.pax.web/pax-web-features/4.1.4/xml/features
-standard-4.0.0 | mvn:org.apache.karaf.features/standard/4.0.0/xml/features
-enterprise-4.0.0 | mvn:org.apache.karaf.features/enterprise/4.0.0/xml/features
-spring-4.0.0 | mvn:org.apache.karaf.features/spring/4.0.0/xml/features
+pax-jms-1.1.0 │ mvn:org.ops4j.pax.jms/pax-jms-features/1.1.0/xml/features
+standard-4.4.0 │ mvn:org.apache.karaf.features/standard/4.4.0/xml/features
+org.ops4j.pax.jdbc-1.5.0 │ mvn:org.ops4j.pax.jdbc/pax-jdbc-features/1.5.0/xml/features
+aries-jpa-2.7.3 │ mvn:org.apache.aries.jpa/jpa-features/2.7.3/xml/features
+framework-4.4.0 │ mvn:org.apache.karaf.features/framework/4.4.0/xml/features
+org.ops4j.pax.web-8.0.2 │ mvn:org.ops4j.pax.web/pax-web-features/8.0.2/xml/features
+pax-transx-0.5.0 │ mvn:org.ops4j.pax.transx/pax-transx-features/0.5.0/xml/features
+openjpa-3.2.0 │ mvn:org.apache.openjpa/openjpa-features/3.2.0/xml/features
+specs-4.4.0 │ mvn:org.apache.karaf.features/specs/4.4.0/xml/features
+hibernate-validator-osgi-features │ mvn:org.hibernate.validator/hibernate-validator-osgi-karaf-features/7.0.1.Final/xml/features
+spring-4.4.0 │ mvn:org.apache.karaf.features/spring/4.4.0/xml/features
+enterprise-4.4.0 │ mvn:org.apache.karaf.features/enterprise/4.4.0/xml/features
+org.ops4j.pax.cdi-1.1.4 │ mvn:org.ops4j.pax.cdi/pax-cdi-features/1.1.4/xml/features
----
===== `feature:repo-add`
@@ -639,18 +655,18 @@ Without argument, the command refreshes all features repository:
----
karaf@root()> feature:repo-refresh
Refreshing feature url mvn:org.ops4j.pax.cdi/pax-cdi-features/0.12.0/xml/features
-Refreshing feature url mvn:org.ops4j.pax.web/pax-web-features/4.1.4/xml/features
-Refreshing feature url mvn:org.apache.karaf.features/standard/4.0.0/xml/features
-Refreshing feature url mvn:org.apache.karaf.features/enterprise/4.0.0/xml/features
-Refreshing feature url mvn:org.apache.karaf.features/spring/4.0.0/xml/features
+Refreshing feature url mvn:org.ops4j.pax.web/pax-web-features/8.0.2/xml/features
+Refreshing feature url mvn:org.apache.karaf.features/standard/4.4.0/xml/features
+Refreshing feature url mvn:org.apache.karaf.features/enterprise/4.4.0/xml/features
+Refreshing feature url mvn:org.apache.karaf.features/spring/4.4.0/xml/features
----
Instead of refreshing all features repositories, you can specify the features repository to refresh, by providing the URL
or the features repository name (and optionally version):
----
-karaf@root()> feature:repo-refresh mvn:org.apache.karaf.features/standard/4.0.0/xml/features
-Refreshing feature url mvn:org.apache.karaf.features/standard/4.0.0/xml/features
+karaf@root()> feature:repo-refresh mvn:org.apache.karaf.features/standard/4.4.0/xml/features
+Refreshing feature url mvn:org.apache.karaf.features/standard/4.4.0/xml/features
----
----
@@ -730,25 +746,25 @@ Using the `-i` option displays only installed features:
karaf@root()> feature:list -i
Name | Version | Required | State | Repository | Description
-------------------------------------------------------------------------------------------------------------------
-aries-proxy | 4.0.0 | | Started | standard-4.0.0 | Aries Proxy
-aries-blueprint | 4.0.0 | x | Started | standard-4.0.0 | Aries Blueprint
-feature | 4.0.0 | x | Started | standard-4.0.0 | Features Support
-shell | 4.0.0 | x | Started | standard-4.0.0 | Karaf Shell
-shell-compat | 4.0.0 | x | Started | standard-4.0.0 | Karaf Shell Compatibility
-deployer | 4.0.0 | x | Started | standard-4.0.0 | Karaf Deployer
-bundle | 4.0.0 | x | Started | standard-4.0.0 | Provide Bundle support
-config | 4.0.0 | x | Started | standard-4.0.0 | Provide OSGi ConfigAdmin support
-diagnostic | 4.0.0 | x | Started | standard-4.0.0 | Provide Diagnostic support
-instance | 4.0.0 | x | Started | standard-4.0.0 | Provide Instance support
-jaas | 4.0.0 | x | Started | standard-4.0.0 | Provide JAAS support
-log | 4.0.0 | x | Started | standard-4.0.0 | Provide Log support
-package | 4.0.0 | x | Started | standard-4.0.0 | Package commands and mbeans
-service | 4.0.0 | x | Started | standard-4.0.0 | Provide Service support
-system | 4.0.0 | x | Started | standard-4.0.0 | Provide System support
-kar | 4.0.0 | x | Started | standard-4.0.0 | Provide KAR (KARaf archive) support
-ssh | 4.0.0 | x | Started | standard-4.0.0 | Provide a SSHd server on Karaf
-management | 4.0.0 | x | Started | standard-4.0.0 | Provide a JMX MBeanServer and a set of MBeans in
-wrap | 0.0.0 | x | Started | standard-4.0.0 | Wrap URL handler
+aries-proxy | 4.4.0 | | Started | standard-4.4.0 | Aries Proxy
+aries-blueprint | 4.4.0 | x | Started | standard-4.4.0 | Aries Blueprint
+feature | 4.4.0 | x | Started | standard-4.4.0 | Features Support
+shell | 4.4.0 | x | Started | standard-4.4.0 | Karaf Shell
+shell-compat | 4.4.0 | x | Started | standard-4.4.0 | Karaf Shell Compatibility
+deployer | 4.4.0 | x | Started | standard-4.4.0 | Karaf Deployer
+bundle | 4.4.0 | x | Started | standard-4.4.0 | Provide Bundle support
+config | 4.4.0 | x | Started | standard-4.4.0 | Provide OSGi ConfigAdmin support
+diagnostic | 4.4.0 | x | Started | standard-4.4.0 | Provide Diagnostic support
+instance | 4.4.0 | x | Started | standard-4.4.0 | Provide Instance support
+jaas | 4.4.0 | x | Started | standard-4.4.0 | Provide JAAS support
+log | 4.4.0 | x | Started | standard-4.4.0 | Provide Log support
+package | 4.4.0 | x | Started | standard-4.4.0 | Package commands and mbeans
+service | 4.4.0 | x | Started | standard-4.4.0 | Provide Service support
+system | 4.4.0 | x | Started | standard-4.4.0 | Provide System support
+kar | 4.4.0 | x | Started | standard-4.4.0 | Provide KAR (KARaf archive) support
+ssh | 4.4.0 | x | Started | standard-4.4.0 | Provide a SSHd server on Karaf
+management | 4.4.0 | x | Started | standard-4.4.0 | Provide a JMX MBeanServer and a set of MBeans in
+wrap | 0.0.0 | x | Started | standard-4.4.0 | Wrap URL handler
----
===== `feature:install`
@@ -766,7 +782,7 @@ We can simulate an installation using `-t` or `--simulate` option: it just displ
----
karaf@root()> feature:install -t -v eventadmin
-Adding features: eventadmin/[4.0.0,4.0.0]
+Adding features: eventadmin/[4.4.0,4.4.0]
No deployment change.
Managing bundle:
org.apache.felix.metatype / 1.0.12
@@ -775,7 +791,7 @@ No deployment change.
You can specify a feature version to install:
----
-karaf@root()> feature:install eventadmin/4.0.0
+karaf@root()> feature:install eventadmin/4.4.0
----
By default, the `feature:install` command is not verbose. If you want to have some details about actions performed by the `feature:install`
@@ -783,7 +799,7 @@ command, you can use the `-v` option:
----
karaf@root()> feature:install -v eventadmin
-Adding features: eventadmin/[4.0.0,4.0.0]
+Adding features: eventadmin/[4.4.0,4.4.0]
No deployment change.
Done.
----
@@ -794,7 +810,7 @@ bundles, you can use the `-r` option:
----
karaf@root()> feature:install -v -r eventadmin
-Adding features: eventadmin/[4.0.0,4.0.0]
+Adding features: eventadmin/[4.4.0,4.4.0]
No deployment change.
Done.
----
diff --git a/manual/src/main/asciidoc/user-guide/urls.adoc b/manual/src/main/asciidoc/user-guide/urls.adoc
index 347f683..611908b 100644
--- a/manual/src/main/asciidoc/user-guide/urls.adoc
+++ b/manual/src/main/asciidoc/user-guide/urls.adoc
@@ -47,7 +47,7 @@ The equivalent of the above bundle would be:
In addition to being less verbose, the Maven url handlers can also resolve snapshots and can use a local copy of the jar if one is available in your Maven local repository.
The `org.ops4j.pax.url.mvn` bundle resolves `mvn` URLs. It can be configured using the file `etc/org.ops4j.pax.url.mvn.cfg`.
-Full reference of `org.ops4j.pax.url.mvn` PID configuration can be found on https://ops4j1.jira.com/wiki/display/paxurl/Aether+Configuration[the pax-web Wiki page].
+Full reference of `org.ops4j.pax.url.mvn` PID configuration can be found on https://ops4j1.jira.com/wiki/display/paxurl/Aether+Configuration[the pax-url Wiki page].
The most important property is:
diff --git a/manual/src/main/asciidoc/user-guide/webcontainer.adoc b/manual/src/main/asciidoc/user-guide/webcontainer.adoc
index aebdb3f..b58c706 100644
--- a/manual/src/main/asciidoc/user-guide/webcontainer.adoc
+++ b/manual/src/main/asciidoc/user-guide/webcontainer.adoc
@@ -14,7 +14,7 @@
==== WebContainer (JSP/Servlet)
-Apache Karaf can act as a complete WebContainer, fully supporting the JSP/Servlet specifications.
+Apache Karaf can act as a complete WebContainer, fully supporting the JSP/Servlet/WebSockets specifications.
Apache Karaf WebContainer supports both:
@@ -27,6 +27,13 @@ To enable the Apache Karaf WebContainer, you just have to install the `war` feat
karaf@root()> feature:install war
----
+However, `war` feature is just an alias for `pax-web-http-war` which itself contains these Pax Web specific features:
+
+* pax-web-http-jetty - OSGi CMPN Http Service implementation using Jetty web container
+* pax-web-war - OSGi CMPN Web Applications implementation (web container agnostic)
+* pax-web-jsp - JSP support (no related OSGi CMPN specification)
+* pax-web-websockets - WebSockets support (no related OSGi CMPN specification)
+
[NOTE]
====
The installation of the `webconsole` feature automatically installs the `war` feature.
@@ -40,8 +47,7 @@ The `war` feature provides:
===== Configuration
-The default port used by the WebContainer is 8181. Note: the connector is actually bound only when at least a servlet or webapplication is using it.
-It means that just installing the `http` or `war` feature doesn't bind the connector.
+The default port used by the WebContainer is 8181. In Pax Web 8, due to internal refactoring, installation of this feature will automatically start the web container without any web applications available.
By default, Karaf creates an internal Jetty connector that you can configure via `etc/org.ops4j.pax.web.cfg`:
@@ -88,100 +94,130 @@ The default Apache Karaf WebContainer `etc/jetty.xml` contains:
----
<?xml version="1.0"?>
<!--
- 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.
+
+ Copyright 2021 OPS4J.
+
+ 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.
+
-->
-<!DOCTYPE Configure PUBLIC "-//Mort Bay Consulting//
-DTD Configure//EN" "http://jetty.mortbay.org/configure.dtd">
-
-<Configure class="org.eclipse.jetty.server.Server">
-
- <!-- =========================================================== -->
- <!-- Set connectors -->
- <!-- =========================================================== -->
- <!-- One of each type! -->
- <!-- =========================================================== -->
-
- <!-- Use this connector for many frequently idle connections and for
- threadless continuations. -->
- <Call name="addConnector">
- <Arg>
- <New class="org.eclipse.jetty.server.nio.SelectChannelConnector">
- <Set name="host">
- <Property name="jetty.host" />
- </Set>
- <Set name="port">
- <Property name="jetty.port" default="8181" />
- </Set>
- <Set name="maxIdleTime">300000</Set>
- <Set name="Acceptors">2</Set>
- <Set name="statsOn">false</Set>
- <Set name="confidentialPort">8443</Set>
- <Set name="lowResourcesConnections">20000</Set>
- <Set name="lowResourcesMaxIdleTime">5000</Set>
- </New>
- </Arg>
- </Call>
-
- <!-- =========================================================== -->
- <!-- Configure Authentication Realms -->
- <!-- Realms may be configured for the entire server here, or -->
- <!-- they can be configured for a specific web app in a context -->
- <!-- configuration (see $(jetty.home)/contexts/test.xml for an -->
- <!-- example). -->
- <!-- =========================================================== -->
- <Call name="addBean">
- <Arg>
- <New class="org.eclipse.jetty.plus.jaas.JAASLoginService">
- <Set name="name">karaf</Set>
- <Set name="loginModuleName">karaf</Set>
- <Set name="roleClassNames">
- <Array type="java.lang.String">
- <Item>org.apache.karaf.jaas.boot.principal.RolePrincipal
- </Item>
- </Array>
- </Set>
- </New>
- </Arg>
- </Call>
- <Call name="addBean">
- <Arg>
- <New class="org.eclipse.jetty.plus.jaas.JAASLoginService">
- <Set name="name">default</Set>
- <Set name="loginModuleName">karaf</Set>
- <Set name="roleClassNames">
- <Array type="java.lang.String">
- <Item>org.apache.karaf.jaas.boot.principal.RolePrincipal
- </Item>
- </Array>
- </Set>
- </New>
- </Arg>
- </Call>
+<!DOCTYPE Configure PUBLIC "-//Jetty//Configure//EN" "http://www.eclipse.org/jetty/configure_9_3.dtd">
+
+<!-- Object named "Server" of org.eclipse.jetty.server.Server class is configured by pax-web-jetty -->
+<Configure id="Server" class="org.eclipse.jetty.server.Server">
+
+ <!-- =========================================================== -->
+ <!-- Set connectors -->
+ <!-- =========================================================== -->
+ <!-- One of each type! -->
+ <!-- =========================================================== -->
+
+ <!-- Use this connector for many frequently idle connections and for
+ threadless continuations. -->
+ <!-- <New id="httpConfig" class="org.eclipse.jetty.server.HttpConfiguration">-->
+ <!-- <Set name="secureScheme">https</Set>-->
+ <!-- <Set name="securePort">-->
+ <!-- <Property name="jetty.secure.port" default="8443" />-->
+ <!-- </Set>-->
+ <!-- <Set name="outputBufferSize">32768</Set>-->
+ <!-- <Set name="requestHeaderSize">8192</Set>-->
+ <!-- <Set name="responseHeaderSize">8192</Set>-->
+ <!-- <Set name="sendServerVersion">true</Set>-->
+ <!-- <Set name="sendDateHeader">false</Set>-->
+ <!-- <Set name="headerCacheSize">512</Set>-->
+ <!-- </New>-->
+
+ <!-- =========================================================== -->
+ <!-- Special server connectors -->
+ <!-- =========================================================== -->
+ <!-- This is a sample for alternative connectors, enable if needed -->
+ <!-- =========================================================== -->
+ <!--
+ <Call name="addConnector">
+ <Arg>
+ <New class="org.eclipse.jetty.server.ServerConnector">
+ <Arg name="server">
+ <Ref refid="Server" />
+ </Arg>
+ <Arg name="factories">
+ <Array type="org.eclipse.jetty.server.ConnectionFactory">
+ <Item>
+ <New class="org.eclipse.jetty.server.HttpConnectionFactory">
+ <Arg name="config">
+ <Ref refid="httpConfig" />
+ </Arg>
+ </New>
+ </Item>
+ </Array>
+ </Arg>
+ <Set name="host">
+ <Property name="jetty.host" default="localhost" />
+ </Set>
+ <Set name="port">
+ <Property name="jetty.port" default="8282" />
+ </Set>
+ <Set name="idleTimeout">
+ <Property name="http.timeout" default="30000" />
+ </Set>
+ <Set name="name">jettyConn1</Set>
+ </New>
+ </Arg>
+ </Call>
+ -->
+
+ <!-- =========================================================== -->
+ <!-- Configure Authentication Realms -->
+ <!-- Realms may be configured for the entire server here, or -->
+ <!-- they can be configured for a specific web app in a context -->
+ <!-- configuration (see $(jetty.home)/contexts/test.xml for an -->
+ <!-- example). -->
+ <!-- =========================================================== -->
+ <!--
+ <Call name="addBean">
+ <Arg>
+ <New class="org.eclipse.jetty.jaas.JAASLoginService">
+ <Set name="name">karaf</Set>
+ <Set name="loginModuleName">karaf</Set>
+ <Set name="roleClassNames">
+ <Array type="java.lang.String">
+ <Item>org.apache.karaf.jaas.boot.principal.RolePrincipal</Item>
+ </Array>
+ </Set>
+ </New>
+ </Arg>
+ </Call>
+ <Call name="addBean">
+ <Arg>
+ <New class="org.eclipse.jetty.jaas.JAASLoginService">
+ <Set name="name">default</Set>
+ <Set name="loginModuleName">karaf</Set>
+ <Set name="roleClassNames">
+ <Array type="java.lang.String">
+ <Item>org.apache.karaf.jaas.boot.principal.RolePrincipal</Item>
+ </Array>
+ </Set>
+ </New>
+ </Arg>
+ </Call>
+ -->
</Configure>
----
-The `SelectChannelConnector` defines the default connector of the WebContainer.
+Pax Web 8 reads `org.ops4j.pax.web` PID configuration which ensures that the default (and secure - if enabled) connetors are running even if there's no specific connector defined in `etc/jetty.xml`.
-This connector defines the 8181 port number for the HTTP protocol (`port` property), and the 8443 port number for the
-HTTPS protocol (`confidentialPort` property).
+The above XML configuration contains (disabled by default) `<Call name="addConnector">` element which shows how to configure additional connector.
-By default, Apache Karaf bind these ports on all network interfaces (`0.0.0.0`). You can config the `host` property
+By default, Apache Karaf bind these ports on all network interfaces (`0.0.0.0`). You can config the `jetty.host` property
to bind on a specific network interface (with a given IP address).
The following resources give you details about advanced `etc/jetty.xml` configurations:
@@ -204,7 +240,7 @@ A WAB is a standard WAR or JAR archive containing at least the following propert
* `Bundle-ManifestVersion: 2` defines that the bundle follows the rules of R4 specification.
* `Bundle-SymbolicName` specifies a unique, non-localizable name for the bundle. This name should be based on the
reverse domain name convention.
-* `Web-ContextPath` specifies the location of the web application.
+* `Web-ContextPath` specifies the context path (must start with `/`) of the web application.
WAB can be deployed directly in Apache Karaf, for instance, by dropping the archive in the `deploy` folder, or using the
`bundle:install` command.
@@ -212,7 +248,58 @@ WAB can be deployed directly in Apache Karaf, for instance, by dropping the arch
For instance, the Apache Karaf manual (documentation) is available as a WAB that you can deploy directly in a running instance:
----
-karaf@root()> bundle:install -s mvn:org.apache.karaf/manual/4.0.0/war
+karaf@root()> bundle:install -s mvn:org.apache.karaf/manual/4.4.0
+----
+
+When `pax-web-karaf` feature is installed, there are new commands available and we can already investigate the details about just installed WAB. For example we can see high-level overview of the deployed WABs - together with context path and base URL (which is calculated based on actual information from `org.ops4j.pax.web` PID).
+
+[source,options="nowrap"]
+----
+karaf@root()> web:wab-list
+Context Path │ Bundle ID │ Symbolic Name │ State │ Base URL
+───────────────┼───────────┼─────────────────────────┼──────────┼────────────────────────────────────
+/documentation │ 72 │ org.apache.karaf.manual │ Deployed │ http://127.0.0.1:8181/documentation
+----
+
+We can see the details about selected WAB:
+
+[source,options="nowrap"]
+----
+karaf@root()> web:wab-info 72
+
+Apache Karaf :: Manual (72)
+---------------------------
+Context Path: /documentation
+Deployment State: Deployed
+WAB ClassPath:
+ - bundle://57d1482b-7ade-42b4-950a-f81d26159dda_72.0:0/
+ServletContainerInitializers:
+ - org.ops4j.pax.web.jsp.JasperInitializer
+Container web fragments (reachable bundles without /META-INF/web-fragment.xml):
+ - (70) org.ops4j.pax.web.pax-web-jsp/8.0.2
+----
+
+`web:context-list` shows information of the web contexts (those created for web applications, but also the ones related to HttpService and Whiteboard web elements):
+
+[source,options="nowrap"]
+----
+karaf@root()> web:context-list
+Bundle ID │ Symbolic Name │ Context Path │ Context Name │ Rank │ Service ID │ Type │ Scope │ Registration Properties
+──────────┼─────────────────────────┼────────────────┼────────────────┼──────┼────────────┼──────┼─────────┼─────────────────────────────────────────────────
+72 │ org.apache.karaf.manual │ /documentation │ /documentation │ MAX │ 0 │ WAB │ static* │ osgi.http.whiteboard.context.path=/documentation
+
+*) This context is using ServletContextHelper/HttpContext without resolving an org.osgi.framework.ServiceReference.
+----
+
+Finally, `web:servlet-list` shows all the servlets for all deployed web applications:
+
+[source,options="nowrap"]
+----
+karaf@root()> web:servlet-list
+Bundle ID │ Name │ Class │ Context Path(s) │ URLs │ Type │ Context Filter
+──────────┼─────────┼─────────────────────────────────────────────────────────────────────┼─────────────────┼───────────────┼──────┼───────────────
+72 │ default │ org.ops4j.pax.web.service.tomcat.internal.web.TomcatResourceServlet │ /documentation │ / │ WAB │ -
+72 │ jsp │ org.ops4j.pax.web.jsp.JspServlet │ /documentation │ *.jspx, *.jsp │ WAB │ -
----
====== WAR (WebApplication aRchive)
@@ -223,8 +310,27 @@ Using the `webbundle` prefix and providing headers directly on the URL, Apache K
For instance, you can deploy the Apache Tomcat sample non-OSGi "classical" WAR with the following command:
+[source,options="nowrap"]
----
-karaf@root()> bundle:install -s "webbundle:http://tomcat.apache.org/tomcat-7.0-doc/appdev/sample/sample.war?Bundle-SymbolicName=tomcat-sample&Web-ContextPath=/sample"
+karaf@root()> bundle:install -s "webbundle:https://tomcat.apache.org/tomcat-9.0-doc/appdev/sample/sample.war?Bundle-SymbolicName=tomcat-sample&Web-ContextPath=/tomcat-docs"
+Bundle ID: 76
+karaf@root()> web:wab-list
+Context Path │ Bundle ID │ Symbolic Name │ State │ Base URL
+───────────────┼───────────┼─────────────────────────┼──────────┼────────────────────────────────────
+/documentation │ 72 │ org.apache.karaf.manual │ Deployed │ http://127.0.0.1:8181/documentation
+/tomcat-docs │ 76 │ tomcat-sample │ Deployed │ http://127.0.0.1:8181/tomcat-docs
+karaf@root()> web:wab-info 76
+
+tomcat-sample (76)
+------------------
+Context Path: /tomcat-docs
+Deployment State: Deployed
+WAB ClassPath:
+ - bundle://57d1482b-7ade-42b4-950a-f81d26159dda_76.0:0/WEB-INF/classes/
+ServletContainerInitializers:
+ - org.ops4j.pax.web.jsp.JasperInitializer
+Container web fragments (reachable bundles without /META-INF/web-fragment.xml):
+ - (70) org.ops4j.pax.web.pax-web-jsp/8.0.2
----
You can note the `webbundle` prefix, and the `Bundle-SymbolicName` and `Web-ContextPath` headers on the URL.
@@ -238,61 +344,52 @@ You can use the Karaf `ProxyService` programmatically, or via the corresponding
===== Commands
-====== `http:list`
+NOTE: This part of documentation is new for Karaf 4.4.0 with Pax Web 8.
-The `http:list` lists the available Servlets deployed in the WebContainer.
+====== `web:servlet-list`
+
+The `web:servlet-list` (previously `http:list`) lists the available Servlets deployed in the WebContainer.
For instance, if you have installed the Apache Karaf WebConsole, you can see the WebConsole Servlets:
+[source,options="nowrap"]
----
-karaf@root()> http:list
-ID | Servlet | Servlet-Name | State | Alias | Url
------------------------------------------------------------------------------------------------------
-113 | ResourceServlet | /res | Deployed | /system/console/res | [/system/console/res/*]
-113 | KarafOsgiManager | ServletModel-2 | Undeployed | /system/console | [/system/console/*]
-113 | KarafOsgiManager | ServletModel-5 | Deployed | /system/console | [/system/console/*]
+karaf@root()> web:servlet-list
+Bundle ID │ Name │ Class │ Context Path(s) │ URLs │ Type │ Context Filter
+──────────┼───────────────────────────────────────────────────────────────┼───────────────────────────────────────────────────────────────────┼─────────────────┼───────────────────────┼─────────────┼───────────────
+93 │ default-d975426d-f19e-4b5a-a889-80603beb34c9 │ org.ops4j.pax.web.service.jetty.internal.web.JettyResourceServlet │ / │ /system/console/res/* │ HttpService │ -
+93 │ org.apache.felix.webconsole.internal.servlet.KarafOsgiManager │ org.apache.felix.webconsole.internal.servlet.KarafOsgiManager │ / │ /system/console/* │ HttpService │ -
----
-The `ID` is the ID of the bundle which provides the servlet (`113` here).
-
-The `State` is the current state of the Servlet (`Deployed` or `Undeployed`).
+The `Bundle ID` is the ID of the bundle which provides the servlet (`93` here).
-The `Url` is the URL where the Servlet is available.
+The `Name` and `Class` show name and FQCN of the servlet.
-====== `web:list`
+The `Context Path(s)` column shows the main context path that hosts the servlet.
-The `web:list` command lists the WebApplication Bundles ("native" WAB or "wrapped WAR") deployed in the WebContainer.
+The `URLs` shows the mapping URI patterns defined for the Servlet.
-For instance, if you installed the Apache Karaf manual WAR file as described previously, you can see it with `web:list`:
+`Type` column shows the source of servlet registration (can be `WAB`, `HttpService` or `Whiteboard`).
-----
-karaf@root()> web:list
-ID | State | Web-State | Level | Web-ContextPath | Name
----------------------------------------------------------------------------------------------------
-111 | Active | Deployed | 80 | /karaf-doc | Apache Karaf :: Manual (4.0.0)
-----
+Finally `Context Filter` shows the Whiteboard context selection filter for the servlet.
-====== `web:stop`
+====== `web:wab-list`
-The `web:stop` command stops a web application in the WebContainer. The `web:stop` command expects a `id` argument
-corresponding to the bundle ID (as displayed by the `web:list` command).
+The `web:wab-list` (previously `web:list`) command lists the WebApplication Bundles ("native" WAB or "wrapped WAR") deployed in the WebContainer.
-For instance, to stop the Apache Karaf manual web application:
+For instance, if you installed the Apache Karaf manual WAR file as described previously, you can see it with `web:wab-list`:
+[source,options="nowrap"]
----
-karaf@root()> web:stop 111
+karaf@root()> web:wab-list
+Context Path │ Bundle ID │ Symbolic Name │ State │ Base URL
+───────────────┼───────────┼─────────────────────────┼──────────┼────────────────────────────────────
+/documentation │ 72 │ org.apache.karaf.manual │ Deployed │ http://127.0.0.1:8181/documentation
----
-====== `web:start`
+====== `web:start` and `web:stop`
-The `web:start` command starts a web application in the WebContainer. The `web:start` command expects a `id` argument
-corresponding to the bundle ID (as displayed by the `web:list` command).
-
-For instance, to start the Apache Karaf manual web application:
-
-----
-karaf@root()> web:start 111
-----
+These two commands were removed from Karaf 4.4 because Pax Web 8 conforms fully to OSGi CMPN Web Applications specification. A WAB associated with bundle has a lifecycle tied to the lifecycle of the bundle. To stop a web application, one has to stop the bundle.
====== `http:proxy-list`
@@ -360,11 +457,12 @@ The ObjectName to use is `org.apache.karaf:type=http,name=*`.
The `Servlets` attribute provides a tabular data providing the list of deployed Servlets including:
-* `Alias` is the Servlet URL alias.
* `Bundle-ID` is the ID of the bundle which provides this Servlet.
+* `Context-Path` is the context path(s) of the target web application.
* `Servlet` is the class name of the Servlet.
-* `State` is the current Servlet state (`Deployed` or `Undeployed`).
-* `URL` is the URL of the Servlet (the Servlet context path).
+* `Servlet Name` is the name of the Servlet.
+* `Type` is the Servlet type indicating its origin (HttpService, Whiteboard or WAB)
+* `URL` is the list of URL mappings of the Servlet.
The `Proxies` attribute provides a tabular data providing the list of HTTP proxies including:
@@ -389,6 +487,7 @@ The ObjectName to use is `org.apache.karaf:type=web,name=*`.
The `WebBundles` attribute provides a tabular data providing the list of deployed Web Applications including:
+* `Context Name` is the name of the web context used by the Web Application.
* `ID` is the ID of the bundle providing the Web Application.
* `Level` is the bundle start level.
* `Name` is the bundle symbolic name providing the Web Application.
diff --git a/web/src/main/java/org/apache/karaf/web/management/internal/WebMBeanImpl.java b/web/src/main/java/org/apache/karaf/web/management/internal/WebMBeanImpl.java
index a601d25..f27aa97 100644
--- a/web/src/main/java/org/apache/karaf/web/management/internal/WebMBeanImpl.java
+++ b/web/src/main/java/org/apache/karaf/web/management/internal/WebMBeanImpl.java
@@ -49,19 +49,21 @@ public class WebMBeanImpl extends StandardMBean implements WebMBean {
public TabularData getWebBundles() throws MBeanException {
try {
CompositeType webType = new CompositeType("Web Bundle", "An OSGi Web bundle",
- new String[]{"ID", "State", "Web-State", "Level", "Web-ContextPath", "Name"},
+ new String[]{"ID", "Context Name", "State", "Web-State", "Level", "Web-ContextPath", "Name"},
new String[]{"ID of the bundle",
+ "Name of the context",
"OSGi state of the bundle",
"Web state of the bundle",
"Start level of the bundle",
"Web context path",
"Name of the bundle"},
- new OpenType[]{SimpleType.LONG, SimpleType.STRING, SimpleType.STRING, SimpleType.INTEGER, SimpleType.STRING, SimpleType.STRING});
+ new OpenType[]{SimpleType.LONG, SimpleType.STRING, SimpleType.STRING, SimpleType.STRING, SimpleType.INTEGER, SimpleType.STRING, SimpleType.STRING});
TabularType tableType = new TabularType("Web Bundles", "Table of web bundles", webType,
- new String[]{"ID"});
+ new String[]{"ID", "Context Name"});
TabularData table = new TabularDataSupport(tableType);
for (WebApplicationInfo webBundle : webContainerService.list()) {
String contextPath = webBundle.getContextPath();
+ String contextName = webBundle.getName();
// get the bundle name
String name = webBundle.getBundle().getHeaders().get(Constants.BUNDLE_NAME);
@@ -80,8 +82,9 @@ public class WebMBeanImpl extends StandardMBean implements WebMBean {
try {
CompositeData data = new CompositeDataSupport(webType,
- new String[]{"ID", "State", "Web-State", "Level", "Web-ContextPath", "Name"},
+ new String[]{"ID", "Context Name", "State", "Web-State", "Level", "Web-ContextPath", "Name"},
new Object[]{webBundle.getBundle().getBundleId(),
+ contextName,
getStateString(webBundle.getBundle()),
webBundle.getDeploymentState(),
level,