karaf-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jbono...@apache.org
Subject svn commit: r1548946 - in /karaf/trunk/manual/src/main/webapp: _navigation.conf users-guide/enterprise.conf users-guide/index.conf users-guide/webcontainer.conf
Date Sat, 07 Dec 2013 17:54:46 GMT
Author: jbonofre
Date: Sat Dec  7 17:54:46 2013
New Revision: 1548946

URL: http://svn.apache.org/r1548946
Log:
[KARAF-2511] Review and update the webcontainer page of the user guide

Added:
    karaf/trunk/manual/src/main/webapp/users-guide/enterprise.conf
Modified:
    karaf/trunk/manual/src/main/webapp/_navigation.conf
    karaf/trunk/manual/src/main/webapp/users-guide/index.conf
    karaf/trunk/manual/src/main/webapp/users-guide/webcontainer.conf

Modified: karaf/trunk/manual/src/main/webapp/_navigation.conf
URL: http://svn.apache.org/viewvc/karaf/trunk/manual/src/main/webapp/_navigation.conf?rev=1548946&r1=1548945&r2=1548946&view=diff
==============================================================================
--- karaf/trunk/manual/src/main/webapp/_navigation.conf (original)
+++ karaf/trunk/manual/src/main/webapp/_navigation.conf Sat Dec  7 17:54:46 2013
@@ -20,13 +20,15 @@ h3. [Users Guide|/users-guide/index]
 - [Instances|/users-guide/instances]
 - [Security|/users-guide/security]
 - [OBR|/users-guide/obr]
-- Enterprise
+- [Enterprise|/users-guide/enterprise]
 -- [WebContainer (JSP/Servlet)|/users-guide/webcontainer]
 -- Naming (JNDI)
 -- Transaction (JTA)
 -- DataSource (JDBC)
 -- MOM (JMS)
 -- Persistence (JPA)
+-- OpenEJB
+-- CDI
 -- [HA/failover and cluster|/users-guide/failover]
 - [Monitoring|/users-guide/monitoring]
 - [WebConsole|/users-guide/webconsole]

Added: karaf/trunk/manual/src/main/webapp/users-guide/enterprise.conf
URL: http://svn.apache.org/viewvc/karaf/trunk/manual/src/main/webapp/users-guide/enterprise.conf?rev=1548946&view=auto
==============================================================================
--- karaf/trunk/manual/src/main/webapp/users-guide/enterprise.conf (added)
+++ karaf/trunk/manual/src/main/webapp/users-guide/enterprise.conf Sat Dec  7 17:54:46 2013
@@ -0,0 +1,10 @@
+h1. Enterprise
+
+Apache Karaf provides a set of enterprise class features.
+
+These features are not installed by default, you have to install yourself depending of your
needs.
+
+The enterprise features available are:
+
+* [WebContainer|webcontainer] providing a complete JSP/Servlet support. These feature turns
Apache Karaf as a complete
+ web container where you can deploy web application (as you can do in Apache Tomcat, or other
JEE application servers).

Modified: karaf/trunk/manual/src/main/webapp/users-guide/index.conf
URL: http://svn.apache.org/viewvc/karaf/trunk/manual/src/main/webapp/users-guide/index.conf?rev=1548946&r1=1548945&r2=1548946&view=diff
==============================================================================
--- karaf/trunk/manual/src/main/webapp/users-guide/index.conf (original)
+++ karaf/trunk/manual/src/main/webapp/users-guide/index.conf Sat Dec  7 17:54:46 2013
@@ -22,6 +22,8 @@ h1. Users Guide
 ** DataSource (JDBC)
 ** MOM (JMS)
 ** Persistence (JPA)
+** OpenEJB
+** CDI
 ** [HA/failover and cluster|failover]
 * [Monitoring|monitoring]
 * [WebConsole|webconsole]

