A Simple Web Application

Introduction

In order to test J2EE Security with the Security Realm and Openldap User Repository we created in the last article in this series, we need an application to protect. The focus of this article is to create a very simple web application that can be protected by J2EE Security.

The application we are going to create will contain a single Servlet. Servlets are the work horse of J2EE web technology. All HTTP requests funneled into a J2EE Container will eventually be answered by an HTTP Servlet.

The Servlet presented in this article will be specific to JBoss because it is going to retrieve the JAAS Subject associated with the thread processing the request. To retrieve the JAAS Subject, a JBoss API, org.jboss.security.SecurityAssociation, needs to be used. Recall, the Security Authentication Subsystem of JBoss is based upon JAAS.

Now, a JAAS Subject will not be present until after J2EE Security has been properly configured. That will not be done until the end of this series. So, be patient.

The Servlet

This example Servlet is actually the first Servlet example that has ever been presented on Thinkmiddleware.com. Up to this point, we’ve covered foundational technologies that are used to build Application Servers. To present a functioning J2EE Security example, a web application is needed.

The JavaDoc for the HTTP Servlet API can be found here.

SimpleServlet.java is a basic Servlet that will handle an HTTP GET or HTTP POST request sent to it. Admittedly, this Servlet doesn’t do anything particularly interesting-it will print HelloWorld in an HTML page it returns. This will be fixed shortly.

An HTTP Servlet must extend the HTTPServlet class. For a GET request, the doGet() method would be called. For a POST request, the doPost() method would be called. In this example, these methods both call the doService() method. Notice that all of these methods take an HTTPServletRequest object and an HTTPServletResponse object.

Now, we want the servlet to retrieve the JAAS Subject associated with our request and dump its contents. The changes needed to accomplish this can be seen in SubjectServlet.java.

Notice, that the dumpSubject() method has been added to the Servlet and is called from the doService() method. The dumpSubject() method is based on the method of the same name introduced in this article. This version of the method takes a PrintWriter object as an argument so the method can send its output directly to the request’s HTTPServletResponse object. Also, JBoss provides a org.jboss.security.SecurityAssociation class that can retrieve the request’s associated JAAS Subject–this class is now called to retrieve the Subject. Also, the JBoss org.jboss.security.SimpleGroup class is used to retrieve J2EE Roles and LDAP Groups from the JAAS Subject.

So, this dumpSubject() method can be used to retrieve the standard information that is stored in a JBoss JAAS Subject.

The contents of a JBoss JAAS Subject will be discussed in a later article.

Deployment Descriptors

Deployment Descriptors are XML configuration files that application containers look for when deploying applications. There are spec-defined deployment descriptors and vendor-specific deployment descriptors. This tutorial only presents the spec-defined deployment descriptors needed to successfully deploy this application.

This Web Application will have two deployment descriptors:

  1. web.xml
  2. application.xml

web.xml

The web.xml file is a spec-defined Deployment Descriptor that describes the Web Application configuration to the application server.

Here is the web.xml for this web application.

This web.xml file defines two Servlets:

  • ProtectedSubjectServlet
  • UnprotectedSubjectServlet

Each Servlet uses the same implementation class: SubjectServlet.

The path of the ProtectedSubjectServlet Servlet is /ProtectedSubjectServlet. The path of the UnprotectedSubjectServlet is /UnprotectedSubjectServlet.

Note, this web.xml file does not define SimpleServlet. So, it can not be called. But, if you would want to call SimpleServlet, add the following to web.xml:

<servlet>
<servlet-name>SimpleServlet</servlet-name>
<servlet-class>SimpleServlet</servlet-class>
</servlet>

<servlet-mapping>
<servlet-name>SimpleServlet</servlet-name>
<url-pattern>/SimpleServlet</url-pattern>
</servlet-mapping>

These stanzas should be placed prior to the last line containing “</web-app>”.

The WAR File

A WAR file is a JAR file with a well-defined format containing the components (static content, JSPs, Java classes, Java libraries) a J2EE Web Application needs. The directory structure is defined by the Servlet Spec. For our application it will contain like the following:

  • META-INF
    META-INF/manifest.mf
    WEB-INF
    WEB-INF/web.xml
    WEB-INF/classes
    WEB-INF/classes/SubjectServlet.class

Note, that the META-INF/manifest.mf file is the default file generated by the jar command.

The Ant build.xml file presented below will build the WAR file.

application.xml

WAR files can be placed inside EAR files–see below. The Deployment Descriptor for an EAR file is called application.xml. The application.xml file for this Web Application can be found here.

This contents of this application.xml file are straightforward enough. The display name will be used by the application server to identify the Enterprise Archive (EAR). The single <module> stanza defines a web application stored in subject.war (described earlier) that should be made available under the context root, /subject (or subject).

Web Application context roots are described in this article.

The EAR File

Multiple WAR files can be packaged together in an EAR file. An EAR file can also contain JAR file that contain EJBs and third-party libraries JAR.

As a standard practice, WAR files can be placed in EAR files. This will be the convention followed in Thinkmiddleware.com examples.

An EAR file is a JAR file with a well-defined format–similar to a WAR file. The format is defined in the J2EE Spec(chapter 8).

The files in our JAR file are:

META-INF
META-INF/application.xml
subject.war

The application and WAR file are described in previous sections.

Ant build.xml

The Ant build.xml that can build this application can be found here.

The full source directory can be downloaded below.

Environment Setup

JAVA_HOME=/usr/java/jdk1.6.0_10
PATH=$JAVA_HOME/bin:$PATH
CLASSPATH=.:../jboss-4.2.3.GA/client/servlet-api.jar:../jboss-4.2.3.GA/server/default/lib/jbosssx.jar:../jboss-4.2.3.GA/client/jboss-annotations-ejb3.jar
export JAVA_HOME PATH CLASSPATH

Note, this works for my environment, but will need to be tweaked for others. I list these environment variables here so that you know where to grab the JBoss libraries in your installation.

Compile and Build

Download the source code jar found in the Download section below.

Create a directory where the contents can be expanded.

Explode the JAR file in that directory.

Setup up the environment as described in the last section.

Download and install Ant.

Setup your environment to use Ant.

Type “ant build. This will build the EAR file.

Deployment

The EAR file built in the last section can be deployed to any J2EE-compliant application server.

If JBoss 4.x is being used, this article will explain how to setup JBoss 4.3.x for Thinkmiddleware.com examples.

In its simplest form, deployment is accomplished by copying the EAR file to $SERVER_HOME/deploy. The Ant script can do this by setting the “deploy_dir” property to $SERVER_HOME/deploy for your environment and running “ant deploy”.

Closing

This is by no means an exhaustive review of J2EE Development. But, it is a good first step. More sophisticated applications will be presented as needed on Thinkmiddleware.com.

Download

The full source code, deployment descriptors, and Ant build.xml can be found here.