![Introduction to Tomcat
[ ]
What's the story behind Tomcat?
As I write this, the most current version of Tomcat is 6.0.20, where 6 is the major
version, 0 is the minor version, and 20 is the bug fix release number. This version
implements, and is completely compliant with, version 2.5 of the Java Servlet
specification, and version 2.1 of the JavaServer Pages (JSP) specification.
That's a pretty hefty mouthful, so let's start at the beginning.
Every superhero has an origins story, and Tomcat is no exception. The Tomcat web
site lists the available versions at http://tomcat.apache.org/whichversion.html,
which shows the first stable release listed as Tomcat 3.x. So what happened to
versions 1 and 2?
Tomcat was conceived in November 1998 by James Duncan Davidson at Sun
Microsystems, who wrote it to form the core of the JavaServer Web Development
Kit (JSWDK) for the Servlet 2.1 specification.
The name 'Tomcat' came to him when he was trying to decide a package name for
the code he was working on. He ended up using com.sun.tomcat.
At the time, Apache JServ, a free servlet container, was in the process of being
updated to support the Servlet 2.1 specification.
However, this effort was abandoned due to the donation of Tomcat by Sun
Microsystems to the Apache Software Foundation, at JavaOne in 1999. It soon
came to life as Tomcat version 3.0, the successor to JSWDK 2.1.
This was a major milestone for the open source community as it meant that a
commercial package owned and developed by Sun Microsystems, and which
implemented the latest Servlet 2.2 and JSP 1.1 specifications, was now being
offered to the general public for free.
All of this made the decision to abandon Apache JServ rather uncontroversial.
The focus soon shifted from updating JServ to support the new specification, to
getting Tomcat to implement features that were missing. The most important
one being the ability to cooperate with the Apache web server. This was critical
to the popularity of Tomcat, as it meant that developers could leverage the static
file handling capabilities of the Apache web server together with the dynamic
capabilities of Tomcat to achieve a well rounded solution. Subsequent Tomcat
releases have actually strengthened this connection component.
In addition, Tomcat can now directly serve static content and so is often deployed
in standalone mode without a separate web server.
This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009
6393 south jamaica court, , englewood, , 80111](https://image.slidesharecdn.com/2054538-250602102958-91ea13b8/85/Download-full-ebook-of-Tomcat-6-Developers-Guide-Damodar-Chetty-instant-download-pdf-15-320.jpg)
![Chapter 1
[ ]
It is interesting to note that Tomcat began life not as its own top level project.
Instead, it started humbly as a subproject within the Jakarta project (an umbrella
project that covers many subprojects such as Apache Commons, Cactus, and JMeter).
It was only in 2005 that it was upgraded to the status of a top level project at Apache.
What exactly is Tomcat?
For most users, the typical web interaction can be represented as follows: Joe User
enters a Uniform Resource Locator (URL) in the browser's location box to request
the resource that is identified by that URL. A URL is composed of a host name, an
optional port (which defaults to 80), and the resource being requested.
When a web server receives that request, it first determines whether the resource
being requested is static or dynamic in nature.
A static resource is one that is identical no matter how many times, or in what order,
that resource is requested. Some examples of these would be a company's logo on a
web page, a CSS style sheet, or a typical HTML page.
The web server handles the request for a static resource by simply fetching the
identified resource from the appropriate path in which its static content resides (for
example, htdocs for Apache), and returning those bytes in the response to the user.
For static resources, a depiction of this request flow is as shown below.
Fetch Static resource
(html, css, gif, jpg, png ...)
Internet
Web Server
(IIS / Apache)
A dynamic resource, on the other hand, indicates a resource that varies its content
based on various factors that may include the specific user making the request, the
time of day when the request is made, or the presence of additional information
in the request that affects how the request is interpreted. Some examples of these
would include the current inventory for a specific product in an online store, or the
availability of a seat on an airplane.
Most web servers are tuned to deliver blazing fast request handling for static
resources. However, they require additional help when dealing with dynamic
resources. This help is typically provided by an additional software component that
is registered with the web server, called a servlet container on the Java EE platform.
This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009
6393 south jamaica court, , englewood, , 80111](https://image.slidesharecdn.com/2054538-250602102958-91ea13b8/85/Download-full-ebook-of-Tomcat-6-Developers-Guide-Damodar-Chetty-instant-download-pdf-16-320.jpg)
![Introduction to Tomcat
[ 10 ]
In the IIS world, access to this servlet container is offered by implementing an
Internet Server Application Programming Interface (ISAPI) extension, which is a
Dynamic Link Library (DLL) that allows you to extend the functionality of IIS. In the
Apache world, you access the container using code written in C or C++.
When a request comes in that is directed at a dynamic resource, the web server
simply hands off that request to its associated servlet container.
The container then springs into action, invokes the appropriate servlet that represents
the requested dynamic resource. This servlet is responsible for generating the response.
The generated response is returned by the servlet container to the web server
which, in turn, returns it to the requesting user. This interaction is depicted in the
following diagram.
request
response
Web
Server Fetch
dynamic
resource
response
Servlet
execute
Container
return
response
Internet
A servlet in its most basic form is a Java class that acts as a dynamic web resource. In
other words, it can be the target of a client browser's request.
Being a Java class, it can tailor its response according to the payload of the incoming
request, the conversation that this request is a part of, as well as other environmental
criteria (such as the time of the day or the inventory status from a database).
It is important to note that there is nothing special about this delegation
mechanism that restricts it only to dynamic resources. You could
configure a web server to also delegate requests for a certain subset of
static resources (for example, those within a given URL path) to the
servlet container.
This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009
6393 south jamaica court, , englewood, , 80111](https://image.slidesharecdn.com/2054538-250602102958-91ea13b8/85/Download-full-ebook-of-Tomcat-6-Developers-Guide-Damodar-Chetty-instant-download-pdf-17-320.jpg)
![Chapter 1
[ 11 ]
JSPs
The problem with using Java code to generate HTML content is that you end up
with a lot of string generation and concatenation to generate the actual HTML
content, interspersed with actual program logic written in Java. This is an unholy
combination as it tends to make the program logic impervious to the person tasked
with maintaining your code. In addition, changes to static content now require you
to compile the servlet class.
Applying the 80-20 rule very loosely to dynamic content, you might find that 80% of
the content of a page is in reality static content. The JavaServer Pages specification
was evolved as the solution to this situation. A JSP (JavaServer Page) is a template
made up primarily of static content with very specific (and hopefully, few)
invocations of Java code to retrieve the dynamic aspects of the page.
The problem of requiring a compilation step was resolved by making a JSP an
artificial construct. The container is responsible for transparently parsing a JSP and
converting it into a bona fide servlet, compiling it, and then invoking it in the same
manner as the other servlets in the application.
As long as the ratio of static to dynamic content is high, that is, as long as there are
more static elements than dynamic elements on a page, even non programmers, such
as graphic artists, can find their way around a JSP file with some comfort.
This is about as much as we will cover on JavaServer Pages technology in this book.
Servlet container
With all that behind us, we are now ready to answer the question posed by this
section's title – what exactly is Tomcat?
Tomcat is classified as a servlet container, that is, an environment within which
servlets can live and prosper. As a container, it provides a lot of administrative
support to servlets, allowing programmers to focus on the core application logic
that is to be implemented, without having to bother about low level specifics such
as session management and class loading.
The servlet and JSP specifications describe the service contract that the container
promises to provide to the servlets and JSP files that we write. Together, the
specifications describe all the services that a container should provide, and specify
how the servlet may make use of those services. As with all other Application
Programming Interfaces (APIs), the specifications describe the 'what' and leave
the 'how' to the implementer of the specific container.
This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009
6393 south jamaica court, , englewood, , 80111](https://image.slidesharecdn.com/2054538-250602102958-91ea13b8/85/Download-full-ebook-of-Tomcat-6-Developers-Guide-Damodar-Chetty-instant-download-pdf-18-320.jpg)
![Introduction to Tomcat
[ 12 ]
Tomcat serves as the 'reference implementation' of these specifications, and as a
result, serves as a guinea pig or canary in the mine shaft for them. In other words,
it provides a sample implementation to prove that the specification can indeed be
implemented, and serves as a guide for other implementers.
The following diagram provides an early bird's eye view of the responsibilities of a
servlet container.
Server Listener Global Resources
Service + Executor
Wrapper +
Valves
Servlet
Security JSP Support
JMX
support
Clustering
Support
Engine
Listener
Listener
Listener
Valves
Valves
Valves
Realm
Realm
Realm
Host +
Context +
Connector
(HTTP)
Connector
(AJP)
Connector
(HTTPS)
Processors
Loader Manager Resources
The primary responsibility of a container is to process an incoming request and to
generate a corresponding response that is then returned to the client.
A Connector component provides the external interface that allows clients to connect
to the container. This component not only accepts incoming connections, but is
also responsible for delegating the processing of the request to an available request
processor thread. The 'Processors' block in the image denotes multiple threads in a
pool that may be used to process the incoming request.
The request processing framework is implemented using a multiple level hierarchy
of sub containers (the servlet Engine, virtual hosts, web application contexts, and
servlet Wrappers) and nested components (Valves, Listeners, Loaders, Resources,
and Security Realms). Note that the '+' sign in the above image indicates that there
can be more than one instance of that component. For instance, more than one
Host, Context, and servlet Wrapper component may be contained within its
parent container.
This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009
6393 south jamaica court, , englewood, , 80111](https://image.slidesharecdn.com/2054538-250602102958-91ea13b8/85/Download-full-ebook-of-Tomcat-6-Developers-Guide-Damodar-Chetty-instant-download-pdf-19-320.jpg)
![Chapter 1
[ 13 ]
The result of processing a request is represented by a response, which is then
returned through the same Connector.
In addition to the core request processing components, the container also
provides support for other aspects of operation, such as logging, security,
and JMX monitoring.
In this book, our primary focus will be on the request processing responsibilities of a
servlet container. These components form the unshaded boxes in the previous image.
Additional topics will be considered only when they are crucial to understanding a
request processing component's actions.
It is important to note that a servlet container is a completely different
beast from an application server.
In the simplest sense, an application server contains a servlet container,
along with other containers, such as an EJB container, an applet container,
and an application client container. In addition, an application server
provides implementations for a number of Service APIs that are required
for heavy duty applications. We will take a closer look at the Java EE
platform in Chapter 2.
Examples of application servers include the JBoss Application Server,
GlassFish, IBM's WebSphere, and BEA's WebLogic.
Whether or not you should use a full fledged application server, with
its support for Enterprise JavaBeans and other Java EE heavy artillery,
depends on your application needs.
Why this book?
Tomcat is one of the few technology areas that is particularly blessed with a plethora
of very well written books, and the Tomcat mailing lists are rather friendly places for
new developers. So really, why another book on Tomcat?
The answer is simple. Most of these books and material focus primarily on the set up,
administration, and management, of a Tomcat server.
This is no accident. Most web developers rarely have to concern themselves with
anything more challenging than setting up a context fragment or changing the
default port for Tomcat from 8080 to 80.
As long as a developer understands the basic terminology of web applications
(such as the context, the context root) and the structure of a WAR file, most modern
Integrated Development Environments (IDEs), such as Eclipse and IntelliJ IDEA,
do all the heavy lifting for you.
This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009
6393 south jamaica court, , englewood, , 80111](https://image.slidesharecdn.com/2054538-250602102958-91ea13b8/85/Download-full-ebook-of-Tomcat-6-Developers-Guide-Damodar-Chetty-instant-download-pdf-20-320.jpg)
![Introduction to Tomcat
[ 14 ]
It seems only appropriate then, for authors to target their books at the typical
administrator or deployer.
For its part, Tomcat exposes a myriad of configuration files that enable even an
obsessive administrator to fine tune the installation and the Java Virtual Machine
as much as desired.
The net result is that your average book contains the customary chapter on
installing Tomcat, chapters on configuring it, on deploying servlets into it, on
integration with either the Apache httpd web server or Microsoft's IIS, and on
securing the installation.
The downside with this approach is that it provides a one-sided view of the
software engineering marvel that is Tomcat. You tend to see it as a black box with
lots of control switches that you can throw, but you never ever really get a chance
to peer into the open vents on the sides of that box.
In this book, I hope to correct that imbalance. I'm going to pry open the service door
on the side of that black box, and take you in on an interesting journey through
some of the sights that most people rarely get to see. A connector shimmering in the
moonlight, the rays of the early morning sun catching an application class loader in
its native state, a lumbering valve caught in motion capture frames as it springs into
action with surprising agility. There are a lot of fantastical beings that populate this
world, if you only dare to venture into it.
In the course of the next few chapters, we will look at Tomcat from the perspective
of someone attempting to understand what makes it tick. Our goal will be to
understand Tomcat as few others do. We'll not only see the control switches on the
outside, but we'll also learn about how these switches affect the machinery within.
Gathering our tools
In this section, I'm going to get together all the pieces that you will need for the
remainder of this book. If you would like to follow along with the rest of this book,
then this section is crucial.
The software that we will download and install includes the following:
The Java SE Development Kit (JDK) version 6.0
A download verifier
Apache Ant 1.7.1
Subversion 1.6.3
Eclipse 3.5 Galileo
•
•
•
•
•
This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009
6393 south jamaica court, , englewood, , 80111](https://image.slidesharecdn.com/2054538-250602102958-91ea13b8/85/Download-full-ebook-of-Tomcat-6-Developers-Guide-Damodar-Chetty-instant-download-pdf-21-320.jpg)
![Chapter 1
[ 15 ]
The workstation that I use throughout this book runs a Microsoft Windows
operating system (XP Professional or Vista).
The version numbers that are specified were current at the time of writing
this text. However, with the speed of product cycles in the open source
arena, it is likely that newer versions will be available by the time you
read this.
Java Development Kit (JDK) 6.0
JDK 6 can be found at http://java.sun.com/javase/downloads/index.jsp.
As with every download page on the Sun web site, there are enough choices to make
your head spin. For our needs, we need the plain vanilla JDK 6.0 that at the time of
writing is JDK 6 Update 14.
Once you've picked the Platform: (Windows) and Language: (Multi-language), you
will end up with a file named jdk-6u14-windows-i586.exe on your workstation.
Execute this file to install it. Once you have accepted the terms and conditions, and
have picked an install directory, the installation process will begin.
Once the JDK has been installed, the installer will prompt you to install the JRE. You
may do so if you wish.
The JDK for 64-bit platforms
There are 64-bit versions of the JDK that are available for
Windows, Linux, and Solaris. The file for 64-bit Windows is
named jdk-6u14-windows-x64.exe.
Verifying downloaded files
Most open source software is hosted on multiple mirror sites, and you are expected
to pick your nearest mirror from which to download it. A key question here is how
do you ensure that the file that you just downloaded is an exact copy of the version
that the open source team intended for download, and there isn't a malicious hacker
chuckling with glee to see you install a Trojan on your workstation?
There are a couple of answers to this question—using PGP keys or using a
message digest.
The former is more secure as it uses public key cryptography, but as a result is also
more complex.
This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009
6393 south jamaica court, , englewood, , 80111](https://image.slidesharecdn.com/2054538-250602102958-91ea13b8/85/Download-full-ebook-of-Tomcat-6-Developers-Guide-Damodar-Chetty-instant-download-pdf-22-320.jpg)
![Introduction to Tomcat
[ 16 ]
The latter, while simpler to use, is not quite as secure, as the most common digest
algorithm (MD5) has some well documented flaws, allowing different files to
generate the same digest. In addition, the MD5 digest value itself may have
been modified by the hacker so that it matches the compromised file.
Using the principle that any security is better than none, you would compute the
MD5 message digest for the downloaded file, and compare that computed value
against the published digest for the file.
You can download a digest generator from either www.formilab.ch/md5/ or
www.nullriver.com/index/products/winmd5sum.
For example, the MD5 digest for the ZIP file distribution of Tomcat 6.0.18 is:
f7d0c15df19fedf52476767f7ce0b6f8
*apache-tomcat-6.0.18.zip
Apache Ant
Apache Ant or Another Neat Tool is a build automation utility that owes its
existence to James Duncan Davidson and Tomcat. It originated as a tool used to
build Tomcat itself. But its widespread popularity ensured that it was promoted
into its own project, independent of Tomcat, in January 2000.
As Ant is written in Java, it inherits its Write Once Run Anywhere aspect, making it
platform independent. Its build directives (by default, in a file named build.xml)
are written using XML - another cross platform advantage.
Ant build directives take the form of targets that describe the actions or tasks that
must be performed, whether creating, deleting, or copying files and directories,
setting classpaths, compiling Java classes, or even packaging your applications.
The ability to define dependencies on targets adds to its flexibility. You can indicate
that a compile target depends on other targets that clear out the output directories,
fetch the latest changes from your source code repository, and set the classpath.
Finally, throw in the ability to define your own targets, and the sky's the limit!
Download the latest version from http://ant.apache.org/bindownload.cgi and
extract the Ant distribution. The version that was current when I wrote this, was
Ant 1.7.1.
You need to add Ant to your PATH. On Windows, this is accomplished by opening
the System Properties box – by right clicking your My Computer icon and clicking
Properties. Pick System from the Control Panel's classic view or press the keyboard
shortcut Windows + Pause/Break.
This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009
6393 south jamaica court, , englewood, , 80111](https://image.slidesharecdn.com/2054538-250602102958-91ea13b8/85/Download-full-ebook-of-Tomcat-6-Developers-Guide-Damodar-Chetty-instant-download-pdf-23-320.jpg)
![Chapter 1
[ 17 ]
On the Advanced system settings tab, click on Environment Variables tab
and edit the Path variable. Add [ANT_HOME]bin to the end of the path variable,
replacing [ANT_HOME] with the absolute path to the location where you extracted
the downloaded file.
Note that path variables in Windows are delimited by a semicolon.
Subversion
Next, we need a way to retrieve the latest version of the Tomcat source code, which
is currently housed in a Subversion repository.
Subversion was conceived in 2000, when CollabNet, Inc. decided that it was time
to write a brand new version control system, and brought on Karl Fogel to head this
effort. The stated goal of the original team was to write a better version of CVS, while
retaining the familiar elements of CVS, to make it easier for developers to switch
without much effort.
Subversion has since dethroned CVS as the system of choice. In particular, it
has been adopted as the standard version control mechanism by the Apache
Software Foundation.
Subversion, like CVS, uses a copy-modify-merge model. In the copy phase, each
developer makes a private copy of the project's source code on to their individual
workstations. This copy acts as a sandbox within which each developer may work.
In the modify phase, each developer makes changes in his or her own working
copy. The changes made by one developer are not visible to the others. If you need
visibility into another developer's changes, you would need to update your working
copy from the repository.
In the merge phase, a developer commits his changes back into the source code.
If a file was modified by another developer since you checked out your copy, you
would then need to merge your changes back into the repository resolving any
conflicts as necessary.
Get the latest version of the Subversion Command-Line Client for Windows from
http://www.collab.net/downloads/subversion/, which is currently 1.6.3.
Execute the downloaded file, CollabNetSubversion-client-1.6.3-3.win32.exe.
The installation is fairly straightforward and only requires that you specify a path
name for your installation.
This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009
6393 south jamaica court, , englewood, , 80111](https://image.slidesharecdn.com/2054538-250602102958-91ea13b8/85/Download-full-ebook-of-Tomcat-6-Developers-Guide-Damodar-Chetty-instant-download-pdf-24-320.jpg)
![Introduction to Tomcat
[ 18 ]
To verify that the software was successfully installed, run the svn --version
command from the command prompt. This command should output the version
of Subversion that is installed on your workstation.
Obtaining the Tomcat source code
You have two options when trying to download the Tomcat source. You could either
use the Subversion version control software, which was described in the last section,
or you could simply download the compressed source distribution of Tomcat as a
ZIP file. The former option is preferred if you expect to be developing in Tomcat,
whereas the latter is simply a snapshot of the code at a given version.
Using Subversion
To obtain the latest source code for Tomcat from the Subversion repository at the
ASF, change your working directory to where you want to download your working
copy (for example, c:tomcat), and execute the following at the command line
(all on one line):
svn checkout http://svn.apache.org/repos/asf/tomcat/tc6.0.x/trunk/
When this completes, you will notice that your current directory now contains a
trunk subfolder with the source directories for Tomcat.
The above command downloads the most up-to-date version of
the source trunk and may result in code that may differ from the
descriptions in this text.
If you would like to ensure that you are working with the exact
codebase covered in this book, then you should use the following
command instead:
svn checkout http://svn.apache.org/repos/asf/tomcat/
tc6.0.x/tags/TOMCAT_6_0_20/
This is the 'copy' phase of your interaction with the Subversion version control
system. The result of this operation is to make a local copy of Tomcat's latest
development code line from the Subversion repository. This lets you play in your
own little sandbox, making changes and experimenting for as long as you need.
This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009
6393 south jamaica court, , englewood, , 80111](https://image.slidesharecdn.com/2054538-250602102958-91ea13b8/85/Download-full-ebook-of-Tomcat-6-Developers-Guide-Damodar-Chetty-instant-download-pdf-25-320.jpg)
![Chapter 1
[ 19 ]
Tomcat source distribution
If you'd rather not install Subversion, a less invasive option would be to simply
download the Tomcat source from the Source Code Distributions section at
http://tomcat.apache.org/download-60.cgi.The source for a previous version
can be downloaded from http://archive.apache.org/dist/tomcat/tomcat-
6/. The only downside with this approach is that the source distribution does not
contain a project file for use with the Eclipse IDE. To get these files, point your
browser at http://svn.apache.org/repos/asf/tomcat/tc6.0.x/trunk (or to
http://svn.apache.org/repos/asf/tomcat/tc6.0.x/tags/TOMCAT_6_0_20 for
the version used in this book) and download the .classpath and .project files.
Ensure that the downloaded files are named exactly the same as their originals.
Getting ready to build Tomcat
Now, we're ready to get started with building the source that we just downloaded.
This is a two step process that utilizes the power of Ant and the build.xml file that
exists in the trunk directory. First change directory to the directory to which your
source code has been downloaded (or unzipped.).
Downloading dependencies
Now, run the download target:
ant download
The download target downloads a number of binaries that are needed for this
build. These artifacts are downloaded to the folder that is identified by the
base.path property in the Ant build.properties.default file. By default,
this will be /usr/share/java. However, you can change this to a different
absolute path such as c:/tomcat/downloads/trunk.
The files that are downloaded include:
The native Tomcat connectors (currently at version 1.1.15).
The Commons daemon library (version 1.0.1), which is used with jsvc—a
Java Service Wrapper that is used to run Tomcat as a non-root user listening
on the privileged port 80 on non Windows operating systems.
•
•
This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009
6393 south jamaica court, , englewood, , 80111](https://image.slidesharecdn.com/2054538-250602102958-91ea13b8/85/Download-full-ebook-of-Tomcat-6-Developers-Guide-Damodar-Chetty-instant-download-pdf-26-320.jpg)
![Introduction to Tomcat
[ 20 ]
The Eclipse JDT JAR, which is used by Tomcat to compile JSPs.
The Nullsoft Scriptable Install System (NSIS)—an open source system to
create Windows installers.
The Commons Collections library.
The Commons Database Connection Pool (version 1.2.2) and Commons Pool
(version 1.4). The build-tomcat-dbcp Ant target renames the packages for
these Commons projects, for example, by replacing org.apache.commons
with org.apache.tomcat.dbcp. The stated goal here is to ensure that the
DBCP and Pool classes, used by Tomcat internally, do not conflict with
any versions of DBCP or Pool classes that are packaged with individual
web applications.
Download errors
I have noticed that the download target sometimes fails when
trying to unzip the NSIS with the following error: java.
io.IOException: Negative seek offset
In such cases, a manual workaround is to simply download
the target ZIP file (in this case http://downloads.
sourceforge.net/nsis/nsis-2.37.zip) and unzip it to
the folder into which the build script is downloading files.
Then, ensure that the test file is present, which in this case is
c:/tomcat/downloads/trunk/nsis-2.37/makensis.exe.
Building Tomcat
We're finally ready to build Tomcat using Ant, so run the deploy target.
ant deploy
This target compiles the Java code and builds the binary distribution of Tomcat. Note
that you can omit the target name because deploy is defined as the default target in
the build.xml file. So the following would be equivalent:
ant
•
•
•
•
This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009
6393 south jamaica court, , englewood, , 80111](https://image.slidesharecdn.com/2054538-250602102958-91ea13b8/85/Download-full-ebook-of-Tomcat-6-Developers-Guide-Damodar-Chetty-instant-download-pdf-27-320.jpg)
![Chapter 1
[ 21 ]
The deploy target builds the Tomcat binaries and copies files out to outputbuild.
The clean target
If you need to start with a clean build, then the clean target is your
friend. It clears out all the output folders for a fresh distribution to be
laid into it.
Starting up your shiny new Tomcat
From the outputbuildbin directory within your Tomcat trunk folder, execute the
startup.bat batch file.
startup
This starts up your Tomcat server in a separate command window. Reassuring log
messages should be output to your console as shown.
This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009
6393 south jamaica court, , englewood, , 80111](https://image.slidesharecdn.com/2054538-250602102958-91ea13b8/85/Download-full-ebook-of-Tomcat-6-Developers-Guide-Damodar-Chetty-instant-download-pdf-28-320.jpg)
![Introduction to Tomcat
[ 22 ]
Now, using your favorite browser, type in the URL http://localhost:8080, and
marvel at what you have wrought.
Finally, to shut down your server, execute the shutdown.bat batch file.
shutdown
This command closes down the Tomcat server gracefully, and you're done.
Eclipse
We're now on to the home stretch. The ultimate prize for us is to be able to use an
IDE to run the Tomcat server. What would be more appropriate for investigating
Tomcat, than the free and full featured open source IDE—Eclipse!
While you can simply use your favorite IDE, the Tomcat source
distributions include project metadata files only for the Eclipse IDE.
This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009
6393 south jamaica court, , englewood, , 80111](https://image.slidesharecdn.com/2054538-250602102958-91ea13b8/85/Download-full-ebook-of-Tomcat-6-Developers-Guide-Damodar-Chetty-instant-download-pdf-29-320.jpg)
![Chapter 1
[ 23 ]
In particular, let's pick Eclipse Galileo, which is the most recent in an annual series
of releases that package multiple major projects. Previous releases have been code
named Callisto, Europa, and Ganymede.
Galileo was released in June 2009, and includes the core Eclipse project along with
almost three dozen other major projects, including the Web Tools Platform project,
the Rich Ajax Platform project, and the SOA Tools Platform project.
Eclipse downloads are available at http://www.eclipse.org/downloads/. Make
sure that you pick the Eclipse IDE for Java EE Developers version. For Windows,
this results in the file eclipse-jee-galileo-win32.zip being copied down to
your workstation.
Eclipse for 64-bit Windows
The above link works fine for downloading Eclipse for the most common
platforms, including 64-bit Linux. However, you have to work a bit
harder to get the 64-bit version for Windows. The downloads for the
Eclipse project are available at http://download.eclipse.org/
eclipse/downloads/. For safety, click the link associated with the
Latest Release version, which is currently at 3.5. These downloads are
named eclipse-SDK-[versionNumber]-[platform].zip. For
Vista 64, this download is eclipse-SDK-3.5-win32-x86_64.zip.
Unzip the Eclipse distribution to a folder of your choice, and execute eclipse.exe to
verify that your IDE starts up.
At startup, you are prompted for a workspace location. A workspace folder is
used to house your projects as well as to store metadata about your plugins and
your IDE preferences.
This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009
6393 south jamaica court, , englewood, , 80111](https://image.slidesharecdn.com/2054538-250602102958-91ea13b8/85/Download-full-ebook-of-Tomcat-6-Developers-Guide-Damodar-Chetty-instant-download-pdf-30-320.jpg)
![Introduction to Tomcat
[ 24 ]
In this dialog, you can either point to an existing workspace folder if you have one,
or to a new folder location. It is recommended that you pick a folder that lies outside
of your Eclipse installation directory so that when you upgrade your Eclipse version,
you can simply delete the old installation folder without losing your workspace.
Once Eclipse starts up, dismiss the Welcome screen to proceed to the
Workbench, and then select the Window | Preferences menu option to
display the Preferences dialog.
In the left pane of this dialog, drill down to Java | Installed JREs, and verify that
your previously installed version of JDK 6 shows up. If it doesn't, then click on the
Add button to add a reference to your JDK.
This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009
6393 south jamaica court, , englewood, , 80111](https://image.slidesharecdn.com/2054538-250602102958-91ea13b8/85/Download-full-ebook-of-Tomcat-6-Developers-Guide-Damodar-Chetty-instant-download-pdf-31-320.jpg)
![Chapter 1
[ 25 ]
We will also set up two classpath variables as shown next—ANT_HOME to point at
the base directory for your Ant installation and TOMCAT_LIBS_BASE to point to
the directory that holds the files downloaded by the download ant target that you
executed while building Tomcat.
If you are building a non-trunk version of Tomcat, then ensure that your
TOMCAT_LIBS_BASE classpath variable points to the path to where the
ant download target downloads its dependencies.
This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009
6393 south jamaica court, , englewood, , 80111](https://image.slidesharecdn.com/2054538-250602102958-91ea13b8/85/Download-full-ebook-of-Tomcat-6-Developers-Guide-Damodar-Chetty-instant-download-pdf-32-320.jpg)
![Introduction to Tomcat
[ 26 ]
Next, import the project file that is present in the working copy of the Tomcat
trunk. Choose File | Import to open the Import dialog. From this dialog, choose
General | Existing Projects into Workspace to import the Eclipse project present
in the Tomcat trunk into your new workspace.
This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009
6393 south jamaica court, , englewood, , 80111](https://image.slidesharecdn.com/2054538-250602102958-91ea13b8/85/Download-full-ebook-of-Tomcat-6-Developers-Guide-Damodar-Chetty-instant-download-pdf-33-320.jpg)
![Chapter 1
[ 27 ]
Click on Finish to import the project.
A project build begins automatically, and you will get the following screen.
This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009
6393 south jamaica court, , englewood, , 80111](https://image.slidesharecdn.com/2054538-250602102958-91ea13b8/85/Download-full-ebook-of-Tomcat-6-Developers-Guide-Damodar-Chetty-instant-download-pdf-34-320.jpg)
![Introduction to Tomcat
[ 28 ]
To start up your Tomcat server from within Eclipse, create a Run configuration
by choosing the Run | Run Configurations… menu option, and select
org.apache.catalina.startup.Bootstrap as the Main class.
Click on Run, and watch the Console pane for output indicating that Tomcat was
successfully started.
Now browse on over to http://localhost:8080 to view the Tomcat welcome page.
Congratulations! You're done.
For now, play with this code by placing breakpoints and stepping through
interesting code sections. We'll explore these sections in far greater detail in the
chapters to come.
In the next couple of chapters, we'll regroup and visit concepts that are necessary for
the exploring that we'll be doing in later chapters.
This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009
6393 south jamaica court, , englewood, , 80111](https://image.slidesharecdn.com/2054538-250602102958-91ea13b8/85/Download-full-ebook-of-Tomcat-6-Developers-Guide-Damodar-Chetty-instant-download-pdf-35-320.jpg)
![Chapter 1
[ 29 ]
Summary
We covered a lot of ground in this chapter. We began by looking at the principles
behind a servlet container. We looked at the origins of Tomcat, and we built
ourselves our very own server by cobbling together a number of software helpers.
We looked at the JDK, the Ant build tool, the Subversion version control tool, and the
Eclipse IDE. We retrieved the latest source from the Tomcat Subversion repository,
and we compiled the Java sources to result in a binary distribution of the container.
In the next chapter, we'll explore some of the ideas embodied in the
servlet specification.
This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009
6393 south jamaica court, , englewood, , 80111](https://image.slidesharecdn.com/2054538-250602102958-91ea13b8/85/Download-full-ebook-of-Tomcat-6-Developers-Guide-Damodar-Chetty-instant-download-pdf-36-320.jpg)
![Servlet API Overview
[ 32 ]
The JCP works by bringing together a group of experts in the subject area,
under the guidance of a technical specification lead to not only develop or revise a
specification, but also to build a reference implementation as well as a technology
compatibility kit.
The process starts with the submission of a Java Specification Request (JSR),
which either proposes a brand new specification or a significant revision to an
existing specification.
An API is the contract that is made by a software package in terms of the
functionality that it makes available to the developer. There is an implicit guarantee
that APIs can be relied upon to exist for a very long time. You can see this at work
in many Java APIs, where even questionable API decisions live on in perpetuity, as
deprecated methods.
A specification has, at its core, the API for some aspect of the technology. For
example, the Servlet 2.5 specification of August 2007 devotes almost half its pages
to the API embodied in its javax.servlet and javax.servlet.http packages.
The rest of its pages are split between the description of concepts that are introduced
by the specification (servlets, the servlet context, sessions, filters, and so on) and
a description of the functional requirements of a Java Enterprise Edition 5
servlet container.
A platform edition specification is a more involved animal and defines a baseline set of
APIs that provide a foundation upon which applications can be built. For example,
the Java Enterprise Edition platform describes a set of APIs (such as the JDBC, JNDI,
and Servlet APIs) that are guaranteed to be available to any application that runs
within a Java EE compliant server.
A reference implementation is the proof of concept implementation for a given
specification, and is intended to prove that the specification can actually be
implemented. Apache Tomcat serves as the reference implementation for the
Servlet and JSP APIs; whereas the Sun Java System Application Server (GlassFish)
is the reference implementation for the entire Java EE 5 stack.
A technology compatibility kit is used to verify that a given implementation is
compliant with its specification. It consists of a set of tests, a mechanism to automate
these tests, useful tools, and documentation. The reference implementation also
serves as a useful platform against which to validate the tests in the TCK.
The current version for the Servlet API is the Java™ Servlet Specification version 2.5
Maintenance Release 6 specification. This specification was developed using the JCP
as Java Specification Request 154.
This document can be downloaded from http://jcp.org/en/jsr/detail?id=154.
This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009
6393 south jamaica court, , englewood, , 80111](https://image.slidesharecdn.com/2054538-250602102958-91ea13b8/85/Download-full-ebook-of-Tomcat-6-Developers-Guide-Damodar-Chetty-instant-download-pdf-38-320.jpg)
![Chapter 2
[ 33 ]
A more recent maintenance release specification of the API can be obtained from
http://jcp.org/aboutJava/communityprocess/mrel/jsr154/index.html.
Java Enterprise Edition platform
The Java Enterprise Edition platform is nothing more than a set of API specifications
that act as building blocks that you can use to build enterprise applications.
With its most recent release, the name of the Java Enterprise Edition
platform has been simplified.
Instead of being called the Java 2 Platform, Enterprise Edition (J2EE)
v1.5, the version up from J2EE v1.4 is now labeled Java Enterprise Edition
5 or Java EE 5. It is incorrect to abbreviate this name as 'JEE'.
The main drivers for this change are a desire to do away with the '2',
which really was beginning to lose its meaning anyway; and to provide
center stage to the word 'Java', which is the core technology underlying
the different platform editions.
While this may seem like just a rebranding decision, there are some real
issues associated with it. Firstly, you need to be aware that you might
come across JARs named j2ee.jar and javaee.jar and will need
to know which one to pick. Secondly, you need to remember that this is
more like deprecation, rather than a replacement, that is, most people
will continue to use the term J2EE long into the future—on resumes, job
requisitions, design documents, and on blogs.
An 'enterprise application', just by the sound of it, seems more forbidding than
plain old 'application'. It is therefore interesting to look at what exactly makes an
application, an 'enterprise application'.
What is an enterprise application?
To help us see the difference here, let us consider prototypical examples of
both types of applications. A representative 'application' might be the standard
personal finance management applications, such as Microsoft's Money™ or Intuit's
Quicken™. A prototypical 'enterprise application', on the other hand, would be an
online banking system.
Both applications are fairly similar in that you can view the transactions for one or
more accounts, transfer money either into or out of an account, schedule bills that
come due, and you can reconcile your checkbook based on statements. In addition,
you may also have the ability to run reports on amortization tables, spending
patterns, or transaction histories.
This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009
6393 south jamaica court, , englewood, , 80111](https://image.slidesharecdn.com/2054538-250602102958-91ea13b8/85/Download-full-ebook-of-Tomcat-6-Developers-Guide-Damodar-Chetty-instant-download-pdf-39-320.jpg)
![Servlet API Overview
[ 34 ]
So what makes one an enterprise application and the other not? The essence of an
enterprise application can be boiled down into four concepts—simultaneous users,
highly performant systems, heterogeneous environments, and a distributed nature.
Simultaneous users
An enterprise application is expected to be used simultaneously by more than one
user. In fact, such applications are often expected to be accessed simultaneously by
hundreds or even thousands of users.
This adds complexity as you now need to apportion system resources across these
users. In addition, you must also ensure that one user does not interfere with the
operations of another, even if they happen to be working on the same data.
Highly available, reliable, and scalable
An enterprise application is one where there is usually significant potential for loss
if its users are unable to access and use it in a predictable manner. This encompasses
the concepts of availability, reliability, and scalability.
An online banking application has to be available when the customer needs it,
irrespective of the time of day. It has to function reliably when used by that customer
and should be able to handle higher peak loads over certain periods such as major
holidays like Christmas or the periods when paychecks are deposited by employers.
A failure on any one of these criteria results in a loss of customers, a loss of revenue,
or both.
While these characteristics are equally important to non-enterprise applications, the
impacts of failure are often much less dramatic as such applications are generally
designed to be used either by a single user, or by a very small set of users.
Heterogeneous environment
A typical enterprise application has very little control over its destiny. Most often it
is cobbled together from various collaborating systems, many of which have been in
operation for a number of years (or decades).
This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009
6393 south jamaica court, , englewood, , 80111](https://image.slidesharecdn.com/2054538-250602102958-91ea13b8/85/Download-full-ebook-of-Tomcat-6-Developers-Guide-Damodar-Chetty-instant-download-pdf-40-320.jpg)
![Chapter 2
[ 35 ]
An enterprise typically already has a significant investment in terms of software,
hardware, staffing, and infrastructure in its existing legacy systems. By necessity, any
new development needs to play nice with these. This may include software systems
(such as Enterprise Resource Planning systems, Custom Relationship Management
products, and mainframe systems), operating systems, data sources (such as IMS,
Oracle, and SQL Server), application servers (such as WebSphere, WebLogic, and
JBoss), communication protocols, and data formats. An ability to integrate nicely
with these disparate technologies is the hallmark of an enterprise application.
A point of note is that one of the most significant investments that an enterprise
makes is in its data. Most of the time this investment is locked within silos
throughout the enterprise, making the task of turning it into useful information a
very daunting one. Most enterprise applications have, as their central focus, the
ability to access this shared data, freeing it from the grips of traditional systems.
On the other hand, non-enterprise applications are fairly standalone entities.
For instance, installations of Microsoft Money never need to deal with the issues
of application or system integration, or with the issues of integrating data from
multiple data stores.
The only real complexity often arises from data transfer format requirements. For
example, personal finance software will typically download transaction data from
financial institutions using either the Open Financial Exchange (OFX) or the Web
Connect (QFX) formats.
Distributed nature
An enterprise application rarely runs on a single computer host. This is
almost always necessitated because of performance and scalability, as there is
a practical limit on how much work can be assigned to a particular computer;
as well as of heterogeneity, since the collaborating systems may run on their
own dedicated hardware.
As a result, when describing your enterprise application, you tend to speak in terms
of server farms, clusters, load balancers, DMZs, firewalls, and so on.
A corollary of this fact is that portions of the enterprise application itself may be
distributed across multiple hosts. For instance, the logic that determines what is
rendered to the user can be separated into its own tier from that of the logic that
defines the business rules for the application, and there can be yet another tier that
houses the persistent data store used by the application.
It is important to note that these tiers can either be logical (when all these tiers run
on the same physical machine, possibly within the same Java Virtual Machine) or
physical (when each of these tiers runs on a dedicated physical machine.)
This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009
6393 south jamaica court, , englewood, , 80111](https://image.slidesharecdn.com/2054538-250602102958-91ea13b8/85/Download-full-ebook-of-Tomcat-6-Developers-Guide-Damodar-Chetty-instant-download-pdf-41-320.jpg)
![Servlet API Overview
[ 36 ]
On the other hand, the typical vanilla application runs on a single workstation and
is designed to serve a single user. You will be hard pressed to find a distributed
implementation of either Money or Quicken.
To summarize, there are very valid reasons as to why enterprise application
development is crucial to a corporation's survival - it serves as the best way to
leverage your existing technology investments.
Java EE architecture
In its most basic form, the Java Enterprise Edition platform describes a set of APIs
that must be implemented by any Java EE compliant application server platform.
These APIs are guaranteed to be available to any application that runs on a Java EE
compliant server.
The API implementations that are provided by a Java EE application server provider
make it easy for a developer to focus on the business requirements, instead of having
to implement infrastructural aspects of a complex enterprise application, such as
having to figure out how to implement 2-phase commits to ensure that transactions
work across disparate data sources.
A transaction is defined as a grouping of tasks that must be either
executed completely or must not be executed at all. The typical example
is that of a transfer of funds between two accounts, which is comprised
of two tasks—a withdrawal from the first account and a deposit into
the second. If a system failure occurs between these two tasks, then
data corruption is likely as the withdrawal has taken place but no
corresponding deposit has occurred. The complexity of transactions in
an enterprise application is compounded by the fact that the individual
tasks may involve completely different database servers or other legacy
data stores.
An additional benefit of writing applications based on the standard Java EE APIs
is that your application is now implementation independent. In other words, your
application can be deployed on any vendor's Java EE compliant application server.
In fact, a popular recommendation is to deploy applications on the
reference implementation, as well as on the target application server. This
ensures that you have not inadvertently locked yourself into a particular
vendor's platform implementation.
This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009
6393 south jamaica court, , englewood, , 80111](https://image.slidesharecdn.com/2054538-250602102958-91ea13b8/85/Download-full-ebook-of-Tomcat-6-Developers-Guide-Damodar-Chetty-instant-download-pdf-42-320.jpg)
![Chapter 2
[ 37 ]
However, you need to take this advice with a pinch of common sense. Vendor
lock-in is not always bad, especially if you are getting something material in return
(such as improved reliability, stability, or functionality). The choice of a vendor is
often based on numerous factors, such as licensing costs, administrative/deployment
staff expertise, and proven performance on existing production applications. As a
result, changing vendors rarely happens as often as one might fear.
There are a few key features about the Java EE architecture that merit mention.
Java based
The Java EE platform is a superset of the Java SE platform. As a result, it inherits its
basic advantages, such as the ability to run Java applications on diverse operating
systems, its mature and flexible object-oriented programming model, its ability to
work well across a network (including over the Internet), its automatic garbage
collection mechanism, and its inherent multithreaded nature, all of which make
for a very compelling package.
Generic APIs
A key aspect of enterprise application development is the need to work and integrate
with a variety of disparate systems. Learning the individual APIs of each of these
diverse systems can be an insurmountable task. Java EE provides a solution for this
problem—by separating the vendor-agnostic aspect of an interaction, the API, from
the vendor-implementation aspect, termed the Service Provider Interface (SPI).
This design provides for an astonishing decrease in the level of complexity that
developers need to contend with during enterprise development.
As an example, consider the Java Naming and Directory Interface API. The
published API is generic enough to be used against any particular vendor
implementation, whether LDAP, the RMI Registry, or even just the file system.
As a developer, all you need is to be aware of the vendor-agnostic API. You will also
supply some configuration information that is appropriate for your choice of vendor
such as the URL at which to access the service, authentication credentials, and the
factory class for the initial context.
A service provider implements not only the SPI that defines the core service
implementation, but also any abstract classes and interfaces that are left undefined in
the API itself. Service providers may be linked into the Java EE platform server either
statically (through configuration files or deployment descriptors) or dynamically at
runtime. When multiple providers implement the same functionality, an application
may choose, at runtime, which particular provider's implementation to use.
This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009
6393 south jamaica court, , englewood, , 80111](https://image.slidesharecdn.com/2054538-250602102958-91ea13b8/85/Download-full-ebook-of-Tomcat-6-Developers-Guide-Damodar-Chetty-instant-download-pdf-43-320.jpg)
![Servlet API Overview
[ 38 ]
As an application programmer, you will typically use a factory method to interact
with the service provider, which will return to you the appropriate instance, which
implements an interface within the Java EE API. Your application interacts with this
generic interface using the functions defined by the API and is completely oblivious
to the specific implementation class.
This basic theme is repeated over and over again within the Java EE.
Java EE containers and container services
The Java EE platform is designed around a containment hierarchy, where an
application server hosts containers, each of which in turn hosts components.
A container is responsible for configuring its components based on the deployment
descriptor, allowing component behavior to be controlled using configuration rather
than code. For example, a deployment descriptor may specify that a particular
Enterprise JavaBeans method may not be invoked unless the user belongs to a
given security role.
It is also responsible for managing the life cycle of its components. For instance,
a servlet container will load the servlet class, instantiate it, call its initialization
method, will repeatedly call its service method as requests come in, and will
finally call its destruction method when it is being taken out of service.
The container is also the gateway through which its components may access
their runtime environment. It is also the intercessor when one component needs
to communicate with another Java EE component. This intercession allows the
container to add value by transparently propagating transactions, implementing
security checks, and so on.
This container-based architecture provides an effective way of providing a
separation of concerns. The deployed components can now focus on the business
problem being solved, whereas the container can provide the plumbing and
infrastructure required to make everything work.
Each platform vendor must implement these containers so as to maintain the contract
with its components as specified in the appropriate API specification. While this
does not stop the vendor from providing additional services through the container, it
does ensure that each component can be guaranteed to find a baseline set of services,
irrespective of the particular vendor implementation that it is deployed into.
The Java EE specification defines four types of containers.
This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009
6393 south jamaica court, , englewood, , 80111](https://image.slidesharecdn.com/2054538-250602102958-91ea13b8/85/Download-full-ebook-of-Tomcat-6-Developers-Guide-Damodar-Chetty-instant-download-pdf-44-320.jpg)
![Chapter 2
[ 39 ]
An application client container provides the runtime environment for Java
programs (either graphical user interface based or command line) that execute on a
client workstation. Application clients are the same as standard Java SE applications,
so no special life cycle calls are made by this container.
An applet container contains applets that typically execute natively within a browser
or through the Java Plug-in product.
A servlet container hosts Servlet API and JavaServer Pages API components, which
are used to service HTTP requests from web clients.
Finally, an Enterprise JavaBeans (EJB) container hosts EJB components,
which houses the business logic that is usually found in the middle tier of a
Java EE application.
A typical servlet container (such as Apache Tomcat) will, among other things, allow
a developer to package a web application as per the Servlet specification. It will load
the appropriate servlets as necessary, will invoke a servlet's lifecycle and service
methods, and will provide the servlet instance with access to information about its
operating context.
Similarly, an EJB container will provide its contained components (Enterprise
JavaBeans) with services for security, transactions, instance pooling, and so on.
A container is usually controlled through configuration files, such as Tomcat's
server.xml file.
Java EE Platform Specification
APIs:
JPA JSF JSTL StAX
Public API
SPI
...
APIs:
JPA JSF JSTL StAX JNDI
Public API
SPI
Provider Implementation
...
deployment descriptor
EJB Container
Components
EJBs
Application
Client
Container
Application
Clients
Applet
Container
Applets
Servlets JSPs
Components
Servlet Container
deployment descriptor
APIs:
JPA JSF JSTL StAX JNDI
Public API
SPI
Provider Implementation
...
Java
SE
Java
SE
Java
SE
Java
SE
TCK
This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009
6393 south jamaica court, , englewood, , 80111](https://image.slidesharecdn.com/2054538-250602102958-91ea13b8/85/Download-full-ebook-of-Tomcat-6-Developers-Guide-Damodar-Chetty-instant-download-pdf-45-320.jpg)
![Servlet API Overview
[ 40 ]
This figure summarizes the concepts that we've introduced so far—the distinction
between the API and the SPI, the Java EE containers, and the component model.
The specification of the platform is comprised of the specifications for multiple
containers. Each container is responsible for hosting its own component model.
The components for each container expect certain services to be provided by
their container.
The face that services expose to components is defined by the service's API. The
vendor implements each service by providing code that implements the SPI, the
abstract classes, and interfaces that are defined by the API.
Finally, a deployment descriptor may be used to configure the container's services
and runtime environment, as well as to define how the components are deployed
into that service.
The Technology Compatibility Kit (TCK) is a set of tests that allow you to validate
the compliance of a container implementation with its specification.
Java EE components and their APIs
The Java EE platform uses a component-based development model. This is different
from a class-based model as a component typically consists of more than one class
cooperating to achieve some reusable unit of functionality.
A Java EE application is built by assembling multiple such standalone components
and deploying them with their configurations into their associated containers.
The power of Java EE comes from the fact that components can be independently
developed, tested, assembled, and deployed into any Java EE compliant vendor's
server implementation.
Each container can deploy its own unique set of components. The application
client container can contain application client components, which are standard
Java programs. The applet container contains applet components. The web container
contains web components, such as JSP, Servlet, Filter, and event listener components,
whereas the EJB container contains enterprise bean components.
Application logic typically resides in the components, and business logic usually
resides in the enterprise bean components.
In this book, we will primarily focus on the servlet container and web components.
Java EE Service APIs
The Service APIs serve to simplify your programming tasks by providing standard
APIs to access diverse systems or alternative implementations.
This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009
6393 south jamaica court, , englewood, , 80111](https://image.slidesharecdn.com/2054538-250602102958-91ea13b8/85/Download-full-ebook-of-Tomcat-6-Developers-Guide-Damodar-Chetty-instant-download-pdf-46-320.jpg)
![Chapter 2
[ 41 ]
The key APIs that are defined by the Java EE platform include:
Java Database Connectivity (JDBC) API: The JDBC API provides a
database-independent mechanism to access a relational database server.
Note that even application client components may access a database directly
via the JDBC API. However, the preferred mechanism in Java EE 5 is to use
the Java Persistence API whenever possible.
Java Naming and Directory Interface (JNDI): A naming service allows
applications to bind an object to a logical name and to use that logical name
at a later time to retrieve that object. Examples of a naming service include
the file system, where a file name maps to a file object, or the Domain
Naming Service, where a URL is used to lookup an IP address.
A Java EE container implements a naming service. A component within
that container can access this naming service to look up various system- or
user-defined objects, such as a DataSource, an environment variable, or an
Enterprise JavaBean.
A directory service lets you manage a hierarchical tree of objects and their
attributes. Examples of directory services include Lightweight Directory
Access Protocol (LDAP) directories that can be used to store user
information such as user names, passwords, and contact details.
Java EE Connector Architecture (JCA): This API lets you access data that is
contained in existing corporate assets such as non-relational databases and
mainframe applications, from within the Java EE platform.
Java API for XML Processing (JAXP): JAXP allows a Java EE application
to process XML documents, using DOM, SAX, or StAX APIs that are
independent of the underlying XML processor implementation.
Java Message Service (JMS) API: A messaging service allows distributed
applications to communicate using messages. This communication is usually
asynchronous. The JMS API provides a generic API that can be used to access
enterprise messaging implementations from different vendors such as TIBCO
or IBM MQ Series.
JavaMail API: This API provides an interface that an application can
use to interact with different email systems. It uses the JavaBeans
Activation Framework (JAF) API to handle MIME data that are
included in email messages.
Java Transaction (JTA) API: This is a generic API for transaction
management that even supports the complexity of transactions involving
distributed databases. The Java Transaction Service (JTS) provides an
implementation of this API.
•
•
•
•
•
•
•
This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009
6393 south jamaica court, , englewood, , 80111](https://image.slidesharecdn.com/2054538-250602102958-91ea13b8/85/Download-full-ebook-of-Tomcat-6-Developers-Guide-Damodar-Chetty-instant-download-pdf-47-320.jpg)
![Servlet API Overview
[ 42 ]
Remote Method Invocation (RMI) over Internet Inter-ORB protocol
(RMI/IIOP): This API allows distributed EJB components to communicate
with each other and with distributed CORBA services.
Java Persistence API (JPA): This API provides an object/relational mapping
facility for developers. Applications should use this technology in preference
to either CMP entity beans or JDBC access.
Web Service APIs: The Java API for XML Web Services (JAX-WS) and Java
API for XML-based RPC (JAX-RPC) support the invocation of web services
using the SOAP/HTTP protocol. The Java Architecture for XML Binding
(JAXB) defines the mapping between Java classes and XML. In addition,
the Java API for XML Registries (JAXR) provides client access to XML
registry servers.
Java IDL: It allows Java EE application components to invoke external
CORBA objects.
JavaServer Faces (JSF): This API provides a standard way to build
component-oriented web applications that run within a web container.
JavaServer Pages Standard Tag Library (JSTL): This library defines tags
that provide core functionality required by web applications.
Streaming API for XML (StAX): The StAX API provides for a simple pull
parsing programming model for XML. Rather than waiting for program
callback, as with the push-parsing that is used by the Simple API for XML
(SAX) parser model, StAX lets the programmer retain control of the
parsing operation.
Java Management Extensions (JMX): This API supports the web-based
management and monitoring of applications and services.
What is a typical Java EE application
architecture?
In the typical multitier model, the enterprise application's functionality is divided
into three tiers.
The Presentation tier, which is comprised of the web container, and which
houses web components like servlets and JSP pages.
The Middle tier, which is comprised of the EJB container, and which houses
enterprise bean components.
The Persistence or Enterprise Information Systems tier, which houses the
persistent data store.
•
•
•
•
•
•
•
•
•
•
•
This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009
6393 south jamaica court, , englewood, , 80111](https://image.slidesharecdn.com/2054538-250602102958-91ea13b8/85/Download-full-ebook-of-Tomcat-6-Developers-Guide-Damodar-Chetty-instant-download-pdf-48-320.jpg)
![Chapter 2
[ 43 ]
The presentation tier reacts to client requests by invoking business logic that resides
in the middle tier and is responsible for generating the view that is rendered at the
client. The business logic for the application is housed in enterprise beans that live in
the middle tier. This tier is responsible for updating the data stores in the persistence
tier, based on the client's actions.
The creation of multiple tiers gives us the opportunity for scalability, but at the cost
of performance.
However, most applications don't require this level of complexity, and so the Java EE
specification does not require that all three tiers should actually be present.
In particular, the presence of an EJB container in the middle tier often adds
unnecessary complexity. In such cases, you do not need a full blown Java EE
application server, such as JBoss or GlassFish. Instead, you can make do with just
a servlet container such as Tomcat.
In this scenario, the client is a browser, which communicates with the servlet container
using HTML over HTTP. Web components receive these incoming requests, process
them, access the data store as necessary, and return a HTML over HTTP response to
the client browser. In this case, the business domain classes, the business rules, and
the presentation logic are typically interwoven into the web components.
This is the application architecture that we will consider for the remainder of
this book.
Hypertext Transfer Protocol (HTTP)
Any communication between two parties requires a clear understanding of how the
communication will be conducted. For example, a telephone conversation is initiated
by the caller lifting the handset from the cradle, checking for a dial tone, and if the
dial tone is present, beginning to dial the desired number. This is usually comprised
of a country code prefix, followed by the country code, an area code, and the phone
number. If the call is made to another phone within the same country, or within the
same area code, the caller might skip these elements.
At the receiving end, the protocol is much simpler. The called party waits until the
phone begins to ring, at which point, she picks up the phone and indicates that she
is ready to receive the communication by saying 'Hello'.
This telephony protocol has been in place for so many years that it has now become
second nature to us, and seems quite unremarkable. Until of course, you move to a
different country, and suddenly realize that your international dialing prefix is not
011, but is 00 instead, or that the area code prefix is now a 0 rather than a 1.
This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009
6393 south jamaica court, , englewood, , 80111](https://image.slidesharecdn.com/2054538-250602102958-91ea13b8/85/Download-full-ebook-of-Tomcat-6-Developers-Guide-Damodar-Chetty-instant-download-pdf-49-320.jpg)
![Servlet API Overview
[ 44 ]
HTTP is just another communication protocol, except that it defines how one
computer may connect to another to request a particular resource. This particular
protocol has been wildly successful since its introduction in 1990 as HTTP/0.9 and
is today the lingua franca of the Internet.
There are some characteristics that are common to the two communication models.
First, there is a connection that needs to be established between the two parties. This
connection has to be held open until the interaction has been completed and the
information has been completely exchanged. In the HTTP/1.1 protocol, this is called
a persistent connection.
Second, there are two aspects to the communication, the protocol and the actual
payload. In the case of HTTP, the payload is usually text marked up using tags that
are defined by the HyperText Markup Language (HTML). However, HTTP may be
used to transfer other data, including audio and video content. The protocol aspects
are carried in communication headers that indicate various capabilities of the client
(such as the client's preferred character encoding), metadata about the resource being
retrieved (such as the length of the payload data), the server's success at retrieving
this resource, and so on.
Third, there is the question of conversational state. In the typical interaction, a client
(usually a web browser) makes a request for a resource, such as a text file or an
image, and a server responds with that resource.
In reality, a single interaction may consist of multiple such request/response pairs.
This usually happens when a browser requests a page that contains one or more
images. In this case, the connection is held open while a request/response pair
occurs for each of the images on that page. However, once the interaction has
been completed, the connection between the two computers is terminated.
This is why HTTP is considered a stateless protocol. The next time the client connects
to the server to make a request, the server has no memory of the prior interaction
with this client.
HTTP, therefore, defines a connection oriented but stateless protocol.
The astute reader will have noticed that a telephone conversation is not
quite the best analogy for an HTTP interaction. While it is connection
oriented, there is an element of state that is retained in the memories of
both parties while the communication is in progress. On the other hand,
the HTTP protocol is completely stateless.
This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009
6393 south jamaica court, , englewood, , 80111](https://image.slidesharecdn.com/2054538-250602102958-91ea13b8/85/Download-full-ebook-of-Tomcat-6-Developers-Guide-Damodar-Chetty-instant-download-pdf-50-320.jpg)
![Chapter 2
[ 45 ]
Note that it is always the client that initiates the connection in this model. The server
has no means to push content to the client. In this usage, the term client refers to the
computer that initiates the communication. While this is usually a client's browser,
it could also be a server host that initiates a web services type of connection. One
way of simulating a push model, for a browser client, is to simply have the client
reconnect, every so often, to refresh its content (say using the refresh meta tag or
with JavaScript).
The underlying protocol used by HTTP is TCP/IP. While this protocol uses the well
known TCP port 80, other ports may be used. For example, by default, your Tomcat
installation will start up and listen on port 8080 for incoming requests.
Uniform Resource Locator, URL
A Uniform Resource Locator (URL) is described in RFC 3986 (http://www.ietf.
org/rfc/rfc3986.txt) as a uniform way of uniquely identifying a resource such
as an electronic document or an image. URLs are designed to implicitly provide a
means of locating the resource by describing its 'location' on a network.
A generic URL is a hierarchical sequence of components, structured as follows:
scheme://hostName:portNumber/path/to/resource?queryString#fragment
An example of which is:
http://www.swengsol.com:80/file.htm?name=bwaynecity=gotham#profile
Here the scheme is http, the host name is www.swengsol.com, the port
number is 80, the path to the resource is /index.html, the query string is
name=bwaynecity=gotham, and the fragment is profile.
The combination of host name and port number taken together is termed
an authority.
A number of these parts are optional, including the port number (which defaults to
the well known ports 80 and 443 for the http and https schemes respectively), the
query string, and the fragment.
When present, a query string is a series of name-value pairs that are preceded with
a question mark and with an ampersand () separating the pairs.
The hierarchical organization of a URL becomes apparent as you travel from left to
right, with its components increasing in specificity the farther right you go. You start
off with a server domain name, a port on that server, and finally an absolute path on
that server. The portion that comes after '?' is additional information that is useful to
process the located resource.
This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009
6393 south jamaica court, , englewood, , 80111](https://image.slidesharecdn.com/2054538-250602102958-91ea13b8/85/Download-full-ebook-of-Tomcat-6-Developers-Guide-Damodar-Chetty-instant-download-pdf-51-320.jpg)
![Servlet API Overview
[ 46 ]
A URL is composed of characters that are taken from a very limited set—the
letters of the basic Latin alphabet (ISO-8859-1), digits, and a few special characters
('-', '.', '_', '~'). All other characters are deemed to be reserved and must be
percent-encoded before use. In other words, you must convert them to their
hexadecimal representation and prefix them with a % sign. For example, a space
character (32 in ISO-8859-1) is encoded as %20. Other characters that should be
encoded include the percent itself (%25) as well as characters that are used as
delimiters (such as '', '$', and ':').
HTTP methods
An HTTP method, or request type, defines the actions that a client may request from
a server. HTTP/1.1 specifies seven such methods.
GET (HTTP/0.9)
This is the oldest and most commonly used method. It is used to GET a resource
(such as a document or an image file) from a server. It can also request dynamic
content by passing in additional parameters in a query string. This method is
intended to be used only for idempotent requests, that is requests that do not cause
state changes on the server. For example, a retrieval of a resource from the server is
considered idempotent.
The URL for a GET request is portable as it is a self contained unit that can be
bookmarked or emailed. Typing it in over and over into a browser's address bar
should return the same content.
There are some downsides to using this method. Though the protocol does not place
any limit on the length of a URL, lengths should be limited to 255 bytes because
some older browsers or proxies may not properly support greater lengths. As the
query string is counted against this limit, this restricts the amount of information that
can be passed using this mechanism. A security risk associated with this method is
that the parameters that are passed to the web server appear on the address bar in
plain text and so can be easily viewed by anyone. In addition, the URL along with its
query string is often logged at the server and at other hops along its journey, leading
to additional security risks.
Finally, while the specification recommends that a GET request is used only for
idempotent requests, nothing prevents an errant application from violating this
recommendation. It is therefore not at all uncommon to find, for example, a GET
request that causes a shopping cart order to be saved, or a credit card to be charged.
This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009
6393 south jamaica court, , englewood, , 80111](https://image.slidesharecdn.com/2054538-250602102958-91ea13b8/85/Download-full-ebook-of-Tomcat-6-Developers-Guide-Damodar-Chetty-instant-download-pdf-52-320.jpg)
![Chapter 2
[ 47 ]
POST (HTTP/1.0)
This method was introduced to handle non-idempotent requests, that is,
requests that cause a state change on the server, such as inserting a record in
the server's database.
Repeated submission of a non idempotent request is unsafe, as it may end up
causing undesirable effects such as a shopping cart order being saved to the database
multiple times. This method sends its parameters to the server as part of the request
body, rather than in a plainly visible query string. This means that a large amount of
data (even megabytes) can be sent from the client.
A key downside is that the URL is no longer self-sufficient, as the parameters are
now part of the body's payload. As a result, the URL cannot be bookmarked or
emailed to others.
PUT (HTTP/1.1)
The PUT method is used to place a document at the location specified by the URL on
the server.
DELETE (HTTP/1.1)
This method is used to delete a document at the specified URL on the server.
TRACE (HTTP/1.1)
The TRACE method simply returns an exact copy of a request to a client. It is
intended for debugging use and traces the path taken by a request.
OPTIONS (HTTP/1.1)
This method allows the client to query the server about the communication options
that are available with regards to a particular resource without explicitly requesting
that resource. The returned response would include header fields that indicate
optional features that are implemented by the server which are applicable to that
resource. For example, the Allow header lists the set of methods (GET, POST,
and so on) that are supported for a given resource.
HEAD (HTTP/1.0)
The HEAD method is identical to GET, except that it asks the server to return only
the headers of a response, without the message body. It is used when a client only
wants to check the metadata of an entity, such as its last modified time.
This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009
6393 south jamaica court, , englewood, , 80111](https://image.slidesharecdn.com/2054538-250602102958-91ea13b8/85/Download-full-ebook-of-Tomcat-6-Developers-Guide-Damodar-Chetty-instant-download-pdf-53-320.jpg)
![Servlet API Overview
[ 48 ]
HTTP requests
The simplest HTTP request is composed of the following elements:
[request-method] [/path/to/resource] [HTTP protocol version]
[request-header=value]+
[blank-line to indicate the end of the request headers]
[POST:request-payload]
The first line of the request contains the following:
The type of the request, which is usually GET, POST, PUT, DELETE, OPTIONS,
HEAD, and TRACE
The name of the resource that is being requested
The protocol that the browser wishes to use for this communication
Following this first line are the request headers, which in turn are followed by the
request's payload (for a POST request).
As shown, the browser is asking the server (specified by the Host: header)
for the specified resource and is stating that it would like to use HTTP 1.1 for
the communication.
Each request header conveys information either about the client's capabilities or
about the request body. Each header is on a separate line, and the end of the headers
is indicated by a blank line. The final section is the request's body, which contains
form parameters for a POST request.
•
•
•
This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009
6393 south jamaica court, , englewood, , 80111](https://image.slidesharecdn.com/2054538-250602102958-91ea13b8/85/Download-full-ebook-of-Tomcat-6-Developers-Guide-Damodar-Chetty-instant-download-pdf-54-320.jpg)
![ayant disparu, ce fut Ahmed Jeddou qui fut porté par l'élection à la tête de la
fraction. Il mourut vers 1909 et fut remplacé par (6) Ahmed Jeddou ould
Boustami. Les nombreuses plaintes dont il fut l'objet provoquèrent sa
démission en janvier 1911. Il mourut peu de temps après (30 mars 1911).
On put trouver la solution de ce commandement difficile, en sortant des
Ahel Eli-Menna, et (7) Sidina ould Zeïn ould Bouddia fut nommé chef, grâce
à l'appoint des Oulad Sidi Ahmed. Ceux-ci partis au Tagant, Sidina n'eut plus
qu'une minorité dans la tribu. Il fut rapidement convaincu d'exactions par
l'ensemble des Brarka, qui, fidèles à leur campement héréditaire, ne
voulaient pas de lui, et révoqué (fin 1912).
On revint donc aux Ahel Eli Menna, et (8) Mohammed Limam ould
Boustami, frère d'Ahmed Jeddou fut élu. Son élection fut assurée par le bloc
des Ahel Bahmouda, Helalma et Ida Ou Amar, mais il eut l'adresse, le jour
même, de caresser les opposants et de s'attirer leur sympathie. Depuis ce
jour, le calme semble revenu. Mohammed Limam, né vers 1870, assure très
correctement son service. C'est un marabout vénéré et paisible. Il vit, autour
de Mal, en bonnes relations avec ses voisins et particulièrement avec Cheikh
Sidïa. Il a un fils, Boustami, né vers 1905, qui commence à le seconder. Il a
un beau troupeau, et passe pour riche[9]
.
[9] Mohammed Limam est mort de la grippe en décembre 1918.
Les notables de la sous-fraction Habrezza sont: Sidi Ahmed et Mostafa
ould Eli Menna, frère du Cheikh, ses cousins, nommés au tableau
généalogique, et Alfa ould Khouna.
Les Ahel Ammi ont pour chef Sidi Ould Ammi et pour notables: Cheikh
ould Ammi et Sidna ould Omar. Ils sont Ahel Hemid ould Aoubak, ainsi que
les deux sous-fractions suivantes:
Les Ahel Hemid ould Aoubak sont le noyau d'une fraction, jadis
florissante, et qui a essaimé. Leur chef est Abd El-Ouadoud ould Sidi Brahim
et leurs notables sont: Al-Hadj ould Ahmed Maaloum et Ahmed Maaloum
ould Sidi Brahim;
Les Ahel Taleb Maham ont pour chef Sidi Mohammed ould Omar ould
Bouddïa et pour notable: Ahmoud ould Bachir.
Les Ida Ou Omar ont pour chef: Ali ould Mokhtar, leur djemaa comprend
Mahfoudh ould Boubba; Brahim ould Al-Ouâar et Sidi ould Ahmed Bouh.](https://image.slidesharecdn.com/2054538-250602102958-91ea13b8/85/Download-full-ebook-of-Tomcat-6-Developers-Guide-Damodar-Chetty-instant-download-pdf-63-320.jpg)
![dans la descendance de son fils aîné (2) Sidi Abd Allah. C'est ce Sidi Abd
Allah, «homme magnifique, avec une barbe imposante qui descendait
jusqu'à la poitrine, un vrai patriarche» que visita l'enseigne Bourrel, en 1860,
et qui lui fit un si cordial accueil. Les chefs, ses fils, furent d'abord (3)
Mahmoud, mort sans postérité, et (4) Mohammed El-Mrabet, mort au début
de 1914.
Mohammed Al-Mrabet était chef de la tribu lors de l'occupation française.
Obéi et aimé de ses gens, dévoué à nos intérêts, il fut un excellent chef
qu'on a eu le regret de voir mourir de la variole en janvier 1914. Il fut
remplacé par surprise et sous l'influence du grand marabout de la famille,
Cheikh Ahmed Mahmoud, par son neveu (5) Mahmoud ould Mohammed
Mokhtar, au détriment de ses fils.
De ses fils, l'aîné, Sidi Abd Allah, ne voulut pas revendiquer ses droits et
les céda à son cadet Ahmed. Ahmed faisait alors ses études chez les
marabouts du Nord. Il revint immédiatement et réclama le commandement.
Entre temps, il suivait les cours de l'école d'Aleg. On finit par lui donner
droit, et en fin 1914, il fut nommé chef de la tribu.
Mais jeune et léger (6) Ahmed ne sut pas se faire obéir; il manqua
totalement de pondération dans son commandement, et dut être remplacé,
en avril 1917 par son prédécesseur (7), Mahmoud ould Mohammed Mokhtar.
Mahmoud, né vers 1862, marabout paisible, n'a qu'une influence limitée;
il est simplement le membre le plus notoire de la djemaa. Il a trois fils:
Hamma Lamin, Mohammed et Ahmed; il subit fortement l'influence de ses
frères: Had Amin et Mrabet, et surtout de son cousin, le grand Cheikh
spirituel de la tribu, Ahmed Mahmoud. Le jeune Ahmed, qui avait commencé
par faire quelque opposition et avait été, de ce fait, puni disciplinairement,
est revenu au calme[10]
.
[10] Mahmoud ould Mohammed Mokhtar est mort de la grippe en
décembre 1918.
2.—Fractionnement.
Les Hijaj du Brakna se partagent ethniquement et administrativement en
les fractions suivantes:](https://image.slidesharecdn.com/2054538-250602102958-91ea13b8/85/Download-full-ebook-of-Tomcat-6-Developers-Guide-Damodar-Chetty-instant-download-pdf-70-320.jpg)
More Related Content
Similar to Download full ebook of Tomcat 6 Developers Guide Damodar Chetty instant download pdf (20)
Download full ebook of Tomcat 6 Developers Guide Damodar Chetty instant download pdf
- 1. Tomcat 6 Developers Guide Damodar Chetty download https://ebookbell.com/product/tomcat-6-developers-guide-damodar- chetty-4109076 Explore and download more ebooks at ebookbell.com
- 2. Here are some recommended products that we believe you will be interested in. You can click the link to download. Tomcat 6 Developers Guide Damodar Chetty https://ebookbell.com/product/tomcat-6-developers-guide-damodar- chetty-6675446 Pro Apache Tomcat 6 Matthew Moodie Kunal Mittal Ed https://ebookbell.com/product/pro-apache-tomcat-6-matthew-moodie- kunal-mittal-ed-2310020 Professional Apache Tomcat 6 Vivek Chopra Sing Li Jeff M Genender https://ebookbell.com/product/professional-apache-tomcat-6-vivek- chopra-sing-li-jeff-m-genender-4106286 Professional Apache Tomcat 6 Vivek Chopra Sing Li Jeff Genender https://ebookbell.com/product/professional-apache-tomcat-6-vivek- chopra-sing-li-jeff-genender-5473382
- 3. Tomcat Rio Dave Baranek https://ebookbell.com/product/tomcat-rio-dave-baranek-33698768 Tomcat The Definitive Guide 2nd Edition 2nd Edition Jason Brittain Ian F Darwin https://ebookbell.com/product/tomcat-the-definitive-guide-2nd- edition-2nd-edition-jason-brittain-ian-f-darwin-34855020 Tomcat 5 Unleashed Lajos Moczar https://ebookbell.com/product/tomcat-5-unleashed-lajos-moczar-980016 Tomcat Joanne Wiley https://ebookbell.com/product/tomcat-joanne-wiley-48783460 Tomcat The Definitive Guide Jason Brittain Ian F Darwin https://ebookbell.com/product/tomcat-the-definitive-guide-jason- brittain-ian-f-darwin-53639336
- 5. Tomcat 6 Developer's Guide Build better web applications by learning how a servlet container actually works Damodar Chetty BIRMINGHAM - MUMBAI This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009 6393 south jamaica court, , englewood, , 80111
- 6. Tomcat 6 Developer's Guide Copyright © 2009 Packt Publishing All rights reserved. No part of this book may be reproduced, stored in a retrieval system, or transmitted in any form or by any means, without the prior written permission of the publisher, except in the case of brief quotations embedded in critical articles or reviews. Every effort has been made in the preparation of this book to ensure the accuracy of the information presented. However, the information contained in this book is sold without warranty, either express or implied. Neither the author, Packt Publishing, nor its dealers or distributors will be held liable for any damages caused or alleged to be caused directly or indirectly by this book. Packt Publishing has endeavored to provide trademark information about all the companies and products mentioned in this book by the appropriate use of capitals. However, Packt Publishing cannot guarantee the accuracy of this information. First published: December 2009 Production Reference: 1091209 Published by Packt Publishing Ltd. 32 Lincoln Road Olton Birmingham, B27 6PA, UK. ISBN 978-1-847197-28-3 www.packtpub.com Cover Image by Vinayak Chittar ([email protected]) This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009 6393 south jamaica court, , englewood, , 80111
- 7. Table of Contents Preface 1 Chapter 1: Introduction to Tomcat 7 What's the story behind Tomcat? 8 What exactly is Tomcat? 9 JSPs 11 Servlet container 11 Why this book? 13 Gathering our tools 14 Java Development Kit (JDK) 6.0 15 Verifying downloaded files 15 Apache Ant 16 Subversion 17 Obtaining the Tomcat source code 18 Using Subversion 18 Tomcat source distribution 19 Getting ready to build Tomcat 19 Starting up your shiny new Tomcat 21 Eclipse 22 Summary 29 Chapter 2: Servlet API Overview 31 Java Community Process 31 Java Enterprise Edition platform 33 What is an enterprise application? 33 Simultaneous users 34 Highly available, reliable, and scalable 34 Heterogeneous environment 34 Distributed nature 35 Java EE architecture 36 Java based 37 Generic APIs 37 This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009 6393 south jamaica court, , englewood, , 80111
- 8. Table of Contents Java EE containers and container services 38 Java EE components and their APIs 40 Java EE Service APIs 40 What is a typical Java EE application architecture? 42 Hypertext Transfer Protocol (HTTP) 43 Uniform Resource Locator, URL 45 HTTP methods 46 GET (HTTP/0.9) 46 POST (HTTP/1.0) 47 PUT (HTTP/1.1) 47 DELETE (HTTP/1.1) 47 TRACE (HTTP/1.1) 47 OPTIONS (HTTP/1.1) 47 HEAD (HTTP/1.0) 47 HTTP requests 48 HTTP responses 50 The response line 50 Response headers 51 Spying on HTTP 52 What is the Servlet API? 52 Servlet container 53 Core servlet classes 55 Servlets 56 ServletConfig interface 57 ServletContext interface 57 Multithreading in servlets 58 Request 60 Response 62 Sessions 64 Filters 64 Listeners 65 Web applications 66 Deployment descriptors 66 Summary 68 Chapter 3: Servlet Container Overview 69 Component taxonomy 71 Architectural benefits 73 Top Level Components 74 Server 74 Service 75 Connectors 76 Container components 78 Engine 78 Virtual host 79 Context 83 This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009 6393 south jamaica court, , englewood, , 80111
- 9. Table of Contents Wrapper 85 Nested components 86 Valve 86 Realm 88 Executor 89 Listener 89 Manager 89 Loader 90 Logger 95 Resources 96 Summary 97 Chapter 4: Starting Up Tomcat 99 Using scripts 99 Setting up the environment 101 Executing the requested command 103 Setting up your project 105 Modifying the Run/Debug configuration 105 Bootstrapping Tomcat 109 Bootstrapping environment variables 109 Bootstrapping class loading 110 Bootstrapping the embedded container 112 Bootstrapping the Tomcat component hierarchy 113 Initializing the Server 119 Adding a new web application to Tomcat in Eclipse 120 Summary 123 Chapter 5: The Server and Service Components 125 Setting up your project 126 Installing MySQL 126 Installing the MySQL driver 130 Enhancing the devguide web application 131 JNDI service 136 Basic JNDI concepts 137 Using JNDI 144 StandardServer 150 Lifecycle 150 Shutdown 151 JNDI implementation 152 StandardService 157 Summary 158 Chapter 6: The Connector Component 159 Connector classification 160 Usage scenario 160 Protocol 161 Implementation architecture 162 This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009 6393 south jamaica court, , englewood, , 80111
- 10. Table of Contents Connector configuration 163 Binding attributes 164 Socket attributes 164 Thread parameters 165 The connector subsystem—a structural perspective 166 Modeling the Request and Response 170 Coyote and Catalina 170 Request classes 171 Response classes 173 HTTP classes 174 Stream classes 175 Helper classes 178 Socket programming 179 Socket options 181 The connector subsystem—a dynamic perspective 182 Initializing the Apache Portable Runtime (APR) 183 Instantiating a Connector 184 Initializing the Mapper 185 Receiving a request 186 Thread notification 186 End point 189 Connection handler 190 Http11Processor 192 CoyoteAdapter 197 Completing the request 198 Summary 199 Chapter 7: The Engine Component 201 Containers 202 Nested components 203 Engine 204 Configuring an Engine 204 Implementation details 205 StandardEngine 206 Container interface 206 ContainerBase abstract class 207 Pipeline 211 Pipeline execution scope 211 Valve execution order 212 StandardPipeline 212 Valve 214 ValveBase 215 StandardEngineValve 216 Request Dumper Valve 216 Request Filter Valve 217 AccessLogValve 219 Summary 224 This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009 6393 south jamaica court, , englewood, , 80111
- 11. Table of Contents Chapter 8: The Host Component 225 Virtual hosts 226 Tomcat virtual hosts 227 Virtual hosting scenarios 228 Configuring a host 232 StandardHost 236 HostConfig 237 Contexts and context fragments 237 DeployedApplication 239 Lifecycle events 240 Periodic events 244 Examples of name-based virtual hosting 245 StandardHostValve 251 The servlet error handling mechanism 252 Exception processing 253 Method termination 255 ErrorReportValve 255 Error page mechanism example 256 Summary 258 Chapter 9: The Context Component 259 Aspects of the Context component 260 The Context aspect 261 Configuration files 261 Context children 263 Web application aspect 265 Configuration files 266 Web application resources 266 Resources 267 Resource cache 268 Resource retrieval 269 BaseDirContext 269 FileDirContext 270 ProxyDirContext 270 Shared library mechanism 272 Manifest file format 273 URLs and protocol handlers 274 Accessing resources 274 Protocol handlers 275 java.net.URL 276 java.net.URLStreamHandler 277 java.net.URLConnection 277 java.net.URLStreamHandlerFactory 278 Protocol handler implementation 278 Locating a stream handler 279 The jndi protocol 280 This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009 6393 south jamaica court, , englewood, , 80111
- 12. Table of Contents Java class loading 281 Advantages of dynamic class loading 282 Class loader hierarchy 284 Class loader rules 284 Implicit and explicit class loading 286 Tomcat class loading 287 Implementing a custom class loader 289 Making a class available 290 The custom web application class loader 291 Class loader initialization 292 ResourceEntry 294 loadClass() 294 findClass() 295 getResource() 296 Context initialization and startup 297 Context initialization 298 Digesting the context fragment 298 Setting the document base 299 Context startup 300 Anti resource locking 301 Setting up the Context's resources 301 Setting up the Context's Loader 302 Publish the work directory 302 Setting up a servlet context 302 Validating optional JARs 303 Naming context 304 Starting nested components 304 Configuring the web application aspect 304 Starting listeners 306 Starting application filters 307 Session manager and the background thread 307 Loading servlets on startup 308 Request processing 308 Hot deploying a context 309 Determining if a reload is necessary 309 Reloading a context 309 Context example 311 Deployment descriptor 311 Source files 311 HelloWorldServlet.java 312 Message.java 313 Listeners 313 MyFilter.java 314 Summary 315 This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009 6393 south jamaica court, , englewood, , 80111
- 13. Table of Contents Chapter 10: The Wrapper Component 317 StandardWrapper 318 Servlet lifecycle 320 Loading a servlet 320 Mappers 321 Mapping rules 321 Tomcat mappers 323 Request processing 328 Filters 330 Filter chain construction 331 Filter chain invocation 333 Request dispatcher 333 Obtaining a request dispatcher 334 Using a request dispatcher 335 Wrapper classes 337 Examples 342 Servlets 342 ForwardingServlet.java 343 Static resources 344 IncludingServlet.java 345 TemplateServlet.java 346 Summary 348 Chapter 11: The Manager Component 349 Session propagation mechanisms 350 Cookies 350 URL rewriting 351 Session 352 Session identifiers 353 Session attributes 353 Session lifetime 354 Session lifecycle events 357 Session serialization 359 Session multi threading 362 Manager 363 ManagerBase 364 StandardManager 371 Persistent manager 373 Store 376 Summary 377 Index 379 This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009 6393 south jamaica court, , englewood, , 80111
- 14. Introduction to Tomcat It is hard to overemphasize the importance of Apache Tomcat in the realm of Java Enterprise Edition web development. Tomcat began its life as source code that was donated by Sun Microsystems to the Apache Software Foundation (ASF). Since then, it has played a central role in the development and validation of the Java Servlet and JavaServer Pages specifications and has been the official reference implementation for these specifications. Its early popularity stemmed from the fact that it was easily integrated with two of the world's most popular web server software, Apache httpd and Microsoft's Internet Information Services (IIS) server. However, since then, it has evolved into a production-grade product used by multiple large corporations (see a partial list at http://wiki.apache.org/tomcat/PoweredBy). Tomcat is also found embedded, in part or whole, in various open source application server offerings. Even when using competing commercial application server offerings such as IBM's WebSphere and BEA's WebLogic, developers often use Tomcat to validate the vendor-independence of their applications. It is also priced just right. It is open source and distributed under the Apache license, meaning it is free for use and modification (see www.apache.org/licenses for details). This also has the side effect of having the source code readily available for examination. This availability of source code, strict adherence to specifications, and proven track record, combine to make Tomcat a unique learning opportunity for us. This book will assist you in taking the covers off this unique project, so that you get to see exactly how a production-grade servlet container is implemented. This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009 6393 south jamaica court, , englewood, , 80111
- 15. Introduction to Tomcat [ ] What's the story behind Tomcat? As I write this, the most current version of Tomcat is 6.0.20, where 6 is the major version, 0 is the minor version, and 20 is the bug fix release number. This version implements, and is completely compliant with, version 2.5 of the Java Servlet specification, and version 2.1 of the JavaServer Pages (JSP) specification. That's a pretty hefty mouthful, so let's start at the beginning. Every superhero has an origins story, and Tomcat is no exception. The Tomcat web site lists the available versions at http://tomcat.apache.org/whichversion.html, which shows the first stable release listed as Tomcat 3.x. So what happened to versions 1 and 2? Tomcat was conceived in November 1998 by James Duncan Davidson at Sun Microsystems, who wrote it to form the core of the JavaServer Web Development Kit (JSWDK) for the Servlet 2.1 specification. The name 'Tomcat' came to him when he was trying to decide a package name for the code he was working on. He ended up using com.sun.tomcat. At the time, Apache JServ, a free servlet container, was in the process of being updated to support the Servlet 2.1 specification. However, this effort was abandoned due to the donation of Tomcat by Sun Microsystems to the Apache Software Foundation, at JavaOne in 1999. It soon came to life as Tomcat version 3.0, the successor to JSWDK 2.1. This was a major milestone for the open source community as it meant that a commercial package owned and developed by Sun Microsystems, and which implemented the latest Servlet 2.2 and JSP 1.1 specifications, was now being offered to the general public for free. All of this made the decision to abandon Apache JServ rather uncontroversial. The focus soon shifted from updating JServ to support the new specification, to getting Tomcat to implement features that were missing. The most important one being the ability to cooperate with the Apache web server. This was critical to the popularity of Tomcat, as it meant that developers could leverage the static file handling capabilities of the Apache web server together with the dynamic capabilities of Tomcat to achieve a well rounded solution. Subsequent Tomcat releases have actually strengthened this connection component. In addition, Tomcat can now directly serve static content and so is often deployed in standalone mode without a separate web server. This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009 6393 south jamaica court, , englewood, , 80111
- 16. Chapter 1 [ ] It is interesting to note that Tomcat began life not as its own top level project. Instead, it started humbly as a subproject within the Jakarta project (an umbrella project that covers many subprojects such as Apache Commons, Cactus, and JMeter). It was only in 2005 that it was upgraded to the status of a top level project at Apache. What exactly is Tomcat? For most users, the typical web interaction can be represented as follows: Joe User enters a Uniform Resource Locator (URL) in the browser's location box to request the resource that is identified by that URL. A URL is composed of a host name, an optional port (which defaults to 80), and the resource being requested. When a web server receives that request, it first determines whether the resource being requested is static or dynamic in nature. A static resource is one that is identical no matter how many times, or in what order, that resource is requested. Some examples of these would be a company's logo on a web page, a CSS style sheet, or a typical HTML page. The web server handles the request for a static resource by simply fetching the identified resource from the appropriate path in which its static content resides (for example, htdocs for Apache), and returning those bytes in the response to the user. For static resources, a depiction of this request flow is as shown below. Fetch Static resource (html, css, gif, jpg, png ...) Internet Web Server (IIS / Apache) A dynamic resource, on the other hand, indicates a resource that varies its content based on various factors that may include the specific user making the request, the time of day when the request is made, or the presence of additional information in the request that affects how the request is interpreted. Some examples of these would include the current inventory for a specific product in an online store, or the availability of a seat on an airplane. Most web servers are tuned to deliver blazing fast request handling for static resources. However, they require additional help when dealing with dynamic resources. This help is typically provided by an additional software component that is registered with the web server, called a servlet container on the Java EE platform. This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009 6393 south jamaica court, , englewood, , 80111
- 17. Introduction to Tomcat [ 10 ] In the IIS world, access to this servlet container is offered by implementing an Internet Server Application Programming Interface (ISAPI) extension, which is a Dynamic Link Library (DLL) that allows you to extend the functionality of IIS. In the Apache world, you access the container using code written in C or C++. When a request comes in that is directed at a dynamic resource, the web server simply hands off that request to its associated servlet container. The container then springs into action, invokes the appropriate servlet that represents the requested dynamic resource. This servlet is responsible for generating the response. The generated response is returned by the servlet container to the web server which, in turn, returns it to the requesting user. This interaction is depicted in the following diagram. request response Web Server Fetch dynamic resource response Servlet execute Container return response Internet A servlet in its most basic form is a Java class that acts as a dynamic web resource. In other words, it can be the target of a client browser's request. Being a Java class, it can tailor its response according to the payload of the incoming request, the conversation that this request is a part of, as well as other environmental criteria (such as the time of the day or the inventory status from a database). It is important to note that there is nothing special about this delegation mechanism that restricts it only to dynamic resources. You could configure a web server to also delegate requests for a certain subset of static resources (for example, those within a given URL path) to the servlet container. This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009 6393 south jamaica court, , englewood, , 80111
- 18. Chapter 1 [ 11 ] JSPs The problem with using Java code to generate HTML content is that you end up with a lot of string generation and concatenation to generate the actual HTML content, interspersed with actual program logic written in Java. This is an unholy combination as it tends to make the program logic impervious to the person tasked with maintaining your code. In addition, changes to static content now require you to compile the servlet class. Applying the 80-20 rule very loosely to dynamic content, you might find that 80% of the content of a page is in reality static content. The JavaServer Pages specification was evolved as the solution to this situation. A JSP (JavaServer Page) is a template made up primarily of static content with very specific (and hopefully, few) invocations of Java code to retrieve the dynamic aspects of the page. The problem of requiring a compilation step was resolved by making a JSP an artificial construct. The container is responsible for transparently parsing a JSP and converting it into a bona fide servlet, compiling it, and then invoking it in the same manner as the other servlets in the application. As long as the ratio of static to dynamic content is high, that is, as long as there are more static elements than dynamic elements on a page, even non programmers, such as graphic artists, can find their way around a JSP file with some comfort. This is about as much as we will cover on JavaServer Pages technology in this book. Servlet container With all that behind us, we are now ready to answer the question posed by this section's title – what exactly is Tomcat? Tomcat is classified as a servlet container, that is, an environment within which servlets can live and prosper. As a container, it provides a lot of administrative support to servlets, allowing programmers to focus on the core application logic that is to be implemented, without having to bother about low level specifics such as session management and class loading. The servlet and JSP specifications describe the service contract that the container promises to provide to the servlets and JSP files that we write. Together, the specifications describe all the services that a container should provide, and specify how the servlet may make use of those services. As with all other Application Programming Interfaces (APIs), the specifications describe the 'what' and leave the 'how' to the implementer of the specific container. This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009 6393 south jamaica court, , englewood, , 80111
- 19. Introduction to Tomcat [ 12 ] Tomcat serves as the 'reference implementation' of these specifications, and as a result, serves as a guinea pig or canary in the mine shaft for them. In other words, it provides a sample implementation to prove that the specification can indeed be implemented, and serves as a guide for other implementers. The following diagram provides an early bird's eye view of the responsibilities of a servlet container. Server Listener Global Resources Service + Executor Wrapper + Valves Servlet Security JSP Support JMX support Clustering Support Engine Listener Listener Listener Valves Valves Valves Realm Realm Realm Host + Context + Connector (HTTP) Connector (AJP) Connector (HTTPS) Processors Loader Manager Resources The primary responsibility of a container is to process an incoming request and to generate a corresponding response that is then returned to the client. A Connector component provides the external interface that allows clients to connect to the container. This component not only accepts incoming connections, but is also responsible for delegating the processing of the request to an available request processor thread. The 'Processors' block in the image denotes multiple threads in a pool that may be used to process the incoming request. The request processing framework is implemented using a multiple level hierarchy of sub containers (the servlet Engine, virtual hosts, web application contexts, and servlet Wrappers) and nested components (Valves, Listeners, Loaders, Resources, and Security Realms). Note that the '+' sign in the above image indicates that there can be more than one instance of that component. For instance, more than one Host, Context, and servlet Wrapper component may be contained within its parent container. This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009 6393 south jamaica court, , englewood, , 80111
- 20. Chapter 1 [ 13 ] The result of processing a request is represented by a response, which is then returned through the same Connector. In addition to the core request processing components, the container also provides support for other aspects of operation, such as logging, security, and JMX monitoring. In this book, our primary focus will be on the request processing responsibilities of a servlet container. These components form the unshaded boxes in the previous image. Additional topics will be considered only when they are crucial to understanding a request processing component's actions. It is important to note that a servlet container is a completely different beast from an application server. In the simplest sense, an application server contains a servlet container, along with other containers, such as an EJB container, an applet container, and an application client container. In addition, an application server provides implementations for a number of Service APIs that are required for heavy duty applications. We will take a closer look at the Java EE platform in Chapter 2. Examples of application servers include the JBoss Application Server, GlassFish, IBM's WebSphere, and BEA's WebLogic. Whether or not you should use a full fledged application server, with its support for Enterprise JavaBeans and other Java EE heavy artillery, depends on your application needs. Why this book? Tomcat is one of the few technology areas that is particularly blessed with a plethora of very well written books, and the Tomcat mailing lists are rather friendly places for new developers. So really, why another book on Tomcat? The answer is simple. Most of these books and material focus primarily on the set up, administration, and management, of a Tomcat server. This is no accident. Most web developers rarely have to concern themselves with anything more challenging than setting up a context fragment or changing the default port for Tomcat from 8080 to 80. As long as a developer understands the basic terminology of web applications (such as the context, the context root) and the structure of a WAR file, most modern Integrated Development Environments (IDEs), such as Eclipse and IntelliJ IDEA, do all the heavy lifting for you. This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009 6393 south jamaica court, , englewood, , 80111
- 21. Introduction to Tomcat [ 14 ] It seems only appropriate then, for authors to target their books at the typical administrator or deployer. For its part, Tomcat exposes a myriad of configuration files that enable even an obsessive administrator to fine tune the installation and the Java Virtual Machine as much as desired. The net result is that your average book contains the customary chapter on installing Tomcat, chapters on configuring it, on deploying servlets into it, on integration with either the Apache httpd web server or Microsoft's IIS, and on securing the installation. The downside with this approach is that it provides a one-sided view of the software engineering marvel that is Tomcat. You tend to see it as a black box with lots of control switches that you can throw, but you never ever really get a chance to peer into the open vents on the sides of that box. In this book, I hope to correct that imbalance. I'm going to pry open the service door on the side of that black box, and take you in on an interesting journey through some of the sights that most people rarely get to see. A connector shimmering in the moonlight, the rays of the early morning sun catching an application class loader in its native state, a lumbering valve caught in motion capture frames as it springs into action with surprising agility. There are a lot of fantastical beings that populate this world, if you only dare to venture into it. In the course of the next few chapters, we will look at Tomcat from the perspective of someone attempting to understand what makes it tick. Our goal will be to understand Tomcat as few others do. We'll not only see the control switches on the outside, but we'll also learn about how these switches affect the machinery within. Gathering our tools In this section, I'm going to get together all the pieces that you will need for the remainder of this book. If you would like to follow along with the rest of this book, then this section is crucial. The software that we will download and install includes the following: The Java SE Development Kit (JDK) version 6.0 A download verifier Apache Ant 1.7.1 Subversion 1.6.3 Eclipse 3.5 Galileo • • • • • This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009 6393 south jamaica court, , englewood, , 80111
- 22. Chapter 1 [ 15 ] The workstation that I use throughout this book runs a Microsoft Windows operating system (XP Professional or Vista). The version numbers that are specified were current at the time of writing this text. However, with the speed of product cycles in the open source arena, it is likely that newer versions will be available by the time you read this. Java Development Kit (JDK) 6.0 JDK 6 can be found at http://java.sun.com/javase/downloads/index.jsp. As with every download page on the Sun web site, there are enough choices to make your head spin. For our needs, we need the plain vanilla JDK 6.0 that at the time of writing is JDK 6 Update 14. Once you've picked the Platform: (Windows) and Language: (Multi-language), you will end up with a file named jdk-6u14-windows-i586.exe on your workstation. Execute this file to install it. Once you have accepted the terms and conditions, and have picked an install directory, the installation process will begin. Once the JDK has been installed, the installer will prompt you to install the JRE. You may do so if you wish. The JDK for 64-bit platforms There are 64-bit versions of the JDK that are available for Windows, Linux, and Solaris. The file for 64-bit Windows is named jdk-6u14-windows-x64.exe. Verifying downloaded files Most open source software is hosted on multiple mirror sites, and you are expected to pick your nearest mirror from which to download it. A key question here is how do you ensure that the file that you just downloaded is an exact copy of the version that the open source team intended for download, and there isn't a malicious hacker chuckling with glee to see you install a Trojan on your workstation? There are a couple of answers to this question—using PGP keys or using a message digest. The former is more secure as it uses public key cryptography, but as a result is also more complex. This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009 6393 south jamaica court, , englewood, , 80111
- 23. Introduction to Tomcat [ 16 ] The latter, while simpler to use, is not quite as secure, as the most common digest algorithm (MD5) has some well documented flaws, allowing different files to generate the same digest. In addition, the MD5 digest value itself may have been modified by the hacker so that it matches the compromised file. Using the principle that any security is better than none, you would compute the MD5 message digest for the downloaded file, and compare that computed value against the published digest for the file. You can download a digest generator from either www.formilab.ch/md5/ or www.nullriver.com/index/products/winmd5sum. For example, the MD5 digest for the ZIP file distribution of Tomcat 6.0.18 is: f7d0c15df19fedf52476767f7ce0b6f8 *apache-tomcat-6.0.18.zip Apache Ant Apache Ant or Another Neat Tool is a build automation utility that owes its existence to James Duncan Davidson and Tomcat. It originated as a tool used to build Tomcat itself. But its widespread popularity ensured that it was promoted into its own project, independent of Tomcat, in January 2000. As Ant is written in Java, it inherits its Write Once Run Anywhere aspect, making it platform independent. Its build directives (by default, in a file named build.xml) are written using XML - another cross platform advantage. Ant build directives take the form of targets that describe the actions or tasks that must be performed, whether creating, deleting, or copying files and directories, setting classpaths, compiling Java classes, or even packaging your applications. The ability to define dependencies on targets adds to its flexibility. You can indicate that a compile target depends on other targets that clear out the output directories, fetch the latest changes from your source code repository, and set the classpath. Finally, throw in the ability to define your own targets, and the sky's the limit! Download the latest version from http://ant.apache.org/bindownload.cgi and extract the Ant distribution. The version that was current when I wrote this, was Ant 1.7.1. You need to add Ant to your PATH. On Windows, this is accomplished by opening the System Properties box – by right clicking your My Computer icon and clicking Properties. Pick System from the Control Panel's classic view or press the keyboard shortcut Windows + Pause/Break. This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009 6393 south jamaica court, , englewood, , 80111
- 24. Chapter 1 [ 17 ] On the Advanced system settings tab, click on Environment Variables tab and edit the Path variable. Add [ANT_HOME]bin to the end of the path variable, replacing [ANT_HOME] with the absolute path to the location where you extracted the downloaded file. Note that path variables in Windows are delimited by a semicolon. Subversion Next, we need a way to retrieve the latest version of the Tomcat source code, which is currently housed in a Subversion repository. Subversion was conceived in 2000, when CollabNet, Inc. decided that it was time to write a brand new version control system, and brought on Karl Fogel to head this effort. The stated goal of the original team was to write a better version of CVS, while retaining the familiar elements of CVS, to make it easier for developers to switch without much effort. Subversion has since dethroned CVS as the system of choice. In particular, it has been adopted as the standard version control mechanism by the Apache Software Foundation. Subversion, like CVS, uses a copy-modify-merge model. In the copy phase, each developer makes a private copy of the project's source code on to their individual workstations. This copy acts as a sandbox within which each developer may work. In the modify phase, each developer makes changes in his or her own working copy. The changes made by one developer are not visible to the others. If you need visibility into another developer's changes, you would need to update your working copy from the repository. In the merge phase, a developer commits his changes back into the source code. If a file was modified by another developer since you checked out your copy, you would then need to merge your changes back into the repository resolving any conflicts as necessary. Get the latest version of the Subversion Command-Line Client for Windows from http://www.collab.net/downloads/subversion/, which is currently 1.6.3. Execute the downloaded file, CollabNetSubversion-client-1.6.3-3.win32.exe. The installation is fairly straightforward and only requires that you specify a path name for your installation. This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009 6393 south jamaica court, , englewood, , 80111
- 25. Introduction to Tomcat [ 18 ] To verify that the software was successfully installed, run the svn --version command from the command prompt. This command should output the version of Subversion that is installed on your workstation. Obtaining the Tomcat source code You have two options when trying to download the Tomcat source. You could either use the Subversion version control software, which was described in the last section, or you could simply download the compressed source distribution of Tomcat as a ZIP file. The former option is preferred if you expect to be developing in Tomcat, whereas the latter is simply a snapshot of the code at a given version. Using Subversion To obtain the latest source code for Tomcat from the Subversion repository at the ASF, change your working directory to where you want to download your working copy (for example, c:tomcat), and execute the following at the command line (all on one line): svn checkout http://svn.apache.org/repos/asf/tomcat/tc6.0.x/trunk/ When this completes, you will notice that your current directory now contains a trunk subfolder with the source directories for Tomcat. The above command downloads the most up-to-date version of the source trunk and may result in code that may differ from the descriptions in this text. If you would like to ensure that you are working with the exact codebase covered in this book, then you should use the following command instead: svn checkout http://svn.apache.org/repos/asf/tomcat/ tc6.0.x/tags/TOMCAT_6_0_20/ This is the 'copy' phase of your interaction with the Subversion version control system. The result of this operation is to make a local copy of Tomcat's latest development code line from the Subversion repository. This lets you play in your own little sandbox, making changes and experimenting for as long as you need. This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009 6393 south jamaica court, , englewood, , 80111
- 26. Chapter 1 [ 19 ] Tomcat source distribution If you'd rather not install Subversion, a less invasive option would be to simply download the Tomcat source from the Source Code Distributions section at http://tomcat.apache.org/download-60.cgi.The source for a previous version can be downloaded from http://archive.apache.org/dist/tomcat/tomcat- 6/. The only downside with this approach is that the source distribution does not contain a project file for use with the Eclipse IDE. To get these files, point your browser at http://svn.apache.org/repos/asf/tomcat/tc6.0.x/trunk (or to http://svn.apache.org/repos/asf/tomcat/tc6.0.x/tags/TOMCAT_6_0_20 for the version used in this book) and download the .classpath and .project files. Ensure that the downloaded files are named exactly the same as their originals. Getting ready to build Tomcat Now, we're ready to get started with building the source that we just downloaded. This is a two step process that utilizes the power of Ant and the build.xml file that exists in the trunk directory. First change directory to the directory to which your source code has been downloaded (or unzipped.). Downloading dependencies Now, run the download target: ant download The download target downloads a number of binaries that are needed for this build. These artifacts are downloaded to the folder that is identified by the base.path property in the Ant build.properties.default file. By default, this will be /usr/share/java. However, you can change this to a different absolute path such as c:/tomcat/downloads/trunk. The files that are downloaded include: The native Tomcat connectors (currently at version 1.1.15). The Commons daemon library (version 1.0.1), which is used with jsvc—a Java Service Wrapper that is used to run Tomcat as a non-root user listening on the privileged port 80 on non Windows operating systems. • • This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009 6393 south jamaica court, , englewood, , 80111
- 27. Introduction to Tomcat [ 20 ] The Eclipse JDT JAR, which is used by Tomcat to compile JSPs. The Nullsoft Scriptable Install System (NSIS)—an open source system to create Windows installers. The Commons Collections library. The Commons Database Connection Pool (version 1.2.2) and Commons Pool (version 1.4). The build-tomcat-dbcp Ant target renames the packages for these Commons projects, for example, by replacing org.apache.commons with org.apache.tomcat.dbcp. The stated goal here is to ensure that the DBCP and Pool classes, used by Tomcat internally, do not conflict with any versions of DBCP or Pool classes that are packaged with individual web applications. Download errors I have noticed that the download target sometimes fails when trying to unzip the NSIS with the following error: java. io.IOException: Negative seek offset In such cases, a manual workaround is to simply download the target ZIP file (in this case http://downloads. sourceforge.net/nsis/nsis-2.37.zip) and unzip it to the folder into which the build script is downloading files. Then, ensure that the test file is present, which in this case is c:/tomcat/downloads/trunk/nsis-2.37/makensis.exe. Building Tomcat We're finally ready to build Tomcat using Ant, so run the deploy target. ant deploy This target compiles the Java code and builds the binary distribution of Tomcat. Note that you can omit the target name because deploy is defined as the default target in the build.xml file. So the following would be equivalent: ant • • • • This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009 6393 south jamaica court, , englewood, , 80111
- 28. Chapter 1 [ 21 ] The deploy target builds the Tomcat binaries and copies files out to outputbuild. The clean target If you need to start with a clean build, then the clean target is your friend. It clears out all the output folders for a fresh distribution to be laid into it. Starting up your shiny new Tomcat From the outputbuildbin directory within your Tomcat trunk folder, execute the startup.bat batch file. startup This starts up your Tomcat server in a separate command window. Reassuring log messages should be output to your console as shown. This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009 6393 south jamaica court, , englewood, , 80111
- 29. Introduction to Tomcat [ 22 ] Now, using your favorite browser, type in the URL http://localhost:8080, and marvel at what you have wrought. Finally, to shut down your server, execute the shutdown.bat batch file. shutdown This command closes down the Tomcat server gracefully, and you're done. Eclipse We're now on to the home stretch. The ultimate prize for us is to be able to use an IDE to run the Tomcat server. What would be more appropriate for investigating Tomcat, than the free and full featured open source IDE—Eclipse! While you can simply use your favorite IDE, the Tomcat source distributions include project metadata files only for the Eclipse IDE. This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009 6393 south jamaica court, , englewood, , 80111
- 30. Chapter 1 [ 23 ] In particular, let's pick Eclipse Galileo, which is the most recent in an annual series of releases that package multiple major projects. Previous releases have been code named Callisto, Europa, and Ganymede. Galileo was released in June 2009, and includes the core Eclipse project along with almost three dozen other major projects, including the Web Tools Platform project, the Rich Ajax Platform project, and the SOA Tools Platform project. Eclipse downloads are available at http://www.eclipse.org/downloads/. Make sure that you pick the Eclipse IDE for Java EE Developers version. For Windows, this results in the file eclipse-jee-galileo-win32.zip being copied down to your workstation. Eclipse for 64-bit Windows The above link works fine for downloading Eclipse for the most common platforms, including 64-bit Linux. However, you have to work a bit harder to get the 64-bit version for Windows. The downloads for the Eclipse project are available at http://download.eclipse.org/ eclipse/downloads/. For safety, click the link associated with the Latest Release version, which is currently at 3.5. These downloads are named eclipse-SDK-[versionNumber]-[platform].zip. For Vista 64, this download is eclipse-SDK-3.5-win32-x86_64.zip. Unzip the Eclipse distribution to a folder of your choice, and execute eclipse.exe to verify that your IDE starts up. At startup, you are prompted for a workspace location. A workspace folder is used to house your projects as well as to store metadata about your plugins and your IDE preferences. This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009 6393 south jamaica court, , englewood, , 80111
- 31. Introduction to Tomcat [ 24 ] In this dialog, you can either point to an existing workspace folder if you have one, or to a new folder location. It is recommended that you pick a folder that lies outside of your Eclipse installation directory so that when you upgrade your Eclipse version, you can simply delete the old installation folder without losing your workspace. Once Eclipse starts up, dismiss the Welcome screen to proceed to the Workbench, and then select the Window | Preferences menu option to display the Preferences dialog. In the left pane of this dialog, drill down to Java | Installed JREs, and verify that your previously installed version of JDK 6 shows up. If it doesn't, then click on the Add button to add a reference to your JDK. This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009 6393 south jamaica court, , englewood, , 80111
- 32. Chapter 1 [ 25 ] We will also set up two classpath variables as shown next—ANT_HOME to point at the base directory for your Ant installation and TOMCAT_LIBS_BASE to point to the directory that holds the files downloaded by the download ant target that you executed while building Tomcat. If you are building a non-trunk version of Tomcat, then ensure that your TOMCAT_LIBS_BASE classpath variable points to the path to where the ant download target downloads its dependencies. This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009 6393 south jamaica court, , englewood, , 80111
- 33. Introduction to Tomcat [ 26 ] Next, import the project file that is present in the working copy of the Tomcat trunk. Choose File | Import to open the Import dialog. From this dialog, choose General | Existing Projects into Workspace to import the Eclipse project present in the Tomcat trunk into your new workspace. This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009 6393 south jamaica court, , englewood, , 80111
- 34. Chapter 1 [ 27 ] Click on Finish to import the project. A project build begins automatically, and you will get the following screen. This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009 6393 south jamaica court, , englewood, , 80111
- 35. Introduction to Tomcat [ 28 ] To start up your Tomcat server from within Eclipse, create a Run configuration by choosing the Run | Run Configurations… menu option, and select org.apache.catalina.startup.Bootstrap as the Main class. Click on Run, and watch the Console pane for output indicating that Tomcat was successfully started. Now browse on over to http://localhost:8080 to view the Tomcat welcome page. Congratulations! You're done. For now, play with this code by placing breakpoints and stepping through interesting code sections. We'll explore these sections in far greater detail in the chapters to come. In the next couple of chapters, we'll regroup and visit concepts that are necessary for the exploring that we'll be doing in later chapters. This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009 6393 south jamaica court, , englewood, , 80111
- 36. Chapter 1 [ 29 ] Summary We covered a lot of ground in this chapter. We began by looking at the principles behind a servlet container. We looked at the origins of Tomcat, and we built ourselves our very own server by cobbling together a number of software helpers. We looked at the JDK, the Ant build tool, the Subversion version control tool, and the Eclipse IDE. We retrieved the latest source from the Tomcat Subversion repository, and we compiled the Java sources to result in a binary distribution of the container. In the next chapter, we'll explore some of the ideas embodied in the servlet specification. This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009 6393 south jamaica court, , englewood, , 80111
- 37. Servlet API Overview In the preceding chapter, Apache Tomcat was described as a reference implementation of the Servlet and JSP specifications. There are two concepts here that go together like peanut butter and jelly—a specification and its implementation. While the bulk of this book is focused on the implementation aspect, this chapter takes a bit of a detour to review the actual specification that is under discussion. Think of it as a walk through the actual requirements that the Tomcat development teams were given to implement. We will begin by taking a look at how specifications are born and nurtured in the world of Java. We will then look at the Java Enterprise Edition specification, the uber-specification of which the Servlet and JSP specifications are but a part. We will end our tour by examining the Servlet and JSP specifications themselves. There is a lot of ground to cover, and concepts will be coming at you from every direction. But at the end of this chapter, you will be able to appreciate exactly how servlets fit into the grand scheme of things, and you will be very well positioned to appreciate the huge effort undertaken by the Apache Tomcat project teams. Readers who are familiar with the Servlet API and the� Hypertext Transfer Protocol (HTTP) may safely skip this chapter. Java Community Process The Java Community Process (JCP) was introduced by Sun Microsystems in 1998. Its primary goal was to engage the greater Java community in the process of developing and revising Java Application Programming Interfaces (APIs). The process is currently at version 2.6 (http://jcp.org/en/procedures/jcp2). This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009 6393 south jamaica court, , englewood, , 80111
- 38. Servlet API Overview [ 32 ] The JCP works by bringing together a group of experts in the subject area, under the guidance of a technical specification lead to not only develop or revise a specification, but also to build a reference implementation as well as a technology compatibility kit. The process starts with the submission of a Java Specification Request (JSR), which either proposes a brand new specification or a significant revision to an existing specification. An API is the contract that is made by a software package in terms of the functionality that it makes available to the developer. There is an implicit guarantee that APIs can be relied upon to exist for a very long time. You can see this at work in many Java APIs, where even questionable API decisions live on in perpetuity, as deprecated methods. A specification has, at its core, the API for some aspect of the technology. For example, the Servlet 2.5 specification of August 2007 devotes almost half its pages to the API embodied in its javax.servlet and javax.servlet.http packages. The rest of its pages are split between the description of concepts that are introduced by the specification (servlets, the servlet context, sessions, filters, and so on) and a description of the functional requirements of a Java Enterprise Edition 5 servlet container. A platform edition specification is a more involved animal and defines a baseline set of APIs that provide a foundation upon which applications can be built. For example, the Java Enterprise Edition platform describes a set of APIs (such as the JDBC, JNDI, and Servlet APIs) that are guaranteed to be available to any application that runs within a Java EE compliant server. A reference implementation is the proof of concept implementation for a given specification, and is intended to prove that the specification can actually be implemented. Apache Tomcat serves as the reference implementation for the Servlet and JSP APIs; whereas the Sun Java System Application Server (GlassFish) is the reference implementation for the entire Java EE 5 stack. A technology compatibility kit is used to verify that a given implementation is compliant with its specification. It consists of a set of tests, a mechanism to automate these tests, useful tools, and documentation. The reference implementation also serves as a useful platform against which to validate the tests in the TCK. The current version for the Servlet API is the Java™ Servlet Specification version 2.5 Maintenance Release 6 specification. This specification was developed using the JCP as Java Specification Request 154. This document can be downloaded from http://jcp.org/en/jsr/detail?id=154. This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009 6393 south jamaica court, , englewood, , 80111
- 39. Chapter 2 [ 33 ] A more recent maintenance release specification of the API can be obtained from http://jcp.org/aboutJava/communityprocess/mrel/jsr154/index.html. Java Enterprise Edition platform The Java Enterprise Edition platform is nothing more than a set of API specifications that act as building blocks that you can use to build enterprise applications. With its most recent release, the name of the Java Enterprise Edition platform has been simplified. Instead of being called the Java 2 Platform, Enterprise Edition (J2EE) v1.5, the version up from J2EE v1.4 is now labeled Java Enterprise Edition 5 or Java EE 5. It is incorrect to abbreviate this name as 'JEE'. The main drivers for this change are a desire to do away with the '2', which really was beginning to lose its meaning anyway; and to provide center stage to the word 'Java', which is the core technology underlying the different platform editions. While this may seem like just a rebranding decision, there are some real issues associated with it. Firstly, you need to be aware that you might come across JARs named j2ee.jar and javaee.jar and will need to know which one to pick. Secondly, you need to remember that this is more like deprecation, rather than a replacement, that is, most people will continue to use the term J2EE long into the future—on resumes, job requisitions, design documents, and on blogs. An 'enterprise application', just by the sound of it, seems more forbidding than plain old 'application'. It is therefore interesting to look at what exactly makes an application, an 'enterprise application'. What is an enterprise application? To help us see the difference here, let us consider prototypical examples of both types of applications. A representative 'application' might be the standard personal finance management applications, such as Microsoft's Money™ or Intuit's Quicken™. A prototypical 'enterprise application', on the other hand, would be an online banking system. Both applications are fairly similar in that you can view the transactions for one or more accounts, transfer money either into or out of an account, schedule bills that come due, and you can reconcile your checkbook based on statements. In addition, you may also have the ability to run reports on amortization tables, spending patterns, or transaction histories. This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009 6393 south jamaica court, , englewood, , 80111
- 40. Servlet API Overview [ 34 ] So what makes one an enterprise application and the other not? The essence of an enterprise application can be boiled down into four concepts—simultaneous users, highly performant systems, heterogeneous environments, and a distributed nature. Simultaneous users An enterprise application is expected to be used simultaneously by more than one user. In fact, such applications are often expected to be accessed simultaneously by hundreds or even thousands of users. This adds complexity as you now need to apportion system resources across these users. In addition, you must also ensure that one user does not interfere with the operations of another, even if they happen to be working on the same data. Highly available, reliable, and scalable An enterprise application is one where there is usually significant potential for loss if its users are unable to access and use it in a predictable manner. This encompasses the concepts of availability, reliability, and scalability. An online banking application has to be available when the customer needs it, irrespective of the time of day. It has to function reliably when used by that customer and should be able to handle higher peak loads over certain periods such as major holidays like Christmas or the periods when paychecks are deposited by employers. A failure on any one of these criteria results in a loss of customers, a loss of revenue, or both. While these characteristics are equally important to non-enterprise applications, the impacts of failure are often much less dramatic as such applications are generally designed to be used either by a single user, or by a very small set of users. Heterogeneous environment A typical enterprise application has very little control over its destiny. Most often it is cobbled together from various collaborating systems, many of which have been in operation for a number of years (or decades). This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009 6393 south jamaica court, , englewood, , 80111
- 41. Chapter 2 [ 35 ] An enterprise typically already has a significant investment in terms of software, hardware, staffing, and infrastructure in its existing legacy systems. By necessity, any new development needs to play nice with these. This may include software systems (such as Enterprise Resource Planning systems, Custom Relationship Management products, and mainframe systems), operating systems, data sources (such as IMS, Oracle, and SQL Server), application servers (such as WebSphere, WebLogic, and JBoss), communication protocols, and data formats. An ability to integrate nicely with these disparate technologies is the hallmark of an enterprise application. A point of note is that one of the most significant investments that an enterprise makes is in its data. Most of the time this investment is locked within silos throughout the enterprise, making the task of turning it into useful information a very daunting one. Most enterprise applications have, as their central focus, the ability to access this shared data, freeing it from the grips of traditional systems. On the other hand, non-enterprise applications are fairly standalone entities. For instance, installations of Microsoft Money never need to deal with the issues of application or system integration, or with the issues of integrating data from multiple data stores. The only real complexity often arises from data transfer format requirements. For example, personal finance software will typically download transaction data from financial institutions using either the Open Financial Exchange (OFX) or the Web Connect (QFX) formats. Distributed nature An enterprise application rarely runs on a single computer host. This is almost always necessitated because of performance and scalability, as there is a practical limit on how much work can be assigned to a particular computer; as well as of heterogeneity, since the collaborating systems may run on their own dedicated hardware. As a result, when describing your enterprise application, you tend to speak in terms of server farms, clusters, load balancers, DMZs, firewalls, and so on. A corollary of this fact is that portions of the enterprise application itself may be distributed across multiple hosts. For instance, the logic that determines what is rendered to the user can be separated into its own tier from that of the logic that defines the business rules for the application, and there can be yet another tier that houses the persistent data store used by the application. It is important to note that these tiers can either be logical (when all these tiers run on the same physical machine, possibly within the same Java Virtual Machine) or physical (when each of these tiers runs on a dedicated physical machine.) This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009 6393 south jamaica court, , englewood, , 80111
- 42. Servlet API Overview [ 36 ] On the other hand, the typical vanilla application runs on a single workstation and is designed to serve a single user. You will be hard pressed to find a distributed implementation of either Money or Quicken. To summarize, there are very valid reasons as to why enterprise application development is crucial to a corporation's survival - it serves as the best way to leverage your existing technology investments. Java EE architecture In its most basic form, the Java Enterprise Edition platform describes a set of APIs that must be implemented by any Java EE compliant application server platform. These APIs are guaranteed to be available to any application that runs on a Java EE compliant server. The API implementations that are provided by a Java EE application server provider make it easy for a developer to focus on the business requirements, instead of having to implement infrastructural aspects of a complex enterprise application, such as having to figure out how to implement 2-phase commits to ensure that transactions work across disparate data sources. A transaction is defined as a grouping of tasks that must be either executed completely or must not be executed at all. The typical example is that of a transfer of funds between two accounts, which is comprised of two tasks—a withdrawal from the first account and a deposit into the second. If a system failure occurs between these two tasks, then data corruption is likely as the withdrawal has taken place but no corresponding deposit has occurred. The complexity of transactions in an enterprise application is compounded by the fact that the individual tasks may involve completely different database servers or other legacy data stores. An additional benefit of writing applications based on the standard Java EE APIs is that your application is now implementation independent. In other words, your application can be deployed on any vendor's Java EE compliant application server. In fact, a popular recommendation is to deploy applications on the reference implementation, as well as on the target application server. This ensures that you have not inadvertently locked yourself into a particular vendor's platform implementation. This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009 6393 south jamaica court, , englewood, , 80111
- 43. Chapter 2 [ 37 ] However, you need to take this advice with a pinch of common sense. Vendor lock-in is not always bad, especially if you are getting something material in return (such as improved reliability, stability, or functionality). The choice of a vendor is often based on numerous factors, such as licensing costs, administrative/deployment staff expertise, and proven performance on existing production applications. As a result, changing vendors rarely happens as often as one might fear. There are a few key features about the Java EE architecture that merit mention. Java based The Java EE platform is a superset of the Java SE platform. As a result, it inherits its basic advantages, such as the ability to run Java applications on diverse operating systems, its mature and flexible object-oriented programming model, its ability to work well across a network (including over the Internet), its automatic garbage collection mechanism, and its inherent multithreaded nature, all of which make for a very compelling package. Generic APIs A key aspect of enterprise application development is the need to work and integrate with a variety of disparate systems. Learning the individual APIs of each of these diverse systems can be an insurmountable task. Java EE provides a solution for this problem—by separating the vendor-agnostic aspect of an interaction, the API, from the vendor-implementation aspect, termed the Service Provider Interface (SPI). This design provides for an astonishing decrease in the level of complexity that developers need to contend with during enterprise development. As an example, consider the Java Naming and Directory Interface API. The published API is generic enough to be used against any particular vendor implementation, whether LDAP, the RMI Registry, or even just the file system. As a developer, all you need is to be aware of the vendor-agnostic API. You will also supply some configuration information that is appropriate for your choice of vendor such as the URL at which to access the service, authentication credentials, and the factory class for the initial context. A service provider implements not only the SPI that defines the core service implementation, but also any abstract classes and interfaces that are left undefined in the API itself. Service providers may be linked into the Java EE platform server either statically (through configuration files or deployment descriptors) or dynamically at runtime. When multiple providers implement the same functionality, an application may choose, at runtime, which particular provider's implementation to use. This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009 6393 south jamaica court, , englewood, , 80111
- 44. Servlet API Overview [ 38 ] As an application programmer, you will typically use a factory method to interact with the service provider, which will return to you the appropriate instance, which implements an interface within the Java EE API. Your application interacts with this generic interface using the functions defined by the API and is completely oblivious to the specific implementation class. This basic theme is repeated over and over again within the Java EE. Java EE containers and container services The Java EE platform is designed around a containment hierarchy, where an application server hosts containers, each of which in turn hosts components. A container is responsible for configuring its components based on the deployment descriptor, allowing component behavior to be controlled using configuration rather than code. For example, a deployment descriptor may specify that a particular Enterprise JavaBeans method may not be invoked unless the user belongs to a given security role. It is also responsible for managing the life cycle of its components. For instance, a servlet container will load the servlet class, instantiate it, call its initialization method, will repeatedly call its service method as requests come in, and will finally call its destruction method when it is being taken out of service. The container is also the gateway through which its components may access their runtime environment. It is also the intercessor when one component needs to communicate with another Java EE component. This intercession allows the container to add value by transparently propagating transactions, implementing security checks, and so on. This container-based architecture provides an effective way of providing a separation of concerns. The deployed components can now focus on the business problem being solved, whereas the container can provide the plumbing and infrastructure required to make everything work. Each platform vendor must implement these containers so as to maintain the contract with its components as specified in the appropriate API specification. While this does not stop the vendor from providing additional services through the container, it does ensure that each component can be guaranteed to find a baseline set of services, irrespective of the particular vendor implementation that it is deployed into. The Java EE specification defines four types of containers. This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009 6393 south jamaica court, , englewood, , 80111
- 45. Chapter 2 [ 39 ] An application client container provides the runtime environment for Java programs (either graphical user interface based or command line) that execute on a client workstation. Application clients are the same as standard Java SE applications, so no special life cycle calls are made by this container. An applet container contains applets that typically execute natively within a browser or through the Java Plug-in product. A servlet container hosts Servlet API and JavaServer Pages API components, which are used to service HTTP requests from web clients. Finally, an Enterprise JavaBeans (EJB) container hosts EJB components, which houses the business logic that is usually found in the middle tier of a Java EE application. A typical servlet container (such as Apache Tomcat) will, among other things, allow a developer to package a web application as per the Servlet specification. It will load the appropriate servlets as necessary, will invoke a servlet's lifecycle and service methods, and will provide the servlet instance with access to information about its operating context. Similarly, an EJB container will provide its contained components (Enterprise JavaBeans) with services for security, transactions, instance pooling, and so on. A container is usually controlled through configuration files, such as Tomcat's server.xml file. Java EE Platform Specification APIs: JPA JSF JSTL StAX Public API SPI ... APIs: JPA JSF JSTL StAX JNDI Public API SPI Provider Implementation ... deployment descriptor EJB Container Components EJBs Application Client Container Application Clients Applet Container Applets Servlets JSPs Components Servlet Container deployment descriptor APIs: JPA JSF JSTL StAX JNDI Public API SPI Provider Implementation ... Java SE Java SE Java SE Java SE TCK This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009 6393 south jamaica court, , englewood, , 80111
- 46. Servlet API Overview [ 40 ] This figure summarizes the concepts that we've introduced so far—the distinction between the API and the SPI, the Java EE containers, and the component model. The specification of the platform is comprised of the specifications for multiple containers. Each container is responsible for hosting its own component model. The components for each container expect certain services to be provided by their container. The face that services expose to components is defined by the service's API. The vendor implements each service by providing code that implements the SPI, the abstract classes, and interfaces that are defined by the API. Finally, a deployment descriptor may be used to configure the container's services and runtime environment, as well as to define how the components are deployed into that service. The Technology Compatibility Kit (TCK) is a set of tests that allow you to validate the compliance of a container implementation with its specification. Java EE components and their APIs The Java EE platform uses a component-based development model. This is different from a class-based model as a component typically consists of more than one class cooperating to achieve some reusable unit of functionality. A Java EE application is built by assembling multiple such standalone components and deploying them with their configurations into their associated containers. The power of Java EE comes from the fact that components can be independently developed, tested, assembled, and deployed into any Java EE compliant vendor's server implementation. Each container can deploy its own unique set of components. The application client container can contain application client components, which are standard Java programs. The applet container contains applet components. The web container contains web components, such as JSP, Servlet, Filter, and event listener components, whereas the EJB container contains enterprise bean components. Application logic typically resides in the components, and business logic usually resides in the enterprise bean components. In this book, we will primarily focus on the servlet container and web components. Java EE Service APIs The Service APIs serve to simplify your programming tasks by providing standard APIs to access diverse systems or alternative implementations. This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009 6393 south jamaica court, , englewood, , 80111
- 47. Chapter 2 [ 41 ] The key APIs that are defined by the Java EE platform include: Java Database Connectivity (JDBC) API: The JDBC API provides a database-independent mechanism to access a relational database server. Note that even application client components may access a database directly via the JDBC API. However, the preferred mechanism in Java EE 5 is to use the Java Persistence API whenever possible. Java Naming and Directory Interface (JNDI): A naming service allows applications to bind an object to a logical name and to use that logical name at a later time to retrieve that object. Examples of a naming service include the file system, where a file name maps to a file object, or the Domain Naming Service, where a URL is used to lookup an IP address. A Java EE container implements a naming service. A component within that container can access this naming service to look up various system- or user-defined objects, such as a DataSource, an environment variable, or an Enterprise JavaBean. A directory service lets you manage a hierarchical tree of objects and their attributes. Examples of directory services include Lightweight Directory Access Protocol (LDAP) directories that can be used to store user information such as user names, passwords, and contact details. Java EE Connector Architecture (JCA): This API lets you access data that is contained in existing corporate assets such as non-relational databases and mainframe applications, from within the Java EE platform. Java API for XML Processing (JAXP): JAXP allows a Java EE application to process XML documents, using DOM, SAX, or StAX APIs that are independent of the underlying XML processor implementation. Java Message Service (JMS) API: A messaging service allows distributed applications to communicate using messages. This communication is usually asynchronous. The JMS API provides a generic API that can be used to access enterprise messaging implementations from different vendors such as TIBCO or IBM MQ Series. JavaMail API: This API provides an interface that an application can use to interact with different email systems. It uses the JavaBeans Activation Framework (JAF) API to handle MIME data that are included in email messages. Java Transaction (JTA) API: This is a generic API for transaction management that even supports the complexity of transactions involving distributed databases. The Java Transaction Service (JTS) provides an implementation of this API. • • • • • • • This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009 6393 south jamaica court, , englewood, , 80111
- 48. Servlet API Overview [ 42 ] Remote Method Invocation (RMI) over Internet Inter-ORB protocol (RMI/IIOP): This API allows distributed EJB components to communicate with each other and with distributed CORBA services. Java Persistence API (JPA): This API provides an object/relational mapping facility for developers. Applications should use this technology in preference to either CMP entity beans or JDBC access. Web Service APIs: The Java API for XML Web Services (JAX-WS) and Java API for XML-based RPC (JAX-RPC) support the invocation of web services using the SOAP/HTTP protocol. The Java Architecture for XML Binding (JAXB) defines the mapping between Java classes and XML. In addition, the Java API for XML Registries (JAXR) provides client access to XML registry servers. Java IDL: It allows Java EE application components to invoke external CORBA objects. JavaServer Faces (JSF): This API provides a standard way to build component-oriented web applications that run within a web container. JavaServer Pages Standard Tag Library (JSTL): This library defines tags that provide core functionality required by web applications. Streaming API for XML (StAX): The StAX API provides for a simple pull parsing programming model for XML. Rather than waiting for program callback, as with the push-parsing that is used by the Simple API for XML (SAX) parser model, StAX lets the programmer retain control of the parsing operation. Java Management Extensions (JMX): This API supports the web-based management and monitoring of applications and services. What is a typical Java EE application architecture? In the typical multitier model, the enterprise application's functionality is divided into three tiers. The Presentation tier, which is comprised of the web container, and which houses web components like servlets and JSP pages. The Middle tier, which is comprised of the EJB container, and which houses enterprise bean components. The Persistence or Enterprise Information Systems tier, which houses the persistent data store. • • • • • • • • • • • This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009 6393 south jamaica court, , englewood, , 80111
- 49. Chapter 2 [ 43 ] The presentation tier reacts to client requests by invoking business logic that resides in the middle tier and is responsible for generating the view that is rendered at the client. The business logic for the application is housed in enterprise beans that live in the middle tier. This tier is responsible for updating the data stores in the persistence tier, based on the client's actions. The creation of multiple tiers gives us the opportunity for scalability, but at the cost of performance. However, most applications don't require this level of complexity, and so the Java EE specification does not require that all three tiers should actually be present. In particular, the presence of an EJB container in the middle tier often adds unnecessary complexity. In such cases, you do not need a full blown Java EE application server, such as JBoss or GlassFish. Instead, you can make do with just a servlet container such as Tomcat. In this scenario, the client is a browser, which communicates with the servlet container using HTML over HTTP. Web components receive these incoming requests, process them, access the data store as necessary, and return a HTML over HTTP response to the client browser. In this case, the business domain classes, the business rules, and the presentation logic are typically interwoven into the web components. This is the application architecture that we will consider for the remainder of this book. Hypertext Transfer Protocol (HTTP) Any communication between two parties requires a clear understanding of how the communication will be conducted. For example, a telephone conversation is initiated by the caller lifting the handset from the cradle, checking for a dial tone, and if the dial tone is present, beginning to dial the desired number. This is usually comprised of a country code prefix, followed by the country code, an area code, and the phone number. If the call is made to another phone within the same country, or within the same area code, the caller might skip these elements. At the receiving end, the protocol is much simpler. The called party waits until the phone begins to ring, at which point, she picks up the phone and indicates that she is ready to receive the communication by saying 'Hello'. This telephony protocol has been in place for so many years that it has now become second nature to us, and seems quite unremarkable. Until of course, you move to a different country, and suddenly realize that your international dialing prefix is not 011, but is 00 instead, or that the area code prefix is now a 0 rather than a 1. This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009 6393 south jamaica court, , englewood, , 80111
- 50. Servlet API Overview [ 44 ] HTTP is just another communication protocol, except that it defines how one computer may connect to another to request a particular resource. This particular protocol has been wildly successful since its introduction in 1990 as HTTP/0.9 and is today the lingua franca of the Internet. There are some characteristics that are common to the two communication models. First, there is a connection that needs to be established between the two parties. This connection has to be held open until the interaction has been completed and the information has been completely exchanged. In the HTTP/1.1 protocol, this is called a persistent connection. Second, there are two aspects to the communication, the protocol and the actual payload. In the case of HTTP, the payload is usually text marked up using tags that are defined by the HyperText Markup Language (HTML). However, HTTP may be used to transfer other data, including audio and video content. The protocol aspects are carried in communication headers that indicate various capabilities of the client (such as the client's preferred character encoding), metadata about the resource being retrieved (such as the length of the payload data), the server's success at retrieving this resource, and so on. Third, there is the question of conversational state. In the typical interaction, a client (usually a web browser) makes a request for a resource, such as a text file or an image, and a server responds with that resource. In reality, a single interaction may consist of multiple such request/response pairs. This usually happens when a browser requests a page that contains one or more images. In this case, the connection is held open while a request/response pair occurs for each of the images on that page. However, once the interaction has been completed, the connection between the two computers is terminated. This is why HTTP is considered a stateless protocol. The next time the client connects to the server to make a request, the server has no memory of the prior interaction with this client. HTTP, therefore, defines a connection oriented but stateless protocol. The astute reader will have noticed that a telephone conversation is not quite the best analogy for an HTTP interaction. While it is connection oriented, there is an element of state that is retained in the memories of both parties while the communication is in progress. On the other hand, the HTTP protocol is completely stateless. This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009 6393 south jamaica court, , englewood, , 80111
- 51. Chapter 2 [ 45 ] Note that it is always the client that initiates the connection in this model. The server has no means to push content to the client. In this usage, the term client refers to the computer that initiates the communication. While this is usually a client's browser, it could also be a server host that initiates a web services type of connection. One way of simulating a push model, for a browser client, is to simply have the client reconnect, every so often, to refresh its content (say using the refresh meta tag or with JavaScript). The underlying protocol used by HTTP is TCP/IP. While this protocol uses the well known TCP port 80, other ports may be used. For example, by default, your Tomcat installation will start up and listen on port 8080 for incoming requests. Uniform Resource Locator, URL A Uniform Resource Locator (URL) is described in RFC 3986 (http://www.ietf. org/rfc/rfc3986.txt) as a uniform way of uniquely identifying a resource such as an electronic document or an image. URLs are designed to implicitly provide a means of locating the resource by describing its 'location' on a network. A generic URL is a hierarchical sequence of components, structured as follows: scheme://hostName:portNumber/path/to/resource?queryString#fragment An example of which is: http://www.swengsol.com:80/file.htm?name=bwaynecity=gotham#profile Here the scheme is http, the host name is www.swengsol.com, the port number is 80, the path to the resource is /index.html, the query string is name=bwaynecity=gotham, and the fragment is profile. The combination of host name and port number taken together is termed an authority. A number of these parts are optional, including the port number (which defaults to the well known ports 80 and 443 for the http and https schemes respectively), the query string, and the fragment. When present, a query string is a series of name-value pairs that are preceded with a question mark and with an ampersand () separating the pairs. The hierarchical organization of a URL becomes apparent as you travel from left to right, with its components increasing in specificity the farther right you go. You start off with a server domain name, a port on that server, and finally an absolute path on that server. The portion that comes after '?' is additional information that is useful to process the located resource. This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009 6393 south jamaica court, , englewood, , 80111
- 52. Servlet API Overview [ 46 ] A URL is composed of characters that are taken from a very limited set—the letters of the basic Latin alphabet (ISO-8859-1), digits, and a few special characters ('-', '.', '_', '~'). All other characters are deemed to be reserved and must be percent-encoded before use. In other words, you must convert them to their hexadecimal representation and prefix them with a % sign. For example, a space character (32 in ISO-8859-1) is encoded as %20. Other characters that should be encoded include the percent itself (%25) as well as characters that are used as delimiters (such as '', '$', and ':'). HTTP methods An HTTP method, or request type, defines the actions that a client may request from a server. HTTP/1.1 specifies seven such methods. GET (HTTP/0.9) This is the oldest and most commonly used method. It is used to GET a resource (such as a document or an image file) from a server. It can also request dynamic content by passing in additional parameters in a query string. This method is intended to be used only for idempotent requests, that is requests that do not cause state changes on the server. For example, a retrieval of a resource from the server is considered idempotent. The URL for a GET request is portable as it is a self contained unit that can be bookmarked or emailed. Typing it in over and over into a browser's address bar should return the same content. There are some downsides to using this method. Though the protocol does not place any limit on the length of a URL, lengths should be limited to 255 bytes because some older browsers or proxies may not properly support greater lengths. As the query string is counted against this limit, this restricts the amount of information that can be passed using this mechanism. A security risk associated with this method is that the parameters that are passed to the web server appear on the address bar in plain text and so can be easily viewed by anyone. In addition, the URL along with its query string is often logged at the server and at other hops along its journey, leading to additional security risks. Finally, while the specification recommends that a GET request is used only for idempotent requests, nothing prevents an errant application from violating this recommendation. It is therefore not at all uncommon to find, for example, a GET request that causes a shopping cart order to be saved, or a credit card to be charged. This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009 6393 south jamaica court, , englewood, , 80111
- 53. Chapter 2 [ 47 ] POST (HTTP/1.0) This method was introduced to handle non-idempotent requests, that is, requests that cause a state change on the server, such as inserting a record in the server's database. Repeated submission of a non idempotent request is unsafe, as it may end up causing undesirable effects such as a shopping cart order being saved to the database multiple times. This method sends its parameters to the server as part of the request body, rather than in a plainly visible query string. This means that a large amount of data (even megabytes) can be sent from the client. A key downside is that the URL is no longer self-sufficient, as the parameters are now part of the body's payload. As a result, the URL cannot be bookmarked or emailed to others. PUT (HTTP/1.1) The PUT method is used to place a document at the location specified by the URL on the server. DELETE (HTTP/1.1) This method is used to delete a document at the specified URL on the server. TRACE (HTTP/1.1) The TRACE method simply returns an exact copy of a request to a client. It is intended for debugging use and traces the path taken by a request. OPTIONS (HTTP/1.1) This method allows the client to query the server about the communication options that are available with regards to a particular resource without explicitly requesting that resource. The returned response would include header fields that indicate optional features that are implemented by the server which are applicable to that resource. For example, the Allow header lists the set of methods (GET, POST, and so on) that are supported for a given resource. HEAD (HTTP/1.0) The HEAD method is identical to GET, except that it asks the server to return only the headers of a response, without the message body. It is used when a client only wants to check the metadata of an entity, such as its last modified time. This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009 6393 south jamaica court, , englewood, , 80111
- 54. Servlet API Overview [ 48 ] HTTP requests The simplest HTTP request is composed of the following elements: [request-method] [/path/to/resource] [HTTP protocol version] [request-header=value]+ [blank-line to indicate the end of the request headers] [POST:request-payload] The first line of the request contains the following: The type of the request, which is usually GET, POST, PUT, DELETE, OPTIONS, HEAD, and TRACE The name of the resource that is being requested The protocol that the browser wishes to use for this communication Following this first line are the request headers, which in turn are followed by the request's payload (for a POST request). As shown, the browser is asking the server (specified by the Host: header) for the specified resource and is stating that it would like to use HTTP 1.1 for the communication. Each request header conveys information either about the client's capabilities or about the request body. Each header is on a separate line, and the end of the headers is indicated by a blank line. The final section is the request's body, which contains form parameters for a POST request. • • • This material is copyright and is licensed for the sole use by ALESSANDRO CAROLLO on 18th December 2009 6393 south jamaica court, , englewood, , 80111
- 55. Another Random Scribd Document with Unrelated Content
- 56. s'imposer et était encore peu connu. Il fallut lui donner un remplaçant et on n'en put trouver d'autre pour ramener le calme, que le vieux Sidi M'hammed. Il a donc repris le titre de Cheikh et en exerce les fonctions par Khalifa. Sidi M'hammed est un professeur réputé; il a autour de lui une trentaine de jeunes gens, surtout Kounta, à qui il donne des cours d'enseignement supérieur. Il a reçu l'ouird et le titre de moqaddem de son parent Khettari ould Sidi-l-Bekkaï ould Hammadi ould Sidi-l-Bekkaï ould Cheikh Sidi-l- Mokhtar. Ce Khettari, venu rejoindre dans le Brakna Sidi-l-Mokhtar ould Bekkaï, se rattachait à Cheikh Sidi Mohammed, le protecteur de Laing. Sa descendance est toujours, sous le nom d'Ahel Khettari, dans le campement de Sidi M'hammed. Les notables de la fraction sont: Mohammed Al-Kouri ould Salek, Sidi ould Ali, Mokhtar ould Hobeïb Allah, Sidina ould Kettari. Les Ahel Bekkaï comprennent 83 tentes et 598 personnes. Leur cheptel est de 4 chevaux, 269 bovins, 6 chameaux, 3.348 têtes de petit bétail et 150 ânes. Leur feu est le lam-alif contre-marqué du billahi . Ils l'apposent sur la cuisse droite des bovins et sur la face gauche du cou pour les chameaux. Leurs terrains de parcours s'étendent: en hivernage, entre Guimi et Chogar Gadel; en saison sèche, à l'Est de Guimi. Aux Kounta, il faut rattacher un petit groupement qui a longtemps vécu dans son sillage et sous les ordres de Sidi M'hammed, et qui est encore en constantes relations avec eux: les Ahel Al-Azrag. Ils vivaient jadis au Tagant et avaient une palmeraie à Talorza. Quelques années déjà avant notre occupation, ils descendaient dans l'Agan, près des Oulad Bou Sif, pendant la saison sèche et ne remontaient dans le Tagant qu'aux premières pluies. Ils ne se fixèrent dans le Brakna que vers 1905 et se dispersèrent de tous côtés; toutes les tentatives faites pour les regrouper ont échoué. Sidi Mohammed se voua lui-même à ce projet et fit nommer par la djemaa Sidi-l- Ami ould Cheikh ould Hanna, dit Sidïa ould Henna, petit-fils d'un marabout de grand renom et qui bénéficiait de la réputation ancestrale. Né vers 1882, c'était d'ailleurs lui-même un homme intelligent et instruit avec lequel les relations furent toujours cordiales. Après des débuts heureux, l'entreprise échoua encore. Les Ahel Al-Azrag, au nombre total de 61 tentes, sont
- 57. aujourd'hui répartis dans le Brakna, le Gorgol et le Tagant, suivant le tableau ci-joint: Brakna, groupement Al-Azrag 25 tentes. —— chez les Tagant 3 —— —— chez les Torkoz 1 —— —— chez les Oulad Bou Sif 1 —— Gorgol, —— —— —— 7 —— Tagant (très dispersés) 24 —— Ce sont des commerçants avisés et actifs. Ils prétendent se rattacher généalogiquement à Cheikh Sidi Omar Cheikh, le grand marabout Kounti du seizième siècle. Les Ahel Cheikh, tant Ahel Sidi Amar qu'Ahel Bekkaï, vont visiter en pèlerinage les tombeaux de leurs ancêtres, et notamment ceux de: a) Baba ould Sidi-l-Mokhtar à Maouella, près de Kaédi, sur la rive gauche du Sénégal; b) Sidi Amar, à Sif al-Fil au sud de Mouit; c) Bambaye ould Sidi Amar, dans le Raag de Kaédi. Comme tous les Kounta, ce sont de grands voyageurs et d'actifs commerçants. Leur centre de négoce est surtout Kaédi. ANNEXE Tableau généalogique des Ahel Cheikh (Kounta) du Brakna. Cheikh Sidi-l-Mokhtar Al- Kabir † 1811. Baba Ahmed † vers 1840. Bekkaï † 1853. Baba 1879. Sidi-l-Mokhtar dit Sidina, † vers 1887. Sidi M'hammed, Al-Abidin.
- 58. chef des Ahel Bekkaï. Baba 1891. Sidi Amar. Khalifa. Bambaye. Chibani, chef actuel des Ahel Sidi Amar. Sidi-l-Mokhtar, né vers 1908. CHAPITRE VII TORKOZ 1.—Historique. Les Torkoz se flattent généralement d'être d'origine arabe (Beni Oummiya). Ils rattachent leur ancêtre éponyme Abd Er-Rahman Rekkaz à Oqba ben Nâfi, le conquérant de l'Afrique du Nord et l'aïeul revendiqué par les Kounta. Voici sa chaîne généalogique: Rekkaz ould Bou Bakrin ould Abd Allah ould Sidi Mohammed ould Sidi Salem ould Sidi Brahim ould Sidi Othman ould Alioun ould Sidi Abd Allah ould Sidi Jaafer ould Salem ould Oqba. Une autre tradition, recueillie chez les tribus voisines et non déniée par quelques Torkoz, leur donne une origine berbère. Les ancêtres des Rakkaz, dit-elle, vinrent, par delà l'Adrar, du Sud marocain avec Bou Bakar ben Omar (onzième siècle). Leurs descendants arrivèrent dans le Sahara occidental, en même temps que les pères des Medlich et des Id Ar-Zimbo. Par la suite, les Torkoz qui s'étaient créé de belles palmeraies dans l'Adrar, en furent dépouillés puis furent chassés du pays par les Smassid. Il en reste à peine quelques tentes dans l'Adrar. Les Torkoz sont les cousins des Chleuh Rekakza et autres qui habitent l'Oued Noun, où ils sont restés guerriers et à moitié
- 59. sédentaires, et également les cousins des Terkeïza, qui habitent l'oasis de Mreïbot, près de Tindouf. Cette tradition se rapproche certainement de la vérité. Rekkaz, id est «le tapoteur» ainsi nommé parce qu'il portait toujours un bâton avec lequel il frappait le sol, vivait au temps de l'imam Hadrami, c'est- à-dire vers la fin du seizième siècle et le début du dix-septième siècle. Cette date est bien déterminée par la tradition, parce qu'elle fait de son fils Ahmed et de son petit-fils Berrek, les chefs Torkoz pendant «la guerre de Boubbah» (dix-septième siècle). Voici le tableau généalogique établissant la filiation ethnique de toutes les fractions torkoz (Brakna, Tagant et même Hodh et Azaouad) à l'égard de Rekkaz. Abd Er- Rahman, le Rekkaz Ahmed Berrek, père des Brarka (Aleg). Ahel Bahmouda. Ida Ou Amar. Helalma. Ahel Hemid ould Boubah. O. Eli Mbarek. Sidi Ahmed, père des Oulad Sidi Ahmed (Moudjéria). O. Sidi Bou Bakar. O. Sidi Reguieg. O. Sidi Ahmed Aleïa. Ahel Bar (rares). O. Sidi Boussar. O. Sidi Salé. Abd Er-Rezzaq, père des Ahel Abd Er-Rezzaq (Hodh.) (Regueïba). Belahmar, ancêtre des Oulad Belahmar (Tagant). Renia, ancêtre des Id ag Renia (Trarza). Talaba, père des Ahel Sidi-l- Mokhtar et des Ahel Tahel Ahmed. Mohammed, père d'Ali Bou Ghareb, qui est l'ancêtre des Ghouareb ou Lghouareb (Tagant). Amar, père de Tiki, qui est l'ancêtre des Oulad Tiki (Tagant). Les premiers Torkoz arrivèrent dans le Brakna «vers le temps du Cherr Boubbah, ou peu après», c'est-à-dire à la fin du dix-septième siècle. C'est de
- 60. là que date la scission de la tribu. Tribu à chameaux jusque-là, les nouvelles conditions géographiques la transformèrent. Les fractions du Tagant: Oulad Sidi Ahmed et Ghouareb, gardèrent leur cheptel camelin. Les Brarka et quelques sous-fractions cousines qui descendaient avec eux vers le sud et s'établissaient dans l'Aftout devinrent propriétaires de bœufs. Les premiers furent longtemps les plus riches. Mais, par la suite, les Brarka doublèrent leurs richesses pastorales par le commerce et furent classés les plus fortunés des cinq fractions. Les Torkoz assurent qu'ils ne prirent pas part à la guerre de Boubbah, n'étant arrivés dans le Sud que quelques années après la conclusion de la paix. Mais les Tolba voisins placent leur arrivée avec la fin du Cherr Boubbah, et disent formellement qu'ils prirent part au combat final de Tin Yefdan. C'est de ce jour que daterait leur dispersion. Ils durent, comme les autres tolba, se soumettre au payement d'une horma, qui fut fort longtemps perçue par les Oulad Ahmed et les Oulad Yahia ben Othman et les Ahel Soueïd Ahmed sur les fractions torkoz ressortissant à leur autorité. Par la suite, leur état s'aggrava de redevance envers les Ahel Soueïd Ahmed. Il est vrai qu'avec le temps les Torkoz du Brakna ont pu se dégager de ces tributs, depuis longtemps déjà en ce qui concerne les Oulad Ahmed, plus récemment pour les Abakak, à qui, par transformation de la tradition, ils ne peuvent encore aujourd'hui refuser, de temps en temps, de légers cadeaux. On trouve, d'ailleurs encore, un certain nombre de tentes torkoz dans les campements Abakak, à qui ils servent de tolba. En résumé, il n'y a plus aujourd'hui dans le Brakna, en fait de Torkoz, que la fraction Brarka. Les Oulad Sidi Ahmed, les Ghouareb et les Oulad Tiki sont dans le Tagant; les Ahel Abd Er-Rezzaq se partagent entre le Hodh et le Regueïba, le Tagant et le Trarza. Il y a même une fraction torkoz de 10 tentes chez les Kounta de l'Azouad, dans la fraction Regagda, sous-fraction des Ahel Sidi Ceddiq. Les Oulad Sidi Ahmed ont vécu plusieurs années au Brakna, où ils s'étaient réfugiés après la perte de leurs chameaux. Ils retournèrent au Tagant, en 1911-1912, mais entendirent conserver l'usage des pâturages du Sud, ce qui amena des conflits avec leurs cousins. Il y eut des batailles sanglantes entre Oulad Sidi Ahmed, Ghouareb, que les premiers voulaient empêcher de boire à Tindel, dans l'influent du Gorgol et Brarka. Elle donna lieu aux sanctions suivantes des autorités du Brakna et du Tagant. 1o Une amende de 500 francs, répartie entre les principaux membres de la djemaa, a été infligée aux Oulad Ahmed;
- 61. 2o D'après les mêmes dispositions, une amende de 300 francs a été infligée aux Brarka; 3o Trois Oulad Ahmed, coupables d'avoir tiré sur les Brarka, ont été punis de quinze jours de prison; 4o Les Torkoz ont été désarmés; 5o Leur tribu, sous le commandement de Sidina a été groupée dans un rayon en rendant la surveillance facile pour le Commandant de Cercle; 6o Une dïa est payée par les coupables aux Brarka blessés. Elle a été fixée, suivant les coutumes, à 340 pièces de guinée filature payables, la moitié en mai et l'autre moitié en août. Après entente avec le Tagant, la question de principe fut réglée ainsi en 1914. Le Brakna, sauf la partie Est-Agan, et le Trarza: Aguiert, Tin Yarech, Letfotar, sont interdits aux Oulad Sidi Ahmed. D'autre part, défense est faite aux Brarka de dépasser la ligne Ouezzan—Lmeïdja—Tindel. Avec les Id ag Jemouella, les relations ont toujours été forts tendues. Avant et depuis notre arrivés, de sanglants combats ont été livrés entre ces deux tribus, et, jusqu'en 1915, où une répression sévère intervint, et jusqu'en mai 1917 où cinq Abakak venus récolter de la gomme et pillarder aussi sur le territoire torkoz et qui furent pris pour des Id ag Jemouella, furent criblés de coups de feu et blessés à coups de massue. Cette méprise n'eut pas d'autres suites que les réparations accoutumées. 2.—Fractionnement. Les Torkoz du Brakna, c'est-à-dire la fraction torkoz des Brakna, se divise en huit sous-fractions. Ahel Bou Hammadi, Ahel Habrezza, Ahel Ammi, Ahel Hemid ould Aoubak, Ahel Taleb Maham, Ida Ou Omar, Helalma, Tolba.
- 62. Les Ahel Bou Hammadi et la sous-fraction suivante: Ahel Habrezza sont des Ahel Bahmouda. Ils ont pour chef Sidi ould Hammadi, et pour djemaa: Jiyed ould Oualati; Abd El-Fettah ould Hamida; Hachim ould Oualati. Les Ahel Habrezza tirent le nom de Habrezza, qui eut une célébrité marquée en son temps, et dont le tombeau se trouve dans le Brakna, en un point ignoré. Ils ont pour chef Mohammed Limam ould Al-Boustami ould Ahmed Jeddou (ould Ali Menna ould Habrezza ould Ba Ahmouda ould Berrek), qui est aussi le chef général de la tribu. Voici la succession depuis Habrezza: (1) Habrezza. (2) Eli Menna. (3) Mohammed. Ahmed Jeddou. Amar. (5) Ahmed Jeddou. Sidi. (4) Boustami. Cheikh. Ahmoud. fille mariée à Sidi Ahmed. (6) Ahmed Jeddou. Moh. Mokhtar. Moh. Lamin. Moh. Limam, chef actuel Mostafa. Sidi Ahmed. Au moment de notre occupation, la tribu vivait sous l'autorité de la djemaa, les derniers chefs (4) Boustami et (5) Ahmed Jeddou ould Mohammed, ayant discrédité le commandement par leurs rivalités. Boustami
- 63. ayant disparu, ce fut Ahmed Jeddou qui fut porté par l'élection à la tête de la fraction. Il mourut vers 1909 et fut remplacé par (6) Ahmed Jeddou ould Boustami. Les nombreuses plaintes dont il fut l'objet provoquèrent sa démission en janvier 1911. Il mourut peu de temps après (30 mars 1911). On put trouver la solution de ce commandement difficile, en sortant des Ahel Eli-Menna, et (7) Sidina ould Zeïn ould Bouddia fut nommé chef, grâce à l'appoint des Oulad Sidi Ahmed. Ceux-ci partis au Tagant, Sidina n'eut plus qu'une minorité dans la tribu. Il fut rapidement convaincu d'exactions par l'ensemble des Brarka, qui, fidèles à leur campement héréditaire, ne voulaient pas de lui, et révoqué (fin 1912). On revint donc aux Ahel Eli Menna, et (8) Mohammed Limam ould Boustami, frère d'Ahmed Jeddou fut élu. Son élection fut assurée par le bloc des Ahel Bahmouda, Helalma et Ida Ou Amar, mais il eut l'adresse, le jour même, de caresser les opposants et de s'attirer leur sympathie. Depuis ce jour, le calme semble revenu. Mohammed Limam, né vers 1870, assure très correctement son service. C'est un marabout vénéré et paisible. Il vit, autour de Mal, en bonnes relations avec ses voisins et particulièrement avec Cheikh Sidïa. Il a un fils, Boustami, né vers 1905, qui commence à le seconder. Il a un beau troupeau, et passe pour riche[9] . [9] Mohammed Limam est mort de la grippe en décembre 1918. Les notables de la sous-fraction Habrezza sont: Sidi Ahmed et Mostafa ould Eli Menna, frère du Cheikh, ses cousins, nommés au tableau généalogique, et Alfa ould Khouna. Les Ahel Ammi ont pour chef Sidi Ould Ammi et pour notables: Cheikh ould Ammi et Sidna ould Omar. Ils sont Ahel Hemid ould Aoubak, ainsi que les deux sous-fractions suivantes: Les Ahel Hemid ould Aoubak sont le noyau d'une fraction, jadis florissante, et qui a essaimé. Leur chef est Abd El-Ouadoud ould Sidi Brahim et leurs notables sont: Al-Hadj ould Ahmed Maaloum et Ahmed Maaloum ould Sidi Brahim; Les Ahel Taleb Maham ont pour chef Sidi Mohammed ould Omar ould Bouddïa et pour notable: Ahmoud ould Bachir. Les Ida Ou Omar ont pour chef: Ali ould Mokhtar, leur djemaa comprend Mahfoudh ould Boubba; Brahim ould Al-Ouâar et Sidi ould Ahmed Bouh.
- 64. Les Helalma (au sing. Helalmi) ont pour chef Bouna ould Alioua et pour notables: Mohammed Sidi ould Al-Hadi et Cheikh ould Taleb Ali. Les Tolba sont une sous-fraction issue des Oulad Eli Mberrek. Ils ont pour chef: Abd El-Moumen ould Cheikh Mohammed Mahmoud ould Abd El-Fettah, et pour notables Abd El-Rafour ould Tolba et Brahim ould Mohammed ould Taleb Ali. Les Torkoz nomadisent en saison sèche autour du Mal; en hivernage entre Mal, Guimi et Aguiert. Leur feu est «berek» qu'ils apposent sur la cuisse droite des animaux. Ils ont plusieurs contre-marques: un trait oblique sur la joue droite, chez les Ahel Ammi; un trait sur la nuque chez les Eli Menna, ainsi que l'amama (turban) soit , sur le barek; un sur le côté droit chez les Ahel Amar Bouddïa; et chez la plupart des gens deux traits parallèles sur le côté droit du cou. Les statistiques de 1917 donnant, pour l'ensemble de la fraction, 208 tentes et 855 âmes, 15 équidés, 73 camelins, 741 bovins, 8.730 ovins et 262 ânes. Les Torkoz sont, avec les Tagant, les gens les plus commerçants du Brakna. Ils vont à Saint-Louis, Louga, Kaolak, Dakar et jusqu'en Gambie et en Casamance, pour vendre des milliers de moutons. Ils servent même d'intermédiaires à certaines tribus voisines pour la vente de leur bestiaux. 3.—Vie religieuse. Un nom domine la vie religieuse du Torkoz: Mrabet ould Sidi Mohammed ould Mrabet Abd El-Fettah, tant par son prestige personnel que par l'héritage acquis de son grand-père, un des grands pontifes de son temps. Mrabet Abd El-Fettah ould Taleb Ali (ould Mohammed ould Ahmed ould Amar ould Eli Mbarek) remplit l'histoire religieuse des Torkoz et d'une partie du Brakna pendant toute la première moitié du dix-neuvième siècle. Il fut l'élève de deux grands maîtres: Sidi-l-Mokhtar, des Id Abhoum (Oulad Biri); Cheikh Menni, des Tagat, l'ancêtre de la fraction Ahel Menni. On lui doit la revivification de Diok et un exemple précieux. Passant un jour à Diok. à 30 kilomètres environ au sud-est de Moudjéria, au cours d'un de ses nombreux voyages dans le Brakna, il affirma à ses compagnons de route qu'une
- 65. inspiration divine lui faisait connaître que ce lieu était béni du ciel et qu'il le choisissait pour y vivre jusqu'à sa mort et que c'est là qu'il désirait voir s'élever son tombeau. Dieu ayant exaucé ses prières, il trouva de l'eau à 0 m. 50 en creusant le sable brûlant. Puis il envoya quelques jeunes captifs, ses élèves, chercher des plants de palmiers, qu'ils payèrent deux vaches aux Oulad Sidi Haïb Allah, de Kçar el-Barka? (Tagant). Sa plantation terminée, Mrabet ould Abd El-Fettah creusa quelques puits de 8 mètres de profondeur; deux d'eau douce qui lui servirent pour arroser ses palmiers et pour les besoins de sa famille, et deux d'eau très légèrement salée pour ses chameaux. Mrabet, qui avait déjà cinquante ans lorsqu'il s'installa à Diok, y mourait vingt-cinq ans plus tard (vers 1840). Son tombeau, construit par son fils Sidi Mohammed, se voit encore près de la palmeraie plantée par Mrabet. C'est une simple construction en pierre et en banco. Il se trouve exactement à Mouilah, près de Diok; il est l'œuvre de son fils Sidi Ahmed. Pendant toute sa vie et les dix années qui suivirent, les palmiers donnèrent une belle et abondante récolte de dattes. La production ayant considérablement diminué, les habitants de Diok, courant de nombreux risques de pillage de la part des Oulad Nacer, qui ravageaient le pays et étant obligés de donner une large hospitalité aux guerriers de passage, Cheikh Sidi Mohammed vers 1875, abandonna la propriété paternelle. Toutefois, il continua de venir tous les ans faire la récolte des dattes; mais les arbres laissés sans soin et d'autre part abîmés par des troupeaux de singes, ne produisirent plus qu'une récolte tous les deux ans. Vers 1897, Mrabet ould Sidi Mohammed ould Fettah, partagea, pendant six ans encore, la récolte avec son oncle Cheikh Mohammed. Puis la palmeraie fut abandonnée complètement en 1903. Ayant appris qu'en 1908 un homme des Ghouareb avait récolté à Diok, dans la palmeraie abandonnée, deux charges de chameau de dattes, Mrabet revendiqua ses droits de propriétaire et paya à un Alaoui de Tijikja une pièce et demie de guinée pour tailler et féconder les dattiers. La palmeraie de Mrabet Abd El-Fettah qui fut partagée entre ses deux fils, Sidi Mohammed et Cheikh Mohammed Ahmed, tous deux décédés, comprend aujourd'hui deux propriétés distinctes: l'une appartenant à Mrabet ould Sidi Mohammed, fils unique de Sidi Mohammed et l'autre aux cinq fils de Cheikh Mohammed, dont l'aîné porte le nom d'Abd Es-Selam.
- 66. En outre, près de cette palmeraie, quelques dattiers ont été plantés par les frères Brahim et Ahmed Djilani ould Dechar qui, par vénération pour la mémoire de leur professeur se constituèrent les gardiens de son tombeau même après le départ de ses fils. La propriété de ces quelques dattiers a été contestée à l'unique fille héritière de Brahim et de Ahmed, Douila ment Ahmed-Abd Allah par Mrabet ould Sidi Mohammed. Ce dernier, en bas âge lors de la plantation des dattiers, prétendit à sa majorité, que ces arbres ayant été placés dans un domaine de sa famille sans autorisation, il les considérait comme sa propriété. L'accord s'est fait aujourd'hui. C'est ce Mrabet ould Sidi Mohammed ould Abd El-Fettah qui est aujourd'hui le maître des destinées religieuses de la tribu. Né vers 1870 d'une mère hijajïa, il a fait ses études auprès de son père et de Cheikh Mohammed Abd Allah ould Mohammed Mahmoud, dans Dieïdiba, dont il est le disciple qadri, et de qui il a reçu les pouvoirs de moqaddem. Il a fait sa soumission dès l'occupation du pays et n'a jamais créé de difficultés. Son frère fut bien mis en prison, en mars 1911, pour opposition à l'élection du chef et lui-même ne fut peut-être pas étranger aux intrigues du moment, mais il a, depuis ce temps, fait oublier ce mauvais moment. Les nombreuses aumônes qu'il reçoit lui ont procuré de grands biens, mais son hospitalité est large. Il est le cadi écouté et le professeur d'enseignement supérieur de la tribu. Ses élèves varient entre 30 et 50. A côté d'une majorité de Torkoz, on y trouve des jeunes gens de plusieurs tribus voisines. Sa réputation dépasse le Brakna et s'étend au Trarza, au Tagant et au Gorgol. La plupart des Torkoz sont les disciples spirituels, dans la voie du Qaderisme, de Mrabet; mais parmi les jeunes gens on voit certaines dissidences se produire et se rallier à Cheikh Sidïa ou à Saad Bouh. Le frère de Mrabet, Abd El-Fettah ould Sidi Mohammed, est aussi un marabout de renom, mais plus occupé que son frère des choses temporelles. C'est un professeur réputé, qui a fait ses études chez les Tendra et se rattache au Cheikh Mohammed Abd Er-Rahman ould Mohammed Salem. Un dernier nom à mentionner: Mohammed ould Taleb Ahmed, notable fort écouté, et qui est un de ceux qui travaillèrent le plus à la réunion des Brarka et des Oulad Sidi Ahmed. Les Torkoz du Brakna honorent par leurs pèlerinages les tombeaux de leurs ancêtres à Hemmal, Begguert, Mal et Kedouacha.
- 67. Ils sont considérés par les Abakak (Id Ou Aïch) comme leurs marabouts cadis et professeurs. Les relations des deux tribus sont tout à fait cordiales. CHAPITRE VIII HIJAJ 1.—Historique. Les Hijaj sont une tribu dérivée des Rehahla. Ils sont donc d'origine arabo-hassane, puisque Rehhal, ancêtre éponyme des Rehahla, est le frère d'Antar, de Yahia et d'Omran, ancêtres des Oulad Nacer, des Oulad Yahia ben Othman, et des Trarza et Brakna, et que ces quatre personnages sont les fils d'Othman ould Oudaï ould Hassan. En ce qui concerne l'historique des Rehahla et par conséquent l'historique lointain des Hijaj, je ne puis que renvoyer à mon ouvrage l'Émirat des Trarza. C'est de la fin de la guerre de Boubbah que date leur «conversion» au maraboutisme; elle résulte probablement, bien que la tradition soit muette sur ce point, de la défaite des Rehahla, hassanes des premières invasions, et de leurs alliés les marabouts, par les Trarza-Brakna. Un individu des Rehahla, le nommé Samba, premier ancêtre connu des Hijaj, ne pouvant plus vivre dans sa tribu vaincue, vint chercher fortune sur les rives de l'Oued Katchi. Il était accompagné d'un de ses cousins, dit Damâni, et de plusieurs serviteurs (fin du dix-septième siècle). Samba eut deux fils: Hamdan et Abd En-Nebi, qui sont les ancêtres des deux premières fractions Hijaj. Damâni est l'ancêtre éponyme de la troisième et dernière fraction des Douamin. Il faut, à partir de maintenant avoir sous les yeux le tableau généalogique de la tente princière pour pouvoir suivre le cours des événements. Tableau généalogique.
- 68. Samba. Hamdan. Abd En-Nabi. Maham. Taleb Brahim. Taleb Amed. Meskour. Al-Hadj Mohammed. Al-Hadj Hossin. Al-Hadj Mokhtar. Mohammed Barhoum. Mokhtar. 1. Mohammed Lamin. 2. Sidi Abd Allah. Al-Qadi. Cheikh Mohammed. Hamenni. Mrabet. Cheikh Ahmed Mahmoud. Mohammed Lamin. 3. Mahmoud. 4. Mohammed Al-Mrabet † 1914. Mohammed. Mokhtar. Moh. Mostafa. Sidi Abd Allah. 6. Ahmed. Inedji. 5. et 7. Mahmoud. Hadj Amin. Ma-l-Aïnin. Hamdan, qui vécut dans le premier quart du dix-huitième siècle, est le premier qui ait fait le pèlerinage à la Mecque et inauguré ainsi ce nom de Hadj, qui allait devenir celui de la tribu. Il eut quatre fils, dont l'un, Meskour,
- 69. est l'ancêtre de la tente princière des Hijaj. Les trois autres mirent au monde chacun un fils, Mohammed, Hossin et Mokhtar. Ces trois cousins firent ensemble le pèlerinage de la Mecque, vers le milieu du dix-huitième siècle. Le second, Hossin, mourut à la Mecque même et y fut enterré; les deux autres revinrent à bon port et furent enterrés, après une vie embellie par les vertus islamiques, le premier à Al-Aguilat, près de Mouit, l'autre à Al-Ouasta. Ce triple pèlerinage auréola ce petit campement d'une gloire, assez rare alors, et on se prit à les désigner sous le sobriquet de «tribu des Hadj» ou «Hijaj». Le nom leur en est resté définitivement. Et de ce jour-là la tribu se voua à la vie maraboutique. La tribu naissante vivait alors dans l'Agan et buvait au puits d'Oudenech, situé à Zkil, au nord-ouest de Chogar-Toro, et à celui d'Al-Ouasta, sis à 15 kilomètres au nord-ouest du premier. Il n'y a rien à dire sur les premiers descendants de Meskour, au cours du dix-huitième siècle. Le commandement est d'ailleurs, à cette époque, l'objet d'âpres compétitions. C'est au début du dix-neuvième siècle qu'il se fixa définitivement dans les Oulad Hamdan et dans les Ahel Meskour par les vertus et le prestige de Mohammed Lamin ould Mokhtar ould Mohammed Barhoum ould Meskour. Cette dévolution de l'autorité devait entraîner, au cours du dix-neuvième siècle, des scissions répétées dans la tribu. Une première fraction alla s'installer dans le Gorgol; on les y retrouve aujourd'hui sous ce nom. En 1910, ils ont été réunis à la tribu-mère du Brakna. D'autres retournèrent vers les cousins Rahahla et furent asservis comme eux au tribut. D'autres enfin, mais antérieurement, qui n'avaient voulu se muer aux marabouts définitifs, allèrent s'affilier aux Oulad Eli (Brakna du Gorgol). De nos jours enfin, vers 1902, la fraction Douamin, qui n'est à proprement parler que cousine des deux, et, à ce titre a toujours fait preuve d'indépendance, ne voulant pas accepter l'autorité des Oulad Hamdan, est allée s'incorporer aux Id ag Fara Brahim, des Dieïdiba. L'accord faillit se faire, il y a quelques années, mais, au dernier moment, on ne s'entendit pas et les choses restèrent en l'état. Mohammed Lamin est compté comme le premier chef de la tribu, désormais constituée en une unité bien vivante. C'est sous son règne, semble-t-il, qu'eut lieu la guerre fort dure, rapportée par le Tarikh de Oualata, et où luttèrent d'une part les Oulad Bella et les Masna de Tichit, d'autre part les Hijaj et les Dehahna alliés. Les Hijaj du Brakna envoyèrent des contingents à leurs frères du Nord. Un combat sanglant, le 19 juillet 1850, mit fin aux hostilités. Après Mohammed Lamin, le pouvoir est resté
- 70. dans la descendance de son fils aîné (2) Sidi Abd Allah. C'est ce Sidi Abd Allah, «homme magnifique, avec une barbe imposante qui descendait jusqu'à la poitrine, un vrai patriarche» que visita l'enseigne Bourrel, en 1860, et qui lui fit un si cordial accueil. Les chefs, ses fils, furent d'abord (3) Mahmoud, mort sans postérité, et (4) Mohammed El-Mrabet, mort au début de 1914. Mohammed Al-Mrabet était chef de la tribu lors de l'occupation française. Obéi et aimé de ses gens, dévoué à nos intérêts, il fut un excellent chef qu'on a eu le regret de voir mourir de la variole en janvier 1914. Il fut remplacé par surprise et sous l'influence du grand marabout de la famille, Cheikh Ahmed Mahmoud, par son neveu (5) Mahmoud ould Mohammed Mokhtar, au détriment de ses fils. De ses fils, l'aîné, Sidi Abd Allah, ne voulut pas revendiquer ses droits et les céda à son cadet Ahmed. Ahmed faisait alors ses études chez les marabouts du Nord. Il revint immédiatement et réclama le commandement. Entre temps, il suivait les cours de l'école d'Aleg. On finit par lui donner droit, et en fin 1914, il fut nommé chef de la tribu. Mais jeune et léger (6) Ahmed ne sut pas se faire obéir; il manqua totalement de pondération dans son commandement, et dut être remplacé, en avril 1917 par son prédécesseur (7), Mahmoud ould Mohammed Mokhtar. Mahmoud, né vers 1862, marabout paisible, n'a qu'une influence limitée; il est simplement le membre le plus notoire de la djemaa. Il a trois fils: Hamma Lamin, Mohammed et Ahmed; il subit fortement l'influence de ses frères: Had Amin et Mrabet, et surtout de son cousin, le grand Cheikh spirituel de la tribu, Ahmed Mahmoud. Le jeune Ahmed, qui avait commencé par faire quelque opposition et avait été, de ce fait, puni disciplinairement, est revenu au calme[10] . [10] Mahmoud ould Mohammed Mokhtar est mort de la grippe en décembre 1918. 2.—Fractionnement. Les Hijaj du Brakna se partagent ethniquement et administrativement en les fractions suivantes:
- 71. 1o Oulad Hamdan; chef: Mahmoud ould Mohammed Mokhtar; 120 tentes et 580 âmes; 200 camelins, 958 bovins, 2.495 ovins, 164 ânes; 2o Oulad Abd En-Nabi: première sous-fraction administrative; chef: Cheikh ould Taleb Brahim, qui a succédé à son frère Jeddou, tous deux neveux de l'ancien chef Cheikh Mostafa ould Taleb Brahim, vieux et cassé, 9 tentes et 28 personnes; 20 bovins, 270 ovins et 10 ânes; deuxième sous- fraction administrative; chef: Mohammed ould Khalil, 20 tentes et 57 personnes, 131 bovins, 325 ovins et 20 ânes; 3o Haratines Hijaj; chef: Kaouri ould Obeïd; 40 tentes et 160 âmes; 74 bovins, 404 ovins et 12 ânes. Ces haratines sont pour la plupart domiciliés dans le Chamama auprès de Mbagne. Un petit nombre d'autres est resté nomade vers Bassi Nguidi. L'ensemble comprend donc 189 tentes et 831 âmes. Le cheptel est de 200 camelins, 1.183 bovins, 3.494 ovins, et 206 ânes. Le feu de la tribu est, comme il convient à ces fils de pèlerins, la marque «Makka» , qu'ils apposent sur la cuisse droite des animaux. Les Hijaj se partagent, d'après leur genre de vie, en deux groupes: les Oulad Hamdan, ou grands nomades du Nord (Amechtil et Akel) et les Oulad Abd En-Nabi, rattachés récemment encore au Gorgol, ou petit nomades du Sud-Est. On pourrait y joindre le groupe cultivateur des Haratines. Fraction à chameaux, les Oulad Hamdan nomadisent dans le Nord-Ouest. En hivernage, ils sont aux environs de Diguet Menné et dans l'Oued; en saison sèche, à Chogar, et aux environs, à Oudnech et à Al-Ouasta. Ce n'est que de nos jours qu'ils ont pu revenir vers ces puits ancestraux. Vers 1900, victimes de plusieurs pillages de la part des Oulad Bou Sba de l'Adrar, ils avaient été obligés de les abandonner et s'étaient cantonnés à Diguet Memmé et à Chogar Tora. De nos jours, ils n'échappent pas toujours aux rezzous, mais ils retrouvent en fin de compte leurs pertes. C'est ainsi que pillés par les Regueïbat en juin 1914, ils rentrèrent peu à peu en possession de leurs chameaux, repris par le peloton méhariste de l'Adrar. Fraction à bœuf et à petit bétail, les Oulad Abd En-Nebi, ne possèdent pas un seul chameau. Ils nomadisent dans un petit rayon, en hivernage, vers Al-Kouïat et Al-Ousakat; en saison sèche, à Bassi Nguidi et à Bilal. Le cadi de la tribu est Mohammed Salem ould Jeddou, d'origine Ahel Babouya, né vers 1865, savant professeur et juriste, élève et disciple de Mohammed Lamin ould Cheikh Mohammed. D'une famille peu connue,
- 72. Mohammed Salem commence seulement à percer grâce à sa science et à sa probité. Les principaux notables sont: les deux fils de Cheikh Mohammed ould Mohammed Lamin, à savoir: Cheikh Ahmed Mahmoud et Mohammed Lamin. Cheikh Ahmed Mahmoud, né vers 1868, est le marabout le plus en vue des Hijaj. Il passe déjà pour être un ouali. Élève et disciple qadri de son père, il se rattache par lui aux grands Cheikhs Sidi Mohammed ould Menni des Tagat, Cheikh Al-Qadi des Deïdiba, et Sidi-l-Mokhtar Al-Kabir, des Kounta. Il est fort instruit, possède une bibliothèque bien garnie et distribue l'enseignement coranique et supérieur à une cinquantaine d'élèves, tant des Hijaj que des tribus voisines, notamment Tadjakant et Id ag Jemouella. Ce Cheikh se confine de plus en plus dans la piété et le mysticisme; il a fini par se désintéresser complètement des affaires administratives et du commandement de la tribu; il abandonne même souvent son école à son cadet. Il vit à l'écart, ermite, plongé dans une quasi perpétuelle kheloua. Son seul fils peut alors l'approcher, et quelquefois son frère Mohammed Lamin. C'est un thaumaturge reconnu, au demeurant le marabout le plus notoire du Cercle, après M'hammed ould Bekkaï, des Kounta. Son frère, Mohammed Lamin, né vers 1870, de la même obédience, très intelligent et très instruit, est moins confiné dans le mysticisme. Il dirige avec beaucoup de savoir une école de trente élèves, où l'on voit, à côté des Hijaj, des Tadjakant et des Dieïdiba. Quand son frère aîné disparaît dans sa retraite, c'est près de cent élèves que comprend cette petite Université nomade. Les deux Cheikhs ont distribué leur ouird à la majeure partie de leurs contribules. Les Hijaj sont tous qadrïa, relevant de deux obédiences différentes, soit surtout celle de Cheikh Al-Qadi, des Dieïdiba, soit celle de Cheikh Sidïa, en définitive par conséquent de la même source des Kounta de l'Azaouad. Les principaux notables de la tribu sont: chez les Oulad Hamdan, Mohammed Fal ould Khalil; Mohammed Fal ould Bokhari, Ahmed ould Najid; Mohammed Abd Er-Rahman ould Sidi; chez les Oulad Abd En-Nabi (1re sous- fraction) Sidi Abd Allah ould Abaïdi, et (2e sous-fraction) Youssef ould Aïssa et Brahim ould Salek; chez les haratines Ahmed ould Biyad et Samba ould Al-Yarg. Le maître d'école coranique attitré de la tribu est Ahmed Abd Ed-Daïm ould Sidi ould Mokhtar Fal, né vers 1855, vieillard peu intelligent et médiocrement instruit, mais honnête, sympathique et très en confiance.
- 73. CHAPITRE IX ID EÏLIK 1.—Historique. Les Id Eïlik se prétendent, comme il convient, d'origine arabe, et se donnent une ascendance ommeïade. Ce qui est plus certain, c'est que l'ancêtre éponyme, Eïlik était un Berbère marabout, qui vivait avec les siens dans le sillage des Oulad Abd Allah, au seizième siècle. Depuis une ou deux générations au moins, cette sympathie unissait les deux tribus: Hassane et Zenaga. La tradition est formelle à ce sujet; elle prétend même que, dès le temps de Bou Baker ben Omar (onzième siècle), les deux tribus étaient alliées, étant venues ensemble d'Arabie, ce qui est un anachronisme manifeste, puisque les Arabes n'arrivent en Mauritanie qu'au quinzième siècle. Il est plus probable qu'Eïlik, Berbère du Sud marocain, arriva au seizième siècle dans les bandes Oulad Abd Allah, qui s'abattaient sur la Mauritanie. C'est ce qui expliquerait l'arrivée commune de la tradition historique. Eïlik laissait quatre fils: Zar, Badelli, Diaoudiaye et Ab Amrar. La descendance des deux derniers s'est fondue dans celle de Zar et de Badelli, et aujourd'hui les Id Eïlik s'attribuent tous l'une de l'autre de ces deux filiations. Zar, de son vrai nom Ishaq, était l'aîné. Le commandement devait rester dans sa famille jusqu'à la fin du dix-huitième siècle, où il passa dans la branche cadette avec Atig, septième descendant de Badelli. En leur qualité de marabouts, les Id Eïlik prirent part à la guerre de Boubbah, au début au moins, dans le clan de leurs frères dans la foi. Mais ils finirent par céder à leur amitié traditionnelle pour les Oulad Abd Allah, et lâchèrent les marabouts se rangeant aux côtés des hassanes. La légende veut que cette trahison ait été consommée à Tin Yefdad même, c'est-à-dire à la dernière et suprême bataille du «Cherr Boubbah». On raconte en effet que, repoussés une première fois par les marabouts, les guerriers s'étaient retirés au Tagant. Les deux camps, s'étant mis à
- 74. nouveau en marche l'un contre l'autre, se rencontrèrent à la mare de Tin Yefdad, au sud d'Ouezzan. Ils se faisaient face depuis plusieurs jours, quand les Ahel Badelli allèrent trouver les chefs guerriers et leur conseillèrent de prendre de nuit le plus d'eau possible dans la mare, puis de la rendre imbuvable, en y faisant piétiner des animaux, traînant des branches d'épineux. Ce conseil fut suivi. Puis au matin, les hassanes attaquèrent les marabouts. Repoussés, ils revinrent inlassablement à la charge et épuisèrent leurs adversaires. A la nuit, chacun resta sur ses positions, mais tandis que les guerriers buvaient et se refaisaient, les marabouts mouraient de soif devant la mare. Le lendemain, incapables de continuer la lutte, ils durent se reconnaître vaincus et accepter les conditions des guerriers. Toute cette histoire paraît bien fantaisiste. Il n'en reste pas moins que les Id Eïlik, marabouts des Oulad Normach, ne leur payent pas de horma officielle, contrairement à toutes les coutumes maures, et que les uns et les autres sont d'accord pour reconnaître que cette situation privilégiée remonte à la guerre de Boubbah et aux concours que les Normach reçurent à cette époque des Id Eïlik. On peut donc en admettre le principe. A la fin du dix-huitième siècle, et sans qu'on sache en quelles circonstances exactement, le commandement passe dans les mains d'Atig ould Ahmed ould Habid ould Hand ould Mohand ould Malik ould Tegueddi ould Badelli ould Eïlik, chef de la branche cadette. Atig meurt en 1810, laissant deux fils: Cheikh Mohammed Mahmoud et Mouïn. C'est à cette date, et par suite des rivalités des deux fils, qui se constituent le groupement actuel des Id Eïlik en deux fractions: Ahel Aleg, Ahel Abary, du nom de la région où ces campements nomadisaient habituellement. On connaît Aleg. Abary est le nom d'une petite rivière du Chamama. Tableau généalogique. Atig, † vers 1810. Cheikh Mohammed Mahmoud, † vers 1840. Mouïn, vers 1880.
- 75. Mostafa, † vers 1839. Sidi Salem. Tig. Cheikh Moh. Fal. Mahfoudh. Mostafa. Ahmed Mouïn. Mostafa. Naji, chef des Ahel Aleg. Isselmou. Abd El- Kerim. Mahmoud, chef des Ahel Abary. Ahmed. Cheikh Mohammed Mahmoud, tout en reconnaissant une certaine indépendance aux Ahel Abary de son frère, conserva encore, nominalement au moins, le commandement de la tribu. A sa mort, vers 1840, il ne laissait que des petits-enfants en bas âge, car son fils Mostafa était mort un an avant lui. Cette situation permit à Mouïn, chef des Ahel Abary, de prendre sa complète autonomie. Cheikh Mohammed Fal ould Mostafa ould Cheikh Mohammed Mahmoud a été un très pieux, très influent et très réputé marabout. On trouva son obédience dans plusieurs tribus maures voisines, et chez beaucoup de Toucouleurs du Chamama. Il était chef des Ahel Aleg, à notre arrivée, et conserva le commandement jusqu'à sa mort (fin 1912), mais depuis plusieurs années déjà, il ne s'occupait plus que de choses pieuses et laissait la direction politique de la fraction (Ahel Aleg) à son fils Naji et à son frère Mahfoudh. Nous n'eûmes que peu de rapports avec ce Cheikh. Il affecta de nous ignorer. Naji (de son vrai nom Mohammed Mahmoud) a succédé à son père Mohammed Fal, en fin 1912, tant dans son commandement politique que dans sa direction spirituelle. A ce titre, il jouit d'un grand prestige dans sa tribu et au dehors, principalement dans la dabaï de haratines et dans les villages toucouleurs du Chamama et perçoit de nombreux cadeaux de toute nature. Très intelligent, fort instruit, sympathique, Naji, vers 1884, est déjà un professeur renommé. Son cours supérieur est suivi assidûment par une trentaine de jeunes gens Id Eïlik, haratines et Toucouleurs. Une de ses sœurs a épousé un fils de Cheikh Sidïa; elle vit actuellement séparée de son mari.
- 76. Welcome to our website – the perfect destination for book lovers and knowledge seekers. We believe that every book holds a new world, offering opportunities for learning, discovery, and personal growth. That’s why we are dedicated to bringing you a diverse collection of books, ranging from classic literature and specialized publications to self-development guides and children's books. More than just a book-buying platform, we strive to be a bridge connecting you with timeless cultural and intellectual values. With an elegant, user-friendly interface and a smart search system, you can quickly find the books that best suit your interests. Additionally, our special promotions and home delivery services help you save time and fully enjoy the joy of reading. Join us on a journey of knowledge exploration, passion nurturing, and personal growth every day! ebookbell.com