Modified: karaf/trunk/manual/src/main/webapp/users-guide/webcontainer.conf
URL: http://svn.apache.org/viewvc/karaf/trunk/manual/src/main/webapp/users-guide/webcontainer.conf?rev=1548946&r1=1548945&r2=1548946&view=diff
==============================================================================
--- karaf/trunk/manual/src/main/webapp/users-guide/webcontainer.conf (original)
+++ karaf/trunk/manual/src/main/webapp/users-guide/webcontainer.conf Sat Dec  7 17:54:46 2013
@@ -1,37 +1,279 @@
-h1. Web applications
+h1. WebContainer
 
-h2. Installing war support
+Apache Karaf can act a complete WebContainer, fully supporting JSP/Servlet specification.
 
-Install the war feature (and the sub-features it requires) -
-{noformat}
-karaf@root> feature:install war 
-{noformat}
+Apache Karaf WebContainer supports both:
 
-The Jetty server should now be listening on {{http://localhost:8181/}}., but with no published
applications available. To configure the port see the [HTTP Service config | http]. 
+* WAB (WebApplication Bundles) which are OSGi native web applications
+* WAR (WebApplication aRchives) which are non-OSGi web applications (the same as you can
deploy in any web container like Apache Tomcat)
 
-h2. Preparing a war so it can be deployed
+To enable the Apache Karaf WebContainer, you just have to install the {{war}} feature:
 
-To deploy a WAR (JSP or Servlet) to Jetty, update its MANIFEST.MF to include the required
OSGi headers as described in [How to OSGi-fy War files | http://team.ops4j.org/wiki/display/ops4j/Pax+Web+Extender+-+War+-+OSGi-fy]
+{code}
+karaf@root()> feature:install war
+{code}
+
+NB: the installation of the {{webconsole}} feature automatically installs the {{war}} feature.
+
+The {{war}} feature provides:
+
+* an embedded web container (powered by Jetty), with its configuration
+* a set of console commands
+* a new war deployer
+
+h2. Configuration
+
+The default port used by the WebContainer is 8181.
+
+The WebContainer configuration is in the {{etc/jetty.xml}} configuration file.
+
+The {{etc/jetty.xml}} is a standard Eclipse Jetty configuration file.
+
+The default Apache Karaf WebContainer {{etc/jetty.xml}} contains:
+
+{code:lang=xml}
+<?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.
+-->
+<!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>
+
+</Configure>
+{code}
+
+The {{SelectChannelConnector}} defines the default connector of the WebContainer.
+
+This connector defines the 8181 port number for the HTTP protocol ({{port}} property), and
the 8443 port number for the
+HTTPS protocol ({{confidentialPort}} property).
+
+By default, Apache Karaf bind these ports on all network interfaces ({{0.0.0.0}}). You can
config the {{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:
+
+* [Standard configuration|http://wiki.eclipse.org/Jetty/Howto/Configure_Jetty]
+* [Enable SSL|http://wiki.eclipse.org/Jetty/Howto/Configure_SSL]
+* [Reference|http://wiki.eclipse.org/Jetty/Reference/jetty.xml_syntax]
+
+h2. Deploy
+
+Apache Karaf WebContainer is able to deploy:
+
+* pure OSGi WebApplication Bundle (WAB)
+* "classical" standard WebApplication aRchive (WAR)
+
+h3. WAB (WebApplication Bundle)
+
+A WAB is a standard WAR or JAR archive containing at least the following properties in the
MANIFEST:
+
+* {{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.
+
+The {{Webapp-Context}} is strongly adviced as well. It defines the Servlet context path.
If not specified, the {{Bundle-SymbolicName}}
+will be used.
+
+You can find details about the WAB MANIFEST properties on the [OPS4J Pax Web website|https://ops4j1.jira.com/wiki/display/ops4j/Pax+Web+Extender+-+War+-+OSGi-fy].
+
+WAB can be deployed directly in Apache Karaf, for instance, by dropping the archive in the
{{deploy}} folder, or using the
+{{bundle:install}} command.
+
+For instance, the Apache Karaf manual (documentation) is available as a WAB that you can
deploy directly in a running instance:
+
+{code}
+karaf@root()> bundle:install -s mvn:org.apache.karaf/manual/3.0.0/war
+{code}
+
+h3. WAR (WebApplication aRchive)
+
+Apache Karaf allows you to deploy directly WAR files without repackaging as WAB.
+
+Using the {{webbundle}} prefix and providing headers directly on the URL, Apache Karaf creates
a WAB "on the fly".
+
+For instance, you can deploy the Apache Tomcat sample non-OSGi "classical" WAR with the following
command:
+
+{code}
+karaf@root()> bundle:install -s "webbundle:http://tomcat.apache.org/tomcat-7.0-doc/appdev/sample/sample.war?Bundle-SymbolicName=tomcat-sample&Webapp-Context=/sample"
+{code}
+
+You can note the {{webbundle}} prefix, and the {{Bundle-SymbolicName}} and {{Webapp-Context}}
headers on the URL.
 
-h2. Deploying a WAR
+h2. Commands
 
-Copy the updated WAR (archive or extracted files) to the _deploy_ directory or install the
war using bundle:install like shown below for the Tomcat sample application.
+h3. {{http:list}}
 
-h2. Deploying the Tomcat sample application
+The {{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:
 
-If you want to deploy a sample web application into Karaf, you could use the following command:
 {code}
-karaf@root> bundle:install -s webbundle:http://tomcat.apache.org/tomcat-5.5-doc/appdev/sample/sample.war?Bundle-SymbolicName=tomcat-sample&Webapp-Context=/sample
+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/*]
 {code}
 
-Then open your web browser and point to [http://localhost:8181/sample/index.html].
+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 {{Url}} is the URL where the Servlet is available.
+
+h3. {{web:list}}
+
+The {{web:list}} command lists the WebApplication Bundles ("native" WAB or "wrapped WAR")
deployed in the WebContainer.
 
-h2. Listing installed web applications
+For instance, if you installed the Apache Karaf manual WAR file as described previously,
you can see it with {{web:list}}:
 
-{noformat}
+{code}
 karaf@root()> web:list
-ID | State       | Web-State   | Level | Web-ContextPath | Name
-----------------------------------------------------------------------------
-95 | Active      | Deployed    | 80    | /sample         | tomcat-sample (0)
-{noformat}
+ID  | State       | Web-State   | Level | Web-ContextPath | Name
+---------------------------------------------------------------------------------------------------
+111 | Active      | Deployed    | 80    | /karaf-doc      | Apache Karaf :: Manual (3.0.0)
+{code}
+
+h3. {{web:stop}}
+
+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).
+
+For instance, to stop the Apache Karaf manual web application:
+
+{code}
+karaf@root()> web:stop 111
+{code}
+
+h3. {{web:start}}
+
+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:
+
+{code}
+karaf@root()> web:start 111
+{code}
+
+h2. JMX HttpMBean
+
+On the JMX layer, you have a MBean dedicated to the manipulation of the Servlets: the HttpMBean.
+
+The ObjectName to use is {{org.apache.karaf:type=http,name=*}}.
+
+h3. Attributes
+
+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.
+* {{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).
+
+h2. JMX WebMBean
+
+On the JMX layer, you have a MBean dedicated to the manipulation of the Web Applications:
the WebMBean.
+
+The ObjectName to use is {{org.apache.karaf:type=web,name=*}}.
+
+h3. Attributes
+
+The {{WebBundles}} attribute provides a tabular data providing the list of deployed Web Applications
including:
+
+* {{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.
+* {{State}} is the current state of the bundle.
+* {{Web-ContextPath}} is the context path of the Web Application.
+* {{Web-State}} is the current status of the Web Application ({{Deployed}} or {{Undeployed}}).
+
+h3. Operations
+
+* {{start(id)}} starts the web context of the bundle with {{id}}.
+* {{start(list)}} starts the web context of the bundles with ID in the provided {{list}}.
+* {{stop(id)}} stops the web context of the bundle with {{id}}.
+* {{stop(list)}} stops the web context of the bundles with ID in the provided {{list}}.
 



Mime
View raw message