Configuring the servlet
Before we can deploy our
servlet, we need to configure it. All Java EE web applications can be
configured via an XML deployment descriptor named web.xml or via annotations. In this section, we will discuss how to configure a Java EE web application via web.xml. The web.xml deployment descriptor for our servlet is as follows:
<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation=
"http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd" version="3.0">
<servlet>
<servlet-name>SimpleServlet</servlet-name>
<servlet-class>
net.ensode.glassfishbook.simpleapp.SimpleServlet
</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>SimpleServlet</servlet-name>
<url-pattern>/simpleservlet</url-pattern>
</servlet-mapping>
</web-app>
The first few lines are
boilerplate XML stating the XML version and encoding, plus the schema
used for the XML file and other information. It is safe to just copy and
paste these lines and reuse them across applications. The<servlet> and<servlet-mapping> XML tags are used to actually configure our servlet.
The<servlet> tag contains two nested tags:<servlet-name> defines a logical name for the servlet and<servlet-class> indicates the Java class defining the servlet.
The<servlet-mapping> tag also contains two nested tags:<servlet-name> matches the value set inside the<servlet> tag and<url-pattern> sets the URL pattern for which the servlet will execute.
The<url-pattern>
tag can be specified in one of the following two ways: by using a path
prefix (which is what the previous example does) or by specifying an
extension suffix.
Path prefix values for<url-pattern>
indicate that any URL paths starting with the given path will be
serviced by the corresponding servlet. Path prefix values must start
with a forward slash.
Java EE web applications
run from within a context root. The context root is the first string in
the URL that is neither the server name or IP address nor the port. For
example, in the URL http://localhost:8080/simpleapp/simpleservlet, the string simpleapp is the context root. The value for<url-pattern> is relative to the application's context root.
Extension suffix values for<url-pattern>
indicate that any URLs ending in the given suffix will be serviced by
the corresponding servlet. In the previous example, we chose to use a
path prefix. If we had chosen to use an extension suffix, the<servlet-mapping> tag would look something like this:
<servlet-mapping>
<servlet>SimpleServlet</servlet>
<url-pattern>*.foo</url-pattern>
</servlet-mapping>
This would direct any URLs ending with the string .foo to our servlet.
The reason the<servlet-name> tag is specified twice (once inside the<servlet> tag and again inside the<servlet-mapping> tag) is because a Java EE web application can have more than one servlet. Each of the servlets must have a<servlet> tag in the application's web.xml file. The<servlet> tag for each must have a corresponding<servlet-mapping> tag. The<servlet-name> nested tag is used to indicate which<servlet> tag corresponds to which<servlet-mapping> tag.
A Java EE web.xml
file can contain many additional XML tags. However, these additional
tags are not needed for this simple example. Additional tags will be
discussed in future examples when they are needed.
Before we can execute our servlet, we need to package it as part of a web application in a WAR (Web ARchive) file.
Packaging the web application
All Java EE web applications
must be packaged in a WAR (Web ARchive) file before they can be
deployed. A WAR file is nothing but a compressed file containing our
code and configuration. WAR files can be created by any utility that can
create files in a ZIP format (for example, WinZip, 7-Zip, and so on).
Also, many Java IDEs and build tools such as ANT and Maven automate WAR
file creation.
A WAR file must contain the following directories (in addition to its root directory):
WEB-INF
WEB-INF/classes
WEB-INF/lib
The root directory contains JSPs , HTML files, JavaScript files, and CSS files.
WEB-INF contains deployment descriptors such as web.xml.
WEB-INF/classes contains the compiled
code (.class files) and may optionally contain property files. Just like
with any Java classes, the directory structure must match the package
structure. Therefore, this directory typically contains several
subdirectories corresponding to the classes contained in it.
WEB-INF/lib contains JAR files containing any library dependencies our code might have.
The root directory, WEB-INF and WEB-INF/classes directories can have subdirectories. Any resources on a subdirectory of the root directory (other than can be accessed by prepending the subdirectory name to its filename. For example, if there was a subdirectory called css containing a CSS file called, this CSS file could be accessed in JSPs and HTML files in the root directory by the following line: WEB-INF) style.css
<link rel="stylesheet" type="text/css" media="screen" href="css/style.css" />
Notice the css prefix to the filename corresponding to the directory where the CSS file resides.
To create a WAR file from
scratch, create the previous directory structure in any directory in
your system, then perform the following steps:
Copy the web.xml file to WEB-INF.
Create the following directory structure under WEB-INF/classes: net/ensode/glassfishbook/simpleapp.
Copy SimpleServlet.class to the simpleapp directory from the previous step.
From the command line, issue the following command from the directory right above WEB-INF: jar cvf simpleapp.war *.
You should now have a WAR file ready for deployment.
When using Maven to build the code, the WAR file is automatically generated when issuing the mvn package command. The WAR file can be found under the target directory. It is named simpleapp.war.
Before we can execute our application, it needs to be deployed.
Deploying the web application
There are several ways of deploying an application. The easiest and
most straightforward way to deploy any Java EE application is to copy
the deployment file (in this case, WAR file) to [glassfish installation directory]/glassfish/domains/domain1/autodeploy.
After copying the WAR file to the autodeploy directory, the system log should show a message similar to the following:
[#|2010-04-08T19:39:48.313-0400|INFO|glassfishv3.0|javax.enterprise.system.tools.deployment.org.glassfish.deployment.common|_ThreadID=28;
_ThreadName=Thread-1;|[AutoDeploy] Successfully autodeployed : /home/heffel/sges-v3/glassfish/domains/domain1/autodeploy/simpleapp.war.|#]
The system log can be found under [glassfish installation directory]/glassfish/domains/domain1/logs/server.log.
The last line should contain the string "Successfully autodeployed", indicating that our WAR file was deployed successfully.
Testing the web application
To verify that the servlet has been properly deployed, we need to point our browser to http://localhost:8080/simpleapp/simpleservlet. After doing so, we should see a page similar to the following:
We
mentioned that URL paths for a Java EE application are relative to their
context root. The default context root for a WAR file is the name of
the WAR file itself (minus the .war extension). As can be seen in the previous screenshot, the context root for our application is simpleapp, which happens to match the name of the WAR file. This default can be changed by adding an additional configuration file to the WEB-INF directory of the WAR file. The name of this file should be sun-web.xml. An example sun-web.xml file that will change the context root of our application from the default simpleapp to simple would look as follows:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE sun-web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Application Server 8.1 Servlet 2.4//EN"
"http://www.sun.com/software/appserver/dtds/sun-web-app_2_4-1.dtd">
<sun-web-app>
<context-root>/simple</context-root>
</sun-web-app>
As can be seen in this example, the context root for the application must be in the<context-root> tag of the sun-web.xml configuration file. After redeploying the file, directing the browser to http://localhost:8080/simple/simpleservlet will execute our servlet. simpleapp.war
The sun-web.xml
file can contain a number of additional tags to configure several
aspects of the application.
