9:39 a.m.
Author: jfrederic.clere(a)jboss.com
Date: 2011-07-06 10:39:25 -0400 (Wed, 06 Jul 2011)
New Revision: 1774
Modified:
trunk/webapps/docs/appdev/deployment.xml
trunk/webapps/docs/appdev/installation.xml
trunk/webapps/docs/appdev/introduction.xml
trunk/webapps/docs/appdev/processes.xml
trunk/webapps/docs/appdev/source.xml
trunk/webapps/docs/building.xml
trunk/webapps/docs/config/host.xml
Log:
Arrange the webapp doc example... Note that webapp itself need to be arranged too.
Modified: trunk/webapps/docs/appdev/deployment.xml
===================================================================
--- trunk/webapps/docs/appdev/deployment.xml 2011-07-06 11:30:20 UTC (rev 1773)
+++ trunk/webapps/docs/appdev/deployment.xml 2011-07-06 14:39:25 UTC (rev 1774)
@@ -8,6 +8,7 @@
<properties>
<author email="craigmcc(a)apache.org">Craig R.
McClanahan</author>
+ <author email="jfclere(a)apache.org">Jean-Frederic
Clere</author>
<title>Deployment</title>
</properties>
@@ -36,7 +37,7 @@
files and JSP pages that comprise your application's user interface. When the
system administrator deploys your application into a particular server, he
or she assigns a <em>context path</em> to your application (a later section
-of this manual describes deployment on Tomcat). Thus, if the
+of this manual describes deployment on JBossWeb). Thus, if the
system administrator assigns your application to the context path
<code>/catalog</code>, then a request URI referring to
<code>/catalog/index.html</code> will retrieve the
<code>index.html</code>
@@ -49,7 +50,7 @@
<p>To facilitate creation of a Web Application Archive file in the required
format, it is convenient to arrange the "executable" files of your web
-application (that is, the files that Tomcat actually uses when executing
+application (that is, the files that JBossWeb actually uses when executing
your app) in the same organization as required by the WAR format itself.
To do this, you will end up with the following contents in your
application's "document root" directory:</p>
@@ -68,6 +69,11 @@
security constraints that you want the server to enforce for you.
This file is discussed in more detail in the following subsection.
<br/><br/></li>
+<li><strong>/WEB-INF/jboss-web.xml</strong> - The <em>JBoss Web
Application Deployment
+ Descriptor</em> for your application. This is an XML file describing the
+ JBossWeb extensions to <strong>/WEB-INF/web.xml</strong>.
+ See <a href="./jbossweb.html">jboss-web.xml</a> for more.
+ <br/><br/></li>
<li><strong>/WEB-INF/classes/</strong> - This directory contains any
Java
class files (and associated resources) required for your application,
including both servlet and non-servlet classes, that are not combined
@@ -102,30 +108,14 @@
<section name="Shared Library Files">
-<p>Like most servlet containers, Tomcat 5 also supports mechanisms to install
-library JAR files (or unpacked classes) once, and make them visible to all
-installed web applications (without having to be included inside the web
-application itself. The details of how Tomcat locates and shares such
-classes are described in the
-<a href="../class-loader-howto.html">Class Loader HOW-TO</a>
documentation.
-For the purposes of our discussion, there are two locations that are commonly
-used within a Tomcat 5 installation for shared code:</p>
-<ul>
-<li><strong>$CATALINA_HOME/common/lib</strong> - JAR files placed here
are
- visible both to web applications and internal Tomcat code. This is a
- good place to put JDBC drivers that are required for both your application
- and internal Tomcat use (such as for a JDBCRealm).
- <br/><br/></li>
-<li><strong>$CATALINA_BASE/shared/lib</strong> - JAR files placed here
are
- visible to all web applications, but not to internal Tomcat code. This
- is the right place for shared libraries that are specific to your
- application.<br/><br/></li>
-</ul>
+<p>If you want to share libraries between webapps put them in a ear file
+with the libraries you want to share.
+</p>
-<p>Out of the box, a standard Tomcat 5 installation includes a variety
+<p>Out of the box, a standard JBossWeb installation includes a variety
of pre-installed shared library files, including:</p>
<ul>
-<li>The <em>Servlet 2.4</em> and <em>JSP 2.0</em> APIs that
are fundamental
+<li>The <em>Servlet 3.0</em> and <em>JSP 2.2</em> APIs that
are fundamental
to writing servlets and JavaServer Pages.<br/><br/></li>
<li>An <em>XML Parser</em> compliant with the JAXP (version 1.2) APIs,
so
your application can perform DOM-based or SAX-based processing of
@@ -137,16 +127,6 @@
<section name="Web Application Deployment Descriptor">
- <blockquote><em>
- <p>The description below uses the variable name $CATALINA_HOME
- to refer to the directory into which you have installed Tomcat 5,
- and is the base directory against which most relative paths are
- resolved. However, if you have configured Tomcat 5 for multiple
- instances by setting a CATALINA_BASE directory, you should use
- $CATALINA_BASE instead of $CATALINA_HOME for each of these
- references.</p>
- </em></blockquote>
-
<p>As mentioned above, the <code>/WEB-INF/web.xml</code> file contains
the
Web Application Deployment Descriptor for your application. As the filename
extension implies, this file is an XML document, and defines everything about
@@ -155,7 +135,7 @@
deployed).</p>
<p>The complete syntax and semantics for the deployment descriptor is defined
-in Chapter 13 of the Servlet API Specification, version 2.3. Over time, it
+in Chapter 13 of the Servlet API Specification, version 3.0. Over time, it
is expected that development tools will be provided that create and edit the
deployment descriptor for you. In the meantime, to provide a starting point,
a <a href="web.xml.txt" target="_new">basic web.xml
file</a>
@@ -164,7 +144,7 @@
<p><strong>NOTE</strong> - The Servlet Specification includes a
Document
Type Descriptor (DTD) for the web application deployment descriptor, and
-Tomcat 5 enforces the rules defined here when processing your application's
+JBossWeb enforces the rules defined here when processing your application's
<code>/WEB-INF/web.xml</code> file. In particular, you
<strong>must</strong>
enter your descriptor elements (such as <code><filter></code>,
<code><servlet></code>, and
<code><servlet-mapping></code> in
@@ -173,71 +153,49 @@
</section>
-<section name="Tomcat Context Descriptor">
+<section name="JBoss Web Application Deployment">
- <blockquote><em>
- <p>The description below uses the variable name $CATALINA_HOME
- to refer to the directory into which you have installed Tomcat 5,
- and is the base directory against which most relative paths are
- resolved. However, if you have configured Tomcat 5 for multiple
- instances by setting a CATALINA_BASE directory, you should use
- $CATALINA_BASE instead of $CATALINA_HOME for each of these
- references.</p>
- </em></blockquote>
-
-<p>A /META-INF/context.xml file can be used to define Tomcat specific
+<p>A /WEB-INF/jboss-web.xml file can be used to define JBossWeb specific
configuration options, such as loggers, data sources, session manager
-configuration and more. This XML file must contain one Context element, which
-will be considered as if it was the child of the Host element corresponding
-to the Host to which the The Tomcat configuration documentation contains
-information on the Context element.</p>
+configuration and more. This XML file is describe in <a
href="./jbossweb.html">jboss-web.xml</a>.
+</p>
</section>
-<section name="Deployment With Tomcat 5">
+<section name="Deployment With JBossWeb">
<p>In order to be executed, a web application must be deployed on
a servlet container. This is true even during development.
We will describe using Tomcat 5 to provide the execution environment.
-A web application can be deployed in Tomcat by one of the following
+A web application can be deployed in JBossWeb by one of the following
approaches:</p>
<ul>
<li><em>Copy unpacked directory hierarchy into a subdirectory in directory
- <code>$CATALINA_HOME/webapps/</code></em>. Tomcat will assign a
+ <code>${jboss.server.base.dir}/standalone/deployments/</code></em>.
JBossWeb will assign a
context path to your application based on the subdirectory name you
choose. We will use this technique in the <code>build.xml</code>
file that we construct, because it is the quickest and easiest approach
- during development. Be sure to restart Tomcat after installing or
- updating your application.
+ during development.
+ you have to create a file named like <code>myapp.war.dodeploy</code> to
+ start the deployement scanner on the myapp.war directory.
<br/><br/></li>
<li><em>Copy the web application archive file into directory
- <code>$CATALINA_HOME/webapps/</code></em>. When Tomcat is started,
it will
+ <code>${jboss.server.base.dir}/standalone/deployments/</code></em>.
When JBossWeb is started, it will
automatically expand the web application archive file into its unpacked
form, and execute the application that way. This approach would typically
be used to install an additional application, provided by a third party
vendor or by your internal development staff, into an existing
- Tomcat installation. <strong>NOTE</strong> - If you use this approach,
- and wish to update your application later, you must both replace the
- web application archive file <strong>AND</strong> delete the expanded
- directory that Tomcat created, and then restart Tomcat, in order to reflect
- your changes.
+ JBossWeb installation. The web-app will be automaticaly deployed.
<br/><br/></li>
-<li><em>Use the Tomcat 5 "Manager" web application to deploy and
undeploy
- web applications</em>. Tomcat 5 includes a web application, deployed
- by default on context path <code>/manager</code>, that allows you to
- deploy and undeploy applications on a running Tomcat server without
- restarting it. See the administrator documentation (TODO: hyperlink)
- for more information on using the Manager web
application.<br/><br/></li>
-<li><em>Use "Manager" Ant Tasks In Your Build Script</em>.
Tomcat 5
- includes a set of custom task definitions for the <code>Ant</code>
- build tool that allow you to automate the execution of commands to the
- "Manager" web application. These tasks are used in the Tomcat deployer.
+<li><em>Use the command line or the Web Management Interface of AS7.
+ web applications</em>. For example something like:
+<source>
+[standalone@localhost:9999 /] deploy /home/jfclere/jbossweb_sandbox/webapps/myapp.war
+'myapp.war' deployed successfully.
+</source>
+ In the above example <code>myapp.war</code> will be deployed under the
context <code>/myapp</code>
<br/><br/></li>
-<li><em>Use the Tomcat Deployer</em>. Tomcat 5 includes a packaged
tool
- bundling the Ant tasks, and can be used to automatically precompile JSPs
- which are part of the web application before deployment to the server.
- <br/><br/></li>
</ul>
<p>Deploying your app on other servlet containers will be specific to each
Modified: trunk/webapps/docs/appdev/installation.xml
===================================================================
--- trunk/webapps/docs/appdev/installation.xml 2011-07-06 11:30:20 UTC (rev 1773)
+++ trunk/webapps/docs/appdev/installation.xml 2011-07-06 14:39:25 UTC (rev 1774)
@@ -9,6 +9,7 @@
<properties>
<author email="craigmcc(a)apache.org">Craig R.
McClanahan</author>
<author email="yoavs(a)apache.org">Yoav Shapira</author>
+ <author email="jfclere(a)apache.org">Jean-Frederic
Clere</author>
<title>Installation</title>
</properties>
@@ -17,13 +18,13 @@
<section name="Installation">
-<p>In order to use Tomcat 6 for developing web applications, you must first
+<p>In order to use AS7 (JBossWeb) for developing web applications, you must first
install it (and the software it depends on). The required steps are outlined
in the following subsections.</p>
<subsection name="JDK">
-<p>Tomcat 6.0 was designed to run on J2SE 5.0.
+<p>AS7 was designed to run on J2SE 6.0.
</p>
<p>Compatible JDKs for many platforms (or links to where they can be found)
@@ -32,18 +33,14 @@
</subsection>
-<subsection name="Tomcat">
+<subsection name="AS7">
-<p>Binary downloads of the <strong>Tomcat</strong> server are available
from
-<a
href="http://tomcat.apache.org/download-60.cgi">http://tomca...;.
+<p>Binary downloads of the <strong>AS7</strong> server are available
from
+<a href="http://www.jboss.org/jbossas/downloads/">JBoss Application
Server downloads</a>.
This manual assumes you are using the most recent release
-of Tomcat 6. Detailed instructions for downloading and installing
-Tomcat 6 are available <a href="../setup.html">here</a>.</p>
+of AS7. Detailed instructions for downloading and installing
+AS7 are available <a
href="https://docs.jboss.org/author/display/AS7/Getting+Started+Deve...
-<p>In the remainder of this manual, example shell scripts assume that you have
-set an environment variable <code>CATALINA_HOME</code> that contains the
-pathname to the directory in which Tomcat 6 has been installed.</p>
-
</subsection>
Modified: trunk/webapps/docs/appdev/introduction.xml
===================================================================
--- trunk/webapps/docs/appdev/introduction.xml 2011-07-06 11:30:20 UTC (rev 1773)
+++ trunk/webapps/docs/appdev/introduction.xml 2011-07-06 14:39:25 UTC (rev 1774)
@@ -8,6 +8,7 @@
<properties>
<author email="craigmcc(a)apache.org">Craig R.
McClanahan</author>
+ <author email="jfclere(a)apache.org">Jean-Frederic
Clere</author>
<title>Introduction</title>
</properties>
@@ -37,6 +38,9 @@
Environment (IDE) tool, you will need to adapt the advice given here to
the details of your particular environment.</p>
+<p>See <a
href="https://docs.jboss.org/author/display/AS7/Getting+Started+Deve...
Started Developing Applications Guide</a> If you want to use Eclipse.
+</p>
+
</section>
@@ -44,10 +48,10 @@
<p>The following links provide access to selected sources of online
information, documentation, and software that is useful in developing
-web applications with Tomcat.</p>
+web applications with JBossWeb.</p>
<ul>
<li><a
href="http://java.sun.com/products/jsp/download.html">http:/...
-
- <i>JavaServer Pages (JSP) Specfication, Version 2.0</i>. Describes
+ <i>JavaServer Pages (JSP) Specfication, Version 2.2</i>. Describes
the programming environment provided by standard implementations
of the JavaServer Pages (JSP) technology. In conjunction with
the Servlet API Specification (see below), this document describes
@@ -57,7 +61,7 @@
API Documentation is included in the specification, and with the
Tomcat download.<br/><br/></li>
<li><a
href="http://java.sun.com/products/servlet/download.html">ht...
-
- <i>Servlet API Specification, Version 2.4</i>. Describes the
+ <i>Servlet API Specification, Version 3.0</i>. Describes the
programming environment that must be provided by all servlet
containers conforming to this specification. In particular, you
will need this document to understand the web application
@@ -74,7 +78,6 @@
chapters on servlet and JSP design are useful even when your application
does not require other J2EE platform components.
<br/><br/></li>
-<li><b>TODO</b> -- Add more entries here!</li>
</ul>
</section>
Modified: trunk/webapps/docs/appdev/processes.xml
===================================================================
--- trunk/webapps/docs/appdev/processes.xml 2011-07-06 11:30:20 UTC (rev 1773)
+++ trunk/webapps/docs/appdev/processes.xml 2011-07-06 14:39:25 UTC (rev 1774)
@@ -17,7 +17,7 @@
<section name="Development Processes">
<p>Although application development can take many forms, this manual proposes
-a fairly generic process for creating web applications using Tomcat. The
+a fairly generic process for creating web applications using JBossWeb. The
following sections highlight the commands and tasks that you, as the developer
of the code, will perform. The same basic approach works when you have
multiple programmers involved, as long as you have an appropriate source code
@@ -31,31 +31,6 @@
will need to figure out the corresponding commands for your system.</p>
-<subsection name="One-Time Setup of Ant and Tomcat for Development">
-
-<p>In order to take advantage of the special Ant tasks that interact with the
-<em>Manager</em> web application, you need to perform the following tasks
-once (no matter how many web applications you plan to develop).</p>
-<ul>
-<li><em>Configure the Ant custom tasks</em>. The implementation code
for the
- Ant custom tasks is in a JAR file named
- <code>$CATALINA_HOME/server/lib/catalina-ant.jar</code>, which must be
- copied in to the <code>lib</code> directory of your Ant installation.
- <br/><br/></li>
-<li><em>Define one or more Tomcat users</em>. The
<em>Manager</em> web
- application runs under a security constraint that requires a user to be
- logged in, and have the security role <code>manager</code> assigned to
- him or her. How such users are defined depends on which Realm you have
- configured in Tomcat's <code>conf/server.xml</code> file -- see the
- <a href="../realm-howto.html">Realm Configuration HOW-TO</a>
for more
- information. You may define any number of users (with any username
- and password that you like) with the <code>manager</code> role.
- <br/><br/></li>
-</ul>
-
-</subsection>
-
-
<subsection name="Create Project Source Code Directory">
<p>The first step is to create a new project source directory, and customize
@@ -111,7 +86,7 @@
directory. The supported properties are listed in the comments inside
the sample <code>build.xml</code> script. At a minimum, you will generally
need to define the <code>catalina.home</code> property defining where
-Tomcat 5 is installed, and the manager application username and password.
+JBossWeb is installed, and the manager application username and password.
You might end up with something like this:</p>
<source>
# Context path to install this application on
@@ -120,9 +95,6 @@
# Tomcat 5 installation directory
catalina.home=/usr/local/apache-tomcat-6.0
-# Manager webapp username and password
-manager.username=myusername
-manager.password=mypassword
</source>
<p>In general, you will <strong>not</strong> want to check the
@@ -224,12 +196,12 @@
<subsection name="Test Your Web Application">
-<p>To test your application, you will want to install it under Tomcat. The
+<p>To test your application, you will want to install it under JBossWeb. The
quickest way to do that is to use the custom Ant tasks that are included in
the sample <code>build.xml</code> script. Using these commands might follow
a pattern like this:</p>
<ul>
-<li><em>Start Tomcat 5 if needed</em>. If Tomcat 5 is not already
running,
+<li><em>Start JBossWeb if needed</em>. If JBossWeb is not already
running,
you will need to start it in the usual way.
<br/><br/></li>
<li><em>Compile your application</em>. Use the <code>ant
compile</code>
@@ -237,9 +209,9 @@
sure that there are no compilation errors.
<br/><br/></li>
<li><em>Install the application</em>. Use the <code>ant
install</code>
- command. This tells Tomcat to immediately start running your app on
+ command. This tells JBossWeb to immediately start running your app on
the context path defined in the <code>app.path</code> build property.
- Tomcat does <strong>NOT</strong> have to be restarted for this to
+ JBossWeb does <strong>NOT</strong> have to be restarted for this to
take effect.<br/><br/></li>
<li><em>Test the application</em>. Using your browser or other
testing
tools, test the functionality of your application.
@@ -251,7 +223,7 @@
be available to be saved (via <code>cvs commit</code>) later on --
the output build directory is deleted and recreated as necessary.
<br/><br/></li>
-<li><em>Reload the application</em>. Tomcat will recognize changes in
+<li><em>Reload the application</em>. JBossWeb will recognize changes
in
JSP pages automatically, but it will continue to use the old versions
of any servlet or JavaBean classes until the application is reloaded.
You can trigger this by executing the <code>ant reload</code> command.
Modified: trunk/webapps/docs/appdev/source.xml
===================================================================
--- trunk/webapps/docs/appdev/source.xml 2011-07-06 11:30:20 UTC (rev 1773)
+++ trunk/webapps/docs/appdev/source.xml 2011-07-06 14:39:25 UTC (rev 1774)
@@ -8,6 +8,7 @@
<properties>
<author email="craigmcc(a)apache.org">Craig R.
McClanahan</author>
+ <author email="jfclere(a)apache.org">Jean-Frederic
Clere</author>
<title>Source Organization</title>
</properties>
@@ -17,13 +18,9 @@
<section name="Directory Structure">
<blockquote><em>
- <p>The description below uses the variable name $CATALINA_HOME
- to refer to the directory into which you have installed Tomcat 5,
- and is the base directory against which most relative paths are
- resolved. However, if you have configured Tomcat 5 for multiple
- instances by setting a CATALINA_BASE directory, you should use
- $CATALINA_BASE instead of $CATALINA_HOME for each of these
- references.</p>
+ <p>The description below uses the variable name ${jboss.server.base.dir}
+ to refer to the directory into which you have installed AS7.
+ </p>
</em></blockquote>
<p>A key recommendation of this manual is to separate the directory
@@ -88,11 +85,10 @@
<li><strong>build/</strong> - When you execute a default build
(<code>ant</code>), this directory will contain an exact image
of the files in the web application archive for this application.
- Tomcat 5 allows you to deploy an application in an unpacked
+ JBossWeb allows you to deploy an application in an unpacked
directory like this, either by copying it to the
- <code>$CATALINA_HOME/webapps</code> directory, or by
<em>installing</em>
- it via the "Manager" web application. The latter approach is very
- useful during development, and will be illustrated below.
+ <code>$jboss.server.base.dir}/standalone/deployments</code> directory, or
by <em>installing</em>
+ it via the command line or the Web Management Interface of AS7.
<br/><br/></li>
<li><strong>dist/</strong> - When you execute the <code>ant
dist</code>
target, this directory will be created. It will create an exact image
@@ -137,12 +133,6 @@
developer can be customized on a per-application basis, or defaulted to
"standard" build properties stored in the developer's home
directory.</p>
- <p>In many cases, your development system administrator will have already
- installed the required JAR files into Tomcat 5's
<code>common/lib</code>
- or <code>shared/lib</code> directories. If this has been done, you need
- to take no actions at all - the example <code>build.xml</code> file
- automatically constructs a compile classpath that includes these files.</p>
-
</subsection>
</section>
@@ -276,22 +266,21 @@
</ul>
<p>For interactive development and testing of your web application using
-Tomcat 5, the following additional targets are defined:</p>
+JBossWeb 5, the following additional targets are defined:</p>
<ul>
-<li><strong>install</strong> - Tell the currently running Tomcat 5 to
make
+<li><strong>install</strong> - Tell the currently running JBossWeb to
make
the application you are developing immediately available for execution
- and testing. This action does not require Tomcat 5 to be restarted, but
- it is also not remembered after Tomcat is restarted the next time.
+ and testing. This action does not require JBossWeb to be restarted.
<br/><br/></li>
<li><strong>reload</strong> - Once the application is installed, you
can
continue to make changes and recompile using the <code>compile</code>
- target. Tomcat 5 will automatically recognize changes made to JSP pages,
- but not to servlet or JavaBean classes - this command will tell Tomcat
+ target. JBossWeb will automatically recognize changes made to JSP pages,
+ but not to servlet or JavaBean classes - this command will tell JBossWeb
to restart the currently installed application so that such changes are
recognized.
<br/><br/></li>
<li><strong>remove</strong> - When you have completed your development
and
- testing activities, you can optionally tell Tomcat 5 to remove this
+ testing activities, you can optionally tell JBossWeb to remove this
application from service.
</li>
</ul>
Modified: trunk/webapps/docs/building.xml
===================================================================
--- trunk/webapps/docs/building.xml 2011-07-06 11:30:20 UTC (rev 1773)
+++ trunk/webapps/docs/building.xml 2011-07-06 14:39:25 UTC (rev 1774)
@@ -94,7 +94,7 @@
<p>
NOTE: That build jar files in output/jars, the <code>jbossweb.jar</code>
-have to be copied in
<code>${jboss.server.data.dir)/modules/org/jboss/as/web/main</code> to be
+have to be copied in
<code>${jboss.server.base.dir)/modules/org/jboss/as/web/main</code> to be
used in AS7.
</p>
Modified: trunk/webapps/docs/config/host.xml
===================================================================
--- trunk/webapps/docs/config/host.xml 2011-07-06 11:30:20 UTC (rev 1773)
+++ trunk/webapps/docs/config/host.xml 2011-07-06 14:39:25 UTC (rev 1774)
@@ -100,7 +100,7 @@
<attributes>
<attribute name="relative-to" required="false">
<p>directory location based on the global path configuration in the domain
model.
- If not specified, it defaults to the JBoss Application data directory
(jboss.server.data.dir).</p>
+ If not specified, it defaults to the JBoss Application data directory
(jboss.server.base.dir).</p>
</attribute>
<attribute name="path" required="false">