Web Application Programmer's Guide

Target Audience and Content

The target audience for this guide is the Web component provider, i.e. the person in charge of developing the Web components on the server side. It describes how the Web component provider should build the deployment descriptors of its Web components and how the web components should be packaged.

The content of this guide is the following:

  1. Target Audience and Content
  2. Developing Web Components
  3. Defining the Web Deployment Descriptor
  4. WAR Packaging

Developing Web Components

Introduction

A Web Component is a generic term which denotes both JSP pages and Servlets. Web components are packaged in a .war file and can be deployed in a JOnAS server via the web container service. Web components can be integrated in a J2EE application by packing the .war file in an .ear file (refer to the J2EE Application Programmer's Guide).

The JOnAS distribution includes a Web application example: The EarSample example.

The directory structure of this application is the following:

etc/xml contains the web.xml file describing the web application
etc/resources/web contains html pages and images; JSP pages can also be placed here.
src/org/objectweb/earsample/servlets servlet sources
src/org/objectweb/earsample/beans beans sources

The bean directory is not needed if beans coming from another application will be used.

The JSP pages

Java Server Pages (JSP) is a technology that allows regular, static HTML, to be mixed with dynamically-generated HTML written in Java programming language for encapsulating the logic that generates the content for the page. Refer to the Java Server PagesTM and the Quickstart guide for more details.

Example:

The following example shows a sample JSP page that lists the content of a cart.

    <!-- Get the session -->
    <%@ page session="true" %>

    <!-- The import to use -->
    <%@ page import="java.util.Enumeration" %>
    <%@ page import="java.util.Vector"      %>

    <html>
    <body bgcolor="white">
      <h1>Content of your cart</h1><br>
      <table>
        <!-- The header of the table -->
        <tr bgcolor="black">
          <td><font color="lightgreen">Product Reference</font></td>
          <td><font color="lightgreen">Product Name</font></td>
          <td><font color="lightgreen">Product Price</font></td>
        </tr>

        <!-- Each iteration of the loop display a line of the table -->
        <%
          Cart cart = (Cart) session.getAttribute("cart");
          Vector products = cart.getProducts();
          Enumeration enum = products.elements();
          // loop through the enumeration
          while (enum.hasMoreElements()) {
              Product prod = (Product) enum.nextElement();
        %>
        <tr>
          <td><%=prod.getReference()%></td>
          <td><%=prod.getName()%></td>
          <td><%=prod.getPrice()%></td>
        </tr>
        <%
        } // end loop
        %>
      </table>
    </body>
    </html>

It is a good idea to hide all the mechanisms for accessing EJBs from JSP pages by using a proxy java bean, referenced in the JSP page by the usebean special tag. This technique is shown in the alarm example, where the .jsp files communicate with the EJB via a proxy java bean ViewProxy.java.

The Servlets

Servlets are modules of Java code that run in an application server for answering client requests. Servlets are not tied to a specific client-server protocol. However, they are most commonly used with HTTP, and the word "Servlet" is often used as referring to an "HTTP Servlet."

Servlets make use of the Java standard extension classes in the packages javax.servlet (the basic Servlet framework) and javax.servlet.http (extensions of the Servlet framework for Servlets that answer HTTP requests).

Typical uses for HTTP Servlets include:

For more details refer to the JavaTM Servlet Technology and the Servlets tutorial.

Example:

The following example is a sample of a Servlet that lists the content of a cart.
This example is the servlet version of the previous JSP page example.

    import java.util.Enumeration;
    import java.util.Vector;
    import java.io.PrintWriter;
    import java.io.IOException;
    import javax.servlet.ServletException;
    import javax.servlet.http.HttpServlet;
    import javax.servlet.http.HttpServletRequest;
    import javax.servlet.http.HttpServletResponse;
    import javax.servlet.http.HttpSession;

    public class GetCartServlet extends HttpServlet {

        protected void doGet(HttpServletRequest req, HttpServletResponse res)
                             throws ServletException, IOException {

            res.setContentType("text/html");
            PrintWriter out = res.getWriter();

            out.println("<html><head><title>Your cart</title></head>");
            out.println("<body>");
            out.println("<h1>Content of your cart</h1><br>");
            out.println("<table>");

            // The header of the table
            out.println("<tr>");
            out.println("<td><font color="lightgreen">Product Reference</font></td>");
            out.println("<td><font color="lightgreen">Product Name</font></td>");
            out.println("<td><font color="lightgreen">Product Price</font></td>");
            out.println("</tr>");

            // Each iteration of the loop display a line of the table
            HttpSession session = req.getSession(true);
            Cart cart = (Cart) session.getAttribute("cart");
            Vector products = cart.getProducts();
            Enumeration enum = products.elements();
            while (enum.hasMoreElements()) {
                Product prod = (Product) enum.nextElement();
                int prodId = prod.getReference();
                String prodName = prod.getName();
                float prodPrice = prod.getPrice();
                out.println("<tr>");
                out.println("<td>" + prodId + </td>);
                out.println("<td>" + prodName + </td>);
                out.println("<td>" + prodPrice + </td>);
                out.println("</tr>");
            }

            out.println("</table>");
            out.println("</body>");
            out.println("</html>");
            out.close();
        }
    }

Accessing an EJB from a Servlet or JSP page

Through the JOnAS web container service, it is possible to access an enterprise java bean and its environment in a J2EE-compliant way.

The following sections describe:

  1. How to access the Remote Home interface of a bean.
  2. How to access the Local Home interface of a bean.
  3. How to access the environment of a bean.
  4. How to start transactions in servlets.
Note that all the following code examples are taken from the The EarSample example provided in the JOnAS distribution.

Accessing the Remote Home interface of a bean:

In this example the servlet gets the Remote Home interface OpHome registered in JNDI using an EJB reference, then creates a new instance of the session bean: 
import javax.naming.Context;
import javax.naming.InitialContext;

//remote interface
import org.objectweb.earsample.beans.secusb.Op;
import org.objectweb.earsample.beans.secusb.OpHome;

        Context initialContext = null;
        try {
            initialContext = new InitialContext();
        } catch (Exception e) {
            out.print("<li>Cannot get initial context for JNDI: ");
            out.println(e + "</li>");
            return;
        }
      // Connecting to OpHome thru JNDI
        OpHome opHome = null;
        try {
            opHome = (OpHome) PortableRemoteObject.narrow(initialContext.lookup
                     ("java:comp/env/ejb/Op"),OpHome.class);
        } catch (Exception e) {
            out.println("<li>Cannot lookup java:comp/env/ejb/Op: " + e + "</li>");
            return;
        }
        // OpBean creation
        Op op = null;
        try {
            op = opHome.create("User1");
        } catch (Exception e) {
            out.println("<li>Cannot create OpBean: " + e + "</li>");
            return;
        }
Note that the following elements must be set in the web.xml file tied to this web application: 
  <ejb-ref>
    <ejb-ref-name>ejb/Op</ejb-ref-name>
    <ejb-ref-type>Session</ejb-ref-type>
    <home>org.objectweb.earsample.beans.secusb.OpHome</home>
    <remote>org.objectweb.earsample.beans.secusb.Op</remote>
    <ejb-link>secusb.jar#Op</ejb-link>
  </ejb-ref>

Accessing the Local Home of a bean:

The following example shows how to obtain a local home interface OpLocalHome using an EJB local reference: 
//local interfaces
import org.objectweb.earsample.beans.secusb.OpLocal;
import org.objectweb.earsample.beans.secusb.OpLocalHome;


      // Connecting to OpLocalHome thru JNDI
        OpLocalHome opLocalHome = null;
        try {
            opLocalHome = (OpLocalHome)
                initialContext.lookup("java:comp/env/ejb/OpLocal");
        } catch (Exception e) {
            out.println("<li>Cannot lookup java:comp/env/ejb/OpLocal: " + e + "</li>");
            return;
        }
This is found in the web.xml file: 
  <ejb-local-ref>
    <ejb-ref-name>ejb/OpLocal</ejb-ref-name>
    <ejb-ref-type>Session</ejb-ref-type>
    <local-home>org.objectweb.earsample.beans.secusb.OpLocalHome</local-home>
    <local>org.objectweb.earsample.beans.secusb.OpLocal</local>
    <ejb-link>secusb.jar#Op</ejb-link>
  </ejb-local-ref>

Accessing the environment of the component:

In this example, the servlet seeks to access the component's environment: 
       String envEntry = null;
        try {
            envEntry = (String) initialContext.lookup("java:comp/env/envEntryString");
        } catch (Exception e) {
            out.println("<li>Cannot get env-entry on JNDI " + e + "</li>");
            return;
        }
This is the corresponding part of the web.xml file: 
  <env-entry>
    <env-entry-name>envEntryString</env-entry-name>
    <env-entry-value>This is a string from the env-entry</env-entry-value>
    <env-entry-type>java.lang.String</env-entry-type>
  </env-entry>

Starting transactions in servlets:

The servlet wants to start transactions via the UserTransaction: 
import javax.transaction.UserTransaction;

       // We want to start transactions from client: get UserTransaction
        UserTransaction utx = null;
        try {
            utx = (UserTransaction) initialContext.lookup("java:comp/UserTransaction");
        } catch (Exception e) {
            out.println("<li>Cannot lookup java:comp/UserTransaction: " + e + "</li>");
            return;
        }

        try {
            utx.begin();
            opLocal.buy(10);
            opLocal.buy(20);
            utx.commit();

        } catch (Exception e) {
            out.println("<li>exception during 1st Tx: " + e + "</li>");
            return;
        }

Defining the Web Deployment Descriptor

Principles

The Web component programmer is responsible for providing the deployment descriptor associated with the developed web components. The Web component provider's responsibilities and the application assembler's responsibilities are to provide an XML deployment descriptor that conforms to the deployment descriptor's XML schema as defined in the Java TM Servlet Specification Version 2.4. (Refer to $JONAS_ROOT/xml/web-app_2_4.xsd or  http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd).

To customize the Web components, information not defined in the standard XML deployment descriptor may be needed. For example, the information may include the mapping of the name of referenced resources to its JNDI name. This information can be specified during the deployment phase, within another XML deployment descriptor that is specific to JOnAS. The JOnAS-specific deployment descriptor's XML schema is located in $JONAS_ROOT/xml/jonas-web-app_X_Y.xsd. The file name of the JOnAS-specific XML deployment descriptor must be the file name of the standard XML deployment descriptor prefixed by 'jonas-'.

The parser gets the specified schema via the classpath (schemas are packaged in the $JONAS_ROOT/lib/common/ow_jonas.jar file).

The standard deployment descriptor (web.xml) should contain structural information that includes the following:

The JOnAS-specific deployment descriptor (jonas-web.xml) may contain information that includes:

<host> element: If the configuration file of the web container contains virtual hosts, the host on which the WAR file is deployed can be set.

<context-root> element: The name of the context on which the application will be deployed should be specified. If it is not specified, the context-root used can be one of the following:

If the context-root is / or empty, the web application is deployed as ROOT context (i.e., http://localhost:9000/).

<java2-delegation-model> element: Set the compliance to the java 2 delegation model.

Examples of Web Deployment Descriptors

Tips

Although some characters, such as ">", are legal, it is good practice to replace them with XML entity references. The following is a list of the predefined entity references for XML:

&lt; < less than
&gt; > greater than
&amp; & ampersand
&apos; ' apostrophe
&quot; " quotation mark

WAR Packaging

Web components are packaged for deployment in a standard Java programming language Archive file called a war file (Web ARchive), which is a jar similar to the package used for Java class libraries. A war has a specific hierarchical directory structure. The top-level directory of a war is the document root of the application.

The document root is where JSP pages, client-side classes and archives, and static web resources are stored. The document root contains a subdirectory called WEB-INF, which contains the following files and directories:

Example

Before building a war file, the java source files must be compiled to obtain the class files (located in the WEB-INF/classes directory) and the two XML deployment descriptors must be written.

Then, the war file (<web-application>.war) is built using the jar command:

    cd <your_webapp_directory>
    jar cvf <web-application>.war *

During the development process, an 'unpacked version' of the war file can be used. Refer to Configuring Web Container Service for information about how to use directories for the web application.