[jboss-svn-commits] JBL Code SVN: r5105 - in labs/jbossweb/trunk: . docbook docbook/usersguide docbook/usersguide/en docbook/usersguide/en/images docbook/usersguide/en/modules
jboss-svn-commits at lists.jboss.org
jboss-svn-commits at lists.jboss.org
Fri Jul 14 17:41:50 EDT 2006
Author: michael.yuan at jboss.com
Date: 2006-07-14 17:41:46 -0400 (Fri, 14 Jul 2006)
New Revision: 5105
Added:
labs/jbossweb/trunk/docbook/
labs/jbossweb/trunk/docbook/usersguide/
labs/jbossweb/trunk/docbook/usersguide/build.xml
labs/jbossweb/trunk/docbook/usersguide/en/
labs/jbossweb/trunk/docbook/usersguide/en/images/
labs/jbossweb/trunk/docbook/usersguide/en/images/architecture-fig01.png
labs/jbossweb/trunk/docbook/usersguide/en/images/architecture-fig02.png
labs/jbossweb/trunk/docbook/usersguide/en/images/architecture-fig03.png
labs/jbossweb/trunk/docbook/usersguide/en/images/architecture-fig04.png
labs/jbossweb/trunk/docbook/usersguide/en/images/introduction-fig01.png
labs/jbossweb/trunk/docbook/usersguide/en/master.xml
labs/jbossweb/trunk/docbook/usersguide/en/modules/
labs/jbossweb/trunk/docbook/usersguide/en/modules/about.xml
labs/jbossweb/trunk/docbook/usersguide/en/modules/architecture.xml
labs/jbossweb/trunk/docbook/usersguide/en/modules/connectors.xml
labs/jbossweb/trunk/docbook/usersguide/en/modules/gettingstarted.xml
labs/jbossweb/trunk/docbook/usersguide/en/modules/introduction.xml
Log:
Add docbook
Added: labs/jbossweb/trunk/docbook/usersguide/build.xml
===================================================================
--- labs/jbossweb/trunk/docbook/usersguide/build.xml 2006-07-14 21:04:47 UTC (rev 5104)
+++ labs/jbossweb/trunk/docbook/usersguide/build.xml 2006-07-14 21:41:46 UTC (rev 5105)
@@ -0,0 +1,20 @@
+<project name="Documentation" default="all.doc" basedir=".">
+
+ <!-- Set the following property to generate the doco in the output folder -->
+ <!--property name="build.dir" value="${basedir}/../../output/docs/guide"/-->
+
+ <property name="pdf.name" value="jboss-docbook.pdf" />
+ <import file="../../../../docbook-support/support.xml" />
+
+ <target name="all.doc" depends="clean">
+ <antcall target="lang.all"><param name="lang" value="en"/></antcall>
+ </target>
+
+ <!-- Use this alternate target to enable uptodate checking, i.e.
+ don't generate docs if nothing has changed
+ <target name="all.doc">
+ <antcall target="lang.all.run"><param name="lang" value="en"/></antcall>
+ </target>
+ -->
+
+</project>
Property changes on: labs/jbossweb/trunk/docbook/usersguide/build.xml
___________________________________________________________________
Name: svn:executable
+ *
Added: labs/jbossweb/trunk/docbook/usersguide/en/images/architecture-fig01.png
===================================================================
(Binary files differ)
Property changes on: labs/jbossweb/trunk/docbook/usersguide/en/images/architecture-fig01.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: labs/jbossweb/trunk/docbook/usersguide/en/images/architecture-fig02.png
===================================================================
(Binary files differ)
Property changes on: labs/jbossweb/trunk/docbook/usersguide/en/images/architecture-fig02.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: labs/jbossweb/trunk/docbook/usersguide/en/images/architecture-fig03.png
===================================================================
(Binary files differ)
Property changes on: labs/jbossweb/trunk/docbook/usersguide/en/images/architecture-fig03.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: labs/jbossweb/trunk/docbook/usersguide/en/images/architecture-fig04.png
===================================================================
(Binary files differ)
Property changes on: labs/jbossweb/trunk/docbook/usersguide/en/images/architecture-fig04.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: labs/jbossweb/trunk/docbook/usersguide/en/images/introduction-fig01.png
===================================================================
(Binary files differ)
Property changes on: labs/jbossweb/trunk/docbook/usersguide/en/images/introduction-fig01.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Added: labs/jbossweb/trunk/docbook/usersguide/en/master.xml
===================================================================
--- labs/jbossweb/trunk/docbook/usersguide/en/master.xml 2006-07-14 21:04:47 UTC (rev 5104)
+++ labs/jbossweb/trunk/docbook/usersguide/en/master.xml 2006-07-14 21:41:46 UTC (rev 5105)
@@ -0,0 +1,35 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3CR3//EN"
+"../../../../docbook-support/support/docbook-dtd/docbookx.dtd" [
+<!ENTITY about SYSTEM "modules/about.xml">
+<!ENTITY introduction SYSTEM "modules/introduction.xml">
+<!ENTITY gettingstarted SYSTEM "modules/gettingstarted.xml">
+<!ENTITY architecture SYSTEM "modules/architecture.xml">
+<!ENTITY connectors SYSTEM "modules/connectors.xml">
+<!ENTITY modules SYSTEM "modules/modules.xml">
+<!ENTITY performance SYSTEM "modules/performance.xml">
+]>
+<book lang="en">
+ <bookinfo>
+ <title>JBoss Web Server User's Guide</title>
+
+ <subtitle>A high performance deployment platform Java EE, PHP, ASP.Net and CGI applications</subtitle>
+ </bookinfo>
+
+ <toc></toc>
+
+ &about;
+
+ &introduction;
+
+ &gettingstarted;
+
+ &architecture;
+
+ &connectors;
+
+ &modules;
+
+ &performance;
+
+</book>
Added: labs/jbossweb/trunk/docbook/usersguide/en/modules/about.xml
===================================================================
--- labs/jbossweb/trunk/docbook/usersguide/en/modules/about.xml 2006-07-14 21:04:47 UTC (rev 5104)
+++ labs/jbossweb/trunk/docbook/usersguide/en/modules/about.xml 2006-07-14 21:41:46 UTC (rev 5105)
@@ -0,0 +1,11 @@
+<chapter id="about">
+
+ <title>About JBoss Web</title>
+
+ <para>JBoss Web is a key component in the JBoss Enterprise Middleware Stack (JEMS). It is runs Java EE, Microsoft ASP.Net, PHP, and CGI applications with native performance matching or even exceeding the Apache Web Server. JBoss Web will replace Tomcat and become the default servlet / JSP container in JBoss AS 5.x and later.</para>
+
+ <para>In this guide, we discuss how to install and use the JBoss Web Server. We cover JBoss Web configuration options, performance considerations, as well as how to run non-Java applications on the server.</para>
+
+ <para>This guide is work in progress. Please send your suggestions or comments to the <ulink url="http://www.jboss.com/index.html?module=bb&op=viewforum&f=230">JBoss Web user forum</ulink>.</para>
+
+</chapter>
Added: labs/jbossweb/trunk/docbook/usersguide/en/modules/architecture.xml
===================================================================
--- labs/jbossweb/trunk/docbook/usersguide/en/modules/architecture.xml 2006-07-14 21:04:47 UTC (rev 5104)
+++ labs/jbossweb/trunk/docbook/usersguide/en/modules/architecture.xml 2006-07-14 21:41:46 UTC (rev 5105)
@@ -0,0 +1,146 @@
+<chapter id="architecture">
+
+ <title>Architecture Overview</title>
+
+ <para>In the previous chapter, you learned how to download, install, and run the JBoss Web Server. In this chapter, we will discuss the overall architecture of the server. It provides the basis for the understanding the configuration options and modules later in this guide.</para>
+
+ <section>
+ <title>Core Server Components</title>
+
+ <para>The core functionality of JBoss Web Server is provided by the Apache Tomcat. Apache Tomcat is embedded inside JBoss Application Server using Embedded Engine. This allows the seamless integration with JBoss components by using underlaying Microkernel system.</para>
+
+ <para>Additional modules allows to use the JBoss Web Server as drop-in replacement for standard native web servers, while offering the Reference Implementation for the Java Servlet and JavaServer Pages technologies. The Java Servlet and JavaServer Pages specifications are developed by Sun under the Java Community Process. </para>
+
+ <figure id="architecture-fig01">
+ <title>JBoss Web Architecture</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="image/architecture-fig01.png" format="PNG"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para><xref linkend="architecture-fig01"/> shows the JBoss Web Server architecture. The brief description of architecture components is described in the following sections.</para>
+
+ <section>
+ <title>Apache Tomcat</title>
+
+ <para>JBoss Web Server currently uses the Apache Tomcat 5.5.x branch. While it supports the same Servlet and JSP Specification versions (i.e., servlet 2.4 and JSP 2.0) as Apache Tomcat 5.0.x, there are significant changes in many areas under the hood, resulting in improved performance, stability, and total cost of ownership.</para>
+
+ <para>The Java servlet 2.5 and JSP 2.1 specifications are to be supported by Tomcat 6.0.x, planned for the second half of 2006.</para>
+ </section>
+
+ <section>
+ <title>JBoss Cache</title>
+
+ <para>JBoss Cache is a replicated and transactional cache. It is replicated since multiple JBossCache instances can be distributed (within the same JVM or across several JVMs whether they reside on the same machine or on different machines on a network) and data is replicated across the whole group. It is transactional because a user can configure a JTA transaction manager and make the cache operation transactional. Note that the cache can also be run without any replication; this is the local mode.</para>
+
+ <para>Currently, it consists of two components: TreeCache and TreeCacheAop. TreeCache is a tree-structured cache that provides replication and transaction context, while TreeCacheAop extends the functionality of TreeCache but behaves as a true object cache providing transparent and finer-grained object mapping into internal cache. </para>
+ </section>
+
+ <section>
+ <title>JBoss JTA</title>
+
+ <para>A clean room implementation of the Java Transaction API part of the J2EE specification, JBoss JTA is made up of a number of a components and interfaces. The interfaces can be used when you change the transaction manager implementation (i.e., plugin a thirdparty implementation).</para>
+ </section>
+
+ <section>
+ <title>JBoss JCA</title>
+
+ <para>A clean room implementation of the J2EE Connector API part of the J2EE specification, JBoss JCA handles the deployment of resource adapters. These include DataSources and ConnectionFactorys and MessageListeners to and from databases, legacy systems or JMS Servers</para>
+ </section>
+
+ <section>
+ <title>JBoss Microkernel</title>
+
+ <para>The JBoss Microkernel is a set of MBeans that runs on top of JBossMX. It has been designed to be totally modular from the ground up. Support classes exists to extend the notion of an MBean into a Service or Deployer.</para>
<para>JBoss MX isJBoss implementation of the JMX technology. JBoss includes a clean room implementation of the JMX API's published by Sun Microsystems. While implementing all the required management functions it is also geared towards acting as a core library of the JBoss Microkernel. JBoss MX supports version 1.2 of the JMX specification (JSR 003) since JBoss versions 3.2.5 and 4.0.0. Support for the JMX Remote API (JSR 160) is under development. </para>
+ </section>
+
+ </section>
+
+ <section>
+ <title>Modules Support</title>
+
+ <para>JBoss Web Server comes with various extension modules that extends the core functionality of both Apache Tomcat standalone, and standard JBoss Application Server. Some modules are platform specific like Microsoft .NET module, and the others are cross platform, and requires a designated platform binaries. <xref linkend="architecture-fig02"/> shows the JBoss Web Server extensions modules.</para>
+
+ <figure id="architecture-fig02">
+ <title>JBoss Web Extensions</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="image/architecture-fig02.png" format="PNG"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <section>
+ <title>Tomcat Native</title>
+
+ <para>Tomcat Native is JNI based library for Operating System Abstraction. The core functionality of Tomcat Native is provided by using Apache Portable Runtime (APR). The primary goal of APR is to provide an API to which software developers may code and be assured of predictable if not identical behavior regardless of the platform on which their software is built, relieving them of the need to code special-case conditions to work around or take advantage of platform-specific deficiencies or features.</para>
+
+ <para>SSL support is enabled by using the OpenSSL library. This gives much higher performance as well as hardware encryption software support then standard Java offers. It also gives exixting users of Apache HTTPD a seamless transition from mod_ssl.</para>
+
+ <para>Tomcat Native uses APR and OpenSSL to provide superior scalability, performance, and better integration with native server technologies (see <xref linkend="architecture-fig03"/>). The Apache Portable Runtime is a highly portable library that is at the heart of Apache HTTP Server 2.x. APR has many uses, including access to advanced IO functionality (such as sendfile, epoll and TCP corking), OS level functionality (random number generation, system status, etc), and native process handling (shared memory, NT pipes and Unix domain sockets).</para>
+
+ <figure id="architecture-fig03">
+ <title>Tomcat Native</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="image/architecture-fig03.png" format="PNG"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>Tomcat Native comes as a set of libraries compiled for the designated Operating System. JBoss Web Server download comes with prebuild native libraries for the following platforms:</para>
+
+ <itemizedlist mark="bullet">
+ <listitem><para>WIN32</para></listitem>
+ <listitem><para>WIN64/AMD64</para></listitem>
+ <listitem><para>WIN64/IA64</para></listitem>
+ <listitem><para>Linux i386</para></listitem>
+ <listitem><para>Linux amd64</para></listitem>
+ <listitem><para>Sun Solaris Sparc</para></listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Native Proxy</title>
+
+ <para>NativeProxy is Servlet abstraction that enables both in-process and out-of-process access to the legacy subsystems regardless of the method that is used for the integrated within the JBoss Web Server (see <xref linkend="architecture-fig04"/>). NativeProxy has integrated advanced application load balancer that offers both high availability and application segmantation for remotely based subsystems.</para>
+
+ <figure id="architecture-fig04">
+ <title>Native Proxy</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="image/architecture-fig04.png" format="PNG"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>Out of process mosules are accessed using Native proxy. Each of the module is run as a daemon either on the local or remote machine. This gives much higer security and stabilty in case of faulty modules.</para>
+
+ </section>
+
+ <section>
+ <title>Proxy Stream</title>
+
+ <para>Proxy stream is a protocol very much similar to the Tomcat AJP/1.3 protocol, with additions for using Operating system advanced connection mechanisms like Unix Domain Sockets or Microsoft Windows Named Pipes. It offers both connection reuse and connection multiplexing. Unlike AJP/1.3 the data transferred can be encrypted, thus rising the security without the need for special network hardware and topology.</para>
+
+ <para>The main purpose for Proxy Steam Protocol is to give transparent access to the out-of-process legacy subsystems that can be hosted on the remote machine. </para>
+
+ </section>
+
+ <section>
+ <title>Native Module API</title>
+
+ <para>This componet is JNI based native abstraction layer for various http centic legacy subsystem. It is responsible for loading the legacy applications inside the process address space of the running JVM.</para>
+ </section>
+
+ <section>
+ <title>URL Rewrite</title>
+
+ <para>This module uses a rule-based rewriting engine (based on a regular-expression parser) to rewrite requested URLs on the fly. It supports an unlimited number of rules and an unlimited number of attached rule conditions for each rule to provide a really flexible and powerful URL manipulation mechanism. The URL manipulations can depend on various tests, for instance server variables, environment variables, HTTP headers, time stamps and even external database lookups in various formats can be used to achieve a really granular URL matching.
</para>
+ </section>
+
+ </section>
+
+</chapter>
\ No newline at end of file
Added: labs/jbossweb/trunk/docbook/usersguide/en/modules/connectors.xml
===================================================================
--- labs/jbossweb/trunk/docbook/usersguide/en/modules/connectors.xml 2006-07-14 21:04:47 UTC (rev 5104)
+++ labs/jbossweb/trunk/docbook/usersguide/en/modules/connectors.xml 2006-07-14 21:41:46 UTC (rev 5105)
@@ -0,0 +1,175 @@
+<chapter id="connectors">
+
+ <title>Configuring Connectors</title>
+
+ <para>Connectors are crucial components in the JBoss Web Server. They are outward interface of the server. For instance, when a web browser client needs to connect to the server, it has to connect to one of the connectors. The connectors are configured as XML elements in the server.xml file.</para>
+
+ <note>
+ <title>Configuration files in JBoss Web Server</title>
+ <para>JBoss Web Server has the same configuration model as the JBoss Application Server. That gives you an easy transition from JBoss Web Server to full-blown Application Server. <xref linkend=""/> shows how the configuration files are organized in JBoss Web Server. Among them, the most important one is the server.xml file.</para>
+ <figure id="configuration-fig01">
+ <title>JBoss Web Architecture</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="image/configuration-fig01.png" format="PNG"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </note>
+
+
+ <section>
+ <title>The HTTP Connector</title>
+
+ <para> The HTTP connector uses sendfile for hadling large static files (all such files will be sent ansychronously using high performance kernel level calls), and uses a socket poller for keepalive, increasing scalability of the server. The following attributes are supported in the HTTP connector: </para>
+
+ <table>
+ <title>Attributes in the HTTP Connector</title>
<tgroup cols="2" >
<colspec colnum="1" colname="col1" colwidth="1*"/>
<colspec colnum="2" colname="col2" colwidth="1*"/>
+
+ <thead>
<row>
<entry>Attribute</entry>
<entry>Description</entry>
</row>
</thead>
+
<tbody>
<row>
<entry>acceptCount</entry>
<entry>The maximum queue length for incoming connection requests when all possible request processing threads are in use. Any requests received when the queue is full will be refused. The default value is 10.</entry>
+ </row>
+ <row>
<entry>address</entry>
<entry>For servers with more than one IP address, this attribute specifies which address will be used for listening on the specified port. By default, this port will be used on all IP addresses associated with the server.</entry>
+ </row>
+ <row>
<entry>allowTrace</entry>
<entry>A boolean value which can be used to enable or disable the TRACE HTTP method. If not specified, this attribute is set to false.</entry>
+ </row>
+ <row>
<entry>bufferSize</entry>
<entry>The size (in bytes) of the buffer to be provided for input streams created by this connector. By default, buffers of 2048 bytes will be provided.</entry>
+ </row>
+ <row>
<entry>compressableMimeType</entry>
<entry>The value is a comma separated list of MIME types for which HTTP compression may be used. The default value is text/html,text/xml,text/plain.</entry>
+ </row>
+ <row>
<entry>compression</entry>
<entry>The Connector may use HTTP/1.1 GZIP compression in an attempt to save server bandwidth. The acceptable values for the parameter is "off" (disable compression), "on" (allow compression, which causes text data to be compressed), "force" (forces compression in all cases), or a numerical integer value (which is equivalent to "on", but specifies the minimum amount of data before the output is compressed). If the content-length is not known and compression is set to "on" or more aggressive, the output will also be compressed. If not specified, this attribute is set to "off".</entry>
+ </row>
+ <row>
<entry>connectionLinger</entry>
<entry>The number of milliseconds during which the sockets used by this Connector will linger when they are closed. The default value is -1 (socket linger is disabled).</entry>
+ </row>
+ <row>
<entry>connectionTimeout</entry>
<entry>The number of milliseconds this Connector will wait, after accepting a connection, for the request URI line to be presented. The default value is 60000 (i.e. 60 seconds).</entry>
+ </row>
+ <row>
<entry>disableUploadTimeout</entry>
<entry>This flag allows the servlet container to use a different, longer connection timeout while a servlet is being executed, which in the end allows either the servlet a longer amount of time to complete its execution, or a longer timeout during data upload. If not specified, this attribute is set to "false".</entry>
+ </row>
+ <row>
<entry>emptySessionPath</entry>
<entry>If set to true, all paths for session cookies will be set to /. This can be useful for portlet specification implementations, but will greatly affect performance if many applications are accessed on a given server by the client. If not specified, this attribute is set to false.</entry>
+ </row>
+ <row>
<entry>enableLookups</entry>
<entry>Set to true if you want calls to request.getRemoteHost() to perform DNS lookups in order to return the actual host name of the remote client. Set to false to skip the DNS lookup and return the IP address in String form instead (thereby improving performance). By default, DNS lookups are enabled.</entry>
+ </row>
+ <row>
<entry>firstReadTimeout</entry>
<entry>The first read of a request will be made using the specified timeout. If no data is available after the specified time, the socket will be placed in the poller. Setting this value to 0 will increase scalability, but will have a minor impact on latency (see the related pollTime attribute). The default value is 100 (100ms). Note: on Windows, the actual value of firstReadTimeout will be 500 + the specified value.</entry>
+ </row>
+ <row>
<entry>maxHttpHeaderSize</entry>
<entry>The maximum size of the request and response HTTP header, specified in bytes. If not specified, this attribute is set to 4096 (4 KB).</entry>
+ </row>
+ <row>
<entry>maxKeepAliveRequests</entry>
<entry>The maximum number of HTTP requests which can be pipelined until the connection is closed by the server. Setting this attribute to 1 will disable HTTP/1.0 keep-alive, as well as HTTP/1.1 keep-alive and pipelining. Setting this to -1 will allow an unlimited amount of pipelined or keep-alive HTTP requests. If not specified, this attribute is set to 100.</entry>
+ </row>
+ <row>
<entry>maxPostSize</entry>
<entry>The maximum size in bytes of the POST which will be handled by the container FORM URL parameter parsing. The limit can be disabled by setting this attribute to a value less than or equal to 0. If not specified, this attribute is set to 2097152 (2 megabytes).</entry>
+ </row>
+ <row>
<entry>maxSavePostSize</entry>
<entry>The maximum size in bytes of the POST which will be saved/buffered by the container during FORM or CLIENT-CERT authentication. For both types of authentication, the POST will be saved/buffered before the user is authenticated. For CLIENT-CERT authentication, the POST is buffered for the duration of the SSL handshake and the buffer emptied when the request is processed. For FORM authentication the POST is saved whilst the user is re-directed to the login form and is retained until the user successfully authenticates or the session associated with the authentication request expires. The limit can be disabled by setting this attribute to -1. Setting the attribute to zero will disable the saving of POST data during authentication. If not specified, this attribute is set to 4096 (4 kilobytes).</entry>
+ </row>
+ <row>
<entry>maxThreads</entry>
<entry>The maximum number of request processing threads to be created by this Connector, which therefore determines the maximum number of simultaneous requests that can be handled. If not specified, this attribute is set to 200.</entry>
+ </row>
+ <row>
<entry>noCompressionUserAgents</entry>
<entry>The value is a comma separated list of regular expressions matching user-agents of HTTP clients for which compression should not be used, because these clients, although they do advertise support for the feature, have a broken implementation. The default value is an empty String (regexp matching disabled).</entry>
+ </row>
+ <row>
<entry>pollTime</entry>
<entry>Duration of a poll call. Lowering this value will slightly decrease latency of connections being kept alive in some cases, but will use more CPU as more poll calls are being made. The default value is 5000 (5ms).</entry>
+ </row>
+ <row>
<entry>pollerSize</entry>
<entry>Amount of sockets that the poller responsible for polling kept alive connections can hold at a given time. Extra connections will be closed right away. The default value is 768, corresponding to 768 keepalive connections.</entry>
+ </row>
+ <row>
<entry>port</entry>
<entry>The TCP port number on which this Connector will create a server socket and await incoming connections. Your operating system will allow only one server application to listen to a particular port number on a particular IP address.</entry>
+ </row>
+ <row>
<entry>protocol</entry>
<entry>This attribute value must be HTTP/1.1 to use the HTTP handler, which is the default.</entry>
+ </row>
+ <row>
<entry>proxyName</entry>
<entry>If this Connector is being used in a proxy configuration, configure this attribute to specify the server name to be returned for calls to request.getServerName().</entry>
+ </row>
+ <row>
<entry>proxyPort</entry>
<entry>If this Connector is being used in a proxy configuration, configure this attribute to specify the server port to be returned for calls to request.getServerPort().</entry>
+ </row>
+ <row>
<entry>restrictedUserAgents</entry>
<entry>The value is a comma separated list of regular expressions matching user-agents of HTTP clients for which HTTP/1.1 or HTTP/1.0 keep alive should not be used, even if the clients advertise support for these features. The default value is an empty String (regexp matching disabled).</entry>
+ </row>
+ <row>
<entry>scheme</entry>
<entry>Set this attribute to the name of the protocol you wish to have returned by calls to request.getScheme(). For example, you would set this attribute to "https" for an SSL Connector. The default value is "http".</entry>
+ </row>
+ <row>
<entry>secure</entry>
<entry>Set this attribute to true if you wish to have calls to request.isSecure() to return true for requests received by this Connector (you would want this on an SSL Connector). The default value is false.</entry>
+ </row>
+ <row>
<entry>sendfileSize</entry>
<entry>Amount of sockets that the poller responsible for sending static files asynchronously can hold at a given time. Extra connections will be closed right away without any data being sent (resulting in a zero length file on the client side). Note that in most cases, sendfile is a call that will return right away (being taken care of "synchonously" by the kernel), and the sendfile poller will not be used, so the amount of static files which can be sent concurrently is much larger than the specified amount. The default value is 256.</entry>
+ </row>
+ <row>
<entry>server</entry>
<entry>The Server header for the http response. Unless your paranoid, you won't need this feature.</entry>
+ </row>
+ <row>
<entry>tcpNoDelay</entry>
<entry>If set to true, the TCP_NO_DELAY option will be set on the server socket, which improves performance under most circumstances. This is set to true by default.</entry>
+ </row>
+ <row>
<entry>threadPriority</entry>
<entry>The priority of the request processing threads within the JVM. The default value is java.lang.Thread#NORM_PRIORITY. See the JavaDoc for the java.lang.Thread class for more details on what this priority means.</entry>
+ </row>
+ <row>
<entry>URIEncoding</entry>
<entry>This specifies the character encoding used to decode the URI bytes, after %xx decoding the URL. If not specified, ISO-8859-1 will be used.</entry>
+ </row>
+ <row>
<entry>useBodyEncodingForURI</entry>
<entry>This specifies if the encoding specified in contentType should be used for URI query parameters, instead of using the URIEncoding. This setting is present for compatibility with Tomcat 4.1.x, where the encoding specified in the contentType, or explicitely set using Request.setCharacterEncoding method was also used for the parameters from the URL. The default value is false.</entry>
+ </row>
+ <row>
<entry>useIPVHosts</entry>
<entry>Set this attribute to true to cause JBoss Web to use the IP address that the request was recieved on to determine the Host to send the request to. The default value is false.</entry>
+ </row>
+ <row>
<entry>useSendfile</entry>
<entry>Use kernel level sendfile for certain static files. The default value is true.</entry>
+ </row>
+ <row>
<entry>xpoweredBy</entry>
<entry>Set this attribute to true to cause JBoss Web to advertise support for the Servlet specification using the header recommended in the specification. The default value is false.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ </section>
+
+ <section>
+ <title>The HTTPS Connector</title>
+
+ <para> When APR is enabled, the HTTPS connector will use a socket poller for keepalive, increasing scalability of the server. It also uses OpenSSL, which may be more optimized than JSSE depending on the processor being used, and can be complemented with many commercial accelerator components. Unlike the HTTP connector, the HTTPS connector cannot use sendfile to optimize static file processing.</para>
+
+ <para>The HTTPS APR connector has the same basic attributes than the HTTP APR connector, but adds OpenSSL specific ones. For instance, here is an example of the HTTPS connector:</para>
+
+ <programlisting>
+<<Connector port="443" maxHttpHeaderSize="8192"
maxThreads="50" enableLookups="false"
+ disableUploadTimeout="true"
acceptCount="100" scheme="https" secure="true"
SSLEngine="on"
SSLCertificateFile="${catalina.base}/conf/localhost.crt"
SSLCertificateKeyFile="${catalina.base}/conf/localhost.key" />
+ </programlisting>
+
+
+ <para>For the full details on using OpenSSL, please refer to OpenSSL documentations and the many books available for it (see the Official OpenSSL website). The SSL specific attributes for the connector are listed in the following table.</para>
+
+ <table>
+ <title>Attributes in the HTTPS Connector</title>
<tgroup cols="2" >
<colspec colnum="1" colname="col1" colwidth="1*"/>
<colspec colnum="2" colname="col2" colwidth="1*"/>
+
+ <thead>
<row>
<entry>Attribute</entry>
<entry>Description</entry>
</row>
</thead>
+
<tbody>
<row>
<entry>SSLEngine</entry>
<entry>Name of the SSLEngine to use. off: Do not use SSL, on: Use SSL but no specific ENGINE. The default value is off.</entry>
+ </row>
+ <row>
<entry>SSLProtocol</entry>
<entry>Protocol which may be used for communicating with clients. The default is "all", with other acceptable values being "SSLv2", "SSLv3", "TLSv1", and "SSLv2+SSLv3".</entry>
+ </row>
+ <row>
<entry>SSLCipherSuite</entry>
<entry> Ciphers which may be used for communicating with clients. The default is "ALL", with other acceptable values being a list of ciphers, with ":" used as the delimiter (see OpenSSL documentation for the list of ciphers supported).</entry>
+ </row>
+ <row>
<entry>SSLCertificateFile</entry>
<entry> Name of the file that contains the server certificate. The format is PEM-encoded.</entry>
+ </row>
+ <row>
<entry>SSLCertificateKeyFile</entry>
<entry> Name of the file that contains the server private key. The format is PEM-encoded. The default value is the value of "SSLCertificateFile" and in this case both certificate and private key have to be in this file (NOT RECOMMENDED).</entry>
+ </row>
+ <row>
<entry>SSLPassword</entry>
<entry> Pass phrase for the encrypted private key. If "SSLPassword" is not provided, the callback fonction should prompt for the pass phrase.</entry>
+ </row>
+ <row>
<entry>SSLVerifyClient</entry>
<entry> Ask client for certificate. The default is "none", meaning the client will not have the opportunity to submit a certificate. Other acceptable values include "optional", "require" and "optionalNoCA".</entry>
+ </row>
+ <row>
<entry>SSLVerifyDepth</entry>
<entry> Maximum verification depth for client certificates. The default is "10".</entry>
+ </row>
+ <row>
<entry>SSLCACertificateFile</entry>
<entry> See the <ulink url="http://httpd.apache.org/docs/2.2/mod/mod_ssl.html">mod_ssl documentation</ulink></entry>
+ </row>
+ <row>
<entry>SSLCACertificatePath</entry>
<entry>See the <ulink url="http://httpd.apache.org/docs/2.2/mod/mod_ssl.html">mod_ssl documentation</ulink></entry>
+ </row>
+ <row>
<entry>SSLCertificateChainFile</entry>
<entry>See the <ulink url="http://httpd.apache.org/docs/2.2/mod/mod_ssl.html">mod_ssl documentation</ulink></entry>
+ </row>
+ <row>
<entry>SSLCARevocationFile</entry>
<entry>See the <ulink url="http://httpd.apache.org/docs/2.2/mod/mod_ssl.html">mod_ssl documentation</ulink></entry>
+ </row>
+ <row>
<entry>SSLCARevocationPath</entry>
<entry>See the <ulink url="http://httpd.apache.org/docs/2.2/mod/mod_ssl.html">mod_ssl documentation</ulink></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ </section>
+
+ <section>
+ <title>The AJP Connector</title>
+
+ <para>The AJP connector is used for machine-to-machine communication. If another server (e.g., an Apache web server or a load balancer) needs to access services on JBoss Web Server, it can use the AJP connector. It is more efficient than the HTTP connector, which targets web browsers.</para>
+
+ <para> The AJP connector uses a socket poller for keepalive, increasing scalability of the server. As AJP is designed around a pool of persistent (or almost persistent) connections, this will reduce significantly the amount of processing threads needed by JBoss Web. Unlike the HTTP connector, the AJP connector cannot use sendfile to optimize static file processing. The following attributes are supported in the AJP connector</para>
+
+
+
+ </section>
+
+ <section>
+ <title></title>
+ <para></para>
+ </section>
+
+</chapter>
\ No newline at end of file
Added: labs/jbossweb/trunk/docbook/usersguide/en/modules/gettingstarted.xml
===================================================================
--- labs/jbossweb/trunk/docbook/usersguide/en/modules/gettingstarted.xml 2006-07-14 21:04:47 UTC (rev 5104)
+++ labs/jbossweb/trunk/docbook/usersguide/en/modules/gettingstarted.xml 2006-07-14 21:41:46 UTC (rev 5105)
@@ -0,0 +1,81 @@
+<chapter id="gettingstarted">
+
+ <title>Getting Started</title>
+
+ <para>In this chapter, we will cover the steps to install the JBoss Web Server and deploy Java EE applications on it. If you are interested in running PHP, CGI, and ASP.Net applications on JBoss Web, please refer to <xref linkend=""/>, <xref linkend=""/>, and <xref linkend=""/> respectively.</para>
+
+ <section>
+ <title>Download Software</title>
+
+ <para>JBoss Web is distributed as a standalone webserver running on top of the JBoss 4 microkernel. The distribution can be downloaded directly from the <ulink url="http://labs.jboss.com/portal/jbossweb/downloads">JBoss Web downloads page</ulink>. JBoss Web is not pure Java. It contains native code, compiled and optimized for each operating operating system. Download the package appropriate for your platform, paying particular attention to whether or not you are running on the 64-bit system.</para>
+
+ <para>Uncompress the distribution wherever you would like JBoss Web installed. The resulting directory (jbossweb-4.0.4beta-linux-i686, for example) contains the JBoss Web instance. </para>
+ </section>
+
+ <section>
+ <title>Runnning JBoss Web</title>
+
+ <para> Because JBoss Web is running on the JBoss Microkernel, it can be started like any JBoss AS instance. Before starting, make sure that your JAVA_HOME environment variable is set to your Java install directory. From the bin directory, run the run.bat or run.sh script, as is appropriate for your platform. If you run this from a shell, you will see the JBoss console log scroll by. If JBoss Web started correctly, the last few lines of output should look like the following:</para>
+
+ <programlisting>
16:33:10,684 INFO [Http11AprProtocol] Starting Coyote HTTP/1.1 on http-172.16.129.72-8080
+16:33:10,727 INFO [AjpAprProtocol] Starting Coyote AJP/1.3 on ajp-172.16.129.72-8009
+16:33:10,738 INFO [Server] JBoss (MX MicroKernel) [4.0.4RC1 (build: CVSTag=JBoss_4_0_4_RC1 date=200602071519)] Started in 16s:128ms
+ </programlisting>
<para>The last line is the message JBoss sends when all services are up and running, letting you know that everything is good. However, the two lines before it are important for JBoss Web. They tell you that JBoss Web is listening on two ports, 8080 and 8009. More importantly, you can see from the output that JBoss Web is using the APR(Apache portable runtime) libraries. This means that you are using the optimized native libraries. Without the APR libraries, you would see output more like the following, with no reference to the APR code.</para>
+
+ <programlisting>
16:47:40,154 INFO [Http11BaseProtocol] Starting Coyote HTTP/1.1 on http-0.0.0.0-8080
+16:47:40,914 INFO [ChannelSocket] JK: ajp13 listening on /0.0.0.0:8009
+16:47:41,064 INFO [JkMain] Jk running ID=0 time=0/299 config=null
+ </programlisting>
<para>In worse cases, like using the wrong version of the libraries for your platform, JBoss Web may completely fail to start. If there is an error, check the console log (the output in your terminal window) or the server log in server/default/log/server.log for more information about the problem.</para>
<para>To access your JBoss Web instance, go to http://localhost:8080/ in your web browser. If everything went well, you will see the JBoss Web start welcome screen. Congratulations, your JBoss Web instance is ready to go.</para>
+
+ </section>
+
+ <section>
+ <title>Deploying Web Applications</title>
+
+ <para> Developing web applications on JBoss Web is easy. To deploy a web application, copy the WAR file to the server/default/deploy directory. After a few seconds, JBoss will deploy the web application automatically. The following output shows the log messages after deploying an application named myapp.war.</para>
+
+ <programlisting>
18:03:01,830 INFO [TomcatDeployer] deploy, ctxPath=/myapp,
+warUrl=.../tmp/deploy/tmp53493myapp-exp.war/
+ </programlisting>
<para>The ctxPath value is /myapp, which means the application would immediately be accessible at http://localhost:8080/myapp.</para>
<para>Changes to the application can be made by copying a newer version of the WAR file into the deploy directory. If you need to remove an application, remove the WAR file from the deploy directory. JBoss Web will undeploy the application, noting the fact in the log.</para>
+
+ <programlisting>
18:06:58,086 INFO [TomcatDeployer] undeploy, ctxPath=/myapp,
+warUrl=.../tmp/deploy/tmp53493myapp-exp.war/
+ </programlisting>
+ </section>
+
+ <section>
+ <title>Run JBoss Web as a Windows Service</title>
+
+ <para>JBoss Web comes with Windows service executable that can run JBoss Web Server as service. The service executable jbosssvc.exe transforms the run.bat and shutdown.bat batch scripts to services. This means that any change made to those scripts will be used both in service and command line mode.</para>
+
+ <para>To install the JBoss Web server as Windows service use the provided service.bat batch file.</para>
+
+ <programlisting>
+C:\> cd c:\jbossweb-4.0.4RC1-windows-i586\bin
C:\> service.bat install
+ </programlisting>
+
+ <para>To start the JBoss Web server as Windows service use Control pannel or net start command. When running in service mode the console output is redirected to the file run.log. You can inspect the file for any errors during service startup.</para>
+
+ <programlisting>
+C:\> net start JBossWebServer
The JBoss Web Server 4 service is starting.
The JBoss Web Server 4 service was started successfully.
+ </programlisting>
+
+ <para>To stop the JBoss Web server as Windows service use Control pannel or net stop command. When running in service mode the console output is redirected to the file shutdown.log. You can inspect the file for any errors during service shutdown.</para>
+
+ <programlisting>
+C:\> net stop JBossWebServer
The JBoss Web Server 4 service was stopped successfully.
+ </programlisting>
+
+ <para>To restart the JBoss Web server as Windows service use Control pannel.</para>
+
+ <para>To remove the JBoss Web server as Windows service use the provided service.bat batch file.</para>
+
+ <programlisting>
+C:\> cd c:\jbossweb-4.0.4RC1-windows-i586\bin
C:\> service.bat uninstall
+ </programlisting>
+
+ <para>
Service customization is done by editing the service.bat script. Each command has a separate section that you can customize. The most common customization task would be changing service names if more then one service instances per box are required.</para>
+
+ </section>
+
+</chapter>
\ No newline at end of file
Added: labs/jbossweb/trunk/docbook/usersguide/en/modules/introduction.xml
===================================================================
--- labs/jbossweb/trunk/docbook/usersguide/en/modules/introduction.xml 2006-07-14 21:04:47 UTC (rev 5104)
+++ labs/jbossweb/trunk/docbook/usersguide/en/modules/introduction.xml 2006-07-14 21:41:46 UTC (rev 5105)
@@ -0,0 +1,43 @@
+<chapter id="introduction">
+
+ <title>Introducing JBoss Web</title>
+
+ <para>JBoss Web Server provides enterprises with a single, high-performance deployment platform for Java EE, Microsoft ASP.NET, PHP and CGI script technologies. It is meant to be used as a replacement for the standard Web servers on all major platforms. JBoss Web is built on Apache Tomcat and Apache Portable Runtime (APR) technologies. It brings together the best of both worlds of Java EE servers and native HTTP servers.</para>
+
+ <para>Apache Tomcat is a full Java Servlet and Java Server Pages (JSP) server. It is a very popular Java application server and is the default servlet container inside the JBoss AS 4.x. However, the plain Apache Tomcat does not perform well in many areas, such as in supporting keep-alive connections, static contents, large files, HTTPS etc. JBoss Web solves those performance problems by leveraging a hybrid model with APR and Tomcat native technologies. The hybrid technology model offers the best from threading and event processing models from the latest OS technologies. As a result, JBoss Web server achieves scalability and performance characteristics that match or exceed the native Apache HTTP Server or IIS. For instance, SSL performance in JBoss Web is almost 4 times faster than that in plain Tomcat (<xref linkend="introduction-fig01"/>).</para>
+
+ <figure id="introduction-fig01">
+ <title>SSL benckmark (x86_64 GNU/Linux)</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/introduction-fig01.png" format="PNG"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>Aside from performance issues, another shortcoming of Apache Tomcat is that it is a poor integration platform. Tomcat runs only Java applications. If you want to run PHP/CGI scripts side-by-side with your Java applications, you have to front Tomcat with the Apache Web Server or other native web servers. The APR-based hybrid model in JBoss Web supports both in- and out-of-process execution of CGI and PHP scripts. Furthermore, JBoss Web supports ASP.Net applications, and allows Java applications to access running .Net services and objects.</para>
+
+ <note>
+ <title></title>
+ <para>For Java EE application developers, JBoss Web is a complete replacement for the Apache Web Server + Tomcat + mod_jk stack.</para>
+ </note>
+
+ <para>Key features of the JBoss Web Server are as follows.</para>
+
+ <itemizedlist mark="bullet">
+ <listitem><para>Full Java EE Support: The power of JBoss Web comes with full Java EE support. Inheriting from Apache Tomcat, JBoss Web supports the JSP 2.0 and Servlet 2.4 specifications, providing a complete web development environment. With add-on JSF libraries (e.g., Apache MyFaces) and JBoss embeddable EJB3 libraries, you can deploy full Java EE 5.0 applications in JBoss Web. JBoss Web runs in the same VM as the JBoss application server, providing a complete environment for everything from simple web applications to complex high-end enterprise applications.</para></listitem>
+
+ <listitem><para>Highly Scalable: JBoss Web scales to the levels required by the most demanding of applications. As we discussed, it out-performs Tomcat by several times and matches the performance of the native Apache Web Server and IIS. The hybrid connection model can handle client loads of 10,000+ concurrent connections.</para></listitem>
+
+ <listitem><para>Fast Static Content: JBoss Web takes advantage of fast OS-specific features to achieve zero-copy transfer of static content. This decreases CPU load and improves application responsiveness.</para></listitem>
+
+ <listitem><para>Clustering Support: JBoss Web can serve an amazing number of requests on a single machine, but when you need to scale beyond that, JBoss Web is there. JBoss web offers full clustering support for web applications. JBoss Web HTTP session replication is based on the powerful JBossCache technology, allowing your application state to be efficiently shared between all the nodes in your application cluster.</para></listitem>
+
+ <listitem><para>OpenSSL Support: The security of your web application matters. SSL is the cornerstone of web security, but Java SSL engines are slow and can put a big burden on your CPU. JBossWeb integrates the native OpenSSL libraries, the fastest and most secure open source SSL implementation. The highly-optimized OpenSSL libraries also allow for hardware acceleration which yield a ten fold performance increase.</para></listitem>
+
+ <listitem><para>URL Rewriting: JBoss Web provides a powerful URL rewriting module, similar to Apache mod_rewrite. URLs can be rewritten to support legacy URLs, handle errors or rapidly respond to web application issues that come up in the hectic day-to-day management of web applications.</para></listitem>
+
+ <listitem><para>Integration: JBoss Web Server provides organizations with a single deployment platform for the most common types of web applications. Not only does JBoss Web support the latest Java web technologies, but also JBoss web can also support applications running on Microsoft .NET, PHP, and CGI. There is no longer any need to manage multiple servers for multiple web platforms. Legacy applications can maintained on JBoss Web, right along side your other applications. New development can take advantage of powerful features of any of these web platforms. JBoss Web gives you the power to choose the right platform for each task, and total flexibility to make changes along the way. </para></listitem>
+ </itemizedlist>
+
+</chapter>
More information about the jboss-svn-commits
mailing list