jbossweb-commits September 2011

jbossweb-commits@lists.jboss.org

1 participants
14 discussions

JBossWeb SVN: r1834 - trunk/java/org/apache/coyote/ajp.

by jbossweb-commits＠lists.jboss.org

Author: jfrederic.clere(a)jboss.com Date: 2011-09-09 10:28:58 -0400 (Fri, 09 Sep 2011) New Revision: 1834 Modified: trunk/java/org/apache/coyote/ajp/AjpAprProcessor.java Log: Fix for JBWEB-201. Modified: trunk/java/org/apache/coyote/ajp/AjpAprProcessor.java =================================================================== --- trunk/java/org/apache/coyote/ajp/AjpAprProcessor.java 2011-09-08 16:22:12 UTC (rev 1833) +++ trunk/java/org/apache/coyote/ajp/AjpAprProcessor.java 2011-09-09 14:28:58 UTC (rev 1834) @@ -533,7 +533,7 @@ } } else { recycle(); - return SocketState.CLOSED; + return SocketState.OPEN; } }

12 years, 9 months

1
0
0 / 0

JBossWeb SVN: r1833 - in trunk: webapps/docs and 1 other directory.

by jbossweb-commits＠lists.jboss.org

Author: jfrederic.clere(a)jboss.com Date: 2011-09-08 12:22:12 -0400 (Thu, 08 Sep 2011) New Revision: 1833 Removed: trunk/webapps/docs/jndi-datasource-examples-howto.xml trunk/webapps/docs/jndi-resources-howto.xml Modified: trunk/build.xml trunk/webapps/docs/index.xml trunk/webapps/docs/project.xml Log: remove more old docs. Modified: trunk/build.xml =================================================================== --- trunk/build.xml 2011-09-08 16:06:13 UTC (rev 1832) +++ trunk/build.xml 2011-09-08 16:22:12 UTC (rev 1833) @@ -165,14 +165,6 @@ includes="*.xml"> <param name="relative-path" expression=".."/> </xslt> - <xslt basedir="webapps/docs/architecture" - destdir="${tomcat.build}/webapps/docs/architecture" - extension=".html" - style="webapps/docs/tomcat-docs.xsl" - excludes="project.xml" - includes="*.xml"> - <param name="relative-path" expression=".."/> - </xslt>  <mkdir dir="${tomcat.build}/webapps/docs/printer" /> @@ -229,15 +221,6 @@ <param name="relative-path" expression="../.."/> <param name="project-menu" expression="nomenu"/> </xslt> - <xslt basedir="webapps/docs/architecture" - destdir="${tomcat.build}/webapps/docs/architecture/printer" - extension=".html" - style="webapps/docs/tomcat-docs.xsl" - excludes="project.xml" - includes="*.xml"> - <param name="relative-path" expression="../.."/> - <param name="project-menu" expression="nomenu"/> - </xslt>  <mkdir dir="${jbossweb.site}" /> @@ -314,17 +297,6 @@ <param name="bodyonly" expression="true"/> <param name="usehead" expression="true"/> </xslt> - <xslt basedir="webapps/docs/architecture" - destdir="${jbossweb.site}/architecture" - extension=".html" - style="webapps/docs/tomcat-docs.xsl" - excludes="project.xml" - includes="*.xml"> - <param name="relative-path" expression=".."/> - <param name="project-menu" expression="nomenu"/> - <param name="bodyonly" expression="true"/> - <param name="usehead" expression="true"/> - </xslt> </target> Modified: trunk/webapps/docs/index.xml =================================================================== --- trunk/webapps/docs/index.xml 2011-09-08 16:06:13 UTC (rev 1832) +++ trunk/webapps/docs/index.xml 2011-09-08 16:22:12 UTC (rev 1833) @@ -63,13 +63,6 @@ - Configuring and using a Java Security Manager to support fine-grained control over the behavior of your web applications. </li> -<li><a href="jndi-resources-howto.html">JNDI Resources</a> - - Configuring standard and custom resources in the JNDI naming context - that is provided to each web application.</li> -<li><a href="jndi-datasource-examples-howto.html"> - JDBC DataSource</a> - - Configuring a JNDI DataSoure with a DB connection pool. - Examples for many popular databases.</li> <li><a href="class-loader-howto.html">Classloading</a> - Information about class loading in JBoss Web, including where to place your application classes so that they are visible.</li> Deleted: trunk/webapps/docs/jndi-datasource-examples-howto.xml =================================================================== --- trunk/webapps/docs/jndi-datasource-examples-howto.xml 2011-09-08 16:06:13 UTC (rev 1832) +++ trunk/webapps/docs/jndi-datasource-examples-howto.xml 2011-09-08 16:22:12 UTC (rev 1833) @@ -1,645 +0,0 @@ -<?xml version="1.0"?> -<!DOCTYPE document [ - <!ENTITY project SYSTEM "project.xml"> -]> -<document url="jndi-datasource-examples-howto.html"> - - &project; - - <properties> - <author email="leslie.hughes(a)rubus.com">Les Hughes</author> - <author email="david-tomcat(a)haraburda.com">David Haraburda</author> - <author>Glenn Nielsen</author> - <author email="yoavs(a)apache.org">Yoav Shapira</author> - <title>JNDI Datasource HOW-TO</title> - </properties> - -<body> - -<section name="Table of Contents"> - -<a href="#Introduction">Introduction</a> -<a href="#Database Connection Pool (DBCP) Configurations"> -Database Connection Pool (DBCP) Configurations</a> -<a href="#Non DBCP Solutions">Non DBCP Solutions</a> -<a href="#Oracle 8i with OCI client">Oracle 8i with OCI client</a> -<a href="#Common Problems">Common Problems</a> - -</section> - -<section name="Introduction"> - -JNDI Datasource configuration is covered extensively in the -JNDI-Resources-HOWTO. However, feedback from <code>tomcat-user</code> has -shown that specifics for individual configurations can be rather tricky. - -Here then are some example configurations that have been posted to -tomcat-user for popular databases and some general tips for db useage. - -You should be aware that since these notes are derived from configuration -and/or feedback posted to <code>tomcat-user</code> YMMV :-). Please let us -know if you have any other tested configurations that you feel may be of use -to the wider audience, or if you feel we can improve this section in anyway. - - -Please note that JNDI resource configuration changed somewhat between -Tomcat 5.0.x and Tomcat 5.5.x. You will most likely need to modify older -JNDI resource configurations to match the syntax in the example below in order -to make them work in Tomcat 6.x.x and JBoss Web. - - - -Also, please note that JNDI DataSource configuration in general, and this -tutorial in particular, assumes that you have read and understood the -<a href="config/context.html">Context</a> and -<a href="config/host.html">Host</a> configuration references, including -the section about Automatic Application Deployment in the latter reference. - -</section> - -<section name="Database Connection Pool (DBCP) Configurations"> - -DBCP provides support for JDBC 2.0. On systems using a 1.4 JVM DBCP -will support JDBC 3.0. Please let us know if you have used DBCP and its -JDBC 3.0 features with a 1.4 JVM. - - -See the <a href="http://jakarta.apache.org/commons/dbcp/configuration.html"> -DBCP documentation</a> for a complete list of configuration parameters. - - -<subsection name="Installation"> -DBCP uses the Jakarta-Commons Database Connection Pool. It relies on -number of Jakarta-Commons components: -<ul> -<li>Jakarta-Commons DBCP</li> -<li>Jakarta-Commons Collections</li> -<li>Jakarta-Commons Pool</li> -</ul> -These libraries are located in a single JAR at -<code>$CATALINA_HOME/lib/tomcat-dbcp.jar</code>. However, -only the classes needed for connection pooling have been included, and the -packages have been renamed to avoid interfering with applications. - - -</subsection> - -<subsection name="Preventing dB connection pool leaks"> - - -A database connection pool creates and manages a pool of connections -to a database. Recycling and reusing already existing connections -to a dB is more efficient than opening a new connection. - - - -There is one problem with connection pooling. A web application has -to explicetely close ResultSet's, Statement's, and Connection's. -Failure of a web application to close these resources can result in -them never being available again for reuse, a db connection pool "leak". -This can eventually result in your web application db connections failing -if there are no more available connections. - - -There is a solution to this problem. The Jakarta-Commons DBCP can be -configured to track and recover these abandoned dB connections. Not -only can it recover them, but also generate a stack trace for the code -which opened these resources and never closed them. - - -To configure a DBCP DataSource so that abandoned dB connections are -removed and recycled add the following attribute to the -<code>Resource</code> configuration for your DBCP DataSource: -<source> - removeAbandoned="true" -</source> -When available db connections run low DBCP will recover and recyle -any abandoned dB connections it finds. The default is <code>false</code>. - - - -Use the <code>removeAbandonedTimeout</code> attribute to set the number -of seconds a dB connection has been idle before it is considered abandoned. -<source> - removeAbandonedTimeout="60" -</source> -The default timeout for removing abandoned connections is 300 seconds. - - - -The <code>logAbandoned</code> attribute can be set to <code>true</code> -if you want DBCP to log a stack trace of the code which abandoned the -dB connection resources. -<source> - logAbandoned="true" -</source> -The default is <code>false</code>. - - -</subsection> - -<subsection name="MySQL DBCP Example"> - -<h3>0. Introduction</h3> -Versions of <a href="http://www.mysql.com/products/mysql/index.html">MySQL</a> and JDBC drivers that have been reported to work: -<ul> -<li>MySQL 3.23.47, MySQL 3.23.47 using InnoDB,, MySQL 3.23.58, MySQL 4.0.1alpha</li> -<li><a href="http://www.mysql.com/products/connector-j">Connector/J</a> 3.0.11-stable (the official JDBC Driver)</li> -<li><a href="http://mmmysql.sourceforge.net">mm.mysql</a> 2.0.14 (an old 3rd party JDBC Driver)</li> -</ul> - - -Before you proceed, don't forget to copy the JDBC Driver's jar into <code>$CATALINA_HOME/lib</code>. - -<h3>1. MySQL configuration</h3> - -Ensure that you follow these instructions as variations can cause problems. - - -Create a new test user, a new database and a single test table. -Your MySQL user must have a password assigned. The driver -will fail if you try to connect with an empty password. -<source> -mysql> GRANT ALL PRIVILEGES ON *.* TO javauser@localhost - -> IDENTIFIED BY 'javadude' WITH GRANT OPTION; -mysql> create database javatest; -mysql> use javatest; -mysql> create table testdata ( - -> id int not null auto_increment primary key, - -> foo varchar(25), - -> bar int); -</source> -<blockquote> -Note: the above user should be removed once testing is -complete! -</blockquote> - - -Next insert some test data into the testdata table. -<source> -mysql> insert into testdata values(null, 'hello', 12345); -Query OK, 1 row affected (0.00 sec) - -mysql> select * from testdata; -+----+-------+-------+ -| ID | FOO | BAR | -+----+-------+-------+ -| 1 | hello | 12345 | -+----+-------+-------+ -1 row in set (0.00 sec) - -mysql> -</source> - - -<h3>2. Context configuration</h3> -Configure the JNDI DataSource in JBoss Web by adding a declaration for your -resource to your <a href="config/context.html">Context</a>. -For example: - -<source> -<Context path="/DBTest" docBase="DBTest" - debug="5" reloadable="true" crossContext="true"> - -  - -  - -  - -  - -  - -  - - <Resource name="jdbc/TestDB" auth="Container" type="javax.sql.DataSource" - maxActive="100" maxIdle="30" maxWait="10000" - username="javauser" password="javadude" driverClassName="com.mysql.jdbc.Driver" - url="jdbc:mysql://localhost:3306/javatest?autoReconnect=true"/> - -</Context> -</source> - - -<h3>3. web.xml configuration</h3> - -Now create a <code>WEB-INF/web.xml</code> for this test application. -<source> -<web-app xmlns="http://java.sun.com/xml/ns/j2ee" - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" - xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee -http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd" - version="2.4"> - <description>MySQL Test App</description> - <resource-ref> - <description>DB Connection</description> - <res-ref-name>jdbc/TestDB</res-ref-name> - <res-type>javax.sql.DataSource</res-type> - <res-auth>Container</res-auth> - </resource-ref> -</web-app> -</source> - - -<h3>4. Test code</h3> -Now create a simple <code>test.jsp</code> page for use later. -<source> -<%@ taglib uri="http://java.sun.com/jsp/jstl/sql" prefix="sql" %> -<%@ taglib uri="http://java.sun.com/jsp/jstl/core" prefix="c" %> - -<sql:query var="rs" dataSource="jdbc/TestDB"> -select id, foo, bar from testdata -</sql:query> - -<html> - <head> - <title>DB Test</title> - </head> - <body> - - <h2>Results</h2> - -<c:forEach var="row" items="${rs.rows}"> - Foo ${row.foo} - Bar ${row.bar} -</c:forEach> - - </body> -</html> -</source> - - -That JSP page makes use of <a href="http://java.sun.com/products/jsp/jstl">JSTL</a>'s SQL and Core taglibs. You can get it from Sun's <a href="http://java.sun.com/webservices/downloads/webservicespack.html">Java Web Services Developer Pack</a> or <a href="http://jakarta.apache.org/taglibs/doc/standard-doc/intro.html">Jakarta Taglib Standard 1.1</a> project - just make sure you get a 1.1.x release. Once you have JSTL, copy <code>jstl.jar</code> and <code>standard.jar</code> to your web app's <code>WEB-INF/lib</code> directory. - - - -Finally deploy your web app into <code>$CATALINA_HOME/webapps</code> either -as a warfile called <code>DBTest.war</code> or into a sub-directory called -<code>DBTest</code> -Once deployed, point a browser at -<code>http://localhost:8080/DBTest/test.jsp</code> to view the fruits of -your hard work. - -</subsection> - -<subsection name="Oracle 8i, 9i & 10g"> -<h3>0. Introduction</h3> - -Oracle requires minimal changes from the MySQL configuration except for the -usual gotchas :-) -Drivers for older Oracle versions may be distributed as *.zip files rather -than *.jar files. JBoss Web will only use <code>*.jar</code> files installed in -<code>$CATALINA_HOME/lib</code>. Therefore <code>classes111.zip</code> -or <code>classes12.zip</code> will need to be renamed with a <code>.jar</code> -extension. Since jarfiles are zipfiles, there is no need to unzip and jar these -files - a simple rename will suffice. - -For Oracle 9i onwards you should use <code>oracle.jdbc.OracleDriver</code> -rather than <code>oracle.jdbc.driver.OracleDriver</code> as Oracle have stated -that <code>oracle.jdbc.driver.OracleDriver</code> is deprecated and support -for this driver class will be discontinued in the next major release. - - -<h3>1. Context configuration</h3> -In a similar manner to the mysql config above, you will need to define your -Datasource in your <a href="config/context.html">Context</a>. Here we define a -Datasource called myoracle using the thin driver to connect as user scott, -password tiger to the sid called mysid. (Note: with the thin driver this sid is -not the same as the tnsname). The schema used will be the default schema for the -user scott. - -Use of the OCI driver should simply involve a changing thin to oci in the URL string. -<source> -<Resource name="jdbc/myoracle" auth="Container" - type="javax.sql.DataSource" driverClassName="oracle.jdbc.OracleDriver" - url="jdbc:oracle:thin:@127.0.0.1:1521:mysid" - username="scott" password="tiger" maxActive="20" maxIdle="10" - maxWait="-1"/> -</source> - - -<h3>2. web.xml configuration</h3> -You should ensure that you respect the element ordering defined by the DTD when you -create you applications web.xml file. -<source> -<resource-ref> - <description>Oracle Datasource example</description> - <res-ref-name>jdbc/myoracle</res-ref-name> - <res-type>javax.sql.DataSource</res-type> - <res-auth>Container</res-auth> -</resource-ref> -</source> -<h3>3. Code example</h3> -You can use the same example application as above (asuming you create the required DB -instance, tables etc.) replacing the Datasource code with something like -<source> -Context initContext = new InitialContext(); -Context envContext = (Context)initContext.lookup("java:/comp/env"); -DataSource ds = (DataSource)envContext.lookup("jdbc/myoracle"); -Connection conn = ds.getConnection(); -//etc. -</source> -</subsection> - - -<subsection name="PostgreSQL"> -<h3>0. Introduction</h3> -PostgreSQL is configured in a similar manner to Oracle. - -<h3>1. Required files </h3> - -Copy the Postgres JDBC jar to $CATALINA_HOME/lib. As with Oracle, the -jars need to be in this directory in order for DBCP's Classloader to find -them. This has to be done regardless of which configuration step you take next. - - -<h3>2. Resource configuration</h3> - - -You have two choices here: define a datasource that is shared across all JBoss Web -applications, or define a datasource specifically for one application. - - -<h4>2a. Shared resource configuration</h4> - -Use this option if you wish to define a datasource that is shared across -multiple JBoss Web applications, or if you just prefer defining your datasource -in this file. - -This author has not had success here, although others have reported so. -Clarification would be appreciated here. - -<source> -<Resource name="jdbc/postgres" auth="Container" - type="javax.sql.DataSource" driverClassName="org.postgresql.Driver" - url="jdbc:postgresql://127.0.0.1:5432/mydb" - username="myuser" password="mypasswd" maxActive="20" maxIdle="10" maxWait="-1"/> -</source> -<h4>2b. Application-specific resource configuration</h4> - - -Use this option if you wish to define a datasource specific to your application, -not visible to other JBoss Web applications. This method is less invasive to your -JBoss Web installation. - - - -Create a resource definition for your <a href="config/context.html">Context</a>. -The Context element should look something like the following. - - -<source> -<Context path="/someApp" docBase="someApp" - crossContext="true" reloadable="true" debug="1"> - -<Resource name="jdbc/postgres" auth="Container" - type="javax.sql.DataSource" driverClassName="org.postgresql.Driver" - url="jdbc:postgresql://127.0.0.1:5432/mydb" - username="myuser" password="mypasswd" maxActive="20" maxIdle="10" -maxWait="-1"/> -</Context> -</source> - -<h3>3. web.xml configuration</h3> -<source> -<resource-ref> - <description>postgreSQL Datasource example</description> - <res-ref-name>jdbc/postgres</res-ref-name> - <res-type>javax.sql.DataSource</res-type> - <res-auth>Container</res-auth> -</resource-ref> -</source> - -<h4>4. Accessing the datasource</h4> - -When accessing the datasource programmatically, remember to prepend -<code>java:/comp/env</code> to your JNDI lookup, as in the following snippet of -code. Note also that "jdbc/postgres" can be replaced with any value you prefer, provided -you change it in the above resource definition file as well. - - -<source> -InitialContext cxt = new InitialContext(); -if ( cxt == null ) { - throw new Exception("Uh oh -- no context!"); -} - -DataSource ds = (DataSource) cxt.lookup( "java:/comp/env/jdbc/postgres" ); - -if ( ds == null ) { - throw new Exception("Data source not found!"); -} -</source> - -</subsection> -</section> - -<section name="Non-DBCP Solutions"> - -These solutions either utilise a single connection to the database (not recommended for anything other -than testing!) or some other pooling technology. - -</section> - -<section name="Oracle 8i with OCI client"> -<subsection name="Introduction"> -Whilst not strictly addressing the creation of a JNDI DataSource using the OCI client, these notes can be combined with the -Oracle and DBCP solution above. - -In order to use OCI driver, you should have an Oracle client installed. You should have installed -Oracle8i(8.1.7) client from cd, and download the suitable JDBC/OCI -driver(Oracle8i 8.1.7.1 JDBC/OCI Driver) from <a href="http://otn.oracle.com/">otn.oracle.com</a>. - - -After renaming <code>classes12.zip</code> file to <code>classes12.jar</code> -for JBoss Web, copy it into <code>$CATALINA_HOME/lib</code>. -You may also have to remove the <code>javax.sql.*</code> classes -from this file depending upon the version of JBoss Web and JDK you are using. - -</subsection> - -<subsection name="Putting it all together"> - -Ensure that you have the <code>ocijdbc8.dll</code> or <code>.so</code> in your <code>$PATH</code> or <code>LD_LIBRARY_PATH</code> - (possibly in <code>$ORAHOME\bin</code>) and also confirm that the native library can be loaded by a simple test program -using <code>System.loadLibrary("ocijdbc8");</code> - - -You should next create a simple test servlet or jsp that has these -critical lines: - -<source> -DriverManager.registerDriver(new -oracle.jdbc.driver.OracleDriver()); -conn = -DriverManager.getConnection("jdbc:oracle:oci8:@database","username","password"); -</source> - -where database is of the form <code>host:port:SID</code> Now if you try to access the URL of your -test servlet/jsp and what you get is a -<code>ServletException</code> with a root cause of <code>java.lang.UnsatisfiedLinkError:get_env_handle</code>. - - -First, the <code>UnsatisfiedLinkError</code> indicates that you have -<ul> -<li>a mismatch between your JDBC classes file and -your Oracle client version. The giveaway here is the message stating that a needed library file cannot be -found. For example, you may be using a classes12.zip file from Oracle Version 8.1.6 with a Version 8.1.5 -Oracle client. The classeXXXs.zip file and Oracle client software versions must match. -</li> -<li>A <code>$PATH</code>, <code>LD_LIBRARY_PATH</code> problem.</li> -<li>It has been reported that ignoring the driver you have downloded from otn and using -the classes12.zip file from the directory <code>$ORAHOME\jdbc\lib</code> will also work. -</li> -</ul> - - -Next you may experience the error <code>ORA-06401 NETCMN: invalid driver designator</code> - - -The Oracle documentation says : "Cause: The login (connect) string contains an invalid -driver designator. Action: Correct the string and re-submit." - -Change the database connect string (of the form <code>host:port:SID</code>) with this one: -<code>(description=(address=(host=myhost)(protocol=tcp)(port=1521))(connect_data=(sid=orcl)))</code> - - -Ed. Hmm, I don't think this is really needed if you sort out your TNSNames - but I'm not an Oracle DBA :-) - -</subsection> -</section> - -<section name="Common Problems"> -Here are some common problems encountered with a web application which -uses a database and tips for how to solve them. - -<subsection name="Intermittent dB Connection Failures"> - -JBoss Web runs within a JVM. The JVM periodically performs garbage collection -(GC) to remove java objects which are no longer being used. When the JVM -performs GC execution of code within JBoss Web freezes. If the maximum time -configured for establishment of a dB connection is less than the amount -of time garbage collection took you can get a db conneciton failure. - - -To collect data on how long garbage collection is taking add the -<code>-verbose:gc</code> argument to your <code>CATALINA_OPTS</code> -environment variable when starting JBoss Web. When verbose gc is enabled -your <code>$CATALINA_BASE/logs/catalina.out</code> log file will include -data for every garbage collection including how long it took. - -When your JVM is tuned correctly 99% of the time a GC will take less -than one second. The remainder will only take a few seconds. Rarely, -if ever should a GC take more than 10 seconds. - -Make sure that the db connection timeout is set to 10-15 seconds. -For the DBCP you set this using the parameter <code>maxWait</code>. - -</subsection> - -<subsection name="Random Connection Closed Exceptions"> - -These can occur when one request gets a db connection from the connection -pool and closes it twice. When using a connection pool, closing the -connection just returns it to the pool for reuse by another request, -it doesn't close the connection. And JBoss Web uses multiple threads to -handle concurrent requests. Here is an example of the sequence -of events which could cause this error in JBoss Web: -<pre> - Request 1 running in Thread 1 gets a db connection. - - Request 1 closes the db connection. - - The JVM switches the running thread to Thread 2 - - Request 2 running in Thread 2 gets a db connection - (the same db connection just closed by Request 1). - - The JVM switches the running thread back to Thread 1 - - Request 1 closes the db connection a second time in a finally block. - - The JVM switches the running thread back to Thread 2 - - Request 2 Thread 2 tries to use the db connection but fails - because Request 1 closed it. -</pre> -Here is an example of properly written code to use a db connection -obtained from a connection pool: -<pre> - Connection conn = null; - Statement stmt = null; // Or PreparedStatement if needed - ResultSet rs = null; - try { - conn = ... get connection from connection pool ... - stmt = conn.createStatement("select ..."); - rs = stmt.executeQuery(); - ... iterate through the result set ... - rs.close(); - rs = null; - stmt.close(); - stmt = null; - conn.close(); // Return to connection pool - conn = null; // Make sure we don't close it twice - } catch (SQLException e) { - ... deal with errors ... - } finally { - // Always make sure result sets and statements are closed, - // and the connection is returned to the pool - if (rs != null) { - try { rs.close(); } catch (SQLException e) { ; } - rs = null; - } - if (stmt != null) { - try { stmt.close(); } catch (SQLException e) { ; } - stmt = null; - } - if (conn != null) { - try { conn.close(); } catch (SQLException e) { ; } - conn = null; - } - } -</pre> - - -</subsection> - -<subsection name="Context versus GlobalNamingResources"> - - Please note that although the above instructions place the JNDI declarations in a Context - element, it is possible and sometimes desirable to place these declarations in the - <a href="config/globalresources.html">GlobalNamingResources</a> section of the server - configuration file. A resource placed in the GlobalNamingResources section will be shared - among the Contexts of the server. - -</subsection> - -<subsection name="JNDI Resource Naming and Realm Interaction"> - - In order to get Realms to work, the realm must refer to the datasource as - defined in the <GlobalNamingResources> or <Context> section, not a datasource as renamed - using <ResourceLink>. - -</subsection> - -</section> - -</body> -</document> Deleted: trunk/webapps/docs/jndi-resources-howto.xml =================================================================== --- trunk/webapps/docs/jndi-resources-howto.xml 2011-09-08 16:06:13 UTC (rev 1832) +++ trunk/webapps/docs/jndi-resources-howto.xml 2011-09-08 16:22:12 UTC (rev 1833) @@ -1,764 +0,0 @@ -<?xml version="1.0"?> -<!DOCTYPE document [ - <!ENTITY project SYSTEM "project.xml"> -]> -<document url="jndi-resources-howto.html"> - - &project; - - <properties> - <author email="craigmcc(a)apache.org">Craig R. McClanahan</author> - <author email="yoavs(a)apache.org">Yoav Shapira</author> - <title>JNDI Resources HOW-TO</title> - </properties> - -<body> - - -<section name="Introduction"> - -JBoss Web provides a JNDI InitialContext implementation -instance for each web application running under it, in a manner that is -compatible with those provided by a -<a href="http://java.sun.com/j2ee">Java2 Enterprise Edition</a> application -server. - -The J2EE standard provides a standard set of elements in -the <code>/WEB-INF/web.xml</code> file to reference resources; resources -referenced in these elements must be defined in an application-server-specific configuration. - - -For JBoss Web, these entries in per-web-application -<code>InitialContext</code> are configured in the -<code><Context></code> elements that can be specified -in either <code>$CATALINA_HOME/conf/server.xml</code> or, preferably, -the per-web-application context XML file (either <code>META-INF/context.xml</code>). - - -JBoss Web maintains a separate namespace of global resources for the -entire server. These are configured in the -<a href="config/globalresources.html"> -<code><GlobalNameingResources></code></a> element of -<code>$CATALINA_HOME/conf/server.xml</code>. You may expose these resources to -web applications by using -<code><ResourceLink></code> elements. - - -The resources defined in these elements -may be referenced by the following elements in the web application deployment -descriptor (<code>/WEB-INF/web.xml</code>) of your web application: -<ul> -<li><code><env-entry></code> - Environment entry, a - single-value parameter that can be used to configure how the application - will operate.</li> -<li><code><resource-ref></code> - Resource reference, - which is typically to an object factory for resources such as a JDBC - <code>DataSource</code>, a JavaMail <code>Session</code>, or custom - object factories configured into JBoss Web.</li> -<li><code><resource-env-ref></code> - Resource - environment reference, a new variation of <code>resource-ref</code> - added in Servlet 2.4 that is simpler to configure for resources - that do not require authentication information.</li> -</ul> - -The <code>InitialContext</code> is configured as a web application is -initially deployed, and is made available to web application components (for -read-only access). All configured entries and resources are placed in -the <code>java:comp/env</code> portion of the JNDI namespace, so a typical -access to a resource - in this case, to a JDBC <code>DataSource</code> - -would look something like this: - -<source> -// Obtain our environment naming context -Context initCtx = new InitialContext(); -Context envCtx = (Context) initCtx.lookup("java:comp/env"); - -// Look up our data source -DataSource ds = (DataSource) - envCtx.lookup("jdbc/EmployeeDB"); - -// Allocate and use a connection from the pool -Connection conn = ds.getConnection(); -... use this connection to access the database ... -conn.close(); -</source> - -See the following Specifications for more information about programming APIs -for JNDI, and for the features supported by Java2 Enterprise Edition (J2EE) -servers, which JBoss Web emulates for the services that it provides: -<ul> -<li><a href="http://java.sun.com/products/jndi/#download">Java Naming and - Directory Interface</a> (included in JDK 1.4, available separately for - prior JDK versions)</li> -<li><a href="http://java.sun.com/j2ee/download.html">J2EE Platform - Specification</a> (in particular, see Chapter 5 on Naming)</li> -</ul> - -</section> - - -<section name="Configuring JNDI Resources"> - -Each available JNDI Resource is configured based on inclusion of the -following elements in the <code><Context></code> or -<code><DefaultContext></code> elements: - -<ul> -<li><a href="config/context.html#Environment Entries"><Environment></a> - - Configure names and values for scalar environment entries that will be - exposed to the web application through the JNDI - <code>InitialContext</code> (equivalent to the inclusion of an - <code><env-entry></code> element in the web application - deployment descriptor).</li> -<li><a href="config/context.html#Resource Definitions"><Resource></a> - - Configure the name and data type of a resource made available to the - application (equivalent to the inclusion of a - <code><resource-ref></code> element in the web application - deployment descriptor).</li> -<li><a href="config/context.html#Resource Links"><ResourceLink></a> - - Add a link to a resource defined in the global JNDI context. Use resource - links to give a web application access to a resource defined in - the<a href="config/globalresources.html"><GlobalNamingResources></a> - child element of the <a href="config/server.html"><Server></a> - element.</li> -<li><a href="config/context.html#Transaction"><Transaction></a> - - Add a resource factory for instantiating the UserTransaction object - instance that is available at <code>java:comp/UserTransaction</code>.</li> - -</ul> - -Any number of these elements may be nested inside a -<a href="config/context.html"><Context></a> element (to be associated -only with that particular web application). - -In addition, the names and values of all <code><env-entry></code> -elements included in the web application deployment descriptor -(<code>/WEB-INF/web.xml</code>) are configured into the initial context as -well, overriding corresponding values from <code>conf/server.xml</code> -only if allowed by the corresponding -<code><Environment></code> element (by setting the -<code>override</code> attribute to "true"). - -Global resources can be defined in the server-wide JNDI context, by adding -the resource elements described above to the -<a href="config/globalresources.html"><GlobalNamingResources></a> -child element of the <a href="config/server.html"><Server></a> -element and using a -<a href="config/context.html#Resource Links"><ResourceLink></a> to -include it in the per-web-application context. - -</section> - - -<section name="JBoss Web Standard Resource Factories"> - - JBoss Web includes a series of standard resource factories that can - provide services to your web applications, but give you configuration - flexibility (in <code>$CATALINA_HOME/conf/server.xml</code>) without - modifying the web application or the deployment descriptor. Each - subsection below details the configuration and usage of the standard - resource factories. - - See <a href="#Adding Custom Resource Factories">Adding Custom - Resource Factories</a> for information about how to create, install, - configure, and use your own custom resource factory classes with - JBoss Web. - - NOTE - Of the standard resource factories, only the - "JDBC Data Source" and "User Transaction" factories are mandated to - be available on other platforms, and then they are required only if - the platform implements the Java2 Enterprise Edition (J2EE) specs. - All other standard resource factories, plus custom resource factories - that you write yourself, are specific to JBoss Web and cannot be assumed - to be available on other containers. - - <subsection name="Generic JavaBean Resources"> - - <h3>0. Introduction</h3> - - This resource factory can be used to create objects of any - Java class that conforms to standard JavaBeans naming conventions (i.e. - it has a zero-arguments constructor, and has property setters that - conform to the setFoo() naming pattern. The resource factory will - create a new instance of the appropriate bean class every time a - <code>lookup()</code> for this entry is made. - - The steps required to use this facility are described below. - - <h3>1. Create Your JavaBean Class</h3> - - Create the JavaBean class which will be instantiated each time - that the resource factory is looked up. For this example, assume - you create a class <code>com.mycompany.MyBean</code>, which looks - like this: - -<source> -package com.mycompany; - -public class MyBean { - - private String foo = "Default Foo"; - - public String getFoo() { - return (this.foo); - } - - public void setFoo(String foo) { - this.foo = foo; - } - - private int bar = 0; - - public int getBar() { - return (this.bar); - } - - public void setBar(int bar) { - this.bar = bar; - } - - -} -</source> - - <h3>2. Declare Your Resource Requirements</h3> - - Next, modify your web application deployment descriptor - (<code>/WEB-INF/web.xml</code>) to declare the JNDI name under which - you will request new instances of this bean. The simplest approach is - to use a <code><resource-env-ref></code> element, like this: - -<source> -<resource-env-ref> - <description> - Object factory for MyBean instances. - </description> - <resource-env-ref-name> - bean/MyBeanFactory - </resource-env-ref-name> - <resource-env-ref-type> - com.mycompany.MyBean - </resource-env-ref-type> -</resource-env-ref> -</source> - - WARNING - Be sure you respect the element ordering - that is required by the DTD for web application deployment descriptors! - See the - <a href="http://java.sun.com/products/servlet/download.html">Servlet - Specification</a> for details. - - <h3>3. Code Your Application's Use Of This Resource</h3> - - A typical use of this resource environment reference might look - like this: - -<source> -Context initCtx = new InitialContext(); -Context envCtx = (Context) initCtx.lookup("java:comp/env"); -MyBean bean = (MyBean) envCtx.lookup("bean/MyBeanFactory"); - -writer.println("foo = " + bean.getFoo() + ", bar = " + - bean.getBar()); -</source> - - <h3>4. Configure JBoss Web's Resource Factory</h3> - - To configure JBoss Web's resource factory, add an elements like this to the - <code>$CATALINA_HOME/conf/server.xml</code> file, nested inside the - <code>Context</code> element for this web application. -<source> -<Context ...> - ... - <Resource name="bean/MyBeanFactory" auth="Container" - type="com.mycompany.MyBean" - factory="org.apache.naming.factory.BeanFactory" - bar="23"/> - ... -</Context> -</source> - - Note that the resource name (here, <code>bean/MyBeanFactory</code> - must match the value specified in the web application deployment - descriptor. We are also initializing the value of the <code>bar</code> - property, which will cause <code>setBar(23)</code> to be called before - the new bean is returned. Because we are not initializing the - <code>foo</code> property (although we could have), the bean will - contain whatever default value is set up by its constructor. - - </subsection> - - - <subsection name="JavaMail Sessions"> - - <h3>0. Introduction</h3> - - In many web applications, sending electronic mail messages is a - required part of the system's functionality. The - <a href="http://java.sun.com/products/javamail">Java Mail</a> API - makes this process relatively straightforward, but requires many - configuration details that the client application must be aware of - (including the name of the SMTP host to be used for message sending). - - JBoss Web includes a standard resource factory that will create - <code>javax.mail.Session</code> session instances for you, already - connected to the SMTP server that is configured in <code>server.xml</code>. - In this way, the application is totally insulated from changes in the - email server configuration environment - it simply asks for, and receives, - a preconfigured session whenever needed. - - The steps required for this are outlined below. - - <h3>1. Declare Your Resource Requirements</h3> - - The first thing you should do is modify the web application deployment - descriptor (<code>/WEB-INF/web.xml</code>) to declare the JNDI name under - which you will look up preconfigured sessions. By convention, all such - names should resolve to the <code>mail</code> subcontext (relative to the - standard <code>java:comp/env</code> naming context that is the root of - all provided resource factories. A typical <code>web.xml</code> entry - might look like this: -<source> -<resource-ref> - <description> - Resource reference to a factory for javax.mail.Session - instances that may be used for sending electronic mail - messages, preconfigured to connect to the appropriate - SMTP server. - </description> - <res-ref-name> - mail/Session - </res-ref-name> - <res-type> - javax.mail.Session - </res-type> - <res-auth> - Container - </res-auth> -</resource-ref> -</source> - - WARNING - Be sure you respect the element ordering - that is required by the DTD for web application deployment descriptors! - See the - <a href="http://java.sun.com/products/servlet/download.html">Servlet - Specification</a> for details. - - <h3>2. Code Your Application's Use Of This Resource</h3> - - A typical use of this resource reference might look like this: -<source> -Context initCtx = new InitialContext(); -Context envCtx = (Context) initCtx.lookup("java:comp/env"); -Session session = (Session) envCtx.lookup("mail/Session"); - -Message message = new MimeMessage(session); -message.setFrom(new InternetAddress(request.getParameter("from")); -InternetAddress to[] = new InternetAddress[1]; -to[0] = new InternetAddress(request.getParameter("to")); -message.setRecipients(Message.RecipientType.TO, to); -message.setSubject(request.getParameter("subject")); -message.setContent(request.getParameter("content"), "text/plain"); -Transport.send(message); -</source> - - Note that the application uses the same resource reference name - that was declared in the web application deployment descriptor. This - is matched up against the resource factory that is configured in - <code>$CATALINA_HOME/conf/server.xml</code>, as described below. - - <h3>3. Configure JBoss Web's Resource Factory</h3> - - To configure JBoss Web's resource factory, add an elements like this to the - <code>$CATALINA_HOME/conf/server.xml</code> file, nested inside the - <code>Context</code> element for this web application. -<source> -<Context ...> - ... - <Resource name="mail/Session" auth="Container" - type="javax.mail.Session" - mail.smtp.host="localhost"/> - ... -</Context> -</source> - - Note that the resource name (here, <code>mail/Session</code>) must - match the value specified in the web application deployment descriptor. - Customize the value of the <code>mail.smtp.host</code> parameter to - point at the server that provides SMTP service for your network. - - <h3>4. Install the JavaMail libraries</h3> - - <a href="http://java.sun.com/products/javamail/downloads/index.html" target="_blank"> - Download the JavaMail API</a>. The JavaMail API requires the Java Activation - Framework (JAF) API as well. The Java Activation Framework can be downloaded - from <a href="http://java.sun.com/products/javabeans/glasgow/jaf.html">Sun's site</a>. - - - This download includes 2 vital libraries for the configuration; - activation.jar and mail.jar. Unpackage both distributions and place - them into $CATALINA_HOME/lib so that they are available to - JBoss Web during the initialization of the mail Session Resource. - Note: placing these jars in both common/lib and a - web application's lib folder will cause an error, so ensure you have - them in the $CATALINA_HOME/lib location only. - - - <h3>Example Application</h3> - - The <code>/examples</code> application included with JBoss Web contains - an example of utilizing this resource factory. It is accessed via the - "JSP Examples" link. The source code for the servlet that actually - sends the mail message is in - <code>/WEB-INF/classes/SendMailServlet.java</code>. - - WARNING - The default configuration assumes that - there is an SMTP server listing on port 25 on <code>localhost</code>. - If this is not the case, edit the - <code>$CATALINA_HOME/conf/server.xml</code> file, and modify the - parameter value for the <code>mail.smtp.host</code> parameter to be - the host name of an SMTP server on your network. - - </subsection> - - <subsection name="JDBC Data Sources"> - - <h3>0. Introduction</h3> - - Many web applications need to access a database via a JDBC driver, - to support the functionality required by that application. The J2EE - Platform Specification requires J2EE Application Servers to make - available a DataSource implementation (that is, a connection - pool for JDBC connections) for this purpose. JBoss Web offers exactly - the same support, so that database-based applications you develop on - JBoss Web using this service will run unchanged on any J2EE server. - - For information about JDBC, you should consult the following: - <ul> - <li><a href="http://java.sun.com/products/jdbc/">http://java.sun.com/products/jdbc/</a> - - Home page for information about Java Database Connectivity.</li> - <li><a href="http://java.sun.com/j2se/1.3/docs/guide/jdbc/spec2/jdbc2.1.frame.html">http://java.sun.com/j2se/1.3/docs/guide/jdbc/spec2/jdbc2.1.frame.html</a> - - The JDBC 2.1 API Specification.</li> - <li><a href="http://java.sun.com/products/jdbc/jdbc20.stdext.pdf">http://java.sun.com/products/jdbc/jdbc20.stdext.pdf</a> - - The JDBC 2.0 Standard Extension API (including the - <code>javax.sql.DataSource</code> API). This package is now known - as the "JDBC Optional Package".</li> - <li><a href="http://java.sun.com/j2ee/download.html">http://java.sun.com/j2ee/download.html</a> - - The J2EE Platform Specification (covers the JDBC facilities that - all J2EE platforms must provide to applications).</li> - </ul> - - NOTE - The default data source support in JBoss Web - is based on the DBCP connection pool from the - <a href="http://jakarta.apache.org/commons">Jakarta Commons</a> - subproject. However, it is possible to use any other connection pool - that implements <code>javax.sql.DataSource</code>, by writing your - own custom resource factory, as described - <a href="#Adding Custom Resource Factories">below</a>. - - <h3>1. Install Your JDBC Driver</h3> - - Use of the JDBC Data Sources JNDI Resource Factory requires - that you make an appropriate JDBC driver available to both JBoss Web internal - classes and to your web application. This is most easily accomplished by - installing the driver's JAR file(s) into the - <code>$CATALINA_HOME/lib</code> directory, which makes the driver - available both to the resource factory and to your application. - - <h3>2. Declare Your Resource Requirements</h3> - - Next, modify the web application deployment descriptor - (<code>/WEB-INF/web.xml</code>) to declare the JNDI name under - which you will look up preconfigured data source. By convention, all such - names should resolve to the <code>jdbc</code> subcontext (relative to the - standard <code>java:comp/env</code> naming context that is the root of - all provided resource factories. A typical <code>web.xml</code> entry - might look like this: -<source> -<resource-ref> - <description> - Resource reference to a factory for java.sql.Connection - instances that may be used for talking to a particular - database that is configured in the server.xml file. - </description> - <res-ref-name> - jdbc/EmployeeDB - </res-ref-name> - <res-type> - javax.sql.DataSource - </res-type> - <res-auth> - Container - </res-auth> -</resource-ref> -</source> - - WARNING - Be sure you respect the element ordering - that is required by the DTD for web application deployment descriptors! - See the - <a href="http://java.sun.com/products/servlet/download.html">Servlet - Specification</a> for details. - - <h3>3. Code Your Application's Use Of This Resource</h3> - - A typical use of this resource reference might look like this: -<source> -Context initCtx = new InitialContext(); -Context envCtx = (Context) initCtx.lookup("java:comp/env"); -DataSource ds = (DataSource) - envCtx.lookup("jdbc/EmployeeDB"); - -Connection conn = ds.getConnection(); -... use this connection to access the database ... -conn.close(); -</source> - - Note that the application uses the same resource reference name - that was declared in the web application deployment descriptor. This - is matched up against the resource factory that is configured in - <code>$CATALINA_HOME/conf/server.xml</code>, as described below. - - <h3>4. Configure JBoss Web's Resource Factory</h3> - - To configure JBoss Web's resource factory, add an element like this to the - <code>/META-INF/context.xml</code> file in the web application. -<source> -<Context ...> - ... - <Resource name="jdbc/EmployeeDB" auth="Container" - type="javax.sql.DataSource" username="dbusername" password="dbpassword" - driverClassName="org.hsql.jdbcDriver" url="jdbc:HypersonicSQL:database" - maxActive="8" maxIdle="4"/> - ... -</Context> -</source> - - Note that the resource name (here, <code>jdbc/EmployeeDB</code>) must - match the value specified in the web application deployment descriptor. - - This example assumes that you are using the HypersonicSQL database - JDBC driver. Customize the <code>driverClassName</code> and - <code>driverName</code> parameters to match your actual database's - JDBC driver and connection URL. - - The configuration properties for JBoss Web's standard data source - resource factory - (<code>org.apache.tomcat.dbcp.dbcp.BasicDataSourceFactory</code>) are - as follows: - <ul> - <li>driverClassName - Fully qualified Java class name - of the JDBC driver to be used.</li> - <li>maxActive - The maximum number of active instances - that can be allocated from this pool at the same time.</li> - <li>maxIdle - The maximum number of connections that - can sit idle in this pool at the same time.</li> - <li>maxWait - The maximum number of milliseconds that the - pool will wait (when there are no available connections) for a - connection to be returned before throwing an exception.</li> - <li>password - Database password to be passed to our - JDBC driver.</li> - <li>url - Connection URL to be passed to our JDBC driver. - (For backwards compatibility, the property <code>driverName</code> - is also recognized.)</li> - <li>user - Database username to be passed to our - JDBC driver.</li> - <li>validationQuery - SQL query that can be used by the - pool to validate connections before they are returned to the - application. If specified, this query MUST be an SQL SELECT - statement that returns at least one row.</li> - </ul> - For more details, please refer to the commons-dbcp documentation. - - </subsection> - -</section> - - -<section name="Adding Custom Resource Factories"> - - If none of the standard resource factories meet your needs, you can - write your own factory and integrate it into JBoss Web, and then configure - the use of this factory in the <code>conf/server.xml</code> configuration - file. In the example below, we will create a factory that only knows how - to create <code>com.mycompany.MyBean</code> beans, from the - <a href="#Generic JavaBean Resources">Generic JavaBean Resources</a> - example, above. - - <h3>1. Write A Resource Factory Class</h3> - - You must write a class that implements the JNDI service provider - <code>javax.naming.spi.ObjectFactory</code> inteface. Every time your - web application calls <code>lookup()</code> on a context entry that is - bound to this factory, the <code>getObjectInstance()</code> method is - called, with the following arguments: - <ul> - <li>Object obj - The (possibly null) object containing - location or reference information that can be used in creating an - object. For JBoss Web, this will always be an object of type - <code>javax.naming.Reference</code>, which contains the class name - of this factory class, as well as the configuration properties - (from <code>conf/server.xml</code>) to use in creating objects - to be returned.</li> - <li>Name name - The name to which this factory is bound - relative to <code>nameCtx</code>, or <code>null</code> if no name - is specified.</li> - <li>Context nameCtx - The context relative to which the - <code>name</code> parameter is specified, or <code>null</code> if - <code>name</code> is relative to the default initial context.</li> - <li>Hashtable environment - The (possibly null) - environment that is used in creating this object. This is generally - ignored in JBoss Web object factories.</li> - </ul> - - To create a resource factory that knows how to produce <code>MyBean</code> - instances, you might create a class like this: - -<source> -package com.mycompany; - -import java.util.Enumeration; -import java.util.Hashtable; -import javax.naming.Context; -import javax.naming.Name; -import javax.naming.NamingException; -import javax.naming.RefAddr; -import javax.naming.Reference; -import javax.naming.spi.ObjectFactory; - -public class MyBeanFactory implements ObjectFactory { - - public Object getObjectInstance(Object obj, - Name name, Context nameCtx, Hashtable environment) - throws NamingException { - - // Acquire an instance of our specified bean class - MyBean bean = new MyBean(); - - // Customize the bean properties from our attributes - Reference ref = (Reference) obj; - Enumeration addrs = ref.getAll(); - while (addrs.hasMoreElements()) { - RefAddr addr = (RefAddr) addrs.nextElement(); - String name = addr.getType(); - String value = (String) addr.getContent(); - if (name.equals("foo")) { - bean.setFoo(value); - } else if (name.equals("bar")) { - try { - bean.setBar(Integer.parseInt(value)); - } catch (NumberFormatException e) { - throw new NamingException("Invalid 'bar' value " + value); - } - } - } - - // Return the customized instance - return (bean); - - } - -} -</source> - - In this example, we are unconditionally creating a new instance of - the <code>com.mycompany.MyBean</code> class, and populating its properties - based on the parameters included in the <code><ResourceParams></code> - element that configures this factory (see below). You should note that any - parameter named <code>factory</code> should be skipped - that parameter is - used to specify the name of the factory class itself (in this case, - <code>com.mycompany.MyBeanFactory</code>) rather than a property of the - bean being configured. - - For more information about <code>ObjectFactory</code>, see the - <a href="http://java.sun.com/products/jndi/docs.html">JNDI 1.2 Service - Provider Interface (SPI) Specification</a>. - - You will need to compile this class against a class path that includes - all of the JAR files in the <code>$CATALINA_HOME/lib</code> directory. When you are through, - place the factory class (and the corresponding bean class) unpacked under - <code>$CATALINA_HOME/lib</code>, or in a JAR file inside - <code>$CATALINA_HOME/lib</code>. In this way, the required class - files are visible to both Catalina internal resources and your web - application. - - <h3>2. Declare Your Resource Requirements</h3> - - Next, modify your web application deployment descriptor - (<code>/WEB-INF/web.xml</code>) to declare the JNDI name under which - you will request new instances of this bean. The simplest approach is - to use a <code><resource-env-ref></code> element, like this: - -<source> -<resource-env-ref> - <description> - Object factory for MyBean instances. - </description> - <resource-env-ref-name> - bean/MyBeanFactory - </resource-env-ref-name> - <resource-env-ref-type> - com.mycompany.MyBean - </resource-env-ref-type> -<resource-env-ref> -</source> - - WARNING - Be sure you respect the element ordering - that is required by the DTD for web application deployment descriptors! - See the - <a href="http://java.sun.com/products/servlet/download.html">Servlet - Specification</a> for details. - - <h3>3. Code Your Application's Use Of This Resource</h3> - - A typical use of this resource environment reference might look - like this: - -<source> -Context initCtx = new InitialContext(); -Context envCtx = (Context) initCtx.lookup("java:comp/env"); -MyBean bean = (MyBean) envCtx.lookup("bean/MyBeanFactory"); - -writer.println("foo = " + bean.getFoo() + ", bar = " + - bean.getBar()); -</source> - - <h3>4. Configure JBoss Web's Resource Factory</h3> - - To configure JBoss Web's resource factory, add an elements like this to the - <code>$CATALINA_HOME/conf/server.xml</code> file, nested inside the - <code>Context</code> element for this web application. -<source> -<Context ...> - ... - <Resource name="bean/MyBeanFactory" auth="Container" - type="com.mycompany.MyBean" - factory="com.mycompany.MyBeanFactory" - bar="23"/> - ... -</Context> -</source> - - Note that the resource name (here, <code>bean/MyBeanFactory</code> - must match the value specified in the web application deployment - descriptor. We are also initializing the value of the <code>bar</code> - property, which will cause <code>setBar(23)</code> to be called before - the new bean is returned. Because we are not initializing the - <code>foo</code> property (although we could have), the bean will - contain whatever default value is set up by its constructor. - - You will also note that, from the application developer's perspective, - the declaration of the resource environment reference, and the programming - used to request new instances, is identical to the approach used for the - Generic JavaBean Resources example. This illustrates one of the - advantages of using JNDI resources to encapsulate functionality - you can - change the underlying implementation without necessarily having to - modify applications using the resources, as long as you maintain - compatible APIs. - -</section> - - - -</body> - -</document> Modified: trunk/webapps/docs/project.xml =================================================================== --- trunk/webapps/docs/project.xml 2011-09-08 16:06:13 UTC (rev 1832) +++ trunk/webapps/docs/project.xml 2011-09-08 16:22:12 UTC (rev 1833) @@ -19,8 +19,6 @@ <item name="Deployer" href="deployer-howto.html"/> <item name="Realms and AAA" href="realm-howto.html"/> <item name="Security Manager" href="security-manager-howto.html"/> - <item name="JNDI Resources" href="jndi-resources-howto.html"/> - <item name="JDBC DataSources" href="jndi-datasource-examples-howto.html"/> <item name="Classloading" href="class-loader-howto.html"/> <item name="JSPs" href="jasper-howto.html"/> <item name="SSL" href="ssl-howto.html"/>

12 years, 9 months

1
0
0 / 0

JBossWeb SVN: r1832 - trunk/webapps/docs.

by jbossweb-commits＠lists.jboss.org

Author: jfrederic.clere(a)jboss.com Date: 2011-09-08 12:06:13 -0400 (Thu, 08 Sep 2011) New Revision: 1832 Removed: trunk/webapps/docs/architecture/ trunk/webapps/docs/cgi-howto.xml trunk/webapps/docs/jasper-howto.xml trunk/webapps/docs/manager-howto.xml trunk/webapps/docs/mbeans-descriptor-howto.xml trunk/webapps/docs/php.xml trunk/webapps/docs/realm-howto.xml trunk/webapps/docs/ssi-howto.xml Modified: trunk/webapps/docs/index.xml trunk/webapps/docs/project.xml Log: Remove old TC docs. Deleted: trunk/webapps/docs/cgi-howto.xml =================================================================== --- trunk/webapps/docs/cgi-howto.xml 2011-09-08 14:43:49 UTC (rev 1831) +++ trunk/webapps/docs/cgi-howto.xml 2011-09-08 16:06:13 UTC (rev 1832) @@ -1,76 +0,0 @@ -<?xml version="1.0"?> -<!DOCTYPE document [ - <!ENTITY project SYSTEM "project.xml"> -]> -<document url="cgi-howto.html"> - - &project; - - <properties> - <author email="glenn(a)apache.org">Glenn L. Nielsen</author> - <title>CGI How To</title> - </properties> - -<body> - -<section name="Introduction"> - -The CGI (Common Gateway Interface) defines a way for a web server to -interact with external content-generating programs, which are often -referred to as CGI programs or CGI scripts. - - -Within JBoss Web, CGI support can be added when you are using JBoss Web as your -HTTP server and require CGI support. Typically this is done -during development when you don't want to run a web server like -Apache httpd. -JBoss Web's CGI support is largely compatible with Apache httpd's, -but there are some limitations (e.g., only one cgi-bin directory). - - -CGI support is implemented using the servlet class -<code>org.apache.catalina.servlets.CGIServlet</code>. Traditionally, -this servlet is mapped to the URL pattern "/cgi-bin/*". - -By default CGI support is disabled in JBoss Web. -</section> - -<section name="Installation"> - -CAUTION - CGI scripts are used to execute programs -external to the JBoss Web JVM. If you are using the Java SecurityManager this -will bypass your security policy configuration in <code>catalina.policy.</code> - -Remove the XML comments from around the CGI servlet and servlet-mapping -configuration in <code>$CATALINA_BASE/conf/web.xml</code>. -</section> - -Only Contexts which are marked as privileged may use the CGI servlet (see the -privileged property of the Context element). - -<section name="Configuration"> - -There are several servlet init parameters which can be used to -configure the behaviour of the CGI servlet. -<ul> -<li>cgiPathPrefix - The CGI search path will start at -the web application root directory + File.separator + this prefix. -The default cgiPathPrefix is <code>WEB-INF/cgi</code></li> -<li>debug - Debugging detail level for messages logged -by this servlet. Default 0.</li> -<li>executable - The of the executable to be used to -run the script. Default is <code>perl</code>.</li> -<li>parameterEncoding - Name of the parameter encoding -to be used with the GCI servlet. Default is -<code>System.getProperty("file.encoding","UTF-8")</code>.</li> -<li>passShellEnvironment - Should the shell environment -variables (if any) be passed to the CGI script? Default is -<code>false</code>.</li> -</ul> - - -</section> - -</body> - -</document> Modified: trunk/webapps/docs/index.xml =================================================================== --- trunk/webapps/docs/index.xml 2011-09-08 14:43:49 UTC (rev 1831) +++ trunk/webapps/docs/index.xml 2011-09-08 16:06:13 UTC (rev 1832) @@ -55,9 +55,6 @@ <li><a href="deployer-howto.html">Deployer</a> - Operating the JBoss Web Deployer to deploy, precompile, and validate web applications.</li> -<li><a href="manager-howto.html">Manager</a> - - Operating the <code>Manager</code> web app to deploy, undeploy, and - redeploy applications while JBoss Web is running.</li> <li><a href="realm-howto.html">Realms and Access Control</a> - Description of how to configure Realms (databases of users, passwords, and their associated roles) for use in web applications that @@ -83,19 +80,11 @@ Installing and configuring SSL support so that your JBoss Web will serve requests using the <code>https</code> protocol.</li> -<li><a href="php.html">PHP</a> - - Using PHPs with JBoss Web.</li> -<li><a href="ssi-howto.html">SSI</a> - - Using Server Side Includes in JBoss Web.</li> -<li><a href="cgi-howto.html">CGI</a> - - Using CGIs with JBoss Web.</li> <li><a href="rewrite.html">URL Rewriting</a> - Using rewriting features in JBoss Web.</li> <li><a href="proxy-howto.html">Proxy Support</a> - Configuring JBoss Web to run behind a proxy server (or a web server functioning as a proxy server).</li> -<li><a href="mbeans-descriptor-howto.html">MBean Descriptor</a> - - Configuring MBean descriptors files for custom components.</li> <li><a href="default-servlet.html">Default Servlet</a> - Configuring the default servlet and customizing directory listings.</li> <li><a href="connectors.html">Connectors</a> - Deleted: trunk/webapps/docs/jasper-howto.xml =================================================================== --- trunk/webapps/docs/jasper-howto.xml 2011-09-08 14:43:49 UTC (rev 1831) +++ trunk/webapps/docs/jasper-howto.xml 2011-09-08 16:06:13 UTC (rev 1832) @@ -1,373 +0,0 @@ -<?xml version="1.0"?> - -<!DOCTYPE document [ - <!ENTITY project SYSTEM "project.xml"> -]> -<document url="jasper-howto.html"> - - &project; - - <properties> - <author email="glenn(a)apache.org">Glenn L. Nielsen</author> - <author email="pero(a)apache.org">Peter Rossbach</author> - <title>Jasper 2 JSP Engine How To</title> - </properties> - -<body> - -<section name="Table of Contents"> - -<a href="#Introduction">Introduction</a> -<a href="#Configuration">Configuration</a> -<a href="#Production Configuration">Production Configuration</a> -<a href="#Web Application Compilation">Web Application Compilation</a> -<a href="#Using Jikes">Using Jikes</a> - -</section> - -<section name="Introduction"> - -JBoss Web uses the Jasper 2 JSP Engine to implement -the <a href="http://java.sun.com/products/jsp/">JavaServer Pages 2.0</a> -specification. - -Jasper 2 has been redesigned to significantly improve performance over -the orignal Jasper. In addition to general code improvements the following -changes were made: -<ul> -<li>JSP Custom Tag Pooling - The java objects instantiated -for JSP Custom Tags can now be pooled and reused. This significantly boosts -the performance of JSP pages which use custom tags.</li> -<li>Background JSP compilation - If you make a change to -a JSP page which had already been compiled Jasper 2 can recompile that -page in the background. The previously compiled JSP page will still be -available to serve requests. Once the new page has been compiled -successfully it will replace the old page. This helps improve availablity -of your JSP pages on a production server.</li> -<li>Recompile JSP when included page changes - Jasper 2 -can now detect when a page included at compile time from a JSP has changed -and then recompile the parent JSP.</li> -<li>JDT used to compile JSP pages - The -Eclipse JDT Java compiler is now used to perform JSP java source code -compilation. This compiler loads source dependencies from the container -classloader. Ant and javac can still be used.</li> -</ul> - - -Jasper is implemented using the servlet class -<code>org.apache.jasper.servlet.JspServlet</code>. - -</section> - -<section name="Configuration"> - -By default Jasper is configured for use when doing web application -development. See the section <a href="#Production Configuration"> -Production Configuration</a> for information on configuring Jasper -for use on a production JBoss Web server. - -The servlet which implements Jasper is configured using init parameters -in your global <code>$CATALINA_BASE/conf/web.xml</code>. - -<ul> -<li>checkInterval - If development is false and checkInterval -is greater than zero, background compiles are enabled. checkInterval is the time -in seconds between checks to see if a JSP page (and its dependent files) needs -to be recompiled. Default <code>0</code> seconds.</li> - -<li>classdebuginfo - Should the class file be compiled with -debugging information? <code>true</code> or <code>false</code>, default -<code>true</code>. -</li> - -<li>classpath - Defines the class path to be used to compile -the generated servlets. This parameter only has an effect if the ServletContext -attribute org.apache.jasper.Constants.SERVLET_CLASSPATH is not set. This -attribute is always set when Jasper is used within JBoss Web. By default the -classpath is created dynamically based on the current web application.</li> - -<li>compiler - Which compiler Ant should use to compile JSP -pages. See the Ant documentation for more information. If the value is not set, -then the default Eclipse JDT Java compiler will be used instead of using Ant. -No default value.</li> - -<li>compilerSourceVM - What JDK version are the source files -compatible with? (Default JDK 1.4)</li> - -<li>compilerTargetVM - What JDK version are the generated files -compatible with? (Default JDK 1.4)</li> - -<li>development - Is Jasper used in development mode? If true, -the frequency at which JSPs are checked for modification may be specified via -the modificationTestInterval parameter.<code>true</code> or <code>false</code>, -default <code>true</code>.</li> - -<li>displaySourceFragment - Should a source fragment be -included in exception messages? <code>true</code> or <code>false</code>, -default <code>true</code>.</li> - -<li>dumpSmap - Should the SMAP info for JSR45 debugging be -dumped to a file? <code>true</code> or <code>false</code>, default -<code>false</code>. <code>false</code> if suppressSmap is true.</li> - -<li>enablePooling - Determines whether tag handler pooling is -enabled. <code>true</code> or <code>false</code>, default <code>true</code>. -</li> - -<li>engineOptionsClass - Allows specifying the Options class -used to configure Jasper. If not present, the default EmbeddedServletOptions -will be used. -</li> - -<li>errorOnUseBeanInvalidClassAttribute - Should Jasper issue -an error when the value of the class attribute in an useBean action is not a -valid bean class? <code>true</code> or <code>false</code>, default -<code>true</code>.</li> - -<li>fork - Have Ant fork JSP page compiles so they are -performed in a seperate JVM from Tomcat? <code>true</code> or -<code>false</code>, default <code>true</code>.</li> - -<li>genStringAsCharArray - Should text strings be generated as char -arrays, to improve performance in some cases? Default <code>false</code>.</li> - -<li>ieClassId - The class-id value to be sent to Internet -Explorer when using <jsp:plugin> tags. Default -<code>clsid:8AD9C840-044E-11D1-B3E9-00805F499D93</code>.</li> - -<li>javaEncoding - Java file encoding to use for generating -java source files. Default <code>UTF8</code>.</li> - -<li>keepgenerated - Should we keep the generated Java source -code for each page instead of deleting it? <code>true</code> or -<code>false</code>, default <code>true</code>.</li> - -<li>mappedfile - Should we generate static content with one -print statement per input line, to ease debugging? -<code>true</code> or <code>false</code>, default <code>true</code>.</li> - -<li>modificationTestInterval - Causes a JSP (and its dependent -files) to not be checked for modification during the specified time interval -(in seconds) from the last time the JSP was checked for modification. A value of -0 will cause the JSP to be checked on every access. Used in development mode -only. Default is <code>4</code> seconds.</li> - -<li>scratchdir - What scratch directory should we use when -compiling JSP pages? Default is the work directory for the current web -application.</li> - -<li>suppressSmap - Should the generation of SMAP info for JSR45 -debugging be suppressed? <code>true</code> or <code>false</code>, default -<code>false</code>.</li> - -<li>trimSpaces - Should white spaces in template text between -actions or directives be trimmed ?, default <code>false</code>.</li> - -<li>xpoweredBy - Determines whether X-Powered-By response -header is added by generated servlet. <code>true</code> or <code>false</code>, -default <code>false</code>.</li> -</ul> - - -The Java compiler from Eclipse JDT in included as the default compiler. It is -an advanced Java compiler which will load all dependencies from the Tomcat class -loader, which will help tremendously when compiling on large installations with -tens of JARs. On fast servers, this will allow sub-second recompilation cycles -for even large JSP pages. - -Apache Ant, which was used in previous Tomcat releases, can be used instead -of the new compiler by simply removing the <code>lib/jasper-jdt.jar</code> file, -and placing the <code>ant.jar</code> file from the latest Ant distribution in -the <code>lib</code> folder. If you do this, you also need to use the "javac" -argument to catalina.sh. - -</section> - -<section name="Production Configuration"> - -The main JSP optimization which can be done is precompilation of JSPs. -However, this might not be possible (for example, when using the -jsp-property-group feature) or practical, in which case the configuration of the -Jasper servlet becomes critical. - -When using Jasper 2 in a production JBoss Web server you should consider -making the following changes from the default configuration. -<ul> -<li>development - To disable on access checks for JSP -pages compilation set this to <code>false</code>.</li> -<li>genStringAsCharArray - To generate slightly more efficient -char arrays, set this to <code>true</code>.</li> -<li>modificationTestInterval - If development has to be set to -<code>true</code> for any reason (such as dynamic generation of JSPs), setting -this to a high value will improve performance a lot.</li> -<li>trimSpaces - To remove useless bytes from the response, -set this to <code>true</code>.</li> -</ul> - - -</section> - -<section name="Web Application Compilation"> - -Using Ant is the preferred way to compile web applications using JSPC. -Use the script given below (a similar script is included in the "deployer" -download) to precompile a webapp: - - - -<source> -<project name="Webapp Precompilation" default="all" basedir="."> - - <import file="${tomcat.home}/bin/catalina-tasks.xml"/> - - <target name="jspc"> - - <jasper - validateXml="false" - uriroot="${webapp.path}" - webXmlFragment="${webapp.path}/WEB-INF/generated_web.xml" - outputDir="${webapp.path}/WEB-INF/src" /> - - </target> - - <target name="compile"> - - <mkdir dir="${webapp.path}/WEB-INF/classes"/> - <mkdir dir="${webapp.path}/WEB-INF/lib"/> - - <javac destdir="${webapp.path}/WEB-INF/classes" - optimize="off" - debug="on" failonerror="false" - srcdir="${webapp.path}/WEB-INF/src" - excludes="**/*.smap"> - <classpath> - <pathelement location="${webapp.path}/WEB-INF/classes"/> - <fileset dir="${webapp.path}/WEB-INF/lib"> - <include name="*.jar"/> - </fileset> - <pathelement location="${tomcat.home}/lib"/> - <fileset dir="${tomcat.home}/common/lib"> - <include name="*.jar"/> - </fileset> - <fileset dir="${tomcat.home}/bin"> - <include name="*.jar"/> - </fileset> - </classpath> - <include name="**" /> - <exclude name="tags/**" /> - </javac> - - </target> - - <target name="all" depends="jspc,compile"> - </target> - - <target name="cleanup"> - <delete> - <fileset dir="${webapp.path}/WEB-INF/src"/> - <fileset dir="${webapp.path}/WEB-INF/classes/org/apache/jsp"/> - </delete> - </target> - -</project> -</source> - - - -The following command line can be used to run the script -(replacing the tokens with the JBoss Web base path and the path to the webapp -which should be precompiled): -<source> -$ANT_HOME/bin/ant -Dtomcat.home=<$TOMCAT_HOME> -Dwebapp.path=<$WEBAPP_PATH> -</source> - - - -Then, the declarations and mappings for the servlets which were generated -during the precompilation must be added to the web application deployment -descriptor. Insert the <code>${webapp.path}/WEB-INF/generated_web.xml</code> -at the right place inside the <code>${webapp.path}/WEB-INF/web.xml</code> file. -Restart the web application (using the manager) and test it to verify it is -running fine with precompiled servlets. An appropriate token placed in the -web application deployment descriptor may also be used to automatically -insert the generated servlet declarations and mappings using Ant filtering -capabilities. - - - -At the jasper2 task you can use the option <code>addWebXmlMappings</code> for -automatic merge the <code>${webapp.path}/WEB-INF/generated_web.xml</code> -with the current web application deployment descriptor at -<code>${webapp.path}/WEB-INF/web.xml</code>. When you want to use Java 5 -features inside your jsp's, add the following javac compiler task attributes: -<code>source="1.5" target="1.5"</code>. For live -applications you can also compile with <code>optimize="on"</code> and -without debug info <code>debug="off"</code>. - - - -When you don't want to stop the jsp generation at first jsp syntax error, use -<code>failOnError="false"</code>and with -<code>showSuccess="true"</code> all successfull jsp to java -generation are printed out. Sometimes it is very helpfull, when you cleanup the -generate java source files at <code>${webapp.path}/WEB-INF/src</code> -and the compile jsp servlet classes at -<code>${webapp.path}/WEB-INF/classes/org/apache/jsp</code>. - - -Hints: -<ul> -<li> When you switch to another JBoss Web release, then regenerate and recompile -your jsp's with the new JBoss Web version.</li> -<li>Use java system property at server runtime to disable tag pooling -<code>org.apache.jasper.runtime.JspFactoryImpl.USE_POOL=false</code>. -and limit the buffering with -<code>org.apache.jasper.runtime.BodyContentImpl.LIMIT_BUFFER=true</code>. Note -that changing from the defaults may affect performance, but it will vary -depending on the application.</li> -</ul> - -</section> - -<section name="Using Jikes"> - -If you wish to use -<a href="http://oss.software.ibm.com/developerworks/opensource/jikes/"> -Jikes</a> to compile JSP pages: -<ul> -<li>From your <a href="ant.apache.org">Ant</a> installation, copy ant.jar -and (if it's available: Ant 1.5 and later) ant-launcher.jar to -<code>$CATALINA_HOME/lib</code>.</li> -<li>Download and install jikes. jikes must support the -encoding option. -Execute <code>jikes -help</code> to verify that it was built with support -for <code>-encoding</code>.</li> -<li>Set the init parameter <code>compiler</code> to <code>jikes</code>.</li> -<li>Define the property <code>-Dbuild.compiler.emacs=true</code> when starting -Tomcat by adding it to your <code>CATALINA_OPTS</code> environment variable. -This changes how jikes outputs error messages so that it is compatible with -Jasper.</li> -<li>If you get an error reporting that jikes can't use UTF8 encoding, try -setting the init parameter <code>javaEncoding</code> to -<code>ISO-8859-1</code>.</li> -</ul> - - -</section> -</body> - -</document> Deleted: trunk/webapps/docs/manager-howto.xml =================================================================== --- trunk/webapps/docs/manager-howto.xml 2011-09-08 14:43:49 UTC (rev 1831) +++ trunk/webapps/docs/manager-howto.xml 2011-09-08 16:06:13 UTC (rev 1832) @@ -1,1238 +0,0 @@ -<?xml version="1.0"?> -<!DOCTYPE document [ - <!ENTITY project SYSTEM "project.xml"> -]> -<document url="manager-howto.html"> - - &project; - - <properties> - <author email="craigmcc(a)apache.org">Craig R. McClanahan</author> - <title>Manager App HOW-TO</title> - </properties> - -<body> - -<section name="Table of Contents"> - - -<a href="#Introduction">Introduction</a> -<a href="#Configuring Manager Application Access"> -Configuring Manager Application Access</a> -<a href="#Supported Manager Commands">Supported Manager Commands</a> -<blockquote> -<a href="#Deploy A New Application Remotely">Deploy A New Application Remotely</a> -<a href="#Deploy A New Application from a Local Path">Deploy A New Application from a Local Path</a> -<a href="#List Currently Deployed Applications"> -List Currently Deployed Applications</a> -<a href="#Reload An Existing Application">Reload An Existing Application</a> -<a href="#List OS and JVM Properties">List OS and JVM Properties</a> -<a href="#List Available Global JNDI Resources"> -List Available Global JNDI Resources</a> -<a href="#List Available Security Roles">List Available Security Roles</a> -<a href="#Session Statistics">Session Statistics</a> -<a href="#Start an Existing Application">Start an Existing Application</a> -<a href="#Stop an Existing Application">Stop an Existing Application</a> -<a href="#Undeploy an Existing Application"> -Undeploy an Existing Application</a> -</blockquote> -<a href="#Executing Manager Commands With Ant"> -Executing Manager Commands With Ant</a> -<a href="#Using the JMX Proxy Servlet"> -Using the JMX Proxy Servlet</a> -<blockquote> -<a href="#What is JMX Proxy Servlet">What is JMX Proxy Servlet?</a> -<a href="#JMX Query command">Query command</a> -<a href="#JMX Set command">Set command</a> -</blockquote> - - -</section> - -<section name="Introduction"> - -In many production environments, it is very useful to have the capability -to deploy a new web application, or undeploy an existing one, without having -to shut down and restart the entire container. In addition, you can request -an existing application to reload itself, even if you have not declared it -to be <code>reloadable</code> in the JBoss Web server -configuration file. - -To support these capabilities, JBoss Web includes a web application -(installed by default on context path <code>/manager</code>) that supports -the following functions: -<ul> -<li>Deploy a new web application from the uploaded contents of a WAR file.</li> -<li>Deploy a new web application, on a specified context path, from the - server file system.</li> -<li>List the currently deployed web applications, as well as the - sessions that are currently active for those web apps.</li> -<li>Reload an existing web application, to reflect changes in the - contents of <code>/WEB-INF/classes</code> or <code>/WEB-INF/lib</code>. - </li> -<li>List the OS and JVM property values.</li> -<li>List the available global JNDI resources, for use in deployment - tools that are preparing <code><ResourceLink></code> elements - nested in a <code><Context></code> deployment description.</li> -<li>List the available security roles defined in the user database.</li> -<li>Start a stopped application (thus making it available again).</li> -<li>Stop an existing application (so that it becomes unavailable), but - do not undeploy it.</li> -<li>Undeploy a deployed web application and delete its document base - directory (unless it was deployed from file system).</li> -</ul> - -There are two ways to configure the Manager web application -<code>Context</code>: -<ul> -<li>Install the <code>manager.xml</code> context configuration file - in the <code>$CATALINA_HOME/conf/[enginename]/[hostname]</code> folder. -</li> -<li>Configure the Manager <code>Context</code> within the - <code>Host</code> configuration in your JBoss Web <code>server.xml</code> - configuration. Here is an example: -<pre> -<Context path="/manager" privileged="true" - docBase="/usr/local/jbossweb/server/webapps/manager"> -</Context> -</pre> -</li> -</ul> - - -If you have JBoss Web configured to support multiple virtual hosts -(websites) you would need to configure a Manager for each. - -There are three ways to use the <code>Manager</code> web application. -<ul> -<li>As an application with a user interface you use in your browser. -Here is an example URL where you can replace <code>localhost</code> with -your website host name: <code>http://localhost/manager/html/</code> .</li> -<li>A minimal version using HTTP requests only which is suitable for use -by scripts setup by system administrators. Commands are given as part of the -request URI, and responses are in the form of simple text that can be easily -parsed and processed. See <a href="#Supported Manager Commands"> -Supported Manager Commands</a> for more information.</li> -<li>A convenient set of task definitions for the Ant -(version 1.4 or later) build tool. See -<a href="#Executing Manager Commands With Ant">Executing Manager Commands -With Ant</a> for more information.</li> -</ul> - - -</section> - -<section name="Configuring Manager Application Access"> - - <blockquote> - The description below uses the variable name $CATALINA_HOME - to refer to the directory into which you have installed JBoss Web, - and is the base directory against which most relative paths are - resolved. However, if you have configured JBoss Web for multiple - instances by setting a CATALINA_BASE directory, you should use - $CATALINA_BASE instead of $CATALINA_HOME for each of these - references. - </blockquote> - -It would be quite unsafe to ship JBoss Web with default settings that allowed -anyone on the Internet to execute the Manager application on your server. -Therefore, the Manager application is shipped with the requirement that anyone -who attempts to use it must authenticate themselves, using a username and -password that have the role manager associated with them. -Further, there is no username in the default users file -(<conf>$CATALINA_HOME/conf/tomcat-users.xml</conf>) that is assigned this -role. Therefore, access to the Manager application is completely disabled -by default. - -To enable access to the Manager web application, you must either create -a new username/password combination and associate the role name -manager with it, or add the manager role -to some existing username/password combination. Exactly where this is done -depends on which <code>Realm</code> implementation you are using: -<ul> -<li>MemoryRealm - If you have not customized your - <code>$CATALINA_HOME/conf/server.xml</code> to select a different one, - JBoss Web defaults to an XML-format file stored at - <code>$CATALINA_HOME/conf/tomcat-users.xml</code>, which can be - edited with any text editor. This file contains an XML - <code><user></code> for each individual user, which might - look something like this: -<source> -<user name="craigmcc" password="secret" roles="standard,manager" /> -</source> - which defines the username and password used by this individual to - log on, and the role names he or she is associated with. You can - add the manager role to the comma-delimited - <code>roles</code> attribute for one or more existing users, and/or - create new users with that assigned role.</li> -<li>JDBCRealm - Your user and role information is stored in - a database accessed via JDBC. Add the manager role - to one or more existing users, and/or create one or more new users - with this role assigned, following the standard procedures for your - environment.</li> -<li>JNDIRealm - Your user and role information is stored in - a directory server accessed via LDAP. Add the manager - role to one or more existing users, and/or create one or more new users - with this role assigned, following the standard procedures for your - environment.</li> -</ul> - -The first time you attempt to issue one of the Manager commands -described in the next section, you will be challenged to log on using -BASIC authentication. The username and password you enter do not matter, -as long as they identify a valid user in the users database who possesses -the role manager. - -In addition to the password restrictions the manager web application -could be restricted by the remote IP address or host by adding a -<code>RemoteAddrValve</code> or <code>RemoteHostValve</code>. Here is -an example of restricting access to the localhost by IP address: -<pre> -<Context path="/manager" privileged="true" - docBase="/usr/local/jbossweb/server/webapps/manager"> - <Valve className="org.apache.catalina.valves.RemoteAddrValve" - allow="127\.0\.0\.1"/> -</Context> -</pre> - -</section> - - -<section name="Supported Manager Commands"> - -All commands that the Manager application knows how to process are -specified in a single request URI like this: -<source> -http://{host}:{port}/manager/{command}?{parameters} -</source> -where <code>{host}</code> and <code>{port}</code> represent the hostname -and port number on which JBoss Web is running, <code>{command}</code> -represents the Manager command you wish to execute, and -<code>{parameters}</code> represents the query parameters -that are specific to that command. In the illustrations below, customize -the host and port appropriately for your installation. - -Most commands accept one or more of the following query parameters: -<ul> -<li>path - The context path (including the leading slash) - of the web application you are dealing with. To select the ROOT web - application, specify "/". NOTE - - It is not possible to perform administrative commands on the - Manager application itself.</li> -<li>war - URL of a web application archive (WAR) file, - pathname of a directory which contains the web application, or a - Context configuration ".xml" file. You can use URLs in any of the - following formats: - <ul> - <li>file:/absolute/path/to/a/directory - The absolute - path of a directory that contains the unpacked version of a web - application. This directory will be attached to the context path - you specify without any changes.</li> - <li>file:/absolute/path/to/a/webapp.war - The absolute - path of a web application archive (WAR) file. This is valid - only for the <code>/deploy</code> command, and is - the only acceptable format to that command.</li> - <li>jar:file:/absolute/path/to/a/warfile.war!/ - The - URL to a local web application archive (WAR) file. You can use any - syntax that is valid for the <code>JarURLConnection</code> class - for reference to an entire JAR file.</li> - <li>file:/absolute/path/to/a/context.xml - The - absolute path of a web application Context configuration ".xml" - file which contains the Context configuration element.</li> - <li>directory - The directory name for the web - applciation context in the Host's application base directory.</li> - <li>webapp.war - The name of a web application war file - located in the Host's application base directory.</li> - </ul></li> -</ul> - -Each command will return a response in <code>text/plain</code> format -(i.e. plain ASCII with no HTML markup), making it easy for both humans and -programs to read). The first line of the response wil begin with either -<code>OK</code> or <code>FAIL</code>, indicating whether the requested -command was successful or not. In the case of failure, the rest of the first -line will contain a description of the problem that was encountered. Some -commands include additional lines of information as described below. - -Internationalization Note - The Manager application looks up -its message strings in resource bundles, so it is possible that the strings -have been translated for your platform. The examples below show the English -version of the messages. - -<blockquote> -WARNING: the legacy commands <code>/install</code> and -<code>/remove</code> are deprecated. -They are presently equivalent to <code>/deploy</code> and <code>/undeploy</code>, -but could be removed in a future release. -</blockquote> - -<subsection name="Deploy A New Application Remotely"> - -<source> -http://localhost:8080/manager/deploy?path=/foo -</source> - -Upload the web application archive (WAR) file that is specified as the -request data in this HTTP PUT request, install it into the <code>appBase</code> -directory of our corresponding virtual host, and start , using the directory -name or the war file name without the .war extension as the path. The -application can later be undeployed (and the corresponding application directory -removed) by use of the <code>/undeploy</code> command. - -The .WAR file may include JBoss Web specific deployment configuration, by -including a Context configuration XML file in -<code>/META-INF/context.xml</code>. - -URL parameters include: -<ul> -<li><code>update</code>: When set to true, any existing update will be - undeployed first. The default value is set to false.</li> -<li><code>tag</code>: Specifying a tag name, this allows associating the - deployed webapp with a version number. The application version can - be later redeployed when needed using only the tag.</li> -</ul> - - -NOTE - This command is the logical -opposite of the <code>/undeploy</code> command. - -If installation and startup is successful, you will receive a response -like this: -<source> -OK - Deployed application at context path /foo -</source> - -Otherwise, the response will start with <code>FAIL</code> and include an -error message. Possible causes for problems include: -<ul> -<li>Application already exists at path /foo - <blockquote> - The context paths for all currently running web applications must be - unique. Therefore, you must undeploy the existing web - application using this context path, or choose a different context path - for the new one. The <code>update</code> parameter may be specified as - a parameter on the URL, with a value of <code>true</code> to avoid this - error. In that case, an undeploy will be performed on an existing - application before performing the deployment. - </blockquote></li> -<li>Encountered exception - <blockquote> - An exception was encountered trying to start the new web application. - Check the JBoss Web logs for the details, but likely explanations include - problems parsing your <code>/WEB-INF/web.xml</code> file, or missing - classes encountered when initializing application event listeners and - filters. - </blockquote></li> -</ul> - -</subsection> - -<subsection name="Deploy A New Application from a Local Path"> - -Deploy and start a new web application, attached to the specified context -<code>path</code> (which must not be in use by any other web application). -This command is the logical opposite of the <code>/undeploy</code> command. - -There are a number of different ways the deploy command can be used. - -<h3>Deploy a version of a previously deployed webapp</h3> - -This can be used to deploy a previous version of a web application, which -has been deployed using the <code>tag</code> attribute. Note that the work -directory for the manager webapp will contain the previously deployed WARs; -removing it would make the deployment fail. -<source> -http://localhost:8080/manager/deploy?path=/footoo&tag=footag -</source> - - -<h3>Deploy a Directory or WAR by URL</h3> - -Deploy a web application directory or ".war" file located on the JBoss Web -server. If no <code>path</code> is specified, the directory name or the war file -name without the ".war" extension is used as the path. The <code>war</code> -parameter specifies a URL (including the <code>file:</code> scheme) for either -a directory or a web application archive (WAR) file. The supported syntax for -a URL referring to a WAR file is described on the Javadocs page for the -<code>java.net.JarURLConnection</code> class. Use only URLs that refer to -the entire WAR file. - -In this example the web application located in the directory -<code>/path/to/foo</code> on the JBoss Web server is deployed as the -web application context named <code>/footoo</code>. -<source> -http://localhost:8080/manager/deploy?path=/footoo&war=file:/path/to/foo -</source> - - -In this example the ".war" file <code>/path/to/bar.war</code> on the -JBoss Web server is deployed as the web application context named -<code>/bar</code>. Notice that there is no <code>path</code> parameter -so the context path defaults to the name of the web application archive -file without the ".war" extension. -<source> -http://localhost:8080/manager/deploy?war=jar:file:/path/to/bar.war!/ -</source> - - -<h3>Deploy a Directory or War from the Host appBase</h3> - -Deploy a web application directory or ".war" file located in your Host -appBase directory. The directory name or the war file name without the ".war" -extension is used as the path. - -In this example the web application located in a sub directory named -<code>foo</code> in the Host appBase directory of the JBoss Web server is -deployed as the web application context named <code>/foo</code>. Notice -that the context path used is the name of the web application directory. -<source> -http://localhost:8080/manager/deploy?war=foo -</source> - - -In this example the ".war" file <code>bar.war</code> located in your -Host appBase directory on the JBoss Web server is deployed as the web -application context named <code>/bar</code>. -<source> -http://localhost:8080/manager/deploy?war=bar.war -</source> - - -<h3>Deploy using a Context configuration ".xml" file</h3> - -If the Host deployXML flag is set to true you can deploy a web -application using a Context configuration ".xml" file and an optional -".war" file or web application directory. The context <code>path</code> -is not used when deploying a web application using a context ".xml" -configuration file. - -A Context configuration ".xml" file can contain valid XML for a -web application Context just as if it were configured in your -JBoss Web <code>server.xml</code> configuration file. Here is an -example: -<source> -<Context path="/foobar" docBase="/path/to/application/foobar" - debug="0"> - -  - <ResourceLink name="users" global="UserDatabase" - type="org.apache.catalina.UserDatabase"/> - -</Context> -</source> - - -When the optional <code>war</code> parameter is set to the URL -for a web application ".war" file or directory it overrides any -docBase configured in the context configuration ".xml" file. - -Here is an example of deploying an application using a Context -configuration ".xml" file. -<source> -http://localhost:8080/manager/deploy?config=file:/path/context.xml -</source> - - -Here is an example of deploying an application using a Context -configuration ".xml" file and a web application ".war" file located -on the server. -<source> -http://localhost:8080/manager/deploy?config=file:/path/context.xml&war=jar:file:/path/bar.war!/ -</source> - - -<h3>Deployment Notes</h3> - -If the Host is configured with unpackWARs=true and you deploy a war -file, the war will be unpacked into a directory in your Host appBase -directory. - -If the application war or directory is installed in your Host appBase -directory and either the Host is configured with autoDeploy=true or -liveDeploy=true, the Context path must match the directory name or -war file name without the ".war" extension. - -For security when untrusted users can manage web applications, the -Host deployXML flag can be set to false. This prevents untrusted users -from deploying web applications using a configuration XML file and -also prevents them from deploying application directories or ".war" -files located outside of their Host appBase. - - -<h3>Deploy Response</h3> - -If installation and startup is successful, you will receive a response -like this: -<source> -OK - Deployed application at context path /foo -</source> - -Otherwise, the response will start with <code>FAIL</code> and include an -error message. Possible causes for problems include: -<ul> -<li>Application already exists at path /foo - <blockquote> - The context paths for all currently running web applications must be - unique. Therefore, you must undeploy the existing web - application using this context path, or choose a different context path - for the new one. The <code>update</code> parameter may be specified as - a parameter on the URL, with a value of <code>true</code> to avoid this - error. In that case, an undeploy will be performed on an existing - application before performing the deployment. - </blockquote></li> -<li>Document base does not exist or is not a readable directory - <blockquote> - The URL specified by the <code>war</code> parameter must identify a - directory on this server that contains the "unpacked" version of a - web application, or the absolute URL of a web application archive (WAR) - file that contains this application. Correct the value specified by - the <code>war</code> parameter. - </blockquote></li> -<li>Encountered exception - <blockquote> - An exception was encountered trying to start the new web application. - Check the JBoss Web logs for the details, but likely explanations include - problems parsing your <code>/WEB-INF/web.xml</code> file, or missing - classes encountered when initializing application event listeners and - filters. - </blockquote></li> -<li>Invalid application URL was specified - <blockquote> - The URL for the directory or web application that you specified - was not valid. Such URLs must start with <code>file:</code>, and URLs - for a WAR file must end in ".war". - </blockquote></li> -<li>Invalid context path was specified - <blockquote> - The context path must start with a slash character. To reference the - ROOT web application use "/". - </blockquote></li> -<li>Context path must match the directory or WAR file name: - <blockquote> - If the application war or directory is installed in your Host appBase - directory and either the Host is configured with autoDeploy=true or - liveDeploy=true, the Context path must match the directory name or - war file name without the ".war" extension. - </blockquote></li> -<li>Only web applications in the Host web application directory can - be installed - <blockquote> - If the Host deployXML flag is set to false this error will happen - if an attempt is made to deploy a web application directory or - ".war" file outside of the Host appBase directory. - </blockquote></li> -</ul> - -</subsection> - -<subsection name="List Currently Deployed Applications"> - -<source> -http://localhost:8080/manager/list -</source> - -List the context paths, current status (<code>running</code> or -<code>stopped</code>), and number of active sessions for all currently -deployed web applications. A typical response immediately -after starting JBoss Web might look like this: -<source> -OK - Listed applications for virtual host localhost -/webdav:running:0 -/examples:running:0 -/manager:running:0 -/:running:0 -</source> - -</subsection> - -<subsection name="Reload An Existing Application"> - -<source> -http://localhost:8080/manager/reload?path=/examples -</source> - -Signal an existing application to shut itself down and reload. This can -be useful when the web application context is not reloadable and you have -updated classes or property files in the <code>/WEB-INF/classes</code> -directory or when you have added or updated jar files in the -<code>/WEB-INF/lib</code> directory. - -NOTE: The <code>/WEB-INF/web.xml</code> -web application configuration file is not reread on a reload. -If you have made changes to your web.xml file you must stop -then start the web application. - - -If this command succeeds, you will see a response like this: -<source> -OK - Reloaded application at context path /examples -</source> - -Otherwise, the response will start with <code>FAIL</code> and include an -error message. Possible causes for problems include: -<ul> -<li>Encountered exception - <blockquote> - An exception was encountered trying to restart the web application. - Check the JBoss Web logs for the details. - </blockquote></li> -<li>Invalid context path was specified - <blockquote> - The context path must start with a slash character. To reference the - ROOT web application use "/". - </blockquote></li> -<li>No context exists for path /foo - <blockquote> - There is no deployed application on the context path - that you specified. - </blockquote></li> -<li>No context path was specified - <blockquote> - The <code>path</code> parameter is required. - </blockquote></li> -<li>Reload not supported on WAR deployed at path /foo - <blockquote> - Currently, application reloading (to pick up changes to the classes or - <code>web.xml</code> file) is not supported when a web application is - deployed directly from a WAR file. It only works when the web application - is deployed from an unpacked directory. If you are using a WAR file, - you should <code>undeploy</code> and then <code>deploy</code> or - <code>deploy</code> with the <code>update</code> parameter the - application again to pick up your changes. - </blockquote></li> -</ul> - -</subsection> - -<subsection name="List OS and JVM Properties"> - -<source> -http://localhost:8080/manager/serverinfo -</source> - -Lists information about the JBoss Web version, OS, and JVM properties. - -If an error occurs, the response will start with <code>FAIL</code> and -include an error message. Possible causes for problems include: -<ul> -<li>Encountered exception - <blockquote> - An exception was encountered trying to enumerate the system properties. - Check the JBoss Web logs for the details. - </blockquote></li> -</ul> - -</subsection> - -<subsection name="List Available Global JNDI Resources"> - -<source> -http://localhost:8080/manager/resources[?type=xxxxx] -</source> - -List the global JNDI resources that are available for use in resource -links for context configuration files. If you specify the <code>type</code> -request parameter, the value must be the fully qualified Java class name of -the resource type you are interested in (for example, you would specify -<code>javax.sql.DataSource</code> to acquire the names of all available -JDBC data sources). If you do not specify the <code>type</code> request -parameter, resources of all types will be returned. - -Depending on whether the <code>type</code> request parameter is specfied -or not, the first line of a normal response will be: -<pre> - OK - Listed global resources of all types -</pre> -or -<pre> - OK - Listed global resources of type xxxxx -</pre> -followed by one line for each resource. Each line is composed of fields -delimited by colon characters (":"), as follows: -<ul> -<li>Global Resource Name - The name of this global JNDI resource, - which would be used in the <code>global</code> attribute of a - <code><ResourceLink></code> element.</li> -<li>Global Resource Type - The fully qualified Java class name of - this global JNDI resource.</li> -</ul> - -If an error occurs, the response will start with <code>FAIL</code> and -include an error message. Possible causes for problems include: -<ul> -<li>Encountered exception - <blockquote> - An exception was encountered trying to enumerate the global JNDI - resources. Check the JBoss Web logs for the details. - </blockquote></li> -<li>No global JNDI resources are available - <blockquote> - The JBoss Web server you are running has been configured without - global JNDI resources. - </blockquote></li> -</ul> - - -</subsection> - - -<subsection name="List Available Security Roles"> - -<source> -http://localhost:8080/manager/roles -</source> - -List the security role names (and corresponding descriptions) that are -available in the <code>org.apache.catalina.UserDatabase</code> resource that -is linked to the <code>users</code> resource reference in the web.xml file -for the Manager web application. This would typically be used, for example, -by a deployment tool that wanted to create -<code><security-role-ref></code> elements to map security role names -used in a web application to the role names actually defined within the -container. - -By default, the <code>users</code> resource reference is pointed at the -global <code>UserDatabase</code> resource. If you choose to utilize a -different user database per virtual host, you should modify the -<code><ResourceLink></code> element in the default -<code>manager.xml</code> context configuration file to point at the global -user database resource for this virtual host. - -When this command is executed, the first line of the response will be: -<pre> - OK - Listed security roles -</pre> -followed by one line for each security role. Each line is composed of -fields delimited by colon characters (":") as follows: -<ul> -<li>Security Role Name - A security role name that is known to JBoss Web - in the user database.</li> -<li>Description - Description of this security role (useful in - creating user interfaces for selecting roles.</li> -</ul> - -If an error occurs, the response will start with <code>FAIL</code> and -include an error message. Possible causes for problems include: -<ul> -<li>Cannot resolve user database reference - A JNDI error prevented - the successful lookup of the <code>org.apache.catalina.UserDatabase</code> - resource. Check the JBoss Web log files for a stack trace associated with - this error.</li> -<li>No user database is available - You have not configured a resource - reference for the <code>users</code> resource that points at an - appropriate user database instance. Check your <code>manager.xml</code> - file and ensure that you have created an appropriate - <code><ResourceLink></code> or - <code><ResourceParams></code> element for this resource.</li> -</ul> - -</subsection> - - -<subsection name="Session Statistics"> - -<source> -http://localhost:8080/manager/sessions?path=/examples -</source> - -Display the default session timeout for a web application, and the -number of currently active sessions that fall within ten-minute ranges of -their actual timeout times. For example, after restarting JBoss Web and then -executing one of the JSP samples in the <code>/examples</code> web app, -you might get something like this: -<source> -OK - Session information for application at context path /examples -Default maximum session inactive interval 30 minutes -30 - <40 minutes:1 sessions -</source> - -</subsection> - - -<subsection name="Start an Existing Application"> - -<source> -http://localhost:8080/manager/start?path=/examples -</source> - -Signal a stopped application to restart, and make itself available again. -Stopping and starting is useful, for example, if the database required by -your application becomes temporarily unavailable. It is usually better to -stop the web application that relies on this database rather than letting -users continuously encounter database exceptions. - -If this command succeeds, you will see a response like this: -<source> -OK - Started application at context path /examples -</source> - -Otherwise, the response will start with <code>FAIL</code> and include an -error message. Possible causes for problems include: -<ul> -<li>Encountered exception - <blockquote> - An exception was encountered trying to start the web application. - Check the JBoss Web logs for the details. - </blockquote></li> -<li>Invalid context path was specified - <blockquote> - The context path must start with a slash character. To reference the - ROOT web application use "/". - </blockquote></li> -<li>No context exists for path /foo - <blockquote> - There is no deployed application on the context path - that you specified. - </blockquote></li> -<li>No context path was specified - <blockquote> - The <code>path</code> parameter is required. - </blockquote></li> -</ul> - -</subsection> - -<subsection name="Stop an Existing Application"> - -<source> -http://localhost:8080/manager/stop?path=/examples -</source> - -Signal an existing application to make itself unavailable, but leave it -deployed. Any request that comes in while an application is -stopped will see an HTTP error 404, and this application will show as -"stopped" on a list applications command. - -If this command succeeds, you will see a response like this: -<source> -OK - Stopped application at context path /examples -</source> - -Otherwise, the response will start with <code>FAIL</code> and include an -error message. Possible causes for problems include: -<ul> -<li>Encountered exception - <blockquote> - An exception was encountered trying to stop the web application. - Check the JBoss Web logs for the details. - </blockquote></li> -<li>Invalid context path was specified - <blockquote> - The context path must start with a slash character. To reference the - ROOT web application use "/". - </blockquote></li> -<li>No context exists for path /foo - <blockquote> - There is no deployed application on the context path - that you specified. - </blockquote></li> -<li>No context path was specified - <blockquote> - The <code>path</code> parameter is required. - </blockquote></li> -</ul> - -</subsection> - - -<subsection name="Undeploy an Existing Application"> - -<source> -http://localhost:8080/manager/undeploy?path=/examples -</source> - -WARNING - This command will delete any web -application artifacts that exist within <code>appBase</code> directory -(typically "webapps") for this virtual host. -This will delete the the application .WAR, if present, -the application directory resulting either from a deploy in unpacked form -or from .WAR expansion as well as the XML Context definition from -<code>$CATALINA_HOME/conf/[enginename]/[hostname]/</code> directory. -If you simply want to take an application -out of service, you should use the <code>/stop</code> command instead. - -Signal an existing application to gracefully shut itself down, and -remove it from JBoss Web (which also makes this context path available for -reuse later). In addition, the document root directory is removed, if it -exists in the <code>appBase</code> directory (typically "webapps") for -this virtual host. This command is the logical opposite of the -<code>/deploy</code> command. - -If this command succeeds, you will see a response like this: -<source> -OK - Undeployed application at context path /examples -</source> - -Otherwise, the response will start with <code>FAIL</code> and include an -error message. Possible causes for problems include: -<ul> -<li>Encountered exception - <blockquote> - An exception was encountered trying to undeploy the web application. - Check the JBoss Web logs for the details. - </blockquote></li> -<li>Invalid context path was specified - <blockquote> - The context path must start with a slash character. To reference the - ROOT web application use "/". - </blockquote></li> -<li>No context exists for path /foo - <blockquote> - There is no deployed application on the context path - that you specified. - </blockquote></li> -<li>No context path was specified - <blockquote> - The <code>path</code> parameter is required. - </blockquote></li> -</ul> - -</subsection> - -</section> - -<section name="Executing Manager Commands With Ant"> - -In addition to the ability to execute Manager commands via HTTP requests, -as documented above, JBoss Web includes a convenient set of Task definitions -for the Ant (version 1.4 or later) build tool. In order to use these -commands, you must perform the following setup operations: -<ul> -<li>Download the binary distribution of Ant from - <a href="http://ant.apache.org">http://ant.apache.org</a>. - You must use version 1.4 or later.</li> -<li>Install the Ant distribution in a convenient directory (called - ANT_HOME in the remainder of these instructions).</li> -<li>Copy the file <code>server/lib/catalina-ant.jar</code> from your JBoss Web 6 - installation into Ant's library directory (<code>$ANT_HOME/lib</code>). - </li> -<li>Add the <code>$ANT_HOME/bin</code> directory to your <code>PATH</code> - environment variable.</li> -<li>Configure at least one username/password combination in your JBoss Web - user database that includes the <code>manager</code> role.</li> -</ul> - -To use custom tasks within Ant, you must declare them first with a -<code><taskdef></code> element. Therefore, your <code>build.xml</code> -file might look something like this: - -<source> -<project name="My Application" default="compile" basedir="."> - -  - <property name="build" value="${basedir}/build"/> - -  - <property name="path" value="/myapp"/> - -  - <property name="url" value="http://localhost:8080/manager"/> - <property name="username" value="myusername"/> - <property name="password" value="mypassword"/> - -  - <taskdef name="deploy" classname="org.apache.catalina.ant.DeployTask"/> - <taskdef name="list" classname="org.apache.catalina.ant.ListTask"/> - <taskdef name="reload" classname="org.apache.catalina.ant.ReloadTask"/> - <taskdef name="resources" classname="org.apache.catalina.ant.ResourcesTask"/> - <taskdef name="roles" classname="org.apache.catalina.ant.RolesTask"/> - <taskdef name="start" classname="org.apache.catalina.ant.StartTask"/> - <taskdef name="stop" classname="org.apache.catalina.ant.StopTask"/> - <taskdef name="undeploy" classname="org.apache.catalina.ant.UndeployTask"/> - -  - <target name="compile" description="Compile web application"> -  - </target> - - <target name="deploy" description="Install web application" - depends="compile"> - <deploy url="${url}" username="${username}" password="${password}" - path="${path}" war="file:${build}${path}.war"/> - </target> - - <target name="reload" description="Reload web application" - depends="compile"> - <reload url="${url}" username="${username}" password="${password}" - path="${path}"/> - </target> - - <target name="undeploy" description="Remove web application"> - <undeploy url="${url}" username="${username}" password="${password}" - path="${path}"/> - </target> - -</project> -</source> - -Now, you can execute commands like <code>ant deploy</code> to deploy the -application to a running instance of JBoss Web, or <code>ant reload</code> to -tell JBoss Web to reload it. Note also that most of the interesting values in -this <code>build.xml</code> file are defined as replaceable properties, so -you can override their values from the command line. For example, you might -consider it a security risk to include the real manager password in your -<code>build.xml</code> file's source code. To avoid this, omit the password -property, and specify it from the command line: -<pre> - ant -Dpassword=secret deploy -</pre> - -<subsection name="Tasks output capture"> - -Using Ant version 1.6.2 or later, -the Catalina tasks offer the option to capture their output in -properties or external files. They support directly the following subset of the -<code><redirector></code> type attributes: - - - <attributes> - - <attribute name="output" required="false"> - Name of a file to which to write the output. If -the error stream is not also redirected to a file or property, it will -appear in this output. - </attribute> - - <attribute name="error" required="false"> - The file to which the standard error of the -command should be redirected. - </attribute> - - <attribute name="logError" required="false"> - This attribute is used when you wish to see -error output in Ant's log and you are redirecting output to a -file/property. The error output will not be included in the output -file/property. If you redirect error with the error or errorProperty -attributes, this will have no effect. - </attribute> - - <attribute name="append" required="false"> - Whether output and error files should be -appended to or overwritten. Defaults to <code>false</code>. - - </attribute> - - <attribute name="createemptyfiles" required="false"> - Whether output and error files should be created -even when empty. Defaults to <code>true</code>. - </attribute> - - <attribute name="outputproperty" required="false"> - The name of a property in which the output of -the command should be stored. Unless the error stream is redirected to -a separate file or stream, this property will include the error output. - </attribute> - - <attribute name="errorproperty" required="false"> - The name of a property in which the standard -error of the command should be stored. - </attribute> - - <attribute name="alwaysLog" required="false"> - This attribute is used when you wish to see the -output you are capturing, appearing also in the Ant's log. It must not be -used unless you are capturing task output. -Defaults to <code>false</code>. -This attribute will be supported directly by <code><redirector></code> -in Ant 1.6.3 - </attribute> - - <attribute name="failonerror" required="false"> - This attribute is used when you wish to avoid that -any manager command processing error terminates the ant execution. Defaults to <code>true</code>. -It must be set to <code>false</code>, if you want to capture error output, -otherwise execution will terminate before anything can be captured. - -This attribute acts only on manager command execution, -any wrong or missing command attribute will still cause Ant execution termination. - </attribute> - - </attributes> - -They also support the embedded <code><redirector></code> element -in which you can specify -its full set of attributes, but <code>input</code>, <code>inputstring</code> and -<code>inputencoding</code> that, even if accepted, are not used because they have -no meaning in this context. -Refer to <a href="http://ant.apache.org">ant manual</a> for details on -<code><redirector></code> element attributes. - - - -Here is a sample build file extract that shows how this output redirection support -can be used: - - -<source> - <target name="manager.deploy" - depends="context.status" - if="context.notInstalled"> - <deploy url="${mgr.url}" - username="${mgr.username}" - password="${mgr.password}" - path="${mgr.context.path}" - config="${mgr.context.descriptor}"/> - </target> - - <target name="manager.deploy.war" - depends="context.status" - if="context.deployable"> - <deploy url="${mgr.url}" - username="${mgr.username}" - password="${mgr.password}" - update="${mgr.update}" - path="${mgr.context.path}" - war="${mgr.war.file}"/> - </target> - - <target name="context.status"> - <property name="running" value="${mgr.context.path}:running"/> - <property name="stopped" value="${mgr.context.path}:stopped"/> - - <list url="${mgr.url}" - outputproperty="ctx.status" - username="${mgr.username}" - password="${mgr.password}"> - </list> - - <condition property="context.running"> - <contains string="${ctx.status}" substring="${running}"/> - </condition> - <condition property="context.stopped"> - <contains string="${ctx.status}" substring="${stopped}"/> - </condition> - <condition property="context.notInstalled"> - <and> - <isfalse value="${context.running}"/> - <isfalse value="${context.stopped}"/> - </and> - </condition> - <condition property="context.deployable"> - <or> - <istrue value="${context.notInstalled}"/> - <and> - <istrue value="${context.running}"/> - <istrue value="${mgr.update}"/> - </and> - <and> - <istrue value="${context.stopped}"/> - <istrue value="${mgr.update}"/> - </and> - </or> - </condition> - <condition property="context.undeployable"> - <or> - <istrue value="${context.running}"/> - <istrue value="${context.stopped}"/> - </or> - </condition> - </target> -</source> - -WARNING: even if it doesn't make many sense, and is always a bad idea, -calling a Catalina task more than once, -badly set Ant tasks depends chains may cause that a task be called -more than once in the same Ant run, even if not intended to. A bit of caution should be exercised when you are -capturing output from that task, because this could lead to something unexpected: -<ul> -<li>when capturing in a property you will find in it only the output from the first call, because -Ant properties are immutable and once set they cannot be changed, -</li> -<li>when capturing in a file, each run will overwrite it and you will find in it only the last call -output, unless you are using the <code>append="true"</code> attribute, in which case you will -see the output of each task call appended to the file. -</li> -</ul> - - -</subsection> - -</section> - -<section name="Using the JMX Proxy Servlet"> - - <subsection name="What is JMX Proxy Servlet"> - The JMX Proxy Servlet is a lightweight proxy to get and set the - JBoss Web internals. (Or any class that has been exposed via an MBean) - Its usage is not very user friendly but the UI is - extremely help for integrating command line scripts for monitoring - and changing the internals of JBoss Web. You can do two things with the proxy: - get information and set information. For you to really understand the - JMX Proxy Servlet, you should have a general understanding of JMX. - If you don't know what JMX is, then prepare to be confused. - </subsection> - - <subsection name="JMX Query command"> - This takes the form: -<source> -http://webserver/manager/jmxproxy/?qry=STUFF -</source> - Where <code>STUFF</code> is the JMX query you wish to perform. For example, - here are some queries you might wish to run: - <ul> - <li> - <code>qry=*%3Atype%3DRequestProcessor%2C* --> - type=RequestProcessor</code> which will locate all - workers which can process requests and report - their state. - </li> - <li> - <code>qry=*%3Aj2eeType=Servlet%2c* --> - j2eeType=Servlet</code> which return all loaded servlets. - </li> - <li> - <code>qry=Catalina%3Atype%3DEnvironment%2Cresourcetype%3DGlobal%2Cname%3DsimpleValue --> - Catalina:type=Environment,resourcetype=Global,name=simpleValue</code> - which look for a specific MBean by the given name. - </li> - </ul> - You'll need to experiment with this to really understand its capabilites. - If you provide no <code>qry</code> parameter, then all of the MBeans will - be displayed. We really recommend looking at the JBoss Web source code and - understand the JMX spec to get a better understanding of all the queries - you may run. - </subsection> - - <subsection name="JMX Set command"> - Now that you can query an MBean, its time to muck with JBoss Web's internals! - The general form of the set command is : -<source> -http://webserver/manager/jmxproxy/?set=BEANNAME&att=MYATTRIBUTE&val=NEWVALUE -</source> - So you need to provide 3 request parameters: - <ol> - <li><code>set</code>: The full bean name</li> - <li><code>att</code>: The attribute you wish to alter</li> - <li><code>val</code>: The new value </li> - </ol> - If all goes ok, then it will say OK, otherwise an error message will be - shown. For example, lets say we wish to turn up debugging on the fly for the - <code>ErrorReportValve</code>. The following will set debugging to 10. -<source> -http://localhost:8080/manager/jmxproxy/?set=Catalina%3Atype%3DValve%2Cname%3DErrorReportValve%2Chost%3Dlocalhost&att=debug&val=10 -</source> - and my result is (YMMV): -<source> -Result: ok -</source> - - Here is what I see if I pass in a bad value. Here is the URL I used, - I try set debugging equal to 'cowbell': -<source> -http://localhost:8080/manager/jmxproxy/?set=Catalina%3Atype%3DValve%2Cname%3DErrorReportValve%2Chost%3Dlocalhost&att=debug&val=cowbell -</source> - When I try that, my result is -<source> -Error: java.lang.NumberFormatException: For input string: "cowbell" -</source> - </subsection> - - -</section> - - - -</body> - -</document> Deleted: trunk/webapps/docs/mbeans-descriptor-howto.xml =================================================================== --- trunk/webapps/docs/mbeans-descriptor-howto.xml 2011-09-08 14:43:49 UTC (rev 1831) +++ trunk/webapps/docs/mbeans-descriptor-howto.xml 2011-09-08 16:06:13 UTC (rev 1832) @@ -1,63 +0,0 @@ -<?xml version="1.0"?> -<!DOCTYPE document [ - <!ENTITY project SYSTEM "project.xml"> -]> -<document url="mbeans-descriptor-howto.html"> - - &project; - - <properties> - <author email="amyroh(a)apache.org">Amy Roh</author> - <title>MBean Descriptor How To</title> - </properties> - -<body> - -<section name="Introduction"> - -JBoss Web uses JMX MBeans as the technology for implementing -manageability of JBoss Web. - -The descriptions of JMX MBeans for Catalina are in the mbeans-descriptor.xml -file in each package. - -You will need to add MBean descriptions for your custom components -in order to avoid a "ManagedBean is not found" exception. - -</section> - -<section name="Adding MBean descriptions"> - -You may also add MBean descriptions for custom components in -a mbeans-descriptor.xml file, located in the same package as the class files -it describes. - -<source> - <mbean name="LDAPRealm" - className="org.apache.catalina.mbeans.ClassNameMBean" - description="Custom LDAPRealm" - domain="Catalina" - group="Realm" - type="com.myfirm.mypackage.LDAPRealm"> - - <attribute name="className" - description="Fully qualified class name of the managed object" - type="java.lang.String" - writeable="false"/> - - <attribute name="debug" - description="The debugging detail level for this component" - type="int"/> - . - . - . - - </mbean> -</source> - - -</section> - -</body> - -</document> Deleted: trunk/webapps/docs/php.xml =================================================================== --- trunk/webapps/docs/php.xml 2011-09-08 14:43:49 UTC (rev 1831) +++ trunk/webapps/docs/php.xml 2011-09-08 16:06:13 UTC (rev 1832) @@ -1,107 +0,0 @@ -<?xml version="1.0"?> -<!DOCTYPE document [ - <!ENTITY project SYSTEM "project.xml"> -]> -<document url="index.html"> - - &project; - - <properties> - <author email="mladen.turk(a)jboss.com">Mladen Turk</author> - <author email="jfrederic.clere(a)jboss.com">Jean-Frederic Clere</author> - <title>Overview</title> - </properties> - -<body> - -<section name="Introduction"> -The PHP Module is a servlet that allows to run PHP embedded scripts. -The servlet calls a native embedded PHP engine with libraries extentions. -The PHP servlet allows to run most of the existing PHP scripts. - -</section> - -<section name="Building"> - -To build simply run buildphp.sh. -The buildphp.sh will detect you platform, download and build the dynamic libraries the PHP library needs and -build the PHP servlet itself. Should should get a tarfile that contains the libraries and a war file with the examples. - -Already build PHP servlets and libraries are available at: -<a href="http://labs.jboss.com/jbossweb/downloads/php/">JBossWeb download area</a> -</section> - -<section name="Installing"> -After extracting the tarball corresponding to you platform. (For example in $JBOSS_HOME, -where JBOSS_HOME should be something like jbossweb-1.0.0.GA). -In $CATALINA_BASE (CATALINA_BASE should be -something like jbossweb-1.0.0.GA/server/default/deploy/jbossweb.sar) do the following: -Edit in the <Server/> of <code>$CATALINA_BASE/server.xml</code> and uncomment the following Listener entry: -<source> - <Listener className="org.apache.catalina.servlets.php.LifecycleListener"/> -</source> -If you want to enable php in all contexts edit <code>$CATALINA_BASE/conf/web.xml</code> and uncomment the php servlet -description and its mapping: -<source> - <servlet> - <servlet-name>php</servlet-name> - <servlet-class>org.apache.catalina.servlets.php.Handler</servlet-class> - <init-param> - <param-name>debug</param-name> - <param-value>0</param-value> - </init-param> - <load-on-startup>6</load-on-startup> - </servlet> - <servlet> - <servlet-name>phps</servlet-name> - <servlet-class>org.apache.catalina.servlets.php.Highlight</servlet-class> - </servlet> -<source> -</source> - <servlet-mapping> - <servlet-name>php</servlet-name> - <url-pattern>*.php</url-pattern> - </servlet-mapping> - <servlet-mapping> - <servlet-name>phps</servlet-name> - <url-pattern>*.phps</url-pattern> - </servlet-mapping> -</source> -Edit the <code>$JBOSS_HOME/bin/run.conf</code> (JBOSS_HOME should be something like jbossweb-1.0.0.GA) add the <code>LD_LIBRARY_PATH</code> variable and modify/add (replace $JBOSS_HOME by its value) -the java.library.path parameter of the JVM: -<source> -LD_LIBRARY_PATH=$JBOSS_HOME/PHP/lib -export LD_LIBRARY_PATH -</source> -Copy the 2 libraries libphp5.so and libphp5servlet.so in $JBOSS_HOME/bin/native, something like: -<source> -cp ./PHP/lib/libphp5.so bin/native -cp ./PHP/lib/libphp5servlet.so bin/native -</source> -</section> -<section name="Using the php demo scripts"> -The <code>php-examples.war</code> warfile of the tarball contains some php demo scripts. -The warfile should be located in $CATALINA_BASE. -They are deployed under /php-examples to use them you only need to modify the <code>$JBOSS_HOME/bin/run.conf</code> as described above. -You don't have to modify the <code>$CATALINA_BASE/conf/web.xml</code> -nor the <code>$CATALINA_BASE/server.xml</code> files. -You have to start and restart the servlet container because of the environment modifications. -To use the examples, try <code>http://localhost:8080/php-examples/index.php</code>. -</section> -<section name="Additing extension libraries"> -For the moment this feature is only supported on Solaris. -Edit the <code>php.ini</code> file and add your library extensions as in the following example: -<source> -extension_dir=/home/jfclere/SunOS_i386_tools/PHP/lib/php/extensions/no-debug-zts-20050922 -extension=openssl.so -extension=pdo_pgsql.so -extension=pgsql.so -</source> -</section> -<section name="Installing on win32 machines"> -Copy the demo webapps/php-examples.war to ./server/default/deploy. -Edit server/default/deploy/jbossweb.sar/server.xml as in other OS. -Copy the dlls in bin/native -</section> -</body> -</document> Modified: trunk/webapps/docs/project.xml =================================================================== --- trunk/webapps/docs/project.xml 2011-09-08 14:43:49 UTC (rev 1831) +++ trunk/webapps/docs/project.xml 2011-09-08 16:06:13 UTC (rev 1832) @@ -12,13 +12,11 @@ <body> <menu name="User Guide"> - <item name="Docs Home" href="index.html"/> + <item name="Docs Home" href="index.html"/> <item name="Introduction" href="introduction.html"/> - <item name="Setup" href="setup.html"/> <item name="System Properties" href="sysprops.html"/> <item name="First webapp" href="appdev/index.html"/> <item name="Deployer" href="deployer-howto.html"/> - <item name="Manager" href="manager-howto.html"/> <item name="Realms and AAA" href="realm-howto.html"/> <item name="Security Manager" href="security-manager-howto.html"/> <item name="JNDI Resources" href="jndi-resources-howto.html"/> @@ -26,9 +24,6 @@ <item name="Classloading" href="class-loader-howto.html"/> <item name="JSPs" href="jasper-howto.html"/> <item name="SSL" href="ssl-howto.html"/> - <item name="PHP" href="php.html"/> - <item name="SSI" href="ssi-howto.html"/> - <item name="CGI" href="cgi-howto.html"/> <item name="URL Rewriting" href="rewrite.html"/> <item name="Proxy Support" href="proxy-howto.html"/> <item name="MBean Descriptor" href="mbeans-descriptor-howto.html"/> @@ -53,9 +48,6 @@ <item name="Release Notes" href="RELEASE-NOTES.txt"/> <item name="Configuration" href="config/index.html"/> <item name="Javadocs" href="api/index.html"/> - <item name="JK 1.2 Documentation" - href="http://tomcat.apache.org/connectors-doc/"/> - <item name="Tomcat FAQ" href="http://tomcat.apache.org/faq" /> </menu> </body> Deleted: trunk/webapps/docs/realm-howto.xml =================================================================== --- trunk/webapps/docs/realm-howto.xml 2011-09-08 14:43:49 UTC (rev 1831) +++ trunk/webapps/docs/realm-howto.xml 2011-09-08 16:06:13 UTC (rev 1832) @@ -1,1471 +0,0 @@ -<?xml version="1.0"?> -<!DOCTYPE document [ - <!ENTITY project SYSTEM "project.xml"> -]> -<document url="realm-howto.html"> - - &project; - - <properties> - <author email="craigmcc(a)apache.org">Craig R. McClanahan</author> - <author email="yoavs(a)apache.org">Yoav Shapira</author> - <author email="arjaquith(a)mindspring.com">Andrew R. Jaquith</author> - <title>Realm Configuration HOW-TO</title> - </properties> - -<body> - - -<section name="Table of Contents"> - - -<a href="#Quick Start">Quick Start</a> -<blockquote> -<a href="#What is a Realm?">What is a Realm?</a> -<a href="#Configuring a Realm">Configuring a Realm</a> -</blockquote> -<a href="#Common Features">Common Features</a> -<blockquote> -<a href="#Digested Passwords">Digested Passwords</a> -<a href="#Example Application">Example Application</a> -<a href="#Manager Application">Manager Application</a> -<a href="#Realm Logging">Logging Within Realms</a> -</blockquote> -<a href="#Standard Realm Implementations"> -Standard Realm Implementations</a> -<blockquote> -<a href="#JDBCRealm">JDBCRealm</a> -<a href="#DataSourceRealm">DataSourceRealm</a> -<a href="#JNDIRealm">JNDIRealm</a> -<a href="#MemoryRealm">MemoryRealm</a> -<a href="#JAASRealm">JAASRealm</a> -</blockquote> - - -</section> - -<section name="Quick Start"> - -This document describes how to configure JBoss Web to support container -managed security, by connecting to an existing "database" of usernames, -passwords, and user roles. You only need to care about this if you are using -a web application that includes one or more -<code><security-constraint></code> elements, and a -<code><login-config></code> element defining how users are required -to authenticate themselves. If you are not utilizing these features, you can -safely skip this document. - -For fundamental background information about container managed security, -see the <a href="http://java.sun.com/products/servlet/download.html">Servlet -Specification (Version 2.4)</a>, Section 12. - -For information about utilizing the Single Sign On feature of -JBoss Web (allowing a user to authenticate themselves once across the entire -set of web applications associated with a virtual host), see -<a href="config/host.html#Single Sign On">here</a>. - -</section> - - -<section name="Overview"> - - -<subsection name="What is a Realm?"> - -A Realm is a "database" of usernames and passwords that -identify valid users of a web application (or set of web applications), plus -an enumeration of the list of roles associated with each valid user. -You can think of roles as similar to groups in Unix-like operating -systems, because access to specific web application resources is granted to -all users possessing a particular role (rather than enumerating the list of -associated usernames). A particular user can have any number of roles -associated with their username. - -Although the Servlet Specification describes a portable mechanism for -applications to declare their security requirements (in the -<code>web.xml</code> deployment descriptor), there is no portable API -defining the interface between a servlet container and the associated user -and role information. In many cases, however, it is desireable to "connect" -a servlet container to some existing authentication database or mechanism -that already exists in the production environment. Therefore, JBoss Web -defines a Java interface (<code>org.apache.catalina.Realm</code>) that -can be implemented by "plug in" components to establish this connection. -Five standard plug-ins are provided, supporting connections to various -sources of authentication information: -<ul> -<li><a href="#JDBCRealm">JDBCRealm</a> - Accesses authentication information - stored in a relational database, accessed via a JDBC driver.</li> -<li><a href="#DataSourceRealm">DataSourceRealm</a> - Accesses authentication - information stored in a relational database, accessed via a named JNDI - JDBC DataSource.</li> -<li><a href="#JNDIRealm">JNDIRealm</a> - Accesses authentication information - stored in an LDAP based directory server, accessed via a JNDI provider. - </li> -<li><a href="#MemoryRealm">MemoryRealm</a> - Accesses authentication - information stored in an in-memory object collection, which is initialized - from an XML document (<code>conf/tomcat-users.xml</code>).</li> -<li><a href="#JAASRealm">JAASRealm</a> - Accesses authentication information - through the Java Authentication & Authorization Service (JAAS) - framework.</li> -</ul> - -It is also possible to write your own <code>Realm</code> implementation, -and integrate it with JBoss Web. To do so, you need to: -<ul> - <li>Implement <code>org.apache.catalina.Realm</code>,</li> - <li>Place your compiled realm in $CATALINA_HOME/server/lib,</li> - <li>Declare your realm as described in the "Configuring a Realm" section below,</li> - <li>Declare your realm to the <a href="mbeans-descriptor-howto.html">MBeans Descriptor</a>.</li> -</ul> - - -</subsection> - - -<subsection name="Configuring a Realm"> - -Before getting into the details of the standard Realm implementations, it is -important to understand, in general terms, how a Realm is configured. In -general, you will be adding an XML element to your <code>conf/server.xml</code> -configuration file, that looks something like this: - -<source> -<Realm className="... class name for this implementation" - ... other attributes for this implementation .../> -</source> - -The <code><Realm></code> element can be nested inside any one of -of the following <code>Container</code> elements. The location of the -Realm element has a direct impact on the "scope" of that Realm -(i.e. which web applications will share the same authentication information): - -<ul> -<li>Inside an <Engine> element - This Realm will be shared - across ALL web applications on ALL virtual hosts, UNLESS it is overridden - by a Realm element nested inside a subordinate <code><Host></code> - or <code><Context></code> element.</li> -<li>Inside a <Host> element - This Realm will be shared across - ALL web applications for THIS virtual host, UNLESS it is overridden - by a Realm element nested inside a subordinate <code><Context></code> - element.</li> -<li>Inside a <Context> element - This Realm will be used ONLY - for THIS web application.</li> -</ul> - - -</subsection> - - -</section> - - -<section name="Common Features"> - - -<subsection name="Digested Passwords"> - -For each of the standard <code>Realm</code> implementations, the -user's password (by default) is stored in clear text. In many -environments, this is undesireable because casual observers of the -authentication data can collect enough information to log on -successfully, and impersonate other users. To avoid this problem, the -standard implementations support the concept of digesting -user passwords. This allows the stored version of the passwords to be -encoded (in a form that is not easily reversible), but that the -<code>Realm</code> implementation can still utilize for -authentication. - -When a standard realm authenticates by retrieving the stored -password and comparing it with the value presented by the user, you -can select digested passwords by specifying the <code>digest</code> -attribute on your <code><Realm></code> element. The value for -this attribute must be one of the digest algorithms supported by the -<code>java.security.MessageDigest</code> class (SHA, MD2, or MD5). -When you select this option, the contents of the password that is -stored in the <code>Realm</code> must be the cleartext version of the -password, as digested by the specified algorithm. - -When the <code>authenticate()</code> method of the Realm is called, the -(cleartext) password specified by the user is itself digested by the same -algorithm, and the result is compared with the value returned by the -<code>Realm</code>. An equal match implies that the cleartext version of the -original password is the same as the one presented by the user, so that this -user should be authorized. - -To calculate the digested value of a cleartext password, two convenience -techniques are supported: -<ul> -<li>If you are writing an application that needs to calculate digested - passwords dynamically, call the static <code>Digest()</code> method of the - <code>org.apache.catalina.realm.RealmBase</code> class, passing the - cleartext password and the digest algorithm name as arguments. This - method will return the digested password.</li> -<li>If you want to execute a command line utility to calculate the digested - password, simply execute -<source> -java org.apache.catalina.realm.RealmBase \ - -a {algorithm} {cleartext-password} -</source> - and the digested version of this cleartext password will be returned to - standard output.</li> -</ul> - -If using digested passwords with DIGEST authentication, the cleartext used - to generate the digest is different. In the examples above - <code>{cleartext-password}</code> must be replaced with - <code>{username}:{realm}:{cleartext-password}</code>. For example, in a - development environment this might take the form - <code>testUser:localhost:8080:testPassword</code>. - -To use either of the above techniques, the -<code>$CATALINA_HOME/lib/catalina.jar</code> and -<code>$CATALINA_HOME/bin/tomcat-juli.jar</code> files will need to be -on your class path to make the <code>RealmBase</code> class available. - - -Non-ASCII usernames and/or passwords are supported using -<source>java org.apache.catalina.realm.RealmBase \ - -a {algorithm} -e {encoding} {input} -</source> -but care is required to ensure that the non-ASCII input is -correctly passed to the digester. -The digester returns <code>{input}:{digest}</code>. If the input appears -corrupted in the return, the digest will be invalid. - -</subsection> - - - -<subsection name="Example Application"> - -The example application shipped with JBoss Web includes an area that is -protected by a security constraint, utilizing form-based login. To access it, -point your browser at -<a href="http://localhost:8080/examples/jsp/security/protected/">http://localhost:8080/examples/jsp/security/protected/</a> -and log on with one of the usernames and passwords described for the default -<a href="#MemoryRealm">MemoryRealm</a>. - -</subsection> - - -<subsection name="Manager Application"> - -If you wish to use the <a href="manager-howto.html">Manager Application</a> -to deploy and undeploy applications in a running JBoss Web installation, you -MUST add the "manager" role to at least one username in your selected Realm -implementation. This is because the manager web application itself uses a -security constraint that requires role "manager" to access ANY request URI -within that application. - -For security reasons, no username in the default Realm (i.e. using -<code>conf/tomcat-users.xml</code> is assigned the "manager" role. Therfore, -no one will be able to utilize the features of this application until the -JBoss Web administrator specifically assigns this role to one or more users. - -</subsection> - -<subsection name="Realm Logging"> - -Debugging and exception messages logged by a <code>Realm</code> will - be recorded by the logging configuration associated with the container - for the realm: its surrounding <a href="config/context.html">Context</a>, - <a href="config/host.html">Host</a>, or - <a href="config/engine.html">Engine</a>. - -</subsection> - -</section> - - -<section name="Standard Realm Implementations"> - -<subsection name="JDBCRealm"> - -<h3>Introduction</h3> - -JDBCRealm is an implementation of the JBoss Web -<code>Realm</code> interface that looks up users in a relational database -accessed via a JDBC driver. There is substantial configuration flexibility -that lets you adapt to existing table and column names, as long as your -database structure conforms to the following requirements: -<ul> -<li>There must be a table, referenced below as the users table, - that contains one row for every valid user that this <code>Realm</code> - should recognize.</li> -<li>The users table must contain at least two columns (it may - contain more if your existing applications required it): - <ul> - <li>Username to be recognized by JBoss Web when the user logs in.</li> - <li>Password to be recognized by JBoss Web when the user logs in. - This value may in cleartext or digested - see below for more - information.</li> - </ul></li> -<li>There must be a table, referenced below as the user roles table, - that contains one row for every valid role that is assigned to a - particular user. It is legal for a user to have zero, one, or more than - one valid role.</li> -<li>The user roles table must contain at least two columns (it may - contain more if your existing applications required it): - <ul> - <li>Username to be recognized by JBoss Web (same value as is specified - in the users table).</li> - <li>Role name of a valid role associated with this user.</li> - </ul></li> -</ul> - -<h3>Quick Start</h3> - -To set up JBoss Web to use JDBCRealm, you will need to follow these steps: -<ol> -<li>If you have not yet done so, create tables and columns in your database - that conform to the requirements described above.</li> -<li>Configure a database username and password for use by JBoss Web, that has - at least read only access to the tables described above. (JBoss Web will - never attempt to write to these tables.)</li> -<li>Place a copy of the JDBC driver you will be using inside the - <code>$CATALINA_HOME/lib</code> directory. - Note that only JAR files are recognized!</li> -<li>Set up a <code><Realm></code> element, as described below, in your - <code>$CATALINA_HOME/conf/server.xml</code> file.</li> -<li>Restart JBoss Web if it is already running.</li> -</ol> - -<h3>Realm Element Attributes</h3> - -To configure JDBCRealm, you will create a <code><Realm></code> -element and nest it in your <code>$CATALINA_HOME/conf/server.xml</code> file, -as described <a href="#Configuring a Realm">above</a>. The following -attributes are supported by this implementation: - -<attributes> - - <attribute name="className" required="true"> - The fully qualified Java class name of this Realm implementation. - You MUST specify the value - "<code>org.apache.catalina.realm.JDBCRealm</code>" here. - </attribute> - - <attribute name="connectionName" required="true"> - The database username used to establish a JDBC connection. - </attribute> - - <attribute name="connectionPassword" required="true"> - The database password used to establish a JDBC connection. - </attribute> - - <attribute name="connectionURL" required="true"> - The database URL used to establish a JDBC connection. - </attribute> - - <attribute name="digest" required="false"> - The digest algorithm used to store passwords in non-plaintext formats. - Valid values are those accepted for the algorithm name by the - <code>java.security.MessageDigest</code> class. See - <a href="#Digested Passwords">Digested Passwords</a> for more - information. If not specified, passwords are stored in clear text. - </attribute> - - <attribute name="driverName" required="true"> - The fully qualified Java class name of the JDBC driver to be used. - Consult the documentation for your JDBC driver for the appropriate - value. - </attribute> - - <attribute name="roleNameCol" required="true"> - The name of the column, in the user roles table, that - contains the name of a role assigned to this user. - </attribute> - - <attribute name="userCredCol" required="true"> - The name of the column, in the users table, that contains - the password for this user (either in clear text, or digested if the - <code>digest</code> attribute is set). - </attribute> - - <attribute name="userNameCol" required="true"> - The name of the column, in the users and user roles - tables, that contains the username of this user. - </attribute> - - <attribute name="userRoleTable" required="true"> - The name of the table that contains one row for each role - assigned to a particular username. This table must include at - least the columns named by the <code>userNameCol</code> and - <code>roleNameCol</code> attributes. - </attribute> - - <attribute name="userTable" required="true"> - The name of the table that contains one row for each username - to be recognized by JBoss Web. This table must include at least the columns - named by the <code>userNameCol</code> and <code>userCredCol</code> - attributes. - </attribute> - -</attributes> - -<h3>Example</h3> - -An example SQL script to create the needed tables might look something -like this (adapt the syntax as required for your particular database): -<source> -create table users ( - user_name varchar(15) not null primary key, - user_pass varchar(15) not null -); - -create table user_roles ( - user_name varchar(15) not null, - role_name varchar(15) not null, - primary key (user_name, role_name) -); -</source> - -Example <code>Realm</code> elements are included (commented out) in the -default <code>$CATALINA_HOME/conf/server.xml</code> file. Here's an example -for using a MySQL database called "authority", configured with the tables -described above, and accessed with username "dbuser" and password "dbpass": -<source> -<Realm className="org.apache.catalina.realm.JDBCRealm" debug="99" - driverName="org.gjt.mm.mysql.Driver" - connectionURL="jdbc:mysql://localhost/authority?user=dbuser&amp;password=dbpass" - userTable="users" userNameCol="user_name" userCredCol="user_pass" - userRoleTable="user_roles" roleNameCol="role_name"/> -</source> - -<h3>Additional Notes</h3> - -JDBCRealm operates according to the following rules: -<ul> -<li>When a user attempts to access a protected resource for the first time, - JBoss Web will call the <code>authenticate()</code> method of this - <code>Realm</code>. Thus, any changes you have made to the database - directly (new users, changed passwords or roles, etc.) will be immediately - reflected.</li> -<li>Once a user has been authenticated, the user (and his or her associated - roles) are cached within JBoss Web for the duration of the user's login. - (For FORM-based authentication, that means until the session times out or - is invalidated; for BASIC authentication, that means until the user - closes their browser). The cached user is not saved and - restored across sessions serialisations. Any changes to the database - information for an already authenticated user will not be - reflected until the next time that user logs on again.</li> -<li>Administering the information in the users and user roles - table is the responsibility of your own applications. JBoss Web does not - provide any built-in capabilities to maintain users and roles.</li> -</ul> - -</subsection> - - -<subsection name="DataSourceRealm"> - -<h3>Introduction</h3> - -DataSourceRealm is an implementation of the JBoss Web -<code>Realm</code> interface that looks up users in a relational database -accessed via a JNDI named JDBC DataSource. There is substantial configuration -flexibility that lets you adapt to existing table and column names, as long -as your database structure conforms to the following requirements: -<ul> -<li>There must be a table, referenced below as the users table, - that contains one row for every valid user that this <code>Realm</code> - should recognize.</li> -<li>The users table must contain at least two columns (it may - contain more if your existing applications required it): - <ul> - <li>Username to be recognized by JBoss Web when the user logs in.</li> - <li>Password to be recognized by JBoss Web when the user logs in. - This value may in cleartext or digested - see below for more - information.</li> - </ul></li> -<li>There must be a table, referenced below as the user roles table, - that contains one row for every valid role that is assigned to a - particular user. It is legal for a user to have zero, one, or more than - one valid role.</li> -<li>The user roles table must contain at least two columns (it may - contain more if your existing applications required it): - <ul> - <li>Username to be recognized by JBoss Web (same value as is specified - in the users table).</li> - <li>Role name of a valid role associated with this user.</li> - </ul></li> -</ul> - -<h3>Quick Start</h3> - -To set up JBoss Web to use DataSourceRealm, you will need to follow these steps: -<ol> -<li>If you have not yet done so, create tables and columns in your database - that conform to the requirements described above.</li> -<li>Configure a database username and password for use by JBoss Web, that has - at least read only access to the tables described above. (JBoss Web will - never attempt to write to these tables.)</li> -<li>Configure a JNDI named JDBC DataSource for your database. Refer to the - <a href="jndi-datasource-examples-howto.html">JNDI DataSource Example HOW-TO</a> - for information on how to configure a JNDI named JDBC DataSource.</li> -<li>Set up a <code><Realm></code> element, as described below, in your - <code>$CATALINA_HOME/conf/server.xml</code> file.</li> -<li>Restart JBoss Web if it is already running.</li> -</ol> - -<h3>Realm Element Attributes</h3> - -To configure DataSourceRealm, you will create a <code><Realm></code> -element and nest it in your <code>$CATALINA_HOME/conf/server.xml</code> file, -as described <a href="#Configuring a Realm">above</a>. The following -attributes are supported by this implementation: - -<attributes> - - <attribute name="className" required="true"> - The fully qualified Java class name of this Realm implementation. - You MUST specify the value - "<code>org.apache.catalina.realm.DataSourceRealm</code>" here. - </attribute> - - <attribute name="dataSourceName" required="true"> - The JNDI named JDBC DataSource for your database. If the DataSource is - local to the context, the name is relative to <code>java:/comp/env</code>, - and otherwise the name should match the name used to define the global - DataSource. - </attribute> - - <attribute name="digest" required="false"> - The digest algorithm used to store passwords in non-plaintext formats. - Valid values are those accepted for the algorithm name by the - <code>java.security.MessageDigest</code> class. See - <a href="#Digested Passwords">Digested Passwords</a> for more - information. If not specified, passwords are stored in clear text. - </attribute> - - <attribute name="localDataSource" required="false"> - When the realm is nested inside a Context element, this allows the - realm to use a DataSource defined for the Context rather than a global - DataSource. If not specified, the default is <code>false</code>: use a - global DataSource. - </attribute> - - <attribute name="roleNameCol" required="true"> - The name of the column, in the user roles table, that - contains the name of a role assigned to this user. - </attribute> - - <attribute name="userCredCol" required="true"> - The name of the column, in the users table, that contains - the password for this user (either in clear text, or digested if the - <code>digest</code> attribute is set). - </attribute> - - <attribute name="userNameCol" required="true"> - The name of the column, in the users and user roles - tables, that contains the username of this user. - </attribute> - - <attribute name="userRoleTable" required="true"> - The name of the table that contains one row for each role - assigned to a particular username. This table must include at - least the columns named by the <code>userNameCol</code> and - <code>roleNameCol</code> attributes. - </attribute> - - <attribute name="userTable" required="true"> - The name of the table that contains one row for each username - to be recognized by JBoss Web. This table must include at least the columns - named by the <code>userNameCol</code> and <code>userCredCol</code> - attributes. - </attribute> - -</attributes> - -<h3>Example</h3> - -An example SQL script to create the needed tables might look something -like this (adapt the syntax as required for your particular database): -<source> -create table users ( - user_name varchar(15) not null primary key, - user_pass varchar(15) not null -); - -create table user_roles ( - user_name varchar(15) not null, - role_name varchar(15) not null, - primary key (user_name, role_name) -); -</source> - -Here is an example for using a MySQL database called "authority", configured -with the tables described above, and accessed with the JNDI JDBC DataSource with -name "java:/comp/env/jdbc/authority". -<source> -<Realm className="org.apache.catalina.realm.DataSourceRealm" debug="99" - dataSourceName="jdbc/authority" - userTable="users" userNameCol="user_name" userCredCol="user_pass" - userRoleTable="user_roles" roleNameCol="role_name"/> -</source> - -<h3>Additional Notes</h3> - -DataSourceRealm operates according to the following rules: -<ul> -<li>When a user attempts to access a protected resource for the first time, - JBoss Web will call the <code>authenticate()</code> method of this - <code>Realm</code>. Thus, any changes you have made to the database - directly (new users, changed passwords or roles, etc.) will be immediately - reflected.</li> -<li>Once a user has been authenticated, the user (and his or her associated - roles) are cached within JBoss Web for the duration of the user's login. - (For FORM-based authentication, that means until the session times out or - is invalidated; for BASIC authentication, that means until the user - closes their browser). The cached user is not saved and - restored across sessions serialisations. Any changes to the database - information for an already authenticated user will not be - reflected until the next time that user logs on again.</li> -<li>Administering the information in the users and user roles - table is the responsibility of your own applications. JBoss Web does not - provide any built-in capabilities to maintain users and roles.</li> -</ul> - -</subsection> - - -<subsection name="JNDIRealm"> - -<h3>Introduction</h3> - -JNDIRealm is an implementation of the JBoss Web -<code>Realm</code> interface that looks up users in an LDAP directory -server accessed by a JNDI provider (typically, the standard LDAP -provider that is available with the JNDI API classes). The realm -supports a variety of approaches to using a directory for -authentication. - -<h4>Connecting to the directory</h4> - -The realm's connection to the directory is defined by the -connectionURL configuration attribute. This is a URL -whose format is defined by the JNDI provider. It is usually an LDAP -URL that specifies the domain name of the directory server to connect -to, and optionally the port number and distinguished name (DN) of the -required root naming context. - -If you have more than one provider you can configure an -alternateURL. If a socket connection can not be -made to the provider at the connectionURL an -attempt will be made to use the alternateURL. - -When making a connection in order to search the directory and -retrieve user and role information, the realm authenticates itself to -the directory with the username and password specified by the -connectionName and -connectionPassword properties. If these properties -are not specified the connection is anonymous. This is sufficient in -many cases. - - - -<h4>Selecting the user's directory entry</h4> - -Each user that can be authenticated must be represented in the -directory by an individual entry that corresponds to an element in the -initial <code>DirContext</code> defined by the -connectionURL attribute. This user entry must have an -attribute containing the username that is presented for -authentication. - -Often the distinguished name of the user's entry contains the -username presented for authentication but is otherwise the same for -all users. In this case the userPattern attribute may -be used to specify the DN, with "{0}" marking where -the username should be substituted. - -Otherwise the realm must search the directory to find a unique entry -containing the username. The following attributes configure this -search: - - <ul> - <li>userBase - the entry that is the base of - the subtree containing users. If not specified, the search - base is the top-level context.</li> - - <li>userSubtree - the search scope. Set to - <code>true</code> if you wish to search the entire subtree - rooted at the userBase entry. The default value - of <code>false</code> requests a single-level search - including only the top level.</li> - - <li>userSearch - pattern specifying the LDAP - search filter to use after substitution of the username.</li> - - </ul> - - - -<h4>Authenticating the user</h4> - -<ul> -<li> -Bind mode - -By default the realm authenticates a user by binding to -the directory with the DN of the entry for that user and the password -presented by the user. If this simple bind succeeds the user is considered to -be authenticated. - -For security reasons a directory may store a digest of the user's -password rather than the clear text version (see <a href="#Digested -Passwords">Digested Passwords</a> for more information). In that case, -as part of the simple bind operation the directory automatically -computes the correct digest of the plaintext password presented by the -user before validating it against the stored value. In bind mode, -therefore, the realm is not involved in digest processing. The -digest attribute is not used, and will be ignored if -set. -</li> - -<li> -Comparison mode -Alternatively, the realm may retrieve the stored -password from the directory and compare it explicitly with the value -presented by the user. This mode is configured by setting the -userPassword attribute to the name of a directory -attribute in the user's entry that contains the password. - -Comparison mode has some disadvantages. First, the -connectionName and -connectionPassword attributes must be configured to -allow the realm to read users' passwords in the directory. For -security reasons this is generally undesirable; indeed many directory -implementations will not allow even the directory manager to read -these passwords. In addition, the realm must handle password digests -itself, including variations in the algorithms used and ways of -representing password hashes in the directory. However, the realm may -sometimes need access to the stored password, for example to support -HTTP Digest Access Authentication (RFC 2069). (Note that HTTP digest -authentication is different from the storage of password digests in -the repository for user information as discussed above). - -</li> -</ul> - -<h4>Assigning roles to the user</h4> - -The directory realm supports two approaches to the representation -of roles in the directory: - -<ul> -<li> -Roles as explicit directory entries - -Roles may be represented by explicit directory entries. A role -entry is usually an LDAP group entry with one attribute -containing the name of the role and another whose values are the -distinguished names or usernames of the users in that role. The -following attributes configure a directory search to -find the names of roles associated with the authenticated user: - -<ul> -<li>roleBase - the base entry for the role search. - If not specified, the search base is the top-level directory - context.</li> - -<li>roleSubtree - the search - scope. Set to <code>true</code> if you wish to search the entire - subtree rooted at the <code>roleBase</code> entry. The default - value of <code>false</code> requests a single-level search - including the top level only.</li> - -<li>roleSearch - the LDAP search filter for - selecting role entries. It optionally includes pattern - replacements "{0}" for the distinguished name and/or "{1}" for the - username of the authenticated user.</li> - -<li>roleName - the attribute in a role entry - containing the name of that role.</li> - -</ul> - -</li> -</ul> - -<ul> -<li> -Roles as an attribute of the user entry - -Role names may also be held as the values of an attribute in the -user's directory entry. Use userRoleName to specify -the name of this attribute. - -</li> -</ul> -A combination of both approaches to role representation may be used. - -<h3>Quick Start</h3> - -To set up JBoss Web to use JNDIRealm, you will need to follow these steps: -<ol> -<li>Make sure your directory server is configured with a schema that matches - the requirements listed above.</li> -<li>If required, configure a username and password for use by JBoss Web, that has - read only access to the information described above. (JBoss Web will - never attempt to modify this information.)</li> -<li>Place a copy of the JNDI driver you will be using (typically - <code>ldap.jar</code> available with JNDI) inside the - <code>$CATALINA_HOME/lib</code> directory.</li> -<li>Set up a <code><Realm></code> element, as described below, in your - <code>$CATALINA_HOME/conf/server.xml</code> file.</li> -<li>Restart JBoss Web if it is already running.</li> -</ol> - -<h3>Realm Element Attributes</h3> - -To configure JNDIRealm, you will create a <code><Realm></code> -element and nest it in your <code>$CATALINA_HOME/conf/server.xml</code> file, -as described <a href="#Configuring a Realm">above</a>. The following -attributes are supported by this implementation: - -<attributes> - <attribute name="className" required="true"> - The fully qualified Java class name of this Realm implementation. - You MUST specify the value - "<code>org.apache.catalina.realm.JNDIRealm</code>" here. - </attribute> - - - <attribute name="connectionName" required="false"> - The directory username to use when establishing a - connection to the directory for LDAP search operations. If not - specified an anonymous connection is made, which is often - sufficient unless you specify the <code>userPassword</code> - property. - </attribute> - - <attribute name="connectionPassword" required="false"> - The directory password to use when establishing a - connection to the directory for LDAP search operations. If not - specified an anonymous connection is made, which is often - sufficient unless you specify the <code>userPassword</code> - property. - </attribute> - - <attribute name="connectionURL" required="true"> - The connection URL to be passed to the JNDI driver when - establishing a connection to the directory. - </attribute> - - <attribute name="contextFactory" required="false"> - The fully qualified Java class name of the JNDI context - factory to be used for this connection. By default, the standard - JNDI LDAP provider is used - (<code>com.sun.jndi.ldap.LdapCtxFactory</code>). - </attribute> - - <attribute name="digest" required="false"> - The digest algorithm to apply to the plaintext password offered - by the user before comparing it with the value retrieved from the - directory. Valid values are those accepted for the algorithm name - by the <code>java.security.MessageDigest</code> class. See <a - href="#Digested Passwords">Digested Passwords</a> for more - information. If not specified the plaintext password is assumed to - be retrieved. Not required unless <code>userPassword</code> is - specified - </attribute> - - <attribute name="roleBase" required="false"> - The base directory entry for performing role searches. If - not specified, the top level element in the directory context - will be used. - </attribute> - - <attribute name="roleName" required="false"> - The name of the attribute that contains role names in the - directory entries found by a role search. In addition you can - use the <code>userRoleName</code> property to specify the name - of an attribute, in the user's entry, containing additional - role names. If <code>roleName</code> is not specified a role - search does not take place, and roles are taken only from the - user's entry. - </attribute> - - <attribute name="roleSearch" required="false"> - The LDAP filter expression used for performing role - searches, following the syntax supported by the - <code>java.text.MessageFormat</code> class. Use - <code>{0}</code> to substitute the distinguished name (DN) of - the user, and/or <code>{1}</code> to substitute the - username. If not specified a role search does not take place - and roles are taken only from the attribute in the user's - entry specified by the <code>userRoleName</code> property. - </attribute> - - <attribute name="roleSubtree" required="false"> - Set to <code>true</code> if you want to search the entire - subtree of the element specified by the <code>roleBase</code> - property for role entries associated with the user. The - default value of <code>false</code> causes only the top level - to be searched. - </attribute> - - <attribute name="userBase" required="false"> - The base element for user searches performed using the - <code>userSearch</code> expression. If not specified, the top - level element in the directory context will be used. Not used - if you are using the <code>userPattern</code> expression. - </attribute> - - <attribute name="userPassword" required="false"> - Name of the attribute in the user's entry containing the - user's password. If you specify this value, JNDIRealm will - bind to the directory using the values specified by - <code>connectionName</code> and - <code>connectionPassword</code> properties, and retrieve the - corresponding attribute for comparison to the value specified - by the user being authenticated. If the <code>digest</code> - attribute is set, the specified digest algorithm is applied to - the password offered by the user before comparing it with the - value retrieved from the directory. If you do - not specify this value, JNDIRealm will - attempt a simple bind to the directory using the DN of the - user's entry and password specified by the user, with a - successful bind being interpreted as an authenticated - user. - </attribute> - - <attribute name="userPattern" required="false"> - A pattern for the distinguished name (DN) of the user's - directory entry, following the syntax supported by the - <code>java.text.MessageFormat</code> class with - <code>{0}</code> marking where the actual username should be - inserted. You can use this property instead of - <code>userSearch</code>, <code>userSubtree</code> and - <code>userBase</code> when the distinguished name contains the - username and is otherwise the same for all users. - </attribute> - - <attribute name="userRoleName" required="false"> - The name of an attribute in the user's directory entry - containing zero or more values for the names of roles assigned - to this user. In addition you can use the - <code>roleName</code> property to specify the name of an - attribute to be retrieved from individual role entries found - by searching the directory. If <code>userRoleName</code> is - not specified all the roles for a user derive from the role - search. - </attribute> - - <attribute name="userSearch" required="false"> - The LDAP filter expression to use when searching for a - user's directory entry, with <code>{0}</code> marking where - the actual username should be inserted. Use this property - (along with the <code>userBase</code> and - <code>userSubtree</code> properties) instead of - <code>userPattern</code> to search the directory for the - user's entry. - </attribute> - - <attribute name="userSubtree" required="false"> - Set to <code>true</code> if you want to search the entire - subtree of the element specified by the <code>userBase</code> - property for the user's entry. The default value of - <code>false</code> causes only the top level to be searched. - Not used if you are using the <code>userPattern</code> - expression. - </attribute> - -</attributes> - -<h3>Example</h3> - -Creation of the appropriate schema in your directory server is beyond the -scope of this document, because it is unique to each directory server -implementation. In the examples below, we will assume that you are using a -distribution of the OpenLDAP directory server (version 2.0.11 or later), which -can be downloaded from -<a href="http://www.openldap.org">http://www.openldap.org</a>. Assume that -your <code>slapd.conf</code> file contains the following settings -(among others): -<source> -database ldbm -suffix dc="mycompany",dc="com" -rootdn "cn=Manager,dc=mycompany,dc=com" -rootpw secret -</source> - -We will assume for <code>connectionURL</code> that the directory -server runs on the same machine as JBoss Web. See <a -href="http://java.sun.com/products/jndi/docs.html">http://java.sun.com/products/jndi/docs.html</a> -for more information about configuring and using the JNDI LDAP -provider. - -Next, assume that this directory server has been populated with elements -as shown below (in LDIF format): - -<source> - -# Define top-level entry -dn: dc=mycompany,dc=com -objectClass: dcObject -dc:mycompany - -# Define an entry to contain people -# searches for users are based on this entry -dn: ou=people,dc=mycompany,dc=com -objectClass: organizationalUnit -ou: people - -# Define a user entry for Janet Jones -dn: uid=jjones,ou=people,dc=mycompany,dc=com -objectClass: inetOrgPerson -uid: jjones -sn: jones -cn: janet jones -mail: j.jones(a)mycompany.com -userPassword: janet - -# Define a user entry for Fred Bloggs -dn: uid=fbloggs,ou=people,dc=mycompany,dc=com -objectClass: inetOrgPerson -uid: fbloggs -sn: bloggs -cn: fred bloggs -mail: f.bloggs(a)mycompany.com -userPassword: fred - -# Define an entry to contain LDAP groups -# searches for roles are based on this entry -dn: ou=groups,dc=mycompany,dc=com -objectClass: organizationalUnit -ou: groups - -# Define an entry for the "tomcat" role -dn: cn=tomcat,ou=groups,dc=mycompany,dc=com -objectClass: groupOfUniqueNames -cn: tomcat -uniqueMember: uid=jjones,ou=people,dc=mycompany,dc=com -uniqueMember: uid=fbloggs,ou=people,dc=mycompany,dc=com - -# Define an entry for the "role1" role -dn: cn=role1,ou=groups,dc=mycompany,dc=com -objectClass: groupOfUniqueNames -cn: role1 -uniqueMember: uid=fbloggs,ou=people,dc=mycompany,dc=com -</source> - -An example <code>Realm</code> element for the OpenLDAP directory -server configured as described above might look like this, assuming -that users use their uid (e.g. jjones) to login to the -application and that an anonymous connection is sufficient to search -the directory and retrieve role information: - -<source> -<Realm className="org.apache.catalina.realm.JNDIRealm" debug="99" - connectionURL="ldap://localhost:389" - userPattern="uid={0},ou=people,dc=mycompany,dc=com" - roleBase="ou=groups,dc=mycompany,dc=com" - roleName="cn" - roleSearch="(uniqueMember={0})" -/> -</source> - -With this configuration, the realm will determine the user's -distinguished name by substituting the username into the -<code>userPattern</code>, authenticate by binding to the directory -with this DN and the password received from the user, and search the -directory to find the user's roles. - -Now suppose that users are expected to enter their email address -rather than their userid when logging in. In this case the realm must -search the directory for the user's entry. (A search is also necessary -when user entries are held in multiple subtrees corresponding perhaps -to different organizational units or company locations). - -Further, suppose that in addition to the group entries you want to -use an attribute of the user's entry to hold roles. Now the entry for -Janet Jones might read as follows: - -<source> -dn: uid=jjones,ou=people,dc=mycompany,dc=com -objectClass: inetOrgPerson -uid: jjones -sn: jones -cn: janet jones -mail: j.jones(a)mycompany.com -memberOf: role2 -memberOf: role3 -userPassword: janet -</source> - - This realm configuration would satisfy the new requirements: - -<source> -<Realm className="org.apache.catalina.realm.JNDIRealm" debug="99" - connectionURL="ldap://localhost:389" - userBase="ou=people,dc=mycompany,dc=com" - userSearch="(mail={0})" - userRoleName="memberOf" - roleBase="ou=groups,dc=mycompany,dc=com" - roleName="cn" - roleSearch="(uniqueMember={0})" -/> -</source> - -Now when Janet Jones logs in as "j.jones(a)mycompany.com", the realm -searches the directory for a unique entry with that value as its mail -attribute and attempts to bind to the directory as -<code>uid=jjones,ou=people,dc=mycompany,dc=com</code> with the given -password. If authentication succeeds, she is assigned three roles: -"role2" and "role3", the values of the "memberOf" attribute in her -directory entry, and "tomcat", the value of the "cn" attribute in the -only group entry of which she is a member. - -Finally, to authenticate the user by retrieving -the password from the directory and making a local comparison in the -realm, you might use a realm configuration like this: - -<source> -<Realm className="org.apache.catalina.realm.JNDIRealm" debug="99" - connectionName="cn=Manager,dc=mycompany,dc=com" -connectionPassword="secret" - connectionURL="ldap://localhost:389" - userPassword="userPassword" - userPattern="uid={0},ou=people,dc=mycompany,dc=com" - roleBase="ou=groups,dc=mycompany,dc=com" - roleName="cn" - roleSearch="(uniqueMember={0})" -/> -</source> - -However, as discussed above, the default bind mode for -authentication is usually to be preferred. - -<h3>Additional Notes</h3> - -JNDIRealm operates according to the following rules: -<ul> -<li>When a user attempts to access a protected resource for the first time, - JBoss Web will call the <code>authenticate()</code> method of this - <code>Realm</code>. Thus, any changes you have made to the directory - (new users, changed passwords or roles, etc.) will be immediately - reflected.</li> -<li>Once a user has been authenticated, the user (and his or her associated - roles) are cached within JBoss Web for the duration of the user's login. - (For FORM-based authentication, that means until the session times out or - is invalidated; for BASIC authentication, that means until the user - closes their browser). The cached user is not saved and - restored across sessions serialisations. Any changes to the directory - information for an already authenticated user will not be - reflected until the next time that user logs on again.</li> -<li>Administering the information in the directory server - is the responsibility of your own applications. JBoss Web does not - provide any built-in capabilities to maintain users and roles.</li> -</ul> - -</subsection> - - -<subsection name="MemoryRealm"> - -<h3>Introduction</h3> - -MemoryRealm is a simple demonstration implementation of the -JBoss Web <code>Realm</code> interface. It is not designed for production use. -At startup time, MemoryRealm loads information about all users, and their -corresponding roles, from an XML document (by default, this document is loaded from <code>$CATALINA_HOME/conf/tomcat-users.xml</code>). Changes to the data -in this file are not recognized until JBoss Web is restarted. - -<h3>Realm Element Attributes</h3> - -To configure MemoryRealm, you will create a <code><Realm></code> -element and nest it in your <code>$CATALINA_HOME/conf/server.xml</code> file, -as described <a href="#Configuring a Realm">above</a>. The following -attributes are supported by this implementation: - -<attributes> - - <attribute name="className" required="true"> - The fully qualified Java class name of this Realm implementation. - You MUST specify the value - "<code>org.apache.catalina.realm.MemoryRealm</code>" here. - </attribute> - - <attribute name="digest" required="false"> - The digest algorithm used to store passwords in non-plaintext formats. - Valid values are those accepted for the algorithm name by the - <code>java.security.MessageDigest</code> class. See - <a href="#Digested Passwords">Digested Passwords</a> for more - information. If not specified, passwords are stored in clear text. - </attribute> - - <attribute name="pathname" required="false"> - Absolute or relative (to $CATALINA_HOME) pathname of the XML document - containing our valid usernames, passwords, and roles. See below for more - information on the format of this file. If not specified, the value - <code>conf/tomcat-users.xml</code> is used. - </attribute> - -</attributes> - -<h3>User File Format</h3> - -The users file (by default, <code>conf/tomcat-users.xml</code> must be an -XML document, with a root element <code><tomcat-users></code>. Nested -inside the root element will be a <code><user></code> element for each -valid user, consisting of the following attributes: -<ul> -<li>name - Username this user must log on with.</li> -<li>password - Password this user must log on with (in - clear text if the <code>digest</code> attribute was not set on the - <code><Realm></code> element, or digested appropriately as - described <a href="#Digested Passwords">here</a> otherwise).</li> -<li>roles - Comma-delimited list of the role names - associated with this user.</li> -</ul> - -<h3>Example</h3> - -The default installation of JBoss Web is configured with a MemoryRealm -nested inside the <code><Engine></code> element, so that it applies -to all virtual hosts and web applications. The default contents of the -<code>conf/tomcat-users.xml</code> file is: -<source> -<tomcat-users> - <user name="tomcat" password="tomcat" roles="tomcat" /> - <user name="role1" password="tomcat" roles="role1" /> - <user name="both" password="tomcat" roles="tomcat,role1" /> -</tomcat-users> -</source> - -<h3>Additional Notes</h3> - -MemoryRealm operates according to the following rules: -<ul> -<li>When JBoss Web first starts up, it loads all defined users and their - associated information from the users file. Changes to the data in - this file will not be recognized until JBoss Web is - restarted.</li> -<li>When a user attempts to access a protected resource for the first time, - JBoss Web will call the <code>authenticate()</code> method of this - <code>Realm</code>.</li> -<li>Once a user has been authenticated, the user (and his or her associated - roles) are cached within JBoss Web for the duration of the user's login. - (For FORM-based authentication, that means until the session times out or - is invalidated; for BASIC authentication, that means until the user - closes their browser). The cached user is not saved and - restored across sessions serialisations.</li> -<li>Administering the information in the users file is the responsibility - of your application. JBoss Web does not - provide any built-in capabilities to maintain users and roles.</li> -</ul> - - -</subsection> - - -<subsection name="JAASRealm"> - -<h3>Introduction</h3> - - JAASRealm is an implementation of the JBoss Web -4 <code>Realm</code> interface that authenticates users through the Java -Authentication & Authorization Service (JAAS) framework, a Java -package that is available as an optional package in Java 2 SDK 1.3 and -is fully integrated as of SDK 1.4 . - Using JAASRealm gives the developer the ability to combine -practically any conceivable security realm with JBoss Web's CMA. - JAASRealm is prototype for JBoss Web of the proposed JAAS-based -J2EE authentication framework for J2EE v1.4, based on the <a - href="http://www.jcp.org/en/jsr/detail?id=196">JCP Specification -Request 196</a> to enhance container-managed security and promote -'pluggable' authentication mechanisms whose implementations would be -container-independent. - - Based on the JAAS login module and principal (see <code>javax.security.auth.spi.LoginModule</code> -and <code>javax.security.Principal</code>), you can develop your own -security mechanism or wrap another third-party mechanism for -integration with the CMA as implemented by JBoss Web. - - - <h3>Quick Start</h3> - To set up JBoss Web to use JAASRealm with your own JAAS login module, - you will need to follow these steps: - <ol> - <li>Write your own LoginModule, User and Role classes based -on JAAS (see -<a href="http://java.sun.com/j2se/1.4.1/docs/guide/security/jaas/tutorials/General...">the -JAAS Authentication Tutorial</a> and -<a href="http://java.sun.com/j2se/1.4.1/docs/guide/security/jaas/JAASLMDevGuide.html">the JAAS Login Module -Developer's Guide</a>) to be managed by the JAAS Login -Context (<code>javax.security.auth.login.LoginContext</code>) -When developing your LoginModule, note that JAASRealm's built-in <code>CallbackHandler</code> -+only recognizes the <code>NameCallback</code> and <code>PasswordCallback</code> at present. - </li> - <li>Although not specified in JAAS, you should create -seperate classes to distinguish between users and roles, extending <code>javax.security.Principal</code>, -so that JBoss Web can tell which Principals returned from your login -module are users and which are roles (see <code>org.apache.catalina.realm.JAASRealm</code>). -Regardless, the first Principal returned is always treated as the user Principal. - </li> - <li>Place the compiled classes on JBoss Web's classpath - </li> - <li>Set up a login.config file for Java (see <a - href="http://java.sun.com/j2se/1.4.1/docs/guide/security/jaas/tutorials/LoginCo...">JAAS -LoginConfig file</a>) and tell JBoss Web where to find it by specifying -its location to the JVM, for instance by setting the environment -variable: <code>JAVA_OPTS=-DJAVA_OPTS=-Djava.security.auth.login.config==$CATALINA_HOME/conf/jaas.config</code></li> - - <li>Configure your security-constraints in your web.xml for -the resources you want to protect</li> - <li>Configure the JAASRealm module in your server.xml </li> - <li>Restart JBoss Web if it is already running.</li> - </ol> - <h3>Realm Element Attributes</h3> - To configure JAASRealm as for step 6 above, you create -a <code><Realm></code> element and nest it in your -<code>$CATALINA_HOME/conf/server.xml</code> -file within your <code><Engine></code> node. The following attributes -are supported by this implementation: - -<attributes> - - <attribute name="className" required="true"> - The fully qualified Java class name of this Realm implementation. - You MUST specify the value - "<code>org.apache.catalina.realm.JAASRealm</code>" here. - </attribute> - - <attribute name="appName" required="true"> - The name of the application as configured in your login configuration file - (<a href="http://java.sun.com/j2se/1.4.1/docs/guide/security/jaas/tutorials/LoginCo...">JAAS LoginConfig</a>). - </attribute> - - <attribute name="userClassNames" required="true"> - A comma-seperated list of the names of the classes that you have made - for your user <code>Principals</code>. - </attribute> - - <attribute name="roleClassNames" required="false"> - A comma-seperated list of the names of the classes that you have made - for your role <code>Principals</code>. - </attribute> - - <attribute name="useContextClassLoader" required="false"> - Instructs JAASRealm to use the context class loader for loading the user-specified - <code>LoginModule</code> class and associated <code>Principal</code> classes. The - default value is <code>true</code>, which is backwards-compatible with the way - Tomcat 4 works. To load classes using the container's classloader, specify - <code>false</code>. - </attribute> - -</attributes> - -<h3>Example</h3> - -Here is an example of how your server.xml snippet should look. - -<source> -<Realm className="org.apache.catalina.realm.JAASRealm" - appName="MyFooRealm" - userClassNames="org.foobar.realm.FooUser" - roleClassNames="org.foobar.realm.FooRole" - debug="99"/> -</source> - -It is the responsibility of your login module to create and save User and -Role objects representing Principals for the user -(<code>javax.security.auth.Subject</code>). If your login module doesn't -create a user object but also doesn't throw a login exception, then the -JBoss Web CMA will break and you will be left at the -http://localhost:8080/myapp/j_security_check URI or at some other -unspecified location. - - The flexibility of the JAAS approach is two-fold: - <ul> - <li>you can carry out whatever processing you require behind -the scenes in your own login module.</li> - <li>you can plug in a completely different LoginModule by changing the configuration -and restarting the server, without any code changes to your application.</li> - </ul> - - <h3>Additional Notes</h3> - <ul> - <li>When a user attempts to access a protected resource for - the first time, JBoss Web will call the <code>authenticate()</code> - method of this <code>Realm</code>. Thus, any changes you have made in - the security mechanism directly (new users, changed passwords or - roles, etc.) will be immediately reflected.</li> - <li>Once a user has been authenticated, the user (and his or - her associated roles) are cached within JBoss Web for the duration of - the user's login. For FORM-based authentication, that means until - the session times out or is invalidated; for BASIC authentication, - that means until the user closes their browser. Any changes to the - security information for an already authenticated user will not - be reflected until the next time that user logs on again.</li> - <li>As with other <code>Realm</code> implementations, digested passwords - are supported if the <code><Realm></code> element in <code>server.xml</code> - contains a <code>digest</code> attribute; JAASRealm's <code>CallbackHandler</code> - will digest the password prior to passing it back to the <code>LoginModule</code></li> - </ul> - -</subsection> - - -<subsection name="CombinedRealm"> - - <h3>Introduction</h3> - - CombinedRealm is an implementation of the - <code>Realm</code> interface that authenticates users through one or more - sub-Realms. - - Using CombinedRealm gives the developer the ability to combine multiple - Realms of the same or different types. This can be used to authenticate - against different sources, provide fall back in case one Realm fails or for - any other purpose that requires multiple Realms. - - Sub-realms are defined by nesting <code>Realm</code> elements inside the - <code>Realm</code> element that defines the CombinedRealm. Authentication - will be attempted against each <code>Realm</code> in the order they are - listed. Authentication against any Realm will be sufficient to authenticate - the user. - - <h3>Realm Element Attributes</h3> - To configure CombinedRealm, you create a <code><Realm></code> - element and nest it in your <code>$CATALINA_BASE/conf/server.xml</code> - file within your <code><Engine></code> or <code><Host></code>. - You can also nest inside a <code><Context></code> node in a - <code>context.xml</code> file. The following attributes are supported by - this implementation: - -<attributes> - - <attribute name="className" required="true"> - The fully qualified Java class name of this Realm implementation. - You MUST specify the value - "<code>org.apache.catalina.realm.CombinedRealm</code>" here. - </attribute> - -</attributes> - -<h3>Example</h3> - -Here is an example of how your server.xml snippet should look to use a -UserDatabase Realm and a DataSource Realm. - -<source> -<Realm className="org.apache.catalina.realm.CombinedRealm" > - <Realm className="org.apache.catalina.realm.UserDatabaseRealm" - resourceName="UserDatabase"/> - <Realm className="org.apache.catalina.realm.DataSourceRealm" debug="99" - dataSourceName="jdbc/authority" - userTable="users" userNameCol="user_name" userCredCol="user_pass" - userRoleTable="user_roles" roleNameCol="role_name"/> -<Realm/> -</source> - -</subsection> - -</section> - -</body> - -</document> Deleted: trunk/webapps/docs/ssi-howto.xml =================================================================== --- trunk/webapps/docs/ssi-howto.xml 2011-09-08 14:43:49 UTC (rev 1831) +++ trunk/webapps/docs/ssi-howto.xml 2011-09-08 16:06:13 UTC (rev 1832) @@ -1,375 +0,0 @@ -<?xml version="1.0"?> -<!DOCTYPE document [ - <!ENTITY project SYSTEM "project.xml"> -]> -<document url="ssi-howto.html"> - -&project; - -<properties> -<author email="glenn(a)apache.org">Glenn L. Nielsen</author> -<title>SSI How To</title> -</properties> - -<body> - -<section name="Introduction"> - -SSI (Server Side Includes) are directives that are placed in HTML pages, -and evaluated on the server while the pages are being served. They let you -add dynamically generated content to an existing HTML page, without having -to serve the entire page via a CGI program, or other dynamic technology. - - -Within JBoss Web SSI support can be added when using JBoss Web as your -HTTP server and you require SSI support. Typically this is done -during development when you don't want to run a web server like Apache. - -JBoss Web SSI support implements the same SSI directives as Apache. See the -<a href="http://httpd.apache.org/docs/howto/ssi.html#basicssidirectives"> -Apache Introduction to SSI</a> for information on using SSI directives. - -SSI support is available as a servlet and as a filter. You should use one -or the other to provide SSI support but not both. - -Servlet based SSI support is implemented using the class -<code>org.apache.catalina.ssi.SSIServlet</code>. Traditionally, this servlet -is mapped to the URL pattern "*.shtml". - -Filter based SSI support is implemented using the class -<code>org.apache.catalina.ssi.SSIFilter</code>. Traditionally, this filter -is mapped to the URL pattern "*.shtml", though it can be mapped to "*" as -it will selectively enable/disable SSI processing based on mime types. The -contentType init param allows you to apply SSI processing to JSP pages, -javascript, or any other content you wish. -By default SSI support is disabled in JBoss Web. -</section> - -<section name="Installation"> - -CAUTION - SSI directives can be used to execute programs -external to the JBoss Web JVM. If you are using the Java SecurityManager this -will bypass your security policy configuration in <code>catalina.policy.</code> - - -To use the SSI servlet, remove the XML comments from around the SSI servlet -and servlet-mapping configuration in -<code>$CATALINA_BASE/conf/web.xml</code>. - -To use the SSI filter, remove the XML comments from around the SSI filter -and filter-mapping configuration in -<code>$CATALINA_BASE/conf/web.xml</code>. - -Only Contexts which are marked as privileged may use SSI features (see the -privileged property of the Context element). - -</section> - -<section name="Servlet Configuration"> - -There are several servlet init parameters which can be used to -configure the behaviour of the SSI servlet. -<ul> -<li>buffered - Should output from this servlet be buffered? -(0=false, 1=true) Default 0 (false).</li> -<li>debug - Debugging detail level for messages logged -by this servlet. Default 0.</li> -<li>expires - The number of seconds before a page with SSI -directives will expire. Default behaviour is for all SSI directives to be -evaluated for every request.</li> -<li>isVirtualWebappRelative - Should "virtual" SSI directive -paths be interpreted as relative to the context root, instead of the server -root? (0=false, 1=true) Default 0 (false).</li> -<li>inputEncoding - The encoding to be assumed for SSI -resources if one cannot be determined from the resource itself. Default is -the default platform encoding.</li> -<li>outputEncoding - The encoding to be used for the result -of the SSI processing. Default is UTF-8.</li> -<li>allowExec - Allow SSI exec. Default is false.</li> -</ul> - - -</section> - -<section name="Filter Configuration"> - -There are several filter init parameters which can be used to -configure the behaviour of the SSI filter. -<ul> -<li>contentType - A regex pattern that must be matched before -SSI processing is applied. When crafting your own pattern, don't forget that a -mime content type may be followed by an optional character set in the form -"mime/type; charset=set" that you must take into account. Default is -"text/x-server-parsed-html(;.*)?".</li> -<li>debug - Debugging detail level for messages logged -by this servlet. Default 0.</li> -<li>expires - The number of seconds before a page with SSI -directives will expire. Default behaviour is for all SSI directives to be -evaluated for every request.</li> -<li>isVirtualWebappRelative - Should "virtual" SSI directive -paths be interpreted as relative to the context root, instead of the server -root? (0=false, 1=true) Default 0 (false).</li> -<li>allowExec - Allow SSI exec. Default is false.</li> -</ul> - - -</section> - -<section name="Directives"> -Server Side Includes are invoked by embedding SSI directives in an HTML document - whose type will be processed by the SSI servlet. The directives take the form of an HTML - comment. The directive is replaced by the results of interpreting it before sending the - page to the client. The general form of a directive is: - <code></code> -The directives are: -<ul> -<li> -config - <code></code> -Used to set the format of dates and other items processed by SSI -</li> -<li> -echo - <code></code> -will be replaced bt the value of the variable. -</li> -<li> -exec - Used to run commands on the host system. -</li> -<li> -include - <code></code> -inserts the contents -</li> -<li> -flastmod - <code></code> -Returns the time that a file was lost modified. -</li> -<li> -fsize - <code></code> -Returns the size of a file. -</li> -<li> -printenv - <code></code> -Returns the list of all the defined variables. -</li> -<li> -set - <code></code> -is used to assign a value to a user-defind variable. -</li> -<li> -if elif endif else - Used to create conditional sections. For example:</li> -<code> -  - Meeting at 10:00 on Mondays -  - Turn in your time card -  - Yoga class at noon. - </code> - </ul> - -See the - <a href="http://httpd.apache.org/docs/howto/ssi.html#basicssidirectives"> -Apache Introduction to SSI</a> for more information on using SSI directives. -</section> - -<section name="Variables"> -The SSI servlet currently implements the following variables: - -<table border="1"> -<tr> -<th>Variable Name</th> -<th>Description</th> -</tr> - -<tr> -<td>AUTH_TYPE</td> -<td> - The type of authentication used for this user: BASIC, FORM, etc.</td> -</tr> - -<tr> -<td>CONTENT_LENGTH</td> -<td> - The length of the data (in bytes or the number of - characters) passed from a form.</td> -</tr> - -<tr> -<td>CONTENT_TYPE</td> -<td> - The MIME type of the query data, such as "text/html".</td> -</tr> - -<tr> -<td>DATE_GMT</td> -<td> -Current date and time in GMT</td> -</tr> - -<tr> -<td>DATE_LOCAL</td> -<td> -Current date and time in the local time zone</td> -</tr> -<tr> -<td>DOCUMENT_NAME</td> -<td> -The current file</td> -</tr> -<tr> -<td>DOCUMENT_URI</td> -<td> -Virtual path to the file</td> -</tr> - -<tr> -<td>GATEWAY_INTERFACE</td> -<td> - The revision of the Common Gateway Interface that the - server uses if enabled: "CGI/1.1".</td> -</tr> - -<tr> -<td>HTTP_ACCEPT</td> -<td> - A list of the MIME types that the client can accept.</td> -</tr> - -<tr> -<td>HTTP_ACCEPT_ENCODING</td> -<td> - A list of the compression types that the client can accept.</td> -</tr> - -<tr> -<td>HTTP_ACCEPT_LANGUAGE</td> -<td> - A list of the laguages that the client can accept.</td> -</tr> -<tr> -<td>HTTP_CONNECTION</td> -<td> - The way that the connection from the client is being managed: - "Close" or "Keep-Alive".</td> -</tr> -<tr> -<td>HTTP_HOST</td> -<td> - The web site that the client requested.</td> -</tr> -<tr> -<td>HTTP_REFERER</td> -<td> - The URL of the document that the client linked from.</td> -</tr> -<tr> -<td>HTTP_USER_AGENT</td> -<td> - The browser the client is using to issue the request.</td> -</tr> -<tr> -<td>LAST_MODIFIED</td> -<td> -Last modification date and time for current file</td> -</tr> -<tr> -<td>PATH_INFO</td> -<td> - Extra path information passed to a servlet.</td> -</tr> -<tr> -<td>PATH_TRANSLATED</td> -<td> - The translated version of the path given by the - variable PATH_INFO.</td> -</tr> -<tr> -<td>QUERY_STRING</td> -<td> -The query string that follows the "?" in the URL. -</td> -</tr> -<tr> -<td>QUERY_STRING_UNESCAPED</td> -<td> -Undecoded query string with all shell metacharacters escaped -with "\"</td> -</tr> -<tr> -<td>REMOTE_ADDR</td> -<td> - The remote IP address of the user making the request.</td> -</tr> -<tr> -<td>REMOTE_HOST</td> -<td> - The remote hostname of the user making the request.</td> -</tr> -<tr> -<td>REMOTE_PORT</td> -<td> - The port number at remote IP address of the user making the request.</td> -</tr> -<tr> -<td>REMOTE_USER</td> -<td> - The authenticated name of the user.</td> -</tr> -<tr> -<td>REQUEST_METHOD</td> -<td> - The method with which the information request was - issued: "GET", "POST" etc.</td> -</tr> -<tr> -<td>REQUEST_URI</td> -<td> - The web page originally requested by the client.</td> -</tr> -<tr> -<td>SCRIPT_FILENAME</td> -<td> - The location of the current web page on the server.</td> -</tr> -<tr> -<td>SCRIPT_NAME</td> -<td> - The name of the web page.</td> -</tr> -<tr> -<td>SERVER_ADDR</td> -<td> - The server's IP address.</td> -</tr> -<tr> -<td>SERVER_NAME</td> -<td> - The server's hostname or IP address.</td> -</tr> -<tr> -<td>SERVER_PORT</td> -<td> - The port on which the server received the request.</td> -</tr> -<tr> -<td>SERVER_PROTOCOL</td> -<td> - The protocol used by the server. E.g. "HTTP/1.1".</td> -</tr> -<tr> -<td>SERVER_SOFTWARE</td> -<td> - The name and version of the server software that is - answering the client request.</td> -</tr> -<tr> -<td>UNIQUE_ID</td> -<td> - A token used to identify the current session if one - has been established.</td> -</tr> -</table> -</section> - -</body> - -</document>

12 years, 9 months

1
0
0 / 0

JBossWeb SVN: r1831 - trunk/webapps/docs.

by jbossweb-commits＠lists.jboss.org

Author: jfrederic.clere(a)jboss.com Date: 2011-09-08 10:43:49 -0400 (Thu, 08 Sep 2011) New Revision: 1831 Removed: trunk/webapps/docs/setup.xml Log: TC doc. Deleted: trunk/webapps/docs/setup.xml =================================================================== --- trunk/webapps/docs/setup.xml 2011-08-31 08:20:29 UTC (rev 1830) +++ trunk/webapps/docs/setup.xml 2011-09-08 14:43:49 UTC (rev 1831) @@ -1,136 +0,0 @@ -<?xml version="1.0"?> -<!DOCTYPE document [ - <!ENTITY project SYSTEM "project.xml"> -]> -<document url="setup.html"> - - &project; - - <properties> - <author email="remm(a)apache.org">Remy Maucherat</author> - <title>JBoss Web Setup</title> - </properties> - -<body> - - <section name="Introduction"> - - This document introduces several ways to set up JBoss Web for running - on different platforms. Please note that some advanced setup issues - are not covered here: the full distribution (ZIP file or tarball) - includes a file called - RUNNING.txt which discusses these issues. We encourage you to refer - to it if the information below does not answer some of your questions. - - </section> - - <section name="Windows"> - - - Installing JBoss Web on Windows can be done easily using the Windows - installer. Its interface and functionality is similar to other wizard - based installers, with only a few items of interest. - NOT YET SUPPORTED in 3.0.x - - - - <ul> - <li>Installation as a service: JBoss Web will be - installed as a Windows - NT/2k/XP service no matter what setting is selected. Using the - checkbox on the component page sets the service as "auto" - startup, so that JBoss Web is automatically started when Windows - starts. For optimal security, the service should be run as a - separate user, with reduced permissions (see the Windows Services - administration tool and its documentation).</li> - <li>Java location: The installer will use the registry - or the JAVA_HOME environment variable to determine the base path - of a J2SE 5 JRE. - </li> - <li>Tray icon: When JBoss Web is run as a service, there - will not be any tray icon present when JBoss Web is running. Note that - when choosing to run JBoss Web at the end of installation, the tray - icon will be used even if JBoss Web was installed as a service.</li> - <li>Refer to the - <a href="windows-service-howto.html">Windows Service HOW-TO</a> - for information on how to manage JBoss Web as Windows NT service. - </li> - </ul> - - - The installer will create shortcuts allowing starting and configuring - JBoss Web. It is important to note that the JBoss Web administration web - application can only be used when JBoss Web is running. - - </section> - - <section name="Unix daemon"> - - JBoss Web can be run as a daemon using the jsvc tool from the - commons-daemon project. Source tarballs for jsvc are included with the - JBoss Web binaries, and need to be compiled. Building jsvc requires - a C ANSI compiler (such as GCC), GNU Autoconf, and a JDK. - - Before running the script, the <code>JAVA_HOME</code> environment - variable should be set to the base path of the JDK. Alternately, when - calling the <code>./configure</code> script, the path of the JDK may - be specified using the <code>--with-java</code> parameter, such as - <code>./configure --with-java=/usr/java</code>. - - Using the following commands should result in a compiled jsvc binary, - located in the <code>$CATALINA_HOME/bin</code> folder. This assumes - that GNU TAR is used, and that <code>CATALINA_HOME</code> is an - environment variable pointing to the base path of the JBoss Web - installation. - - Please note that you should use the GNU make (gmake) instead of - the native BSD make on FreeBSD systems. - - Download a commons-daemon binary from the Jakarta Commons download page, - and place jsvc.tar.gz and commons-daemon.jar in the - <code>$CATALINA_HOME/bin</code> folder. - -<source> - cd $CATALINA_HOME/bin - tar xvfz jsvc.tar.gz - cd jsvc-src - autoconf - ./configure - make - cp jsvc .. - cd .. -</source> - - JBoss Web can then be run as a daemon using the following commands. - -<source> - cd $CATALINA_HOME - ./bin/jsvc -cp ./bin/bootstrap.jar \ - -outfile ./logs/catalina.out -errfile ./logs/catalina.err \ - org.apache.catalina.startup.Bootstrap -</source> - - jsvc has other useful parameters, such as <code>-user</code> which - causes it to switch to another user after the daemon initialization is - complete. This allows, for example, running JBoss Web as a non privileged - user while still being able to use privileged ports. - <code>jsvc --help</code> will return the full jsvc usage - information. In particular, the <code>-debug</code> option is useful - to debug issues running jsvc. - - The file <code>$CATALINA_HOME/bin/jsvc/native/tomcat.sh</code> can be - used as a template for starting JBoss Web automatically at boot time from - <code>/etc/init.d</code>. The file is currently setup for running - Tomcat 4.1.x, so it is necessary to edit it and change the classname - from <code>BootstrapService</code> to <code>Bootstrap</code>. - - Note that the Commons-Daemon JAR file must be on your runtime classpath - to run JBoss Web in this manner. The Commons-Daemon JAR file is in the Class-Path - entry of the bootstrap.jar manifest, but if you get a ClassNotFoundException - or a NoClassDefFoundError for a Commons-Daemon class, add the Commons-Daemon - JAR to the -cp argument when launching jsvc. - - </section> - -</body> -</document>

12 years, 9 months

1
0
0 / 0

← Newer
1
2
Older →

2024

2023

2022

2021

2020

2019

2018

2017

2016

2015

2014

2013

2012

2011

2010

2009

2008

2007

jbossweb-commits September 2011