Java Enterprise Edition 5 (Java EE 5)

January 20, 2008 Java Enterprise Edition 5 (Java EE 5) Java Platform, Enterprise Edition or Java EE is a widely used platform for server programming in the Java programming language. The Java platform (Enterprise Edition) differs from the Java Standard Edition Platform (Java SE) in that it adds libraries which provide functionality to deploy fault-tolerant, distributed, multi-tier Java software, based largely on modular components running on an application server. PRWeb

]]> Developers today increasingly recognize the need for distributed, transactional, and portable applications that leverage the speed, security, and reliability of server-side technology. In the world of information technology, enterprise applications must be designed, built, and produced for less money, with greater speed, and with fewer resources.With the JavaTM Platform, Enterprise Edition (Java EE), development of Java enterprise applications has never been easier or faster. The aim of the Java EE 5 platform is to provide developers a powerful set of APIs while reducing development time, reducing application complexity, and improving application performance.The Java EE 5 platform introduces a simplified programming model. With Java EE 5 technology, XML deployment descriptors are now optional. Instead, a developer can simply enter the information as an annotation directly into a Java source file, and the Java EE server will configure the component at deployment and runtime. These annotations are generally used to embed in a program data that would otherwise be furnished in a deployment descriptor. With annotations, the specification information is put directly in your code next to the program element that it affects.In the Java EE platform, dependency injection can be applied to all resources that a component needs, effectively hiding the creation and lookup of resources from application code. Dependency injection can be used in EJB containers, web containers, and application clients. Dependency injection allows the Java EE container to automatically insert references to other required components or resources using annotations.The Java Persistence API is new to the Java EE 5 platform. The Java Persistence API provides an object/relational mapping for managing relational data in enterprise beans, web components, and application clients. It can also be used in Java SE applications, outside of the Java EE environment.This tutorial uses examples to describe the features and functionalities available in the Java EE 5 platform for developing enterprise applications. Whether you are a new or experienced Enterprise developer, you should find the examples and accompanying text a valuable and accessible knowledge base for creating your own solutions.If you are new to Java EE enterprise application development, this chapter is a good place to start. Here you will review development basics, learn about the Java EE architecture and APIs, become acquainted with important terms and concepts, and find out how to approach Java EE application programming, assembly, and deployment. January 20, 2008 Java EE Application Model The Java EE application model begins with the Java programming language and the Java virtual machine. The proven portability, security, and developer productivity they provide forms the basis of the application model. Java EE is designed to support applications that implement enterprise services for customers, employees, suppliers, partners, and others who make demands on or contributions to the enterprise. Such applications are inherently complex, potentially accessing data from a variety of sources and distributing applications to a variety of clients.To better control and manage these applications, the business functions to support these various users are conducted in the middle tier. The middle tier represents an environment that is closely controlled by an enterprise’s information technology department. The middle tier is typically run on dedicated server hardware and has access to the full services of the enterprise.The Java EE application model defines an architecture for implementing services as multitier applications that deliver the scalability, accessibility, and manageability needed by enterprise-level applications. This model partitions the work needed to implement a multitier service into two parts: the business and presentation logic to be implemented by the developer, and the standard system services provided by the Java EE platform. The developer can rely on the platform to provide solutions for the hard systems-level problems of developing a multitier service. January 20, 2008 Distributed Multitiered Applications The Java EE platform uses a distributed multitiered application model for enterprise applications. Application logic is divided into components according to function, and the various application components that make up a Java EE application are installed on different machines depending on the tier in the multitiered Java EE environment to which the application component belongs. <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnaay.html#bnaaz">Figure 1-1</a> shows two multitiered Java EE applications divided into the tiers described in the following list. The Java EE application parts shown in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnaay.html#bnaaz"> Figure 1-1</a> are presented in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnaay.html#bnabb"> Java EE Components</a>. <ul> <li> Client-tier components run on the client machine. </li> <li> Web-tier components run on the Java EE server. </li> <li> Business-tier components run on the Java EE server. </li> <li> Enterprise information system (EIS)-tier software runs on the EIS server. </li> </ul> <a name="indexterm-5"></a>Although a Java EE application can consist of the three or four tiers shown in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnaay.html#bnaaz"> Figure 1-1</a>, Java EE multitiered applications are generally considered to be three-tiered applications because they are distributed over three locations: client machines, the Java EE server machine, and the database or legacy machines at the back end. Three-tiered applications that run in this way extend the standard two-tiered client and server model by placing a multithreaded application server between the client application and back-end storage. <a name="bnaaz"></a> <h6>Figure 1-1 Multitiered Applications</h6> <img src="http://java.sun.com/javaee/5/docs/tutorial/doc/figures/overview-multitieredApplications.gif" alt="Diagram of multitiered application structure, including client tier, web tier, business tier, and EIS tier."> <a name="bnaba"></a> <h4>Security</h4> While other enterprise application models require platform-specific security measures in each application, the Java EE security environment enables security constraints to be defined at deployment time. The Java EE platform makes applications portable to a wide variety of security implementations by shielding application developers from the complexity of implementing security features. The Java EE platform provides standard declarative access control rules that are defined by the developer and interpreted when the application is deployed on the server. Java EE also provides standard login mechanisms so application developers do not have to implement these mechanisms in their applications. The same application works in a variety of different security environments without changing the source code. <a name="bnabb"></a> <h4>Java EE Components</h4> <a name="indexterm-6"></a><a name="indexterm-7"></a>Java EE applications are made up of components. A Java EE component is a self-contained functional software unit that is assembled into a Java EE application with its related classes and files and that communicates with other components. The Java EE specification defines the following Java EE components: <ul> <li> Application clients and applets are components that run on the client. </li> <li> Java Servlet, JavaServer Faces, and JavaServer PagesTM (JSPTM) technology components are web components that run on the server. </li> <li> Enterprise JavaBeansTM (EJBTM) components (enterprise beans) are business components that run on the server. </li> </ul> Java EE components are written in the Java programming language and are compiled in the same way as any program in the language. The difference between Java EE components and “standard” Java classes is that Java EE components are assembled into a Java EE application, are verified to be well formed and in compliance with the Java EE specification, and are deployed to production, where they are run and managed by the Java EE server. <a name="bnabc"></a> <h4>Java EE Clients</h4> <a name="indexterm-8"></a> A Java EE client can be a web client or an application client. <a name="bnabd"></a> <h5>Web Clients</h5> <a name="indexterm-9"></a><a name="indexterm-10"></a>A web client consists of two parts: (1) dynamic web pages containing various types of markup language (HTML, XML, and so on), which are generated by web components running in the web tier, and (2) a web browser, which renders the pages received from the server. A web client is sometimes called a thin client. Thin clients usually do not query databases, execute complex business rules, or connect to legacy applications. When you use a thin client, such heavyweight operations are off-loaded to enterprise beans executing on the Java EE server, where they can leverage the security, speed, services, and reliability of Java EE server-side technologies. <a name="bnabe"></a> <h5>Applets</h5> <a name="indexterm-11"></a>A web page received from the web tier can include an embedded applet. An applet is a small client application written in the Java programming language that executes in the Java virtual machine installed in the web browser. However, client systems will likely need the Java Plug-in and possibly a security policy file for the applet to successfully execute in the web browser. Web components are the preferred API for creating a web client program because no plug-ins or security policy files are needed on the client systems. Also, web components enable cleaner and more modular application design because they provide a way to separate applications programming from web page design. Personnel involved in web page design thus do not need to understand Java programming language syntax to do their jobs. <a name="bnabf"></a> <h5>Application Clients</h5> <a name="indexterm-12"></a><a name="indexterm-13"></a><a name="indexterm-14"></a>An application client runs on a client machine and provides a way for users to handle tasks that require a richer user interface than can be provided by a markup language. It typically has a graphical user interface (GUI) created from the Swing or the Abstract Window Toolkit (AWT) API, but a command-line interface is certainly possible. Application clients directly access enterprise beans running in the business tier. However, if application requirements warrant it, an application client can open an HTTP connection to establish communication with a servlet running in the web tier. Application clients written in languages other than Java can interact with Java EE 5 servers, enabling the Java EE 5 platform to interoperate with legacy systems, clients, and non-Java languages. <a name="bnabg"></a> <h5>The JavaBeansTM Component Architecture</h5> <a name="indexterm-15"></a>The server and client tiers might also include components based on the JavaBeans component architecture (JavaBeans components) to manage the data flow between an application client or applet and components running on the Java EE server, or between server components and a database. JavaBeans components are not considered Java EE components by the Java EE specification. JavaBeans components have properties and have <tt>get</tt> and <tt>set</tt> methods for accessing the properties. JavaBeans components used in this way are typically simple in design and implementation but should conform to the naming and design conventions outlined in the JavaBeans component architecture. <a name="bnabh"></a> <h5>Java EE Server Communications</h5> <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnaay.html#bnabi">Figure 1-2</a> shows the various elements that can make up the client tier. The client communicates with the business tier running on the Java EE server either directly or, as in the case of a client running in a browser, by going through JSP pages or servlets running in the web tier. <a name="bnabi"></a> <h6>Figure 1-2 Server Communication</h6> <img src="http://java.sun.com/javaee/5/docs/tutorial/doc/figures/overview-serverCommunications.gif" alt="Diagram of client-server communication. Application clients access the business tier directly. Browsers, web pages, and applets access the web tier."><a name="indexterm-16"></a>Your Java EE application uses a thin browser-based client or thick application client. In deciding which one to use, you should be aware of the trade-offs between keeping functionality on the client and close to the user (thick client) and off-loading as much functionality as possible to the server (thin client). The more functionality you off-load to the server, the easier it is to distribute, deploy, and manage the application; however, keeping more functionality on the client can make for a better perceived user experience. <a name="bnabj"></a> <h4>Web Components</h4> <a name="indexterm-17"></a><a name="indexterm-18"></a>Java EE web components are either servlets or pages created using JSP technology (JSP pages) and/or JavaServer Faces technology. Servlets are Java programming language classes that dynamically process requests and construct responses. JSP pages are text-based documents that execute as servlets but allow a more natural approach to creating static content. JavaServer Faces technology builds on servlets and JSP technology and provides a user interface component framework for web applications. <a name="indexterm-19"></a><a name="indexterm-20"></a><a name="indexterm-21"></a>Static HTML pages and applets are bundled with web components during application assembly but are not considered web components by the Java EE specification. Server-side utility classes can also be bundled with web components and, like HTML pages, are not considered web components. As shown in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnaay.html#bnabm"> Figure 1-3</a>, the web tier, like the client tier, might include a JavaBeans component to manage the user input and send that input to enterprise beans running in the business tier for processing. <a name="bnabm"></a> <h6>Figure 1-3 Web Tier and Java EE Applications</h6> <img src="http://java.sun.com/javaee/5/docs/tutorial/doc/figures/overview-webTier.gif" alt="Diagram of client-server communication showing detail of JavaBeans components and JSP pages in the web tier."> <a name="bnabk"></a> <h4>Business Components</h4> <a name="indexterm-22"></a><a name="indexterm-23"></a>Business code, which is logic that solves or meets the needs of a particular business domain such as banking, retail, or finance, is handled by enterprise beans running in the business tier. <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnaay.html#bnabn"> Figure 1-4</a> shows how an enterprise bean receives data from client programs, processes it (if necessary), and sends it to the enterprise information system tier for storage. An enterprise bean also retrieves data from storage, processes it (if necessary), and sends it back to the client program. <a name="bnabn"></a> <h6>Figure 1-4 Business and EIS Tiers</h6> <img src="http://java.sun.com/javaee/5/docs/tutorial/doc/figures/overview-businessAndEisTiers.gif" alt="Diagram of client-server communication showing detail of entities, session beans, and message-driven beans in the business tier."> <a name="bnabl"></a> <h4>Enterprise Information System Tier</h4> <a name="indexterm-24"></a><a name="indexterm-25"></a>The enterprise information system tier handles EIS software and includes enterprise infrastructure systems such as enterprise resource planning (ERP), mainframe transaction processing, database systems, and other legacy information systems. For example, Java EE application components might need access to enterprise information systems for database connectivity. January 20, 2008 Java EE Containers Normally, thin-client multitiered applications are hard to write because they involve many lines of intricate code to handle transaction and state management, multithreading, resource pooling, and other complex low-level details. The component-based and platform-independent Java EE architecture makes Java EE applications easy to write because business logic is organized into reusable components. In addition, the Java EE server provides underlying services in the form of a container for every component type. Because you do not have to develop these services yourself, you are free to concentrate on solving the business problem at hand. <a name="bnabp"></a> <h4>Container Services</h4> <a name="indexterm-31"></a> Containers are the interface between a component and the low-level platform-specific functionality that supports the component. Before a web, enterprise bean, or application client component can be executed, it must be assembled into a Java EE module and deployed into its container. The assembly process involves specifying container settings for each component in the Java EE application and for the Java EE application itself. Container settings customize the underlying support provided by the Java EE server, including services such as security, transaction management, Java Naming and Directory InterfaceTM (JNDI) lookups, and remote connectivity. Here are some of the highlights: <ul> <li> <a name="indexterm-32"></a>The Java EE security model lets you configure a web component or enterprise bean so that system resources are accessed only by authorized users. </li> <li> <a name="indexterm-33"></a>The Java EE transaction model lets you specify relationships among methods that make up a single transaction so that all methods in one transaction are treated as a single unit. </li> <li> JNDI lookup services provide a unified interface to multiple naming and directory services in the enterprise so that application components can access these services. </li> <li> The Java EE remote connectivity model manages low-level communications between clients and enterprise beans. After an enterprise bean is created, a client invokes methods on it as if it were in the same virtual machine. </li> </ul> <a name="indexterm-34"></a>Because the Java EE architecture provides configurable services, application components within the same Java EE application can behave differently based on where they are deployed. For example, an enterprise bean can have security settings that allow it a certain level of access to database data in one production environment and another level of database access in another production environment. <a name="indexterm-35"></a>The container also manages nonconfigurable services such as enterprise bean and servlet life cycles, database connection resource pooling, data persistence, and access to the Java EE platform APIs (see <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnacj.html"> Java EE 5 APIs</a>). <a name="bnabq"></a> <h4>Container Types</h4> The deployment process installs Java EE application components in the Java EE containers as illustrated in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnabo.html#bnabr"> Figure 1-5</a>. <a name="bnabr"></a> <h6>Figure 1-5 Java EE Server and Containers</h6> <img src="http://java.sun.com/javaee/5/docs/tutorial/doc/figures/overview-serverAndContainers.gif" alt="Diagram of client-server communication showing servlets and JSP pages in the web tier and enterprise beans in the business tier."> <ul> <li> <a name="indexterm-36"></a>Java EE server: The runtime portion of a Java EE product. A Java EE server provides EJB and web containers. </li> <li> <a name="indexterm-37"></a>Enterprise JavaBeans (EJB) container: Manages the execution of enterprise beans for Java EE applications. Enterprise beans and their container run on the Java EE server. </li> <li> <a name="indexterm-38"></a>Web container: Manages the execution of JSP page and servlet components for Java EE applications. Web components and their container run on the Java EE server. </li> <li> <a name="indexterm-39"></a>Application client container: Manages the execution of application client components. Application clients and their container run on the client. </li> <li> <a name="indexterm-40"></a>Applet container: Manages the execution of applets. Consists of a web browser and Java Plug-in running on the client together. </li> </ul> January 20, 2008 Web Services Support Web services are web-based enterprise applications that use open, XML-based standards and transport protocols to exchange data with calling clients. The Java EE platform provides the XML APIs and tools you need to quickly design, develop, test, and deploy web services and clients that fully interoperate with other web services and clients running on Java-based or non-Java-based platforms. To write web services and clients with the Java EE XML APIs, all you do is pass parameter data to the method calls and process the data returned; or for document-oriented web services, you send documents containing the service data back and forth. No low-level programming is needed because the XML API implementations do the work of translating the application data to and from an XML-based data stream that is sent over the standardized XML-based transport protocols. These XML-based standards and protocols are introduced in the following sections. The translation of data to a standardized XML-based data stream is what makes web services and clients written with the Java EE XML APIs fully interoperable. This does not necessarily mean that the data being transported includes XML tags because the transported data can itself be plain text, XML data, or any kind of binary data such as audio, video, maps, program files, computer-aided design (CAD) documents and the like. The next section introduces XML and explains how parties doing business can use XML tags and schemas to exchange data in a meaningful way. <a name="bnabt"></a> <h4>XML</h4> <a name="indexterm-42"></a>XML is a cross-platform, extensible, text-based standard for representing data. When XML data is exchanged between parties, the parties are free to create their own tags to describe the data, set up schemas to specify which tags can be used in a particular kind of XML document, and use XML stylesheets to manage the display and handling of the data. For example, a web service can use XML and a schema to produce price lists, and companies that receive the price lists and schema can have their own stylesheets to handle the data in a way that best suits their needs. Here are examples: <ul> <li> One company might put XML pricing information through a program to translate the XML to HTML so that it can post the price lists to its intranet. </li> <li> A partner company might put the XML pricing information through a tool to create a marketing presentation. </li> <li> Another company might read the XML pricing information into an application for processing. </li> </ul> <a name="bnabu"></a> <h4>SOAP Transport Protocol</h4> <a name="indexterm-43"></a>Client requests and web service responses are transmitted as Simple Object Access Protocol (SOAP) messages over HTTP to enable a completely interoperable exchange between clients and web services, all running on different platforms and at various locations on the Internet. HTTP is a familiar request-and response standard for sending messages over the Internet, and SOAP is an XML-based protocol that follows the HTTP request-and-response model. The SOAP portion of a transported message handles the following: <ul> <li> Defines an XML-based envelope to describe what is in the message and how to process the message </li> <li> Includes XML-based encoding rules to express instances of application-defined data types within the message </li> <li> Defines an XML-based convention for representing the request to the remote service and the resulting response </li> </ul> <a name="bnabv"></a> <h4>WSDL Standard Format</h4> <a name="indexterm-44"></a>The Web Services Description Language (WSDL) is a standardized XML format for describing network services. The description includes the name of the service, the location of the service, and ways to communicate with the service. WSDL service descriptions can be stored in UDDI registries or published on the web (or both). The Sun Java System Application Server Platform Edition 8 provides a tool for generating the WSDL specification of a web service that uses remote procedure calls to communicate with clients. <a name="bnabw"></a> <h4>UDDI and ebXML Standard Formats</h4> <a name="indexterm-45"></a><a name="indexterm-46"></a>Other XML-based standards, such as Universal Description, Discovery and Integration (UDDI) and ebXML, make it possible for businesses to publish information on the Internet about their products and web services, where the information can be readily and globally accessed by clients who want to do business. January 20, 2008 Java EE Application Assembly and Deployment A Java EE application is packaged into one or more standard units for deployment to any Java EE platform-compliant system. Each unit contains: * A functional component or components (such as an enterprise bean, JSP page, servlet, or applet) * An optional deployment descriptor that describes its content Once a Java EE unit has been produced, it is ready to be deployed. Deployment typically involves using a platform’s deployment tool to specify location-specific information, such as a list of local users that can access it and the name of the local database. Once deployed on a local platform, the application is ready to run. January 20, 2008 Packaging Applications A Java EE application is delivered in an Enterprise Archive (EAR) file, a standard Java Archive (JAR) file with an <tt>.ear</tt> extension. Using EAR files and modules makes it possible to assemble a number of different Java EE applications using some of the same components. No extra coding is needed; it is only a matter of assembling (or packaging) various Java EE modules into Java EE EAR files.<a name="indexterm-48"></a>An EAR file (see <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnaby.html#bnabz">Figure 1-6</a>) contains Java EE modules and deployment descriptors. A deployment descriptor is an XML document with an <tt>.xml</tt> extension that describes the deployment settings of an application, a module, or a component. Because deployment descriptor information is declarative, it can be changed without the need to modify the source code. At runtime, the Java EE server reads the deployment descriptor and acts upon the application, module, or component accordingly.<a name="bnabz"></a><h6>Figure 1-6 EAR File Structure</h6><img src="http://java.sun.com/javaee/5/docs/tutorial/doc/figures/overview-applicationModule.gif" alt="Diagram of EAR file structure. META-INF and web, application client, EJB, and resource adapter modules are under the assembly root."><a name="indexterm-49"></a><a name="indexterm-50"></a>There are two types of deployment descriptors: Java EE and runtime. A Java EE deployment descriptor is defined by a Java EE specification and can be used to configure deployment settings on any Java EE-compliant implementation. A runtime deployment descriptor is used to configure Java EE implementation-specific parameters. For example, the Sun Java System Application Server Platform Edition 9 runtime deployment descriptor contains information such as the context root of a web application, the mapping of portable names of an application’s resources to the server’s resources, and Application Server implementation-specific parameters, such as caching directives. The Application Server runtime deployment descriptors are named <tt>sun-</tt>moduleType<tt>.xml</tt> and are located in the same <tt>META-INF</tt> directory as the Java EE deployment descriptor.<a name="indexterm-51"></a>A Java EE module consists of one or more Java EE components for the same container type and one component deployment descriptor of that type. An enterprise bean module deployment descriptor, for example, declares transaction attributes and security authorizations for an enterprise bean. A Java EE module without an application deployment descriptor can be deployed as a stand-alone module. The four types of Java EE modules are as follows: <ul><li><a name="indexterm-52"></a>EJB modules, which contain class files for enterprise beans and an EJB deployment descriptor. EJB modules are packaged as JAR files with a <tt>.jar</tt> extension.</li> <li><a name="indexterm-53"></a><a name="indexterm-54"></a>Web modules, which contain servlet class files, JSP files, supporting class files, GIF and HTML files, and a web application deployment descriptor. Web modules are packaged as JAR files with a <tt>.war</tt> (Web ARchive) extension.</li> <li><a name="indexterm-55"></a>Application client modules, which contain class files and an application client deployment descriptor. Application client modules are packaged as JAR files with a <tt>.jar</tt> extension.</li> <li><a name="indexterm-56"></a>Resource adapter modules, which contain all Java interfaces, classes, native libraries, and other documentation, along with the resource adapter deployment descriptor. Together, these implement the Connector architecture (see <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnacj.html#bnacz">J2EE Connector Architecture</a>) for a particular EIS. Resource adapter modules are packaged as JAR files with an <tt>.rar</tt> (resource adapter archive) extension.</li></ul> January 20, 2008 Development Roles Reusable modules make it possible to divide the application development and deployment process into distinct roles so that different people or companies can perform different parts of the process.<a name="indexterm-59"></a>The first two roles involve purchasing and installing the Java EE product and tools. After software is purchased and installed, Java EE components can be developed by application component providers, assembled by application assemblers, and deployed by application deployers. In a large organization, each of these roles might be executed by different individuals or teams. This division of labor works because each of the earlier roles outputs a portable file that is the input for a subsequent role. For example, in the application component development phase, an enterprise bean software developer delivers EJB JAR files. In the application assembly role, another developer combines these EJB JAR files into a Java EE application and saves it in an EAR file. In the application deployment role, a system administrator at the customer site uses the EAR file to install the Java EE application into a Java EE server.The different roles are not always executed by different people. If you work for a small company, for example, or if you are prototyping a sample application, you might perform the tasks in every phase. <a name="bnacb"></a><h4>Java EE Product Provider</h4> <a name="indexterm-60"></a>The Java EE product provider is the company that designs and makes available for purchase the Java EE platform APIs, and other features defined in the Java EE specification. Product providers are typically application server vendors who implement the Java EE platform according to the Java EE 5 Platform specification. <a name="bnacc"></a><h4>Tool Provider</h4> <a name="indexterm-61"></a>The tool provider is the company or person who creates development, assembly, and packaging tools used by component providers, assemblers, and deployers. <a name="bnacd"></a><h4>Application Component Provider</h4> The application component provider is the company or person who creates web components, enterprise beans, applets, or application clients for use in Java EE applications. <a name="bnace"></a><h5>Enterprise Bean Developer</h5> <a name="indexterm-62"></a>An enterprise bean developer performs the following tasks to deliver an EJB JAR file that contains one or more enterprise beans: <ul><li>Writes and compiles the source code</li> <li>Specifies the deployment descriptor</li> <li>Packages the <tt>.class</tt> files and deployment descriptor into the EJB JAR file</li></ul> <a name="bnacf"></a><h5>Web Component Developer</h5> <a name="indexterm-63"></a>A web component developer performs the following tasks to deliver a WAR file containing one or more web components: <ul><li>Writes and compiles servlet source code</li> <li>Writes JSP, JavaServer Faces, and HTML files</li> <li>Specifies the deployment descriptor</li> <li>Packages the <tt>.class</tt>, <tt>.jsp</tt>, and<tt>.html</tt> files and deployment descriptor into the WAR file</li></ul> <a name="bnacg"></a><h5>Application Client Developer</h5> <a name="indexterm-64"></a>An application client developer performs the following tasks to deliver a JAR file containing the application client: <ul><li>Writes and compiles the source code</li> <li>Specifies the deployment descriptor for the client</li> <li>Packages the <tt>.class</tt> files and deployment descriptor into the JAR file</li></ul> <a name="bnach"></a><h4>Application Assembler</h4> <a name="indexterm-65"></a>The application assembler is the company or person who receives application modules from component providers and assembles them into a Java EE application EAR file. The assembler or deployer can edit the deployment descriptor directly or can use tools that correctly add XML tags according to interactive selections. A software developer performs the following tasks to deliver an EAR file containing the Java EE application: <ul><li>Assembles EJB JAR and WAR files created in the previous phases into a Java EE application (EAR) file</li> <li>Specifies the deployment descriptor for the Java EE application</li> <li>Verifies that the contents of the EAR file are well formed and comply with the Java EE specification</li></ul> <a name="bnaci"></a><h4>Application Deployer and Administrator</h4> <a name="indexterm-66"></a>The application deployer and administrator is the company or person who configures and deploys the Java EE application, administers the computing and networking infrastructure where Java EE applications run, and oversees the runtime environment. Duties include such things as setting transaction controls and security attributes and specifying connections to databases.<a name="indexterm-67"></a>During configuration, the deployer follows instructions supplied by the application component provider to resolve external dependencies, specify security settings, and assign transaction attributes. During installation, the deployer moves the application components to the server and generates the container-specific classes and interfaces.A deployer or system administrator performs the following tasks to install and configure a Java EE application: <ul><li>Adds the Java EE application (EAR) file created in the preceding phase to the Java EE server</li> <li>Configures the Java EE application for the operational environment by modifying the deployment descriptor of the Java EE application</li> <li>Verifies that the contents of the EAR file are well formed and comply with the Java EE specification</li> <li>Deploys (installs) the Java EE application EAR file into the Java EE server</li></ul> January 20, 2008 Java EE 5 APIs <a name="indexterm-68"></a><a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnacj.html#bnack">Figure 1-7</a> illustrates the availability of the Java EE 5 platform APIs in each Java EE container type. The following sections give a brief summary of the technologies required by the Java EE platform, and the APIs used in Java EE applications. <a name="bnack"></a> <h6>Figure 1-7 Java EE Platform APIs</h6> <img src="http://java.sun.com/javaee/5/docs/tutorial/doc/figures/overview-j2eeArchitecture.gif" alt="Diagram of Java EE Platform APIs for the applet, web, EJB, and application client containers."> <a name="bnacl"></a> <h4>Enterprise JavaBeans Technology</h4> <a name="indexterm-69"></a>An Enterprise JavaBeansTM (EJB) component, or enterprise bean, is a body of code having fields and methods to implement modules of business logic. You can think of an enterprise bean as a building block that can be used alone or with other enterprise beans to execute business logic on the Java EE server. <a name="indexterm-70"></a><a name="indexterm-71"></a>There are two kinds of enterprise beans: session beans and message-driven beans. A session bean represents a transient conversation with a client. When the client finishes executing, the session bean and its data are gone. A message-driven bean combines features of a session bean and a message listener, allowing a business component to receive messages asynchronously. Commonly, these are Java Message Service (JMS) messages. In Java EE 5, entity beans have been replaced by Java persistence API entities. An entity represents persistent data stored in one row of a database table. If the client terminates, or if the server shuts down, the persistence manager ensures that the entity data is saved. <a name="bnacm"></a> <h4>Java Servlet Technology</h4> <a name="indexterm-72"></a><a name="indexterm-73"></a>Java servlet technology lets you define HTTP-specific servlet classes. A servlet class extends the capabilities of servers that host applications that are accessed by way of a request-response programming model. Although servlets can respond to any type of request, they are commonly used to extend the applications hosted by web servers. <a name="bnacn"></a> <h4>JavaServer Pages Technology</h4> <a name="indexterm-74"></a><a name="indexterm-75"></a>JavaServer PagesTM (JSP) technology lets you put snippets of servlet code directly into a text-based document. A JSP page is a text-based document that contains two types of text: static data (which can be expressed in any text-based format such as HTML, WML, and XML) and JSP elements, which determine how the page constructs dynamic content. <a name="bnaco"></a> <h4>JavaServer Pages Standard Tag Library</h4> <a name="indexterm-76"></a><a name="indexterm-77"></a>The JavaServer Pages Standard Tag Library (JSTL) encapsulates core functionality common to many JSP applications. Instead of mixing tags from numerous vendors in your JSP applications, you employ a single, standard set of tags. This standardization allows you to deploy your applications on any JSP container that supports JSTL and makes it more likely that the implementation of the tags is optimized. JSTL has iterator and conditional tags for handling flow control, tags for manipulating XML documents, internationalization tags, tags for accessing databases using SQL, and commonly used functions. <a name="bnacp"></a> <h4>JavaServer Faces</h4> <a name="indexterm-78"></a>JavaServer Faces technology is a user interface framework for building web applications. The main components of JavaServer Faces technology are as follows: <ul> <li> A GUI component framework. </li> <li> A flexible model for rendering components in different kinds of HTML or different markup languages and technologies. A <tt>Renderer</tt> object generates the markup to render the component and converts the data stored in a model object to types that can be represented in a view. </li> <li> A standard <tt>RenderKit</tt> for generating HTML/4.01 markup. </li> </ul> The following features support the GUI components: <ul> <li> Input validation </li> <li> Event handling </li> <li> Data conversion between model objects and components </li> <li> Managed model object creation </li> <li> Page navigation configuration </li> </ul> All this functionality is available using standard Java APIs and XML-based configuration files. <a name="bnacq"></a> <h4>Java Message Service API</h4> <a name="indexterm-79"></a>The Java Message Service (JMS) API is a messaging standard that allows Java EE application components to create, send, receive, and read messages. It enables distributed communication that is loosely coupled, reliable, and asynchronous. <a name="bnacr"></a> <h4>Java Transaction API</h4> <a name="indexterm-80"></a><a name="indexterm-81"></a>The Java Transaction API (JTA) provides a standard interface for demarcating transactions. The Java EE architecture provides a default auto commit to handle transaction commits and rollbacks. An auto commit means that any other applications that are viewing data will see the updated data after each database read or write operation. However, if your application performs two separate database access operations that depend on each other, you will want to use the JTA API to demarcate where the entire transaction, including both operations, begins, rolls back, and commits. <a name="bnacs"></a> <h4>JavaMail API</h4> <a name="indexterm-82"></a>Java EE applications use the JavaMailTM API to send email notifications. The JavaMail API has two parts: an application-level interface used by the application components to send mail, and a service provider interface. The Java EE platform includes JavaMail with a service provider that allows application components to send Internet mail. <a name="bnact"></a> <h4>JavaBeans Activation Framework</h4> <a name="indexterm-83"></a><a name="indexterm-84"></a>The JavaBeans Activation Framework (JAF) is included because JavaMail uses it. JAF provides standard services to determine the type of an arbitrary piece of data, encapsulate access to it, discover the operations available on it, and create the appropriate JavaBeans component to perform those operations. <a name="bnacu"></a> <h4>Java API for XML Processing</h4> <a name="indexterm-85"></a><a name="indexterm-86"></a>The Java API for XML Processing (JAXP), part of the Java SE platform, supports the processing of XML documents using Document Object Model (DOM), Simple API for XML (SAX), and Extensible Stylesheet Language Transformations (XSLT). JAXP enables applications to parse and transform XML documents independent of a particular XML processing implementation. JAXP also provides namespace support, which lets you work with schemas that might otherwise have naming conflicts. Designed to be flexible, JAXP lets you use any XML-compliant parser or XSL processor from within your application and supports the W3C schema. You can find information on the W3C schema at this URL: <a href="http://www.w3.org/XML/Schema">http://www.w3.org/XML/Schema</a>. <a name="bnacv"></a> <h4>Java API for XML Web Services (JAX-WS)</h4> <a name="indexterm-87"></a><a name="indexterm-88"></a>The JAX-WS specification provides support for web services that use the JAXB API for binding XML data to Java objects. The JAX-WS specification defines client APIs for accessing web services as well as techniques for implementing web service endpoints. The Web Services for J2EE specification describes the deployment of JAX-WS-based services and clients. The EJB and servlet specifications also describe aspects of such deployment. It must be possible to deploy JAX-WS-based applications using any of these deployment models. The JAX-WS specification describes the support for message handlers that can process message requests and responses. In general, these message handlers execute in the same container and with the same privileges and execution context as the JAX-WS client or endpoint component with which they are associated. These message handlers have access to the same JNDI <tt>java:comp/env</tt> namespace as their associated component. Custom serializers and deserializers, if supported, are treated in the same way as message handlers. <a name="bnacw"></a> <h4>Java Architecture for XML Binding (JAXB)</h4> <a name="indexterm-89"></a><a name="indexterm-90"></a>The Java Architecture for XML Binding (JAXB) provides a convenient way to bind an XML schema to a representation in Java language programs. JAXB can be used independently or in combination with JAX-WS, where it provides a standard data binding for web service messages. All Java EE application client containers, web containers, and EJB containers support the JAXB API. <a name="bnacx"></a> <h4>SOAP with Attachments API for Java</h4> <a name="indexterm-91"></a><a name="indexterm-92"></a>The SOAP with Attachments API for Java (SAAJ) is a low-level API on which JAX-WS and JAXR depend. SAAJ enables the production and consumption of messages that conform to the SOAP 1.1 specification and SOAP with Attachments note. Most developers do not use the SAAJ API, instead using the higher-level JAX-WS API. <a name="bnacy"></a> <h4>Java API for XML Registries</h4> <a name="indexterm-93"></a><a name="indexterm-94"></a><a name="indexterm-95"></a><a name="indexterm-96"></a>The Java API for XML Registries (JAXR) lets you access business and general-purpose registries over the web. JAXR supports the ebXML Registry and Repository standards and the emerging UDDI specifications. By using JAXR, developers can learn a single API and gain access to both of these important registry technologies. Additionally, businesses can submit material to be shared and search for material that others have submitted. Standards groups have developed schemas for particular kinds of XML documents; two businesses might, for example, agree to use the schema for their industry’s standard purchase order form. Because the schema is stored in a standard business registry, both parties can use JAXR to access it. <a name="bnacz"></a> <h4>J2EE Connector Architecture</h4> <a name="indexterm-97"></a><a name="indexterm-98"></a><a name="indexterm-99"></a>The J2EE Connector architecture is used by tools vendors and system integrators to create resource adapters that support access to enterprise information systems that can be plugged in to any Java EE product. A resource adapter is a software component that allows Java EE application components to access and interact with the underlying resource manager of the EIS. Because a resource adapter is specific to its resource manager, typically there is a different resource adapter for each type of database or enterprise information system. The J2EE Connector architecture also provides a performance-oriented, secure, scalable, and message-based transactional integration of Java EE-based web services with existing EISs that can be either synchronous or asynchronous. Existing applications and EISs integrated through the J2EE Connector architecture into the Java EE platform can be exposed as XML-based web services by using JAX-WS and Java EE component models. Thus JAX-WS and the J2EE Connector architecture are complementary technologies for enterprise application integration (EAI) and end-to-end business integration. <a name="bnada"></a> <h4>Java Database Connectivity API</h4> <a name="indexterm-100"></a><a name="indexterm-101"></a>The Java Database Connectivity (JDBC) API lets you invoke SQL commands from Java programming language methods. You use the JDBC API in an enterprise bean when you have a session bean access the database. You can also use the JDBC API from a servlet or a JSP page to access the database directly without going through an enterprise bean. The JDBC API has two parts: an application-level interface used by the application components to access a database, and a service provider interface to attach a JDBC driver to the Java EE platform. <a name="bnadb"></a> <h4>Java Persistence API</h4> The Java Persistence API is a Java standards-based solution for persistence. Persistence uses an object-relational mapping approach to bridge the gap between an object oriented model and a relational database. Java Persistence consists of three areas: <ul> <li> The Java Persistence API </li> <li> The query language </li> <li> Object/relational mapping metadata </li> </ul> <a name="bnadc"></a> <h4>Java Naming and Directory Interface</h4> <a name="indexterm-102"></a><a name="indexterm-103"></a><a name="indexterm-104"></a><a name="indexterm-105"></a><a name="indexterm-106"></a><a name="indexterm-107"></a><a name="indexterm-108"></a>The Java Naming and Directory InterfaceTM (JNDI) provides naming and directory functionality, enabling applications to access multiple naming and directory services, including existing naming and directory services such as LDAP, NDS, DNS, and NIS. It provides applications with methods for performing standard directory operations, such as associating attributes with objects and searching for objects using their attributes. Using JNDI, a Java EE application can store and retrieve any type of named Java object, allowing Java EE applications to coexist with many legacy applications and systems. <a name="indexterm-109"></a><a name="indexterm-110"></a>Java EE naming services provide application clients, enterprise beans, and web components with access to a JNDI naming environment. A naming environment allows a component to be customized without the need to access or change the component’s source code. A container implements the component’s environment and provides it to the component as a JNDI naming context. <a name="indexterm-111"></a><a name="indexterm-112"></a>A Java EE component can locate its environment naming context using JNDI interfaces. A component can create a <tt>javax.naming.InitialContext</tt> object and looks up the environment naming context in <tt>InitialContext</tt> under the name <tt>java:comp/env</tt>. A component’s naming environment is stored directly in the environment naming context or in any of its direct or indirect subcontexts. <a name="indexterm-113"></a><a name="indexterm-114"></a><a name="indexterm-115"></a>A Java EE component can access named system-provided and user-defined objects. The names of system-provided objects, such as JTA <tt>UserTransaction</tt> objects, are stored in the environment naming context, <tt>java:comp/en</tt>v. The Java EE platform allows a component to name user-defined objects, such as enterprise beans, environment entries, JDBC <tt>DataSource</tt> objects, and message connections. An object should be named within a subcontext of the naming environment according to the type of the object. For example, enterprise beans are named within the subcontext <tt>java:comp/env/ejb</tt>, and JDBC <tt>DataSource</tt> references in the subcontext <tt>java:comp/env/jdbc</tt>. <a name="bnadd"></a> <h4>Java Authentication and Authorization Service</h4> <a name="indexterm-116"></a><a name="indexterm-117"></a>The Java Authentication and Authorization Service (JAAS) provides a way for a Java EE application to authenticate and authorize a specific user or group of users to run it. JAAS is a Java programming language version of the standard Pluggable Authentication Module (PAM) framework, which extends the Java Platform security architecture to support user-based authorization. <a name="bnade"></a> <h4>Simplified Systems Integration</h4> The Java EE platform is a platform-independent, full systems integration solution that creates an open marketplace in which every vendor can sell to every customer. Such a marketplace encourages vendors to compete, not by trying to lock customers into their technologies but instead by trying to outdo each other in providing products and services that benefit customers, such as better performance, better tools, or better customer support. The Java EE 5 APIs enable systems and applications integration through the following: <ul> <li> Unified application model across tiers with enterprise beans </li> <li> Simplified request-and-response mechanism with JSP pages and servlets </li> <li> Reliable security model with JAAS </li> <li> XML-based data interchange integration with JAXP, SAAJ, and JAX-WS </li> <li> Simplified interoperability with the J2EE Connector architecture </li> <li> Easy database connectivity with the JDBC API </li> <li> Enterprise application integration with message-driven beans and JMS, JTA, and JNDI </li> </ul> January 20, 2008 Sun Java System Application Server Platform Edition 9 The Sun Java System Application Server Platform Edition 9 is a fully compliant implementation of the Java EE 5 platform. In addition to supporting all the APIs described in the previous sections, the Application Server includes a number of Java EE tools that are not part of the Java EE 5 platform but are provided as a convenience to the developer. This section briefly summarizes the tools that make up the Application Server. Instructions for starting and stopping the Application Server, starting the Admin Console, and starting and stopping the Java DB database server are in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/gfiud.html"> Chapter 2, Using the Tutorial Examples</a>. <a name="bnadg"></a> <h4>Tools</h4> <a name="indexterm-120"></a>The Application Server contains the tools listed in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnadf.html#bnadh"> Table 1-1</a>. Basic usage information for many of the tools appears throughout the tutorial. For detailed information, see the online help in the GUI tools. <a name="bnadh"></a> <h6>Table 1-1 Application Server Tools</h6> <table ID="Table1"> <col width="95*"> <col width="260*"> <tbody> <tr> <th align="left" valign="top"> Tool </th> <th align="left" valign="top"> Description </th> </tr> <tr> <td align="left" valign="top"><a name="indexterm-121"></a>Admin Console </td> <td align="left" valign="top">A web-based GUI Application Server administration utility. Used to stop the Application Server and manage users, resources, and applications. </td> </tr> <tr> <td align="left" valign="top"><a name="indexterm-122"></a><tt>asadmin</tt> </td> <td align="left" valign="top">A command-line Application Serveradministration utility. Used to start and stop the Application Server and manage users, resources, and applications. </td> </tr> <tr> <td align="left" valign="top"><a name="indexterm-123"></a><tt>asant</tt> </td> <td align="left" valign="top">A portable command-line build tool that is an extension of the Ant tool developed by the Apache Software Foundation (see <a href="http://ant.apache.org/"> http://ant.apache.org/</a>). <tt>asant</tt> contains additional tasks that interact with the Application Server administration utility. </td> </tr> <tr> <td align="left" valign="top"><a name="indexterm-124"></a><tt>appclient</tt> </td> <td align="left" valign="top">A command-line tool that launches the application client container and invokes the client application packaged in the application client JAR file. </td> </tr> <tr> <td align="left" valign="top"><a name="indexterm-125"></a><tt>capture-schema</tt> </td> <td align="left" valign="top">A command-line tool to extract schema information from a database, producing a schema file that the Application Server can use for container-managed persistence. </td> </tr> <tr> <td align="left" valign="top"><a name="indexterm-126"></a><tt>package-appclient</tt> </td> <td align="left" valign="top">A command-line tool to package the application client container libraries and JAR files. </td> </tr> <tr> <td align="left" valign="top"><a name="indexterm-127"></a>Java DB database </td> <td align="left" valign="top">A copy of the Java DB database server. </td> </tr> <tr> <td align="left" valign="top"><a name="indexterm-128"></a><tt>verifier</tt> </td> <td align="left" valign="top">A command-line tool to validate Java EE deployment descriptors. </td> </tr> <tr> <td align="left" valign="top"><a name="indexterm-129"></a><tt>xjc</tt> </td> <td align="left" valign="top">A command-line tool to transform, or bind, a source XML schema to a set of JAXB content classes in the Java programming language. </td> </tr> <tr> <td align="left" valign="top"><a name="indexterm-130"></a><tt>schemagen</tt> </td> <td align="left" valign="top">A command-line tool to create a schema file for each namespace referenced in your Java classes. </td> </tr> <tr> <td align="left" valign="top"><a name="indexterm-131"></a><tt>wsimport</tt> </td> <td align="left" valign="top">A command-line tool to generate JAX-WS portable artifacts for a given WSDL file. After generation, these artifacts can be packaged in a WAR file with the WSDL and schema documents along with the endpoint implementation and then deployed. </td> </tr> <tr> <td align="left" valign="top"><a name="indexterm-132"></a><tt>wsgen</tt> </td> <td align="left" valign="top">A command-line tool to read a web service endpoint class and generate all the required JAX-WS portable artifacts for web service deployment and invocation. </td> </tr> </tbody> </table> January 20, 2008 Getting Started with Web Applications A web application is a dynamic extension of a web or application server. There are two types of web applications: <ul><li><a name="indexterm-163"></a>Presentation-oriented: A presentation-oriented web application generates interactive web pages containing various types of markup language (HTML, XML, and so on) and dynamic content in response to requests. Chapters <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnafd.html">Chapter 4, Java Servlet Technology</a> through <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnaxu.html">Chapter 15, Internationalizing and Localizing Web Applications</a> cover how to develop presentation-oriented web applications.</li> <li><a name="indexterm-164"></a>Service-oriented: A service-oriented web application implements the endpoint of a web service. Presentation-oriented applications are often clients of service-oriented web applications. Chapters <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnayl.html">Chapter 16, Building Web Services with JAX-WS</a> and <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnbhf.html">Chapter 19, SOAP with Attachments API for Java</a> cover how to develop service-oriented web applications.</li></ul> January 20, 2008 Web Applications In the Java 2 platform, web components provide the dynamic extension capabilities for a web server. Web components are either Java servlets, JSP pages, or web service endpoints. The interaction between a web client and a web application is illustrated in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/geysj.html#bnads">Figure 3-1</a>. The client sends an HTTP request to the web server. A web server that implements Java Servlet and JavaServer Pages technology converts the request into an <tt>HTTPServletRequest</tt> object. This object is delivered to a web component, which can interact with JavaBeans components or a database to generate dynamic content. The web component can then generate an <tt>HTTPServletResponse</tt> or it can pass the request to another web component. Eventually a web component generates a <tt>HTTPServletResponse</tt> object. The web server converts this object to an HTTP response and returns it to the client.<a name="bnads"></a><h6>Figure 3-1 Java Web Application Request Handling</h6><img src="http://java.sun.com/javaee/5/docs/tutorial/doc/figures/web-requestHandling.gif" alt="Diagram of web application request handling. Clients and web components communicate using HttpServletRequest and HttpServletResponse.">Servlets are Java programming language classes that dynamically process requests and construct responses. JSP pages are text-based documents that execute as servlets but allow a more natural approach to creating static content. Although servlets and JSP pages can be used interchangeably, each has its own strengths. Servlets are best suited for service-oriented applications (web service endpoints are implemented as servlets) and the control functions of a presentation-oriented application, such as dispatching requests and handling nontextual data. JSP pages are more appropriate for generating text-based markup such as HTML, Scalable Vector Graphics (SVG), Wireless Markup Language (WML), and XML.Since the introduction of Java Servlet and JSP technology, additional Java technologies and frameworks for building interactive web applications have been developed. <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/geysj.html#bnadt">Figure 3-2</a> illustrates these technologies and their relationships.<a name="bnadt"></a><h6>Figure 3-2 Java Web Application Technologies</h6><img src="http://java.sun.com/javaee/5/docs/tutorial/doc/figures/web-technologies.gif" alt="Diagram of web application technologies. JavaServer Pages, the JSP Standard Tag Library, and JavaServer Faces rest on JavaServlet technology.">Notice that Java Servlet technology is the foundation of all the web application technologies, so you should familiarize yourself with the material in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnafd.html">Chapter 4, Java Servlet Technology</a> even if you do not intend to write servlets. Each technology adds a level of abstraction that makes web application prototyping and development faster and the web applications themselves more maintainable, scalable, and robust.Web components are supported by the services of a runtime platform called a web container. A web container provides services such as request dispatching, security, concurrency, and life-cycle management. It also gives web components access to APIs such as naming, transactions, and email.<a name="indexterm-167"></a><a name="indexterm-168"></a>Certain aspects of web application behavior can be configured when the application is installed, or deployed, to the web container. The configuration information is maintained in a text file in XML format called a web application deployment descriptor (DD). A DD must conform to the schema described in the <a href="http://java.sun.com/products/servlet/download.html#specs">Java Servlet Specification</a>.This chapter gives a brief overview of the activities involved in developing web applications. First it summarizes the web application life cycle. Then it describes how to package and deploy very simple web applications on the Application Server. It moves on to configuring web applications and discusses how to specify the most commonly used configuration parameters. It then introduces an example, Duke’s Bookstore, which illustrates all the Java EE web-tier technologies, and describes how to set up the shared components of this example. Finally it discusses how to access databases from web applications and set up the database resources needed to run Duke’s Bookstore. January 20, 2008 Web Application Life Cycle A web application consists of web components, static resource files such as images, and helper classes and libraries. The web container provides many supporting services that enhance the capabilities of web components and make them easier to develop. However, because a web application must take these services into account, the process for creating and running a web application is different from that of traditional stand-alone Java classes. The process for creating, deploying, and executing a web application can be summarized as follows: 1. Develop the web component code. 2. Develop the web application deployment descriptor. 3. Compile the web application components and helper classes referenced by the components. 4. Optionally package the application into a deployable unit. 5. Deploy the application into a web container. 6. Access a URL that references the web application. Developing web component code is covered in the later chapters. Steps 2 through 4 are expanded on in the following sections and illustrated with a Hello, World-style presentation-oriented application. This application allows a user to enter a name into an HTML form (Figure 3-3) and then displays a greeting after the name is submitted (Figure 3-4). Figure 3-3 Greeting Form Screen capture of Duke‘s greeting, Figure 3-4 Response Screen capture of Duke‘s response, The Hello application contains two web components that generate the greeting and the response. This chapter discusses two versions of the application: a JSP version called hello1, in which the components are implemented by two JSP pages (tut-install/javaeetutorial5/examples/web/hello1/web/index.jsp and tut-install/javaeetutorial5/examples/web/hello1/web/response.jsp) and a servlet version called hello2, in which the components are implemented by two servlet classes (tut-install/javaeetutorial5/examples/web/hello2/src/servlets/GreetingServlet.java and tut-install/javaeetutorial5/examples/web/hello2/src/servlets/ResponseServlet.java). The two versions are used to illustrate tasks involved in packaging, deploying, configuring, and running an application that contains web components. The section Chapter 2, Using the Tutorial Examples explains how to get the code for these examples. After you install the tutorial bundle, the source code for the examples is in the following directories: * tut-install/javaeetutorial5/examples/web/hello1/ * tut-install/javaeetutorial5/examples/web/hello2/ January 20, 2008 Web Modules In the Java EE architecture, web components and static web content files such as images are called web resources. A web module is the smallest deployable and usable unit of web resources. A Java EE web module corresponds to a web application as defined in the Java Servlet specification.In addition to web components and web resources, a web module can contain other files: <ul><li><a name="indexterm-176"></a><a name="indexterm-177"></a>Server-side utility classes (database beans, shopping carts, and so on). Often these classes conform to the JavaBeans component architecture.</li> <li>Client-side classes (applets and utility classes).</li></ul> A web module has a specific structure. The top-level directory of a web module is the document root of the application. The document root is where JSP pages, client-side classes and archives, and static web resources, such as images, are stored.The document root contains a subdirectory named <tt>WEB-INF</tt>, which contains the following files and directories: <ul><li><a name="indexterm-178"></a><tt>web.xml</tt>: The web application deployment descriptor</li> <li>Tag library descriptor files (see <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnamu.html">Tag Library Descriptors</a>)</li> <li><tt>classes</tt>: A directory that contains server-side classes: servlets, utility classes, and JavaBeans components</li> <li><tt>tags</tt>: A directory that contains tag files, which are implementations of tag libraries (see <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnama.html#bnamb">Tag File Location</a>)</li> <li><tt>lib</tt>: A directory that contains JAR archives of libraries called by server-side classes</li></ul> If your web module does not contain any servlets, filter, or listener components then it does not need a web application deployment descriptor. In other words, if your web module only contains JSP pages and static files then you are not required to include a <tt>web.xml</tt> file. The <tt>hello1</tt> example, first discussed in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnadx.html#bnadz">Packaging Web Modules</a>, contains only JSP pages and images and therefore does not include a deployment descriptor.You can also create application-specific subdirectories (that is, package directories) in either the document root or the <tt>WEB-INF/classes/</tt> directory.A web module can be deployed as an unpacked file structure or can be packaged in a JAR file known as a web archive (WAR) file. Because the contents and use of WAR files differ from those of JAR files, WAR file names use a <tt>.war</tt> extension. The web module just described is portable; you can deploy it into any web container that conforms to the Java Servlet Specification.<a name="indexterm-179"></a>To deploy a WAR on the Application Server, the file must also contain a runtime deployment descriptor. The runtime deployment descriptor is an XML file that contains information such as the context root of the web application and the mapping of the portable names of an application’s resources to the Application Server’s resources. The Application Server web application runtime DD is named <tt>sun-web.xml</tt> and is located in the <tt>WEB-INF</tt> directory along with the web application DD. The structure of a web module that can be deployed on the Application Server is shown in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnadx.html#bnady">Figure 3-5</a>.<a name="bnady"></a><h6>Figure 3-5 Web Module Structure</h6><img src="http://java.sun.com/javaee/5/docs/tutorial/doc/figures/web-module.gif" alt="Diagram of web module structure. WEB-INF and web pages are under the root. Under WEB-INF are descriptors and the lib, classes, and tags directories."> <a name="bnadz"></a><h4>Packaging Web Modules</h4> A web module must be packaged into a WAR in certain deployment scenarios and whenever you want to distribute the web module. You package a web module into a WAR by executing the <tt>jar</tt> command in a directory laid out in the format of a web module, by using the Ant utility, or by using the IDE tool of your choice. This tutorial shows you how to use NetBeans IDE or Ant to build, package, and deploy the sample applications.To build the <tt>hello1</tt> application with NetBeans IDE, follow these instructions: <ol><li>Select File→Open Project.</li> <li>In the Open Project dialog, navigate to:<pre>tut-install/javaeetutorial5/examples/web/</pre></li> <li>Select the <tt>hello1</tt> folder.</li> <li>Select the Open as Main Project check box.</li> <li>Click Open Project Folder.</li> <li>In the Projects tab, right-click the <tt>hello1</tt> project and select Build Project.</li></ol> To build the <tt>hello1</tt> application using the Ant utility, follow these steps: <ol><li>In a terminal window, go to <tt></tt>tut-install<tt>/javaeetutorial5/examples/web/hello1/</tt>.</li> <li>Type <tt>ant</tt>. This command will spawn any necessary compilations, copy files to the <tt></tt>tut-install<tt>/javaeetutorial5/examples/web/hello1/build/</tt> directory, create the WAR file, and copy it to the <tt></tt>tut-install<tt>/javaeetutorial5/examples/web/hello1/dist/</tt> directory.</li></ol> <a name="bnaea"></a><h4>Deploying a WAR File</h4> <a name="indexterm-180"></a>You can deploy a WAR file to the Application Server in a few ways: <ul><li>Copying the WAR into the <tt></tt>domain-dir<tt>/autodeploy/</tt> directory.</li> <li>Using the Admin Console.</li> <li>By running <tt>asadmin</tt> or <tt>ant</tt> to deploy the WAR.</li> <li>Using NetBeans IDE.</li></ul> All these methods are described briefly in this chapter; however, throughout the tutorial, you will use <tt>ant</tt> and NetBeans IDE for packaging and deploying. <a name="bnaeb"></a><h5>Setting the Context Root</h5> <a name="indexterm-181"></a>A context root identifies a web application in a Java EE server. You specify the context root when you deploy a web module. A context root must start with a forward slash (<tt>/</tt>) and end with a string.In a packaged web module for deployment on the Application Server, the context root is stored in <tt>sun-web.xml</tt>.To edit the context root, do the following: <ol><li>Expand your project tree in the Projects pane of NetBeans IDE.</li> <li>Expand the Web Pages and WEB-INF nodes of your project.</li> <li>Double-click <tt>sun-web.xml</tt>.</li> <li>In the editor pane, click Edit As XML.</li> <li>Edit the context root, which is enclosed by the <tt>context-root</tt> element.</li></ol> <a name="bnaec"></a><h5>Deploying a Packaged Web Module</h5> <a name="indexterm-182"></a>If you have deployed the <tt>hello1</tt> application, before proceeding with this section, undeploy the application by following one of the procedures described in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnadx.html#bnaen">Undeploying Web Modules</a>. <a name="bnaed"></a><h5>Deploying with the Admin Console</h5> <ol><li>Expand the Applications node.</li> <li>Select the Web Applications node.</li> <li>Click the Deploy button.</li> <li>Select the radio button labeled “Package file to be uploaded to the Application Server.”</li> <li>Type the full path to the WAR file (or click on Browse to find it), and then click the OK button.</li> <li>Click Next.</li> <li>Type the application name.</li> <li>Type the context root.</li> <li>Select the Enabled box.</li> <li>Click the Finish button.</li></ol> <a name="bnaee"></a><h5>Deploying with <tt>asadmin</tt></h5> <a name="indexterm-183"></a>To deploy a WAR with <tt>asadmin</tt>, open a terminal window or command prompt and execute<pre><tt>asadmin deploy </tt>full-path-to-war-file<tt></tt></pre> <a name="bnaef"></a><h5>Deploying with Ant</h5> To deploy a WAR with the Ant tool, open a terminal window or command prompt in the directory where you built and packaged the WAR, and execute<pre><tt>ant deploy</tt></pre> <a name="bnaeg"></a><h5>Deploying with NetBeans IDE</h5> To deploy a WAR with NetBeans IDE, do the following: <ol><li>Select File→Open Project.</li> <li>In the Open Project dialog, navigate to your project and open it.</li> <li>In the Projects tab, right-click the project and select Deploy Project.</li></ol> <a name="bnaeh"></a><h4>Testing Deployed Web Modules</h4> Now that the web module is deployed, you can view it by opening the application in a web browser. By default, the application is deployed to host <tt>localhost</tt> on port 8080. The context root of the web application is <tt>hello1</tt>.To test the application, follow these steps: <ol><li>Open a web browser.</li> <li>Enter the following URL in the web address box:<pre>http://localhost:8080/hello1</pre></li> <li>Enter your name, and click Submit.</li></ol> The application should display the name you submitted as shown in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnadu.html#bnadv">Figure 3-3</a> and <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnadu.html#bnadw">Figure 3-4</a>. <a name="bnaei"></a><h4>Listing Deployed Web Modules</h4> <a name="indexterm-184"></a>The Application Server provides two ways to view the deployed web modules: the Admin Console and the <tt>asadmin</tt> command.To use the Admin Console: <ol><li>Open the URL <tt>http://localhost:4848/asadmin</tt> in a browser.</li> <li>Expand the nodes Applications→Web Applications.</li></ol> Use the <tt>asadmin</tt> command as follows:<pre><tt>asadmin list-components</tt></pre> <a name="bnaej"></a><h4>Updating Web Modules</h4> <a name="indexterm-185"></a><a name="indexterm-186"></a>A typical iterative development cycle involves deploying a web module and then making changes to the application components. To update a deployed web module, you must do the following: <ol><li>Recompile any modified classes.</li> <li>If you have deployed a packaged web module, update any modified components in the WAR.</li> <li>Redeploy the module.</li> <li>Reload the URL in the client.</li></ol> <a name="bnaek"></a><h5>Updating a Packaged Web Module</h5> <a name="indexterm-187"></a>This section describes how to update the <tt>hello1</tt> web module that you packaged.First, change the greeting in the file <tt></tt>tut-install<tt>/javaeetutorial5/examples/web/hello1/web/index.jsp</tt> to<pre><h2>Hi, my name is Duke. What’s yours?</h2></pre>To update the project in NetBeans IDE: <ul><li>Right-click on the project and select Build Project.</li> <li>Right-click on the project and select Deploy Project.</li></ul> To update the project using the Ant build tool: <ul><li>Type <tt>ant</tt> to copy the modified JSP page into the <tt>build</tt> directory.</li> <li>Type <tt>ant deploy</tt> to deploy the WAR file.</li></ul> To view the modified module, reload the URL in the browser.You should see the screen in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnadx.html#bnael">Figure 3-6</a> in the browser.<a name="bnael"></a><h6>Figure 3-6 New Greeting</h6><img src="http://java.sun.com/javaee/5/docs/tutorial/doc/figures/web-newGreeting.gif" alt="Screen capture of Duke‘s new greeting, " hi,="" my="" is="" duke.="" what="" s="" yours?="" includes="" a="" text="" field="" for="" your="" name="" submit="" and="" reset="" buttons.="" height="350" width="662"> <a name="bnaem"></a><h5>Dynamic Reloading</h5> <a name="indexterm-188"></a>If dynamic reloading is enabled, you do not have to redeploy an application or module when you change its code or deployment descriptors. All you have to do is copy the changed JSP or class files into the deployment directory for the application or module. The deployment directory for a web module named context-root is <tt></tt>domain-dir<tt>/applications/j2ee-modules/</tt>context-root<tt></tt>. The server checks for changes periodically and redeploys the application, automatically and dynamically, with the changes.This capability is useful in a development environment, because it allows code changes to be tested quickly. Dynamic reloading is not recommended for a production environment, however, because it may degrade performance. In addition, whenever a reload is done, the sessions at that time become invalid and the client must restart the session.To enable dynamic reloading, use the Admin Console: <ol><li>Select the Applications Server node.</li> <li>Select the Advanced tab.</li> <li>Check the Reload Enabled box to enable dynamic reloading.</li> <li>Enter a number of seconds in the Reload Poll Interval field to set the interval at which applications and modules are checked for code changes and dynamically reloaded.</li> <li>Click the Save button.</li></ol> In addition, to load new servlet files or reload deployment descriptor changes, you must do the following: <ol><li>Create an empty file named <tt>.reload</tt> at the root of the module:<pre>domain-dir/applications/j2ee-modules/context-root/.reload</pre></li> <li>Explicitly update the <tt>.reload</tt> file’s time stamp each time you make these changes. On UNIX, execute<pre><tt>touch .reload</tt></pre></li></ol> For JSP pages, changes are reloaded automatically at a frequency set in the Reload Poll Interval field. To disable dynamic reloading of JSP pages, set the Reload Poll Interval field value to –1.<a name="indexterm-189"></a> <a name="bnaen"></a><h4>Undeploying Web Modules</h4> <a name="indexterm-190"></a>You can undeploy web modules in four ways: you can use NetBeans IDE, the Admin Console, the <tt>asadmin</tt> command, or the Ant tool.To use NetBeans IDE: <ol><li>Ensure the Sun Java System Application Server is running.</li> <li>In the Runtime window, expand the Sun Java System Application Server instance and the node containing the application or module.</li> <li>Right-click the application or module and choose Undeploy.</li></ol> To use the Admin Console: <ol><li>Open the URL <tt>http://localhost:4848/asadmin</tt> in a browser.</li> <li>Expand the Applications node.</li> <li>Select Web Applications.</li> <li>Click the check box next to the module you wish to undeploy.</li> <li>Click the Undeploy button.</li></ol> Use the <tt>asadmin</tt> command as follows:<pre><tt>asadmin undeploy </tt>context-root<tt></tt></pre>To use the Ant tool, execute the following command in the directory where you built and packaged the WAR:<pre><tt>ant undeploy</tt></pre> January 20, 2008 Configuring Web Applications Web applications are configured by means of elements contained in the web application deployment descriptor. The following sections give a brief introduction to the web application features you will usually want to configure. A number of security parameters can be specified; these are covered in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bncas.html"> Chapter 30, Securing Web Applications</a>. In the following sections, examples demonstrate procedures for configuring the Hello, World application. If Hello, World does not use a specific configuration feature, the section gives references to other examples that illustrate how to specify the deployment descriptor element. <a name="bnaep"></a> <h4>Mapping URLs to Web Components</h4> <a name="indexterm-192"></a>When a request is received by the web container it must determine which web component should handle the request. It does so by mapping the URL path contained in the request to a web application and a web component. A URL path contains the context root and an alias: <pre>http://host:port/context-root/alias</pre> <a name="bnaeq"></a> <h5>Setting the Component Alias</h5> <a name="indexterm-193"></a>The alias identifies the web component that should handle a request. The alias path must start with a forward slash (<tt>/</tt>) and end with a string or a wildcard expression with an extension (for example, <tt>*.jsp</tt>). Since web containers automatically map an alias that ends with <tt>*.jsp</tt>, you do not have to specify an alias for a JSP page unless you wish to refer to the page by a name other than its file name. The <tt>hello2</tt> application has two servlets that need to be mapped in the <tt>web.xml</tt> file. You can edit a web applicationfs <tt>web.xml</tt> file in NetBeans IDE by doing the following: <ol> <li> Select File¨Open Project. </li> <li> In the Open Project dialog, navigate to: <pre>tut-install/javaeetutorial5/examples/web/</pre> </li> <li> Select the <tt>hello2</tt> folder. </li> <li> Select the Open as Main Project check box. </li> <li> Click Open Project Folder. </li> <li> Expand the project tree in the Projects pane. </li> <li> Expand the Web pages node and then the WEB-INF node in the project tree. </li> <li> Double-click the <tt>web.xml</tt> file inside the WEB-INF node. </li> </ol> The following steps describe how to make the necessary edits to the <tt>web.xml</tt> file, including how to set the display name and how to map the servlet components. Because the edits are already in the file, you can just use the steps to view the settings. To set the display name: <ol> <li> Click General at the top of the editor to open the general view. </li> <li> Enter <tt>hello2</tt> in the Display Name field. </li> </ol> To perform the servlet mappings: <ol> <li> Click Servlets at the top of the editor to open the servlets view. </li> <li> Click Add Servlet. </li> <li> In the Add Servlet dialog, enter <tt>GreetingServlet</tt> in the Servlet Name field. </li> <li> Enter <tt>servlets.GreetingServlet</tt> in the Servlet Class field. </li> <li> Enter <tt>/greeting</tt> in the URL Pattern field. </li> <li> Click OK. </li> <li> Repeat the preceding steps, except enter <tt>ResponseServlet</tt> as the servlet name, <tt>servlets.ResponseServlet</tt> as the servlet class, and <tt>/response</tt> as the URL pattern. </li> </ol> If you are not using NetBeans IDE, you can add these settings using a text editor. To package the example with NetBeans IDE, do the following: <ol> <li> Select File¨Open Project. </li> <li> In the Open Project dialog, navigate to: <pre>tut-install/javaeetutorial5/examples/web/</pre> </li> <li> Select the <tt>hello2</tt> folder. </li> <li> Select the Open as Main Project check box. </li> <li> Click Open Project Folder. </li> <li> In the Projects tab, right-click the <tt>hello2</tt> project and select Build Project. </li> </ol> To package the example with the Ant utility, do the following: <ol> <li> In a terminal window, go to <tt></tt>tut-install<tt>/javaeetutorial5/examples/web/hello2/</tt>. </li> <li> Type <tt>ant</tt>. This target will build the WAR file and copy it to the <tt> </tt>tut-install<tt>/javaeetutorial5/examples/web/hello2/dist/</tt> directory. </li> </ol> To deploy the example using NetBeans IDE, right-click on the project in the Projects pane and select Deploy Project. To deploy the example using Ant, type <tt>ant deploy</tt>. The deploy target in this case gives you an incorrect URL to run the application. To run the application, please use the URL shown at the end of this section. To run the application, first deploy the web module, and then open the URL <tt>http://localhost:8080/hello2/greeting</tt> in a browser. <a name="bnaer"></a> <h4>Declaring Welcome Files</h4> <a name="indexterm-194"></a>The welcome files mechanism allows you to specify a list of files that the web container will use for appending to a request for a URL (called a valid partial request) that is not mapped to a web component. For example, suppose you define a welcome file <tt>welcome.html</tt>. When a client requests a URL such as <tt>host:port/webapp/directory</tt>, where directory is not mapped to a servlet or JSP page, the file <tt></tt> host<tt>:</tt>port<tt>/</tt>webapp<tt>/</tt>directory<tt>/welcome.html</tt> is returned to the client. If a web container receives a valid partial request, the web container examines the welcome file list and appends to the partial request each welcome file in the order specified and checks whether a static resource or servlet in the WAR is mapped to that request URL. The web container then sends the request to the first resource in the WAR that matches. If no welcome file is specified, the Application Server will use a file named <tt>index.</tt>XXX<tt></tt>, where XXX can be <tt>html</tt> or <tt>jsp</tt>, as the default welcome file. If there is no welcome file and no file named <tt>index.</tt>XXX<tt></tt>, the Application Server returns a directory listing. To specify a welcome file in the web application deployment descriptor using NetBeans IDE, do the following: <ol> <li> Open the project if you havenft already. </li> <li> Expand the projectfs node in the Projects pane. </li> <li> Expand the Web Pages node and then the WEB-INF node. </li> <li> Double-click <tt>web.xml</tt>. </li> <li> Do one of the following, making sure that the JSP pages you specify are actually included in the WAR file: <ol> <li> Click Pages at the top of the editor pane and enter the names of the JSP pages that act as welcome files in the Welcome Files field. </li> <li> Click XML at the top of the editor pane, specify the JSP pages using <tt>welcome-file</tt> elements and include these elements inside a <tt>welcome-file-list</tt> element. The <tt>welcome-file</tt> element defines the JSP page to be used as the welcome page. The example discussed in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnama.html"> Encapsulating Reusable Content Using Tag Files</a> has a welcome file. </li> </ol> </li></ol> <a name="bnaes"></a> <h4>Setting Initialization Parameters</h4> <a name="indexterm-195"></a> The web components in a web module share an object that represents their application context (see <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnagl.html"> Accessing the Web Context</a>). You can pass initialization parameters to the context or to a web component. To add a context parameter using NetBeans IDE, do the following: <ol> <li> Open the project if you havenft already. </li> <li> Expand the projectfs node in the Projects pane. </li> <li> Expand the Web Pages node and then the WEB-INF node. </li> <li> Double-click <tt>web.xml</tt>. </li> <li> Click General at the top of the editor pane. </li> <li> Select the Context Parameters node. </li> <li> Click Add. </li> <li> In the Add Context Parameter dialog, do the following: <ol> <li> Enter the name that specifies the context object in the Param Name field. </li> <li> Enter the parameter to pass to the context object in the Param Value field. </li> <li> Click OK. </li> </ol> </li></ol> Alternatively, you can edit the XML of the <tt>web.xml</tt> file directly by clicking XML at the top of the editor pane and using the following elements to add a context parameter: <ul> <li> A <tt>param-name</tt> element that specifies the context object </li> <li> A <tt>param-value</tt> element that specifies the parameter to pass to the context object </li> <li> A <tt>context-param</tt> element that encloses the previous two elements </li> </ul> For a sample context parameter, see the example discussed in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnahb.html"> The Example JSP Pages</a>. <a name="indexterm-196"></a>To add a web component initialization parameter using NetBeans IDE, do the following: <ol> <li> Open the project if you havenft already. </li> <li> Expand the projectfs node in the Projects pane. </li> <li> Expand the Web Pages node and then the WEB-INF node. </li> <li> Double-click <tt>web.xml</tt>. </li> <li> Click Servlets at the top of the editor pane. </li> <li> After entering the servletfs name, class, and URL pattern, click the Add button under the Initialization Parameters table. </li> <li> In the Add Initialization Parameter dialog: <ol> <li> Enter the name of the parameter in the Param Name field. </li> <li> Enter the parameterfs value in the Param Value Field. </li> <li> Click OK. </li> </ol> </li></ol> Alternatively, you can edit the XML of the <tt>web.xml</tt> file directly by clicking XML at the top of the editor pane and using the following elements to add a context parameter: <ul> <li> A <tt>param-name</tt> element that specifies the name of the initialization parameter </li> <li> A <tt>param-value</tt> element that specifies the value of the initialization parameter </li> <li> An <tt>init-param</tt> element that encloses the previous two elements </li> </ul> <a name="bnaet"></a> <h4>Mapping Errors to Error Screens</h4> <a name="indexterm-197"></a><a name="indexterm-198"></a><a name="indexterm-199"></a><a name="indexterm-200"></a>When an error occurs during execution of a web application, you can have the application display a specific error screen according to the type of error. In particular, you can specify a mapping between the status code returned in an HTTP response or a Java programming language exception returned by any web component (see <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnafi.html#bnafn"> Handling Servlet Errors</a>) and any type of error screen. To set up error mappings using NetBeans IDE, do the following: <ol> <li> Open the project if you havenft already. </li> <li> Expand the projectfs node in the Projects pane. </li> <li> Expand the Web Pages node and then the WEB-INF node. </li> <li> Double-click <tt>web.xml</tt>. </li> <li> Click Pages at the top of the editor pane. </li> <li> Expand the Error Pages node. </li> <li> Click Add. </li> <li> In the Add Error Page dialog: <ol> <li> Click Browse to locate the page that you want to act as the error page. </li> <li> Enter the HTTP status code that will cause the error page to be opened in the Error Code field. </li> <li> Enter the exception that will cause the error page to load in the Exception Type field. </li> <li> Click OK. </li> </ol> </li></ol> Alternatively, you can click XML at the top of the editor pane and enter the error page mapping by hand using the following elements: <ul> <li> An <tt>exception-type</tt> element specifying either the exception or the HTTP status code that will cause the error page to be opened. </li> <li> A <tt>location</tt> element that specifies the name of a web resource to be invoked when the status code or exception is returned. The name should have a leading forward slash (<tt>/</tt>). </li> <li> An <tt>error-page</tt> element that encloses the previous two elements. </li> </ul> You can have multiple <tt>error-page</tt> elements in your deployment descriptor. Each one of the elements identifies a different error that causes an error page to open. This error page can be the same for any number of <tt>error-page</tt> elements. <hr> Note - You can also define error screens for a JSP page contained in a WAR. If error screens are defined for both the WAR and a JSP page, the JSP pagefs error page takes precedence. See <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnahe.html#bnahi"> Handling JSP Page Errors</a>. <hr> For a sample error page mapping, see the example discussed in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnaff.html"> The Example Servlets</a>. <a name="bnaeu"></a> <h4>Declaring Resource References</h4> If your web component uses objects such as enterprise beans, data sources, or web services, you use Java EE annotations to inject these resources into your application. Annotations eliminate a lot of the boilerplate lookup code and configuration elements that previous versions of Java EE required. Although resource injection using annotations can be more convenient for the developer, there are some restrictions from using it in web applications. First, you can only inject resources into container-managed objects. This is because a container must have control over the creation of a component so that it can perform the injection into a component. As a result, you cannot inject resources into objects such as simple JavaBeans components. However, JavaServer Faces managed beans are managed by the container; therefore, they can accept resource injections. Additionally, JSP pages cannot accept resource injections. This is because the information represented by annotations must be available at deployment time, but the JSP page is compiled after that; therefore, the annotation will not be seen when it is needed. Those components that can accept resource injections are listed in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnaeo.html#bnaev"> Table 3-1</a>. This section describes how to use a couple of the annotations supported by a servlet container to inject resources. <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnbrl.html"> Chapter 25, Persistence in the Web Tier</a> describes how web applications use annotations supported by the Java Persistence API. <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bncas.html"> Chapter 30, Securing Web Applications</a> describes how to use annotations to specify information about securing web applications. <a name="bnaev"></a> <h6>Table 3-1 Web Components That Accept Resource Injections</h6> <table ID="Table1"> <col width="75*"> <col width="253*"> <tbody> <tr> <th align="left" valign="top"> Component </th> <th align="left" valign="top"> Interface/Class </th> </tr> <tr> <td align="left" valign="top">Servlets </td> <td align="left" valign="top"><tt>javax.servlet.Servlet</tt> </td> </tr> <tr> <td align="left" valign="top">Servlet Filters </td> <td align="left" valign="top"><tt>javax.servlet.ServletFilter</tt> </td> </tr> <tr> <td align="left" valign="top">Event Listeners </td> <td align="left" valign="top"><tt>javax.servlet.ServletContextListener</tt> <tt>javax.servlet.ServletContextAttributeListener</tt> <tt>javax.servlet.ServletRequestListener</tt> <tt>javax.servlet.ServletRequestAttributeListener</tt> <tt>javax.servlet.http.HttpSessionListener</tt> <tt>javax.servlet.http.HttpSessionAttributeListener</tt> </td> </tr> <tr> <td align="left" valign="top">Taglib Listeners </td> <td align="left" valign="top">Same as above </td> </tr> <tr> <td align="left" valign="top">Taglib Tag Handlers </td> <td align="left" valign="top"><tt>javax.servlet.jsp.tagext.JspTag</tt> </td> </tr> <tr> <td align="left" valign="top">Managed Beans </td> <td align="left" valign="top">Plain Old Java Objects </td> </tr> </tbody> </table> <a name="bnaew"></a> <h5>Declaring a Reference to a Resource</h5> The <tt>@Resource</tt> annotation is used to declare a reference to a resource such as a data source, an enterprise bean, or an environment entry. This annotation is equivalent to declaring a <tt>resource-ref</tt> element in the deployment descriptor. The <tt>@Resource</tt> annotation is specified on a class, method or field. The container is responsible for injecting references to resources declared by the <tt>@Resource</tt> annotation and mapping it to the proper JNDI resources. In the following example, the <tt>@Resource</tt> annotation is used to inject a data source into a component that needs to make a connection to the data source, as is done when using JDBC technology to access a relational database: <pre>@Resource javax.sql.DataSource catalogDS; public getProductsByCategory() { // get a connection and execute the query Connection conn = catalogDS.getConnection(); .. }</pre> The container injects this data source prior to the component being made available to the application. The data source JNDI mapping is inferred from the field name <tt>catalogDS</tt> and the type, <tt>javax.sql.DataSource</tt>. If you have multiple resources that you need to inject into one component, you need to use the <tt>@Resources</tt> annotation to contain them, as shown by the following example: <pre>@Resources ({ @Resource (name="myDB" type=java.sql.DataSource), @Resource(name="myMQ" type=javax.jms.ConnectionFactory) })</pre> The web application examples in this tutorial use the Java Persistence API to access relational databases. This API does not require you to explicitly create a connection to a data source. Therefore, the examples do not use the <tt>@Resource</tt> annotation to inject a data source. However, this API supports the <tt>@PersistenceUnit</tt> and <tt>@PersistenceContext</tt> annotations for injecting <tt>EntityManagerFactory</tt> and <tt>EntityManager</tt> instances, respectively. <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnbrl.html"> Chapter 25, Persistence in the Web Tier</a> describes these annotations and the use of the Java Persistence API in web applications. <a name="bnaex"></a> <h5>Declaring a Reference to a Web Service</h5> The <tt>@WebServiceRef</tt> annotation provides a reference to a web service. The following example shows uses the <tt>@WebServiceRef</tt> annotation to declare a reference to a web service. <tt>WebServiceRef</tt> uses the <tt>wsdlLocation</tt> element to specify the URI of the deployed servicefs WSDL file: <pre>... import javax.xml.ws.WebServiceRef; ... public class ResponseServlet extends HTTPServlet { @WebServiceRef(wsdlLocation= "http://localhost:8080/helloservice/hello?wsdl") static HelloService service;</pre> January 20, 2008 Accessing Databases from Web Applications Data that is shared between web components and is persistent between invocations of a web application is usually maintained in a database. To maintain a catalog of books, the Duke’s Bookstore examples described in Chapters <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnafd.html">Chapter 4, Java Servlet Technology</a> through <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnaxu.html">Chapter 15, Internationalizing and Localizing Web Applications</a> use the Java DB database included with the Application Server.To access the data in a database, web applications use the new Java Persistence API (see <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnbpz.html">Chapter 24, Introduction to the Java Persistence API</a>). See <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnbrl.html">Chapter 25, Persistence in the Web Tier</a> to learn how the Duke’s Bookstore applications use this API to access the book data.To run the Duke’s Bookstore applications, you need to first populate the database with the book data and create a data source in the application server. The rest of this section explains how to perform these tasks. <a name="bnafa"></a><h4>Populating the Example Database</h4> <a name="indexterm-204"></a>When you deploy any of the Duke’s Bookstore applications using <tt>ant deploy</tt>, the database is automatically populated at the same time. If you want to populate the database separately from the deploy task or are using NetBeans IDE to deploy the application, follow these steps: <ol><li>In a terminal window, go to the <tt>books</tt> directory or any one of the <tt>bookstore1</tt> through <tt>bookstore6</tt> example directories.</li> <li>Start the Java DB database server. For instructions, see <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnadk.html">Starting and Stopping the Java DB Database Server</a>. You don’t have to do this if you are using NetBeans IDE. It starts the database server automatically.</li> <li>Type <tt>ant create-tables</tt>. This task runs a command to read the file <tt>tutorial.sql</tt> and execute the SQL commands contained in the file.</li> <li>At the end of the processing, you should see the following output:<pre>... [sql] 181 of 181 SQL statements executed successfully</pre></li></ol> When you are running <tt>create-tables</tt>, don’t worry if you see a message that an SQL statement failed. This usually happens the first time you run the command because it always tries to delete an existing database table first before it creates a new one. The first time through, there is no table yet, of course. <a name="bnafb"></a><h4>Creating a Data Source in the Application Server</h4> A <tt>DataSource</tt> object has a set of properties that identify and describe the real world data source that it represents. These properties include information such as the location of the database server, the name of the database, the network protocol to use to communicate with the server, and so on.<a name="indexterm-205"></a>Data sources in the Application Server implement connection pooling. To define the Duke’s Bookstore data source, you use the installed Derby connection pool named <tt>DerbyPool</tt>.You create the data source using the Application Server Admin Console, following this procedure: <ol><li>Expand the Resources node.</li> <li>Expand the JDBC node.</li> <li>Select the JDBC Resources node.</li> <li>Click the New... button.</li> <li>Type <tt>jdbc/BookDB</tt> in the JNDI Name field.</li> <li>Choose <tt>DerbyPool</tt> for the Pool Name.</li> <li>Click OK.</li></ol> January 20, 2008 Java Servlet Technology As soon as the web began to be used for delivering services, service providers recognized the need for dynamic content. Applets, one of the earliest attempts toward this goal, focused on using the client platform to deliver dynamic user experiences. At the same time, developers also investigated using the server platform for this purpose. Initially, Common Gateway Interface (CGI) scripts were the main technology used to generate dynamic content. Although widely used, CGI scripting technology has a number of shortcomings, including platform dependence and lack of scalability. To address these limitations, Java Servlet technology was created as a portable way to provide dynamic, user-oriented content. January 20, 2008 What Is a Servlet? A servlet is a Java programming language class that is used to extend the capabilities of servers that host applications accessed by means of a request-response programming model. Although servlets can respond to any type of request, they are commonly used to extend the applications hosted by web servers. For such applications, Java Servlet technology defines HTTP-specific servlet classes.<a name="indexterm-207"></a><a name="indexterm-208"></a><a name="indexterm-209"></a><a name="indexterm-210"></a><a name="indexterm-211"></a>The <a href="http://java.sun.com/javaee/5/docs/api/javax/servlet/package-summary.html">javax.servlet</a> and <a href="http://java.sun.com/javaee/5/docs/api/javax/servlet/http/package-summary.html">javax.servlet.http</a> packages provide interfaces and classes for writing servlets. All servlets must implement the <a href="http://java.sun.com/javaee/5/docs/api/javax/servlet/Servlet.html">Servlet</a> interface, which defines life-cycle methods. When implementing a generic service, you can use or extend the <a href="http://java.sun.com/javaee/5/docs/api/javax/servlet/GenericServlet.html">GenericServlet</a> class provided with the Java Servlet API. The <a href="http://java.sun.com/javaee/5/docs/api/javax/servlet/http/HttpServlet.html">HttpServlet</a> class provides methods, such as <tt>doGet</tt> and <tt>doPost</tt>, for handling HTTP-specific services.This chapter focuses on writing servlets that generate responses to HTTP requests. January 20, 2008 Servlet Life Cycle The life cycle of a servlet is controlled by the container in which the servlet has been deployed. When a request is mapped to a servlet, the container performs the following steps. <ol><li><a name="indexterm-214"></a>If an instance of the servlet does not exist, the web container <ol><li>Loads the servlet class.</li> <li>Creates an instance of the servlet class.</li> <li>Initializes the servlet instance by calling the <tt>init</tt> method. Initialization is covered in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnafu.html">Initializing a Servlet</a>.</li></ol> </li> <li>Invokes the <tt>service</tt> method, passing request and response objects. Service methods are discussed in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnafv.html">Writing Service Methods</a>.</li></ol> If the container needs to remove the servlet, it finalizes the servlet by calling the servlet’s <tt>destroy</tt> method. Finalization is discussed in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnags.html">Finalizing a Servlet</a>. <a name="bnafj"></a><h4>Handling Servlet Life-Cycle Events</h4> <a name="indexterm-215"></a><a name="indexterm-216"></a>You can monitor and react to events in a servlet’s life cycle by defining listener objects whose methods get invoked when life-cycle events occur. To use these listener objects you must define and specify the listener class. <a name="bnafk"></a><h5>Defining the Listener Class</h5> <a name="indexterm-217"></a><a name="indexterm-218"></a>You define a listener class as an implementation of a listener interface. <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnafi.html#bnafl">Table 4-2</a> lists the events that can be monitored and the corresponding interface that must be implemented. When a listener method is invoked, it is passed an event that contains information appropriate to the event. For example, the methods in the <tt>HttpSessionListener</tt> interface are passed an <tt>HttpSessionEvent</tt>, which contains an <tt>HttpSession</tt>.<a name="bnafl"></a><h6>Table 4-2 Servlet Life-Cycle Events</h6><table ID="Table1"><col width="75*"><col width="76*"><col width="203*"><tbody><tr><th align="left" valign="top">Object</th> <th align="left" valign="top">Event</th> <th align="left" valign="top">Listener Interface and Event Class</th> </tr> <tr><td rowspan="2" align="left" valign="top">Web context (see <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnagl.html">Accessing the Web Context</a>)</td> <td align="left" valign="top">Initialization and destruction</td> <td align="left" valign="top"><a href="http://java.sun.com/javaee/5/docs/api/javax/servlet/ServletContextListener.html">javax.servlet.ServletContextListener</a> and<a href="http://java.sun.com/javaee/5/docs/api/javax/servlet/ServletContextEvent.html">ServletContextEvent</a></td> </tr> <tr><td align="left" valign="top">Attribute added, removed, or replaced</td> <td align="left" valign="top"><a href="http://java.sun.com/javaee/5/docs/api/javax/servlet/ServletContextAttributeListener.html">javax.servlet.ServletContextAttributeListener</a> and<a href="http://java.sun.com/javaee/5/docs/api/javax/servlet/ServletContextAttributeEvent.html">ServletContextAttributeEvent</a></td> </tr> <tr><td rowspan="2" align="left" valign="top">Session (See <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnagm.html">Maintaining Client State</a>)</td> <td align="left" valign="top">Creation, invalidation, activation, passivation, and timeout</td> <td align="left" valign="top"><a href="http://java.sun.com/javaee/5/docs/api/javax/servlet/http/HttpSessionListener.html">javax.servlet.http.HttpSessionListener</a>, <a href="http://java.sun.com/javaee/5/docs/api/javax/servlet/http/HttpSessionActivationListener.html">javax.servlet.http.HttpSessionActivationListener</a>, and<a href="http://java.sun.com/javaee/5/docs/api/javax/servlet/http/HttpSessionEvent.html">HttpSessionEvent</a></td> </tr> <tr><td align="left" valign="top">Attribute added, removed, or replaced</td> <td align="left" valign="top"><a href="http://java.sun.com/javaee/5/docs/api/javax/servlet/http/HttpSessionAttributeListener.html">javax.servlet.http.HttpSessionAttributeListener</a> and<a href="http://java.sun.com/javaee/5/docs/api/javax/servlet/http/HttpSessionBindingEvent.html">HttpSessionBindingEvent</a></td> </tr> <tr><td rowspan="2" align="left" valign="top">Request</td> <td align="left" valign="top">A servlet request has started being processed by web components</td> <td align="left" valign="top"><a href="http://java.sun.com/javaee/5/docs/api/javax/servlet/ServletRequestListener.html">javax.servlet.ServletRequestListener</a> and<a href="http://java.sun.com/javaee/5/docs/api/javax/servlet/ServletRequestEvent.html">ServletRequestEvent</a></td> </tr> <tr><td align="left" valign="top">Attribute added, removed, or replaced</td> <td align="left" valign="top"><a href="http://java.sun.com/javaee/5/docs/api/javax/servlet/ServletRequestAttributeListener.html">javax.servlet.ServletRequestAttributeListener</a> and<a href="http://java.sun.com/javaee/5/docs/api/javax/servlet/ServletRequestAttributeEvent.html">ServletRequestAttributeEvent</a></td> </tr> </tbody></table><a name="indexterm-219"></a>The <tt></tt>tut-install<tt>/javaeetutorial5/examples/web/bookstore1/src/java/com/sun/bookstore1/listeners/ContextListener</tt> class creates and removes the database access and counter objects used in the Duke’s Bookstore application. The methods retrieve the web context object from <tt>ServletContextEvent</tt> and then store (and remove) the objects as servlet context attributes.<pre>import database.BookDBAO; import javax.servlet.*; import util.Counter; import javax.ejb.*; import javax.persistence.*; public final class ContextListener implements ServletContextListener { private ServletContext context = null; @PersistenceUnit EntityManagerFactory emf; public void contextInitialized(ServletContextEvent event) { context = event.getServletContext(); try { BookDBAO bookDB = new BookDBAO(emf); context.setAttribute("bookDB", bookDB); } catch (Exception ex) { System.out.println( "Couldn’t create database: " + ex.getMessage()); } Counter counter = new Counter(); context.setAttribute("hitCounter", counter); counter = new Counter(); context.setAttribute("orderCounter", counter); } public void contextDestroyed(ServletContextEvent event) { context = event.getServletContext(); BookDBAO bookDB = context.getAttribute("bookDB"); bookDB.remove(); context.removeAttribute("bookDB"); context.removeAttribute("hitCounter"); context.removeAttribute("orderCounter"); } }</pre> <a name="bnafm"></a><h5>Specifying Event Listener Classes</h5> You specify an event listener class using the <tt>listener</tt> element of the deployment descriptor. Review <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnaff.html">The Example Servlets</a> for information on how to specify the <tt>ContextListener</tt> listener class. You can specify an event listener using the deployment descriptor editor of NetBeans IDE by doing the following: <ol><li>Expand your application’s project node.</li> <li>Expand the project’s Web Pages and WEB-INF nodes.</li> <li>Double-click <tt>web.xml</tt>.</li> <li>Click General at the top of the <tt>web.xml</tt> editor.</li> <li>Expand the Web Application Listeners node.</li> <li>Click Add.</li> <li>In the Add Listener dialog, click Browse to locate the listener class.</li> <li>Click OK.</li></ol> <a name="bnafn"></a><h4>Handling Servlet Errors</h4> Any number of exceptions can occur when a servlet executes. When an exception occurs, the web container generates a default page containing the message<pre>A Servlet Exception Has Occurred</pre>But you can also specify that the container should return a specific error page for a given exception. Review the deployment descriptor file included with the example to learn how to map the exceptions <tt>exception.BookNotFound</tt>, <tt>exception.BooksNotFound</tt>, and <tt>exception.OrderException</tt> returned by the Duke’s Bookstore application to <tt>errorpage.html</tt>.See <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnaeo.html#bnaet">Mapping Errors to Error Screens</a> for instructions on how to specify error pages using NetBeans IDE. January 20, 2008 Sharing Information Web components, like most objects, usually work with other objects to accomplish their tasks. There are several ways they can do this. They can use private helper objects (for example, JavaBeans components), they can share objects that are attributes of a public scope, they can use a database, and they can invoke other web resources. The Java Servlet technology mechanisms that allow a web component to invoke other web resources are described in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnagi.html">Invoking Other Web Resources</a>. <a name="bnafp"></a><h4>Using Scope Objects</h4> <a name="indexterm-221"></a>Collaborating web components share information by means of objects that are maintained as attributes of four scope objects. You access these attributes using the <tt>[get|set]Attribute</tt> methods of the class representing the scope. <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnafo.html#bnafq">Table 4-3</a> lists the scope objects.<a name="bnafq"></a><h6>Table 4-3 Scope Objects</h6><table ID="Table1"><col width="55*"><col width="103*"><col width="195*"><tbody><tr><th align="left" valign="top">Scope Object</th> <th align="left" valign="top">Class</th> <th align="left" valign="top">Accessible From</th> </tr> <tr><td align="left" valign="top">Web context</td> <td align="left" valign="top"><a href="http://java.sun.com/javaee/5/docs/api/javax/servlet/ServletContext.html">javax.servlet.ServletContext</a></td> <td align="left" valign="top">Web components within a web context. See <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnagl.html">Accessing the Web Context</a>.</td> </tr> <tr><td align="left" valign="top">Session</td> <td align="left" valign="top"><a href="http://java.sun.com/javaee/5/docs/api/javax/servlet/http/HttpSession.html">javax.servlet.http.HttpSession</a></td> <td align="left" valign="top">Web components handling a request that belongs to the session. See <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnagm.html">Maintaining Client State</a>.</td> </tr> <tr><td align="left" valign="top">Request</td> <td align="left" valign="top">subtype of <a href="http://java.sun.com/javaee/5/docs/api/javax/servlet/ServletRequest.html">javax.servlet.ServletRequest</a></td> <td align="left" valign="top">Web components handling the request.</td> </tr> <tr><td align="left" valign="top">Page</td> <td align="left" valign="top"><a href="http://java.sun.com/javaee/5/docs/api/javax/servlet/jsp/JspContext.html">javax.servlet.jsp.JspContext</a></td> <td align="left" valign="top">The JSP page that creates the object. See <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnahl.html#bnahn">Using Implicit Objects</a>.</td> </tr> </tbody></table><a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnafo.html#bnafr">Figure 4-1</a> shows the scoped attributes maintained by the Duke’s Bookstore application.<a name="bnafr"></a><h6>Figure 4-1 Duke’s Bookstore Scoped Attributes</h6><img src="http://java.sun.com/javaee/5/docs/tutorial/doc/figures/web-scopedAttributes.gif" alt="Diagram of Duke‘s Bookstore scoped attributes. Session attributes are currency and cart, web context attributes are hitCounter, bookDB, orderCounter."> <a name="bnafs"></a><h4>Controlling Concurrent Access to Shared Resources</h4> <a name="indexterm-222"></a>In a multithreaded server, it is possible for shared resources to be accessed concurrently. In addition to scope object attributes, shared resources include in-memory data (such as instance or class variables) and external objects such as files, database connections, and network connections. Concurrent access can arise in several situations: <ul><li>Multiple web components accessing objects stored in the web context.</li> <li>Multiple web components accessing objects stored in a session.</li> <li><a name="indexterm-223"></a>Multiple threads within a web component accessing instance variables. A web container will typically create a thread to handle each request. If you want to ensure that a servlet instance handles only one request at a time, a servlet can implement the <a href="http://java.sun.com/javaee/5/docs/api/javax/servlet/SingleThreadModel.html">SingleThreadModel</a> interface. If a servlet implements this interface, you are guaranteed that no two threads will execute concurrently in the servlet’s service method. A web container can implement this guarantee by synchronizing access to a single instance of the servlet, or by maintaining a pool of web component instances and dispatching each new request to a free instance. This interface does not prevent synchronization problems that result from web components accessing shared resources such as static class variables or external objects. In addition, the Servlet 2.4 specification deprecates the <tt>SingleThreadModel</tt> interface.</li></ul> When resources can be accessed concurrently, they can be used in an inconsistent fashion. To prevent this, you must control the access using the synchronization techniques described in the <a href="http://java.sun.com/docs/books/tutorial/essential/concurrency/index.html">Threads</a> lesson in <a href="http://java.sun.com/docs/books/tutorial/">The Java Tutorial, Fourth Edition</a>, by Sharon Zakhour et al. (Addison-Wesley, 2006).The preceding section showed five scoped attributes shared by more than one servlet: <tt>bookDB</tt>, <tt>cart</tt>, <tt>currency</tt>, <tt>hitCounter</tt>, and <tt>orderCounter</tt>. The <tt>bookDB</tt> attribute is discussed in the next section. The cart, currency, and counters can be set and read by multiple multithreaded servlets. To prevent these objects from being used inconsistently, access is controlled by synchronized methods. For example, here is the <tt>Counter</tt> class, located at <tt></tt>tut-install<tt>/javaeetutorial5/examples/web/bookstore1/src/java/com/sun/bookstore1/util/</tt>:<pre>public class Counter { private int counter; public Counter() { counter = 0; } public synchronized int getCounter() { return counter; } public synchronized int setCounter(int c) { counter = c; return counter; } public synchronized int incCounter() { return(++counter); } }</pre> <a name="bnaft"></a><h4>Accessing Databases</h4> <a name="indexterm-224"></a>Data that is shared between web components and is persistent between invocations of a web application is usually maintained by a database. Web components use the Java Persistence API to access relational databases. The data for Duke’s Bookstore is maintained in a database and is accessed through the database access class <tt></tt>tut-install<tt>/javaeetutorial5/examples/web/bookstore1/src/java/com/sun/bookstore1/database/BookDBAO</tt>. For example, <tt>ReceiptServlet</tt> invokes the <tt>BookDBAO.buyBooks</tt> method to update the book inventory when a user makes a purchase. The <tt>buyBooks</tt> method invokes <tt>buyBook</tt> for each book contained in the shopping cart, as shown in the following code.<pre>public void buyBooks(ShoppingCart cart) throws OrderException{ Collection items = cart.getItems(); Iterator i = items.iterator(); try { while (i.hasNext()) { ShoppingCartItem sci = (ShoppingCartItem)i.next(); Book bd = (Book)sci.getItem(); String id = bd.getBookId(); int quantity = sci.getQuantity(); buyBook(id, quantity); } } catch (Exception ex) { throw new OrderException("Commit failed: " + ex.getMessage()); } } public void buyBook(String bookId, int quantity) throws OrderException { try { Book requestedBook = em.find(Book.class, bookId); if (requestedBook != null) { int inventory = requestedBook.getInventory(); if ((inventory - quantity) >= 0) { int newInventory = inventory - quantity; requestedBook.setInventory(newInventory); } else{ throw new OrderException("Not enough of " + bookId + " in stock to complete order."); } } } catch (Exception ex) { throw new OrderException("Couldn’t purchase book: " + bookId + ex.getMessage()); } }</pre><a name="indexterm-225"></a><a name="indexterm-226"></a>To ensure that the order is processed in its entirety, the call to <tt>buyBooks</tt> is wrapped in a single transaction. In the following code, the calls to the <tt>begin</tt> and <tt>commit</tt> methods of <tt>UserTransaction</tt> mark the boundaries of the transaction. The call to the <tt>rollback</tt> method of <tt>UserTransaction</tt> undoes the effects of all statements in the transaction so as to protect the integrity of the data.<pre>try { utx.begin(); bookDB.buyBooks(cart); utx.commit(); } catch (Exception ex) { try { utx.rollback(); } catch(Exception e) { System.out.println("Rollback failed: "+e.getMessage()); } System.err.println(ex.getMessage()); orderCompleted = false;} }</pre> January 20, 2008 Initializing a Servlet After the web container loads and instantiates the servlet class and before it delivers requests from clients, the web container initializes the servlet. To customize this process to allow the servlet to read persistent configuration data, initialize resources, and perform any other one-time activities, you override the <tt>init</tt> method of the <tt>Servlet</tt> interface. A servlet that cannot complete its initialization process should throw <tt>UnavailableException</tt>. All the servlets that access the bookstore database (<tt>BookStoreServlet</tt>, <tt>CatalogServlet</tt>, <tt>BookDetailsServlet</tt>, and <tt>ShowCartServlet</tt>) initialize a variable in their <tt>init</tt> method that points to the database access object created by the web context listener: <pre>public class CatalogServlet extends HttpServlet { private BookDBAO bookDB; public void init() throws ServletException { bookDB = (BookDBAO)getServletContext(). getAttribute("bookDB"); if (bookDB == null) throw new UnavailableException("Couldn’t get database."); } }</pre> January 20, 2008 Writing Service Methods The service provided by a servlet is implemented in the <tt>service</tt> method of a <tt>GenericServlet</tt>, in the <tt>doMethod</tt> methods (where Method can take the value <tt>Get</tt>, <tt>Delete</tt>, <tt>Options</tt>, <tt>Post</tt>, <tt>Put</tt>, or <tt>Trace</tt>) of an <tt>HttpServlet</tt> object, or in any other protocol-specific methods defined by a class that implements the <tt>Servlet</tt> interface. In the rest of this chapter, the term service method is used for any method in a servlet class that provides a service to a client.The general pattern for a service method is to extract information from the request, access external resources, and then populate the response based on that information.<a name="indexterm-234"></a>For HTTP servlets, the correct procedure for populating the response is to first retrieve an output stream from the response, then fill in the response headers, and finally write any body content to the output stream. Response headers must always be set before the response has been committed. Any attempt to set or add headers after the response has been committed will be ignored by the web container. The next two sections describe how to get information from requests and generate responses. <a name="bnafw"></a><h4>Getting Information from Requests</h4> <a name="indexterm-235"></a><a name="indexterm-236"></a><a name="indexterm-237"></a><a name="indexterm-238"></a>A request contains data passed between a client and the servlet. All requests implement the <a href="http://java.sun.com/javaee/5/docs/api/javax/servlet/ServletRequest.html">ServletRequest</a> interface. This interface defines methods for accessing the following information: <ul><li>Parameters, which are typically used to convey information between clients and servlets</li> <li>Object-valued attributes, which are typically used to pass information between the servlet container and a servlet or between collaborating servlets</li> <li>Information about the protocol used to communicate the request and about the client and server involved in the request</li> <li>Information relevant to localization</li></ul> <a name="indexterm-239"></a>For example, in <tt>CatalogServlet</tt> the identifier of the book that a customer wishes to purchase is included as a parameter to the request. The following code fragment illustrates how to use the <tt>getParameter</tt> method to extract the identifier:<pre>String bookId = request.getParameter("Add"); if (bookId != null) { Book book = bookDB.getBook(bookId);</pre><a name="indexterm-240"></a><a name="indexterm-241"></a><a name="indexterm-242"></a><a name="indexterm-243"></a>You can also retrieve an input stream from the request and manually parse the data. To read character data, use the <a href="http://java.sun.com/javase/6/docs/api/java/io/BufferedReader.html">BufferedReader</a> object returned by the request’s <tt>getReader</tt> method. To read binary data, use the <a href="http://java.sun.com/javaee/5/docs/api/javax/servlet/ServletInputStream.html">ServletInputStream</a> returned by <tt>getInputStream</tt>.<a name="indexterm-244"></a><a name="indexterm-245"></a><a name="indexterm-246"></a>HTTP servlets are passed an HTTP request object, <a href="http://java.sun.com/javaee/5/docs/api/javax/servlet/http/HttpServletRequest.html">HttpServletRequest</a>, which contains the request URL, HTTP headers, query string, and so on.<a name="indexterm-247"></a>An HTTP request URL contains the following parts:<pre>http://[host]:[port][request-path]?[query-string]</pre><a name="indexterm-248"></a>The request path is further composed of the following elements: <ul><li>Context path: A concatenation of a forward slash (<tt>/</tt>) with the context root of the servlet’s web application.</li> <li>Servlet path: The path section that corresponds to the component alias that activated this request. This path starts with a forward slash (<tt>/</tt>).</li> <li>Path info: The part of the request path that is not part of the context path or the servlet path.</li></ul> If the context path is <tt>/catalog</tt> and for the aliases listed in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnafv.html#bnafx">Table 4-4</a>, <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnafv.html#bnafy">Table 4-5</a> gives some examples of how the URL will be parsed.<a name="bnafx"></a><h6>Table 4-4 Aliases</h6><table ID="Table1"><col width="178*"><col width="178*"><tbody><tr><th align="left" valign="top">Pattern</th> <th align="left" valign="top">Servlet</th> </tr> <tr><td align="left" valign="top"><tt>/lawn/*</tt></td> <td align="left" valign="top"><tt>LawnServlet</tt></td> </tr> <tr><td align="left" valign="top"><tt>/*.jsp</tt></td> <td align="left" valign="top"><tt>JSPServlet</tt></td> </tr> </tbody></table><a name="bnafy"></a><h6>Table 4-5 Request Path Elements</h6><table ID="Table2"><col width="162*"><col width="116*"><col width="77*"><tbody><tr><th align="left" valign="top">Request Path</th> <th align="left" valign="top">Servlet Path</th> <th align="left" valign="top">Path Info</th> </tr> <tr><td align="left" valign="top"><tt>/catalog/lawn/index.html</tt></td> <td align="left" valign="top"><tt>/lawn</tt></td> <td align="left" valign="top"><tt>/index.html</tt></td> </tr> <tr><td align="left" valign="top"><tt>/catalog/help/feedback.jsp</tt></td> <td align="left" valign="top"><tt>/help/feedback.jsp</tt></td> <td align="left" valign="top"><tt>null</tt></td> </tr> </tbody></table><a name="indexterm-249"></a>Query strings are composed of a set of parameters and values. Individual parameters are retrieved from a request by using the <tt>getParameter</tt> method. There are two ways to generate query strings: <ul><li>A query string can explicitly appear in a web page. For example, an HTML page generated by <tt>CatalogServlet</tt> could contain the link <tt><a href="/bookstore1/catalog?Add=101">Add To Cart</a></tt>. <tt>CatalogServlet</tt> extracts the parameter named <tt>Add</tt> as follows:<pre>String bookId = request.getParameter("Add");</pre></li> <li>A query string is appended to a URL when a form with a <tt>GET</tt> HTTP method is submitted. In the Duke’s Bookstore application, <tt>CashierServlet</tt> generates a form, then a user name input to the form is appended to the URL that maps to <tt>ReceiptServlet</tt>, and finally <tt>ReceiptServlet</tt> extracts the user name using the <tt>getParameter</tt> method.</li></ul> <a name="bnafz"></a><h4>Constructing Responses</h4> <a name="indexterm-250"></a><a name="indexterm-251"></a><a name="indexterm-252"></a>A response contains data passed between a server and the client. All responses implement the <a href="http://java.sun.com/javaee/5/docs/api/javax/servlet/ServletResponse.html">ServletResponse</a> interface. This interface defines methods that allow you to: <ul><li><a name="indexterm-253"></a><a name="indexterm-254"></a><a name="indexterm-255"></a><a name="indexterm-256"></a>Retrieve an output stream to use to send data to the client. To send character data, use the <a href="http://java.sun.com/javase/6/docs/api/java/io/PrintWriter.html">PrintWriter</a> returned by the response’s <tt>getWriter</tt> method. To send binary data in a MIME body response, use the <a href="http://java.sun.com/javaee/5/docs/api/javax/servlet/ServletOutputStream.html">ServletOutputStream</a> returned by <tt>getOutputStream</tt>. To mix binary and text data (as in a multipart response), use a <tt>ServletOutputStream</tt> and manage the character sections manually.</li> <li>Indicate the content type (for example, <tt>text/html</tt>) being returned by the response with the <tt>setContentType(String)</tt> method. This method must be called before the response is committed. A registry of content type names is kept by the Internet Assigned Numbers Authority (IANA) at <a href="http://www.iana.org/assignments/media-types/">http://www.iana.org/assignments/media-types/</a>.</li> <li><a name="indexterm-257"></a>Indicate whether to buffer output with the <tt>setBufferSize(int)</tt> method. By default, any content written to the output stream is immediately sent to the client. Buffering allows content to be written before anything is actually sent back to the client, thus providing the servlet with more time to set appropriate status codes and headers or forward to another web resource. The method must be called before any content is written or before the response is committed.</li> <li>Set localization information such as locale and character encoding. See <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnaxu.html">Chapter 15, Internationalizing and Localizing Web Applications</a> for details.</li></ul> <a name="indexterm-258"></a><a name="indexterm-259"></a><a name="indexterm-260"></a>HTTP response objects, <a href="http://java.sun.com/javaee/5/docs/api/javax/servlet/http/HttpServletResponse.html">HttpServletResponse</a>, have fields representing HTTP headers such as the following: <ul><li>Status codes, which are used to indicate the reason a request is not satisfied or that a request has been redirected.</li> <li>Cookies, which are used to store application-specific information at the client. Sometimes cookies are used to maintain an identifier for tracking a user’s session (see <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnagm.html#bnagr">Session Tracking</a>).</li></ul> In Duke’s Bookstore, <tt>BookDetailsServlet</tt> generates an HTML page that displays information about a book that the servlet retrieves from a database. The servlet first sets response headers: the content type of the response and the buffer size. The servlet buffers the page content because the database access can generate an exception that would cause forwarding to an error page. By buffering the response, the servlet prevents the client from seeing a concatenation of part of a Duke’s Bookstore page with the error page should an error occur. The <tt>doGet</tt> method then retrieves a <tt>PrintWriter</tt> from the response.To fill in the response, the servlet first dispatches the request to <tt>BannerServlet</tt>, which generates a common banner for all the servlets in the application. This process is discussed in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnagi.html#bnagj">Including Other Resources in the Response</a>. Then the servlet retrieves the book identifier from a request parameter and uses the identifier to retrieve information about the book from the bookstore database. Finally, the servlet generates HTML markup that describes the book information and then commits the response to the client by calling the <tt>close</tt> method on the <tt>PrintWriter</tt>.<pre>public class BookDetailsServlet extends HttpServlet { ... public void doGet (HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { ... // set headers before accessing the Writer response.setContentType("text/html"); response.setBufferSize(8192); PrintWriter out = response.getWriter(); // then write the response out.println("<html>" + "<head><title>+ messages.getString("TitleBookDescription") +</title></head>"); // Get the dispatcher; it gets the banner to the user RequestDispatcher dispatcher = getServletContext(). getRequestDispatcher("/banner"); if (dispatcher != null) dispatcher.include(request, response); // Get the identifier of the book to display String bookId = request.getParameter("bookId"); if (bookId != null) { // and the information about the book try { Book bd = bookDB.getBook(bookId); ... // Print the information obtained out.println("<h2>" + bd.getTitle() + "</h2>" + ... } catch (BookNotFoundException ex) { response.resetBuffer(); throw new ServletException(ex); } } out.println("</body></html>"); out.close(); } }</pre><tt>BookDetailsServlet</tt> generates a page that looks like <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnafv.html#bnaga">Figure 4-2</a>.<a name="bnaga"></a><h6>Figure 4-2 Book Details</h6><img src="http://java.sun.com/javaee/5/docs/tutorial/doc/figures/web-bookDetails.gif" alt="Screen capture of book details. Shows " web="" servers="" for="" fun="" profit="" author,="" review,="" price,="" with="" links="" add="" to="" cart="" and="" continue="" shopping.="" height="657" width="662"> January 20, 2008 Filtering Requests and Responses A filter is an object that can transform the header and content (or both) of a request or response. Filters differ from web components in that filters usually do not themselves create a response. Instead, a filter provides functionality that can be “attached” to any kind of web resource. Consequently, a filter should not have any dependencies on a web resource for which it is acting as a filter; this way it can be composed with more than one type of web resource. The main tasks that a filter can perform are as follows: <ul><li>Query the request and act accordingly.</li> <li>Block the request-and-response pair from passing any further.</li> <li>Modify the request headers and data. You do this by providing a customized version of the request.</li> <li>Modify the response headers and data. You do this by providing a customized version of the response.</li> <li>Interact with external resources.</li></ul> Applications of filters include authentication, logging, image conversion, data compression, encryption, tokenizing streams, XML transformations, and so on.You can configure a web resource to be filtered by a chain of zero, one, or more filters in a specific order. This chain is specified when the web application containing the component is deployed and is instantiated when a web container loads the component.In summary, the tasks involved in using filters are <ul><li>Programming the filter</li> <li>Programming customized requests and responses</li> <li>Specifying the filter chain for each web resource</li></ul> <a name="bnagc"></a><h4>Programming Filters</h4> <a name="indexterm-262"></a><a name="indexterm-263"></a><a name="indexterm-264"></a><a name="indexterm-265"></a>The filtering API is defined by the <tt>Filter</tt>, <tt>FilterChain</tt>, and <tt>FilterConfig</tt> interfaces in the <tt>javax.servlet</tt> package. You define a filter by implementing the <a href="http://java.sun.com/javaee/5/docs/api/javax/servlet/Filter.html">Filter</a> interface. The most important method in this interface is <tt>doFilter</tt>, which is passed request, response, and filter chain objects. This method can perform the following actions: <ul><li>Examine the request headers.</li> <li>Customize the request object if the filter wishes to modify request headers or data.</li> <li>Customize the response object if the filter wishes to modify response headers or data.</li> <li>Invoke the next entity in the filter chain. If the current filter is the last filter in the chain that ends with the target web component or static resource, the next entity is the resource at the end of the chain; otherwise, it is the next filter that was configured in the WAR. The filter invokes the next entity by calling the <tt>doFilter</tt> method on the chain object (passing in the request and response it was called with, or the wrapped versions it may have created). Alternatively, it can choose to block the request by not making the call to invoke the next entity. In the latter case, the filter is responsible for filling out the response.</li> <li>Examine response headers after it has invoked the next filter in the chain.</li> <li>Throw an exception to indicate an error in processing.</li></ul> <a name="indexterm-266"></a>In addition to <tt>doFilter</tt>, you must implement the <tt>init</tt> and <tt>destroy</tt> methods. The <tt>init</tt> method is called by the container when the filter is instantiated. If you wish to pass initialization parameters to the filter, you retrieve them from the <tt>FilterConfig</tt> object passed to <tt>init</tt>.The Duke’s Bookstore application uses the filters <tt>HitCounterFilter</tt> and <tt>OrderFilter</tt>, located at <tt></tt>tut-install<tt>/javaeetutorial5/examples/web/bookstore1/src/java/com/sun/bookstore1/filters/</tt>, to increment and log the value of counters when the entry and receipt servlets are accessed.In the <tt>doFilter</tt> method, both filters retrieve the servlet context from the filter configuration object so that they can access the counters stored as context attributes. After the filters have completed application-specific processing, they invoke <tt>doFilter</tt> on the filter chain object passed into the original <tt>doFilter</tt> method. The elided code is discussed in the next section.<pre>public final class HitCounterFilter implements Filter { private FilterConfig filterConfig = null; public void init(FilterConfig filterConfig) throws ServletException { this.filterConfig = filterConfig; } public void destroy() { this.filterConfig = null; } public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException { if (filterConfig == null) return; StringWriter sw = new StringWriter(); PrintWriter writer = new PrintWriter(sw); Counter counter = (Counter)filterConfig. getServletContext(). getAttribute("hitCounter"); writer.println(); writer.println("==============="); writer.println("The number of hits is: " + counter.incCounter()); writer.println("==============="); // Log the resulting string writer.flush(); System.out.println(sw.getBuffer().toString()); ... chain.doFilter(request, wrapper); ... } }</pre> <a name="bnagd"></a><h4>Programming Customized Requests and Responses</h4> <a name="indexterm-267"></a><a name="indexterm-268"></a>There are many ways for a filter to modify a request or response. For example, a filter can add an attribute to the request or can insert data in the response. In the Duke’s Bookstore example, <tt>HitCounterFilter</tt> inserts the value of the counter into the response.A filter that modifies a response must usually capture the response before it is returned to the client. To do this, you pass a stand-in stream to the servlet that generates the response. The stand-in stream prevents the servlet from closing the original response stream when it completes and allows the filter to modify the servlet’s response.<a name="indexterm-269"></a>To pass this stand-in stream to the servlet, the filter creates a response wrapper that overrides the <tt>getWriter</tt> or <tt>getOutputStream</tt> method to return this stand-in stream. The wrapper is passed to the <tt>doFilter</tt> method of the filter chain. Wrapper methods default to calling through to the wrapped request or response object. This approach follows the well-known Wrapper or Decorator pattern described in Design Patterns, Elements of Reusable Object-Oriented Software, by Erich Gamma et al. (Addison-Wesley, 1995). The following sections describe how the hit counter filter described earlier and other types of filters use wrappers.<a name="indexterm-270"></a><a name="indexterm-271"></a>To override request methods, you wrap the request in an object that extends <a href="http://java.sun.com/javaee/5/docs/api/javax/servlet/ServletRequestWrapper.html">ServletRequestWrapper</a> or <a href="http://java.sun.com/javaee/5/docs/api/javax/servlet/http/HttpServletRequestWrapper.html">HttpServletRequestWrapper</a>. To override response methods, you wrap the response in an object that extends <a href="http://java.sun.com/javaee/5/docs/api/javax/servlet/ServletResponseWrapper.html">ServletResponseWrapper</a> or <a href="http://java.sun.com/javaee/5/docs/api/javax/servlet/http/HttpServletResponseWrapper.html">HttpServletResponseWrapper</a>.<tt>HitCounterFilter</tt> wraps the response in a <tt></tt>tut-install<tt>/javaeetutorial5/examples/web/bookstore1/src/java/com/sun/bookstore1/filters/CharResponseWrapper</tt>. The wrapped response is passed to the next object in the filter chain, which is <tt>BookStoreServlet</tt>. Then <tt>BookStoreServlet</tt> writes its response into the stream created by <tt>CharResponseWrapper</tt>. When <tt>chain.doFilter</tt> returns, <tt>HitCounterFilter</tt> retrieves the servlet’s response from <tt>PrintWriter</tt> and writes it to a buffer. The filter inserts the value of the counter into the buffer, resets the content length header of the response, and then writes the contents of the buffer to the response stream.<pre>PrintWriter out = response.getWriter(); CharResponseWrapper wrapper = new CharResponseWrapper( (HttpServletResponse)response); chain.doFilter(request, wrapper); CharArrayWriter caw = new CharArrayWriter(); caw.write(wrapper.toString().substring(0, wrapper.toString().indexOf("</body>")-1)); caw.write("\n<center>" + messages.getString("Visitor") + "" + counter.getCounter() + "</center>"); caw.write("\n</body></html>"); response.setContentLength(caw.toString().getBytes().length); out.write(caw.toString()); out.close(); public class CharResponseWrapper extends HttpServletResponseWrapper { private CharArrayWriter output; public String toString() { return output.toString(); } public CharResponseWrapper(HttpServletResponse response){ super(response); output = new CharArrayWriter(); } public PrintWriter getWriter(){ return new PrintWriter(output); } }</pre><a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnagb.html#bnage">Figure 4-3</a> shows the entry page for Duke’s Bookstore with the hit counter.<a name="bnage"></a><h6>Figure 4-3 Duke’s Bookstore with Hit Counter</h6><img src="http://java.sun.com/javaee/5/docs/tutorial/doc/figures/web-dukesBookstore.gif" alt="Screen capture of Duke‘s Bookstore with " components="" for="" web="" developers="" recommendation,="" start="" shopping="" link="" and="" you="" are="" visitor="" number="" 2.="" height="627" width="662"> <a name="bnagf"></a><h4>Specifying Filter Mappings</h4> <a name="indexterm-272"></a><a name="indexterm-273"></a><a name="indexterm-274"></a><a name="indexterm-275"></a>A web container uses filter mappings to decide how to apply filters to web resources. A filter mapping matches a filter to a web component by name, or to web resources by URL pattern. The filters are invoked in the order in which filter mappings appear in the filter mapping list of a WAR. You specify a filter mapping list for a WAR in its deployment descriptor, either with NetBeans IDE or by coding the list by hand with XML.To declare the filter and map it to a web resource using NetBeans IDE, do the following: <ol><li>Expand the application’s project node in the Project pane.</li> <li>Expand the Web Pages and WEB-INF nodes under the project node.</li> <li>Double-click <tt>web.xml</tt>.</li> <li>Click Filters at the top of the editor pane.</li> <li>Expand the Servlet Filters node in the editor pane.</li> <li>Click Add Filter Element to map the filter to a web resource by name or by URL pattern.</li> <li>In the Add Servlet Filter dialog, enter the name of the filter in the Filter Name field.</li> <li>Click Browse to locate the servlet class to which the filter applies. You can include wildcard characters so that you can apply the filter to more than one servlet.</li> <li>Click OK.</li></ol> To constrain how the filter is applied to requests, do the following: <ol><li>Expand the Filter Mappings node in the Filters tab of the editor pane.</li> <li>Select the filter from the list of filters.</li> <li>Click Add.</li> <li>In the Add Filter Mapping dialog, select one of the following dispatcher types: <ul><li><tt>REQUEST</tt>: Only when the request comes directly from the client</li> <li><tt>FORWARD</tt>: Only when the request has been forwarded to a component (see <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnagi.html#bnagk">Transferring Control to Another Web Component</a>)</li> <li><tt>INCLUDE</tt>: Only when the request is being processed by a component that has been included (see <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnagi.html#bnagj">Including Other Resources in the Response</a>)</li> <li><tt>ERROR</tt>: Only when the request is being processed with the error page mechanism (see <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnafi.html#bnafn">Handling Servlet Errors</a>)You can direct the filter to be applied to any combination of the preceding situations by selecting multiple dispatcher types. If no types are specified, the default option is <tt>REQUEST</tt>.</li></ul> </li></ol> You can declare, map, and constrain the filter by editing the XML in the web application deployment descriptor directly by following these steps: <ol><li>While in the <tt>web.xml</tt> editor pane in NetBeans IDE, click XML at the top of the editor pane.</li> <li>Declare the filter by adding a <tt>filter</tt> element right after the <tt>display-name</tt> element. The <tt>filter</tt> element creates a name for the filter and declares the filter’s implementation class and initialization parameters.</li> <li>Map the filter to a web resource by name or by URL pattern using the <tt>filter-mapping</tt> element: <ol><li>Include a <tt>filter-name</tt> element that specifies the name of the filter as defined by the <tt>filter</tt> element.</li> <li>Include a <tt>servlet-name</tt> element that specifies to which servlet the filter applies. The <tt>servlet-name</tt> element can include wildcard characters so that you can apply the filter to more than one servlet.</li></ol> </li> <li>Constrain how the filter will be applied to requests by specifying one of the enumerated dispatcher options (described in step 4 of the preceding set of steps) with the <tt>dispatcher</tt> element and adding the <tt>dispatcher</tt> element to the <tt>filter-mapping</tt> element.You can direct the filter to be applied to any combination of the preceding situations by including multiple <tt>dispatcher</tt> elements. If no elements are specified, the default option is <tt>REQUEST</tt>.</li></ol> If you want to log every request to a web application, you map the hit counter filter to the URL pattern <tt>/*</tt>. <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnagb.html#bnagg">Table 4-6</a> summarizes the filter definition and mapping list for the Duke’s Bookstore application. The filters are matched by servlet name, and each filter chain contains only one filter.<a name="bnagg"></a><h6>Table 4-6 Duke’s Bookstore Filter Definition and Mapping List</h6><table ID="Table1"><col width="90*"><col width="144*"><col width="106*"><tbody><tr><th align="left" valign="top">Filter</th> <th align="left" valign="top">Class</th> <th align="left" valign="top">Servlet</th> </tr> <tr><td align="left" valign="top"><tt>HitCounterFilter</tt></td> <td align="left" valign="top"><tt>filters.HitCounterFilter</tt></td> <td align="left" valign="top"><tt>BookStoreServlet</tt></td> </tr> <tr><td align="left" valign="top"><tt>OrderFilter</tt></td> <td align="left" valign="top"><tt>filters.OrderFilter</tt></td> <td align="left" valign="top"><tt>ReceiptServlet</tt></td> </tr> </tbody></table><a name="indexterm-276"></a><a name="indexterm-277"></a>You can map a filter to one or more web resources and you can map more than one filter to a web resource. This is illustrated in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnagb.html#bnagh">Figure 4-4</a>, where filter F1 is mapped to servlets S1, S2, and S3, filter F2 is mapped to servlet S2, and filter F3 is mapped to servlets S1 and S2.<a name="bnagh"></a><h6>Figure 4-4 Filter-to-Servlet Mapping</h6><img src="http://java.sun.com/javaee/5/docs/tutorial/doc/figures/web-filterMapping.gif" alt="Diagram of filter-to-servlet mapping with filters F1-F3 and servlets S1-S3. F1 filters S1-S3, then F2 filters S2, then F3 filters S1 and S2."><a name="indexterm-278"></a><a name="indexterm-279"></a>Recall that a filter chain is one of the objects passed to the <tt>doFilter</tt> method of a filter. This chain is formed indirectly by means of filter mappings. The order of the filters in the chain is the same as the order in which filter mappings appear in the web application deployment descriptor.<a name="indexterm-280"></a><a name="indexterm-281"></a>When a filter is mapped to servlet S1, the web container invokes the <tt>doFilter</tt> method of F1. The <tt>doFilter</tt> method of each filter in S1’s filter chain is invoked by the preceding filter in the chain by means of the <tt>chain.doFilter</tt> method. Because S1’s filter chain contains filters F1 and F3, F1’s call to <tt>chain.doFilter</tt> invokes the <tt>doFilter</tt> method of filter F3. When F3’s <tt>doFilter</tt> method completes, control returns to F1’s <tt>doFilter</tt> method. January 20, 2008 Invoking Other Web Resources Web components can invoke other web resources in two ways: indirectly and directly. A web component indirectly invokes another web resource when it embeds a URL that points to another web component in content returned to a client. In the Duke’s Bookstore application, most web components contain embedded URLs that point to other web components. For example, <tt>ShowCartServlet</tt> indirectly invokes the <tt>CatalogServlet</tt> through the following embedded URL:<pre>/bookstore1/catalog</pre>A web component can also directly invoke another resource while it is executing. There are two possibilities: The web component can include the content of another resource, or it can forward a request to another resource.<a name="indexterm-283"></a><a name="indexterm-284"></a>To invoke a resource available on the server that is running a web component, you must first obtain a <a href="http://java.sun.com/javaee/5/docs/api/javax/servlet/RequestDispatcher.html">RequestDispatcher</a> object using the <tt>getRequestDispatcher("URL")</tt> method.You can get a <tt>RequestDispatcher</tt> object from either a request or the web context; however, the two methods have slightly different behavior. The method takes the path to the requested resource as an argument. A request can take a relative path (that is, one that does not begin with a <tt>/</tt>), but the web context requires an absolute path. If the resource is not available or if the server has not implemented a <tt>RequestDispatcher</tt> object for that type of resource, <tt>getRequestDispatcher</tt> will return null. Your servlet should be prepared to deal with this condition. <a name="bnagj"></a><h4>Including Other Resources in the Response</h4> <a name="indexterm-285"></a><a name="indexterm-286"></a>It is often useful to include another web resource (for example, banner content or copyright information) in the response returned from a web component. To include another resource, invoke the <tt>include</tt> method of a <tt>RequestDispatcher</tt> object:<pre>include(request, response);</pre>If the resource is static, the <tt>include</tt> method enables programmatic server-side includes. If the resource is a web component, the effect of the method is to send the request to the included web component, execute the web component, and then include the result of the execution in the response from the containing servlet. An included web component has access to the request object, but it is limited in what it can do with the response object: <ul><li>It can write to the body of the response and commit a response.</li> <li>It cannot set headers or call any method (for example, <tt>setCookie</tt>) that affects the headers of the response.</li></ul> The banner for the Duke’s Bookstore application is generated by <tt>BannerServlet</tt>. Note that both <tt>doGet</tt> and <tt>doPost</tt> are implemented because <tt>BannerServlet</tt> can be dispatched from either method in a calling servlet.<pre>public class BannerServlet extends HttpServlet { public void doGet (HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { output(request, response); } public void doPost (HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { output(request, response); } private void output(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { PrintWriter out = response.getWriter(); out.println("<body bgcolor=\"#ffffff\">" + "<center>" + "<hr> &nbsp;" + "<h1>" + "Duke’s " + <img src=\"" + request.getContextPath() + "/duke.books.gif\">" + "Bookstore" + "</h1>" + "</center>" + " &nbsp; <hr> "); } }</pre>Each servlet in the Duke’s Bookstore application includes the result from <tt>BannerServlet</tt> using the following code:<pre>RequestDispatcher dispatcher = getServletContext().getRequestDispatcher("/banner"); if (dispatcher != null) dispatcher.include(request, response); }</pre> <a name="bnagk"></a><h4>Transferring Control to Another Web Component</h4> In some applications, you might want to have one web component do preliminary processing of a request and have another component generate the response. For example, you might want to partially process a request and then transfer to another component depending on the nature of the request.<a name="indexterm-287"></a><a name="indexterm-288"></a>To transfer control to another web component, you invoke the <tt>forward</tt> method of a <tt>RequestDispatcher</tt>. When a request is forwarded, the request URL is set to the path of the forwarded page. The original URI and its constituent parts are saved as request attributes <tt>javax.servlet.forward.[request-uri|context-path|servlet-path|path-info|query-string]</tt>. The <tt></tt>tut-install<tt>/javaeetutorial5/examples/web/bookstore2/src/java/com/sun/bookstore2/dispatcher/Dispatcher</tt> servlet, used by a version of the Duke’s Bookstore application described in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnall.html">The Example JSP Pages</a>, saves the path information from the original URL, retrieves a <tt>RequestDispatcher</tt> from the request, and then forwards to the JSP page, <tt></tt>tut-install<tt>/javaeetutorial5/examples/web/bookstore3/web/template/template.jsp</tt>.<pre>public class Dispatcher extends HttpServlet { public void doGet(HttpServletRequest request, HttpServletResponse response) { RequestDispatcher dispatcher = request. getRequestDispatcher("/template.jsp"); if (dispatcher != null) dispatcher.forward(request, response); } public void doPost(HttpServletRequest request, ... }</pre>The <tt>forward</tt> method should be used to give another resource responsibility for replying to the user. If you have already accessed a <tt>ServletOutputStream</tt> or <tt>PrintWriter</tt> object within the servlet, you cannot use this method; doing so throws an <tt>IllegalStateException</tt>. January 20, 2008 Accessing the Web Context The context in which web components execute is an object that implements the <a href="http://java.sun.com/javaee/5/docs/api/javax/servlet/ServletContext.html">ServletContext</a> interface. You retrieve the web context using the <tt>getServletContext</tt> method. The web context provides methods for accessing: <ul><li>Initialization parameters</li> <li>Resources associated with the web context</li> <li>Object-valued attributes</li> <li>Logging capabilities</li></ul> The web context is used by the Duke’s Bookstore filters <tt>HitCounterFilter</tt> and <tt>OrderFilter</tt>, which are discussed in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnagb.html">Filtering Requests and Responses</a>. Each filter stores a counter as a context attribute. Recall from <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnafo.html#bnafs">Controlling Concurrent Access to Shared Resources</a> that the counter’s access methods are synchronized to prevent incompatible operations by servlets that are running concurrently. A filter retrieves the counter object using the context’s <tt>getAttribute</tt> method. The incremented value of the counter is recorded in the log.<pre>public final class HitCounterFilter implements Filter { private FilterConfig filterConfig = null; public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException { ... StringWriter sw = new StringWriter(); PrintWriter writer = new PrintWriter(sw); ServletContext context = filterConfig. getServletContext(); Counter counter = (Counter)context. getAttribute("hitCounter"); ... writer.println("The number of hits is: " + counter.incCounter()); ... System.out.println(sw.getBuffer().toString()); ... } }</pre> January 20, 2008 Maintaining Client State Many applications require that a series of requests from a client be associated with one another. For example, the Duke’s Bookstore application saves the state of a user’s shopping cart across requests. Web-based applications are responsible for maintaining such state, called a session, because HTTP is stateless. To support applications that need to maintain state, Java Servlet technology provides an API for managing sessions and allows several mechanisms for implementing sessions. <a name="bnagn"></a><h4>Accessing a Session</h4> <a name="indexterm-294"></a><a name="indexterm-295"></a>Sessions are represented by an <a href="http://java.sun.com/javaee/5/docs/api/javax/servlet/http/HttpSession.html">HttpSession</a> object. You access a session by calling the <tt>getSession</tt> method of a request object. This method returns the current session associated with this request, or, if the request does not have a session, it creates one. <a name="bnago"></a><h4>Associating Objects with a Session</h4> <a name="indexterm-296"></a>You can associate object-valued attributes with a session by name. Such attributes are accessible by any web component that belongs to the same web context and is handling a request that is part of the same session.The Duke’s Bookstore application stores a customer’s shopping cart as a session attribute. This allows the shopping cart to be saved between requests and also allows cooperating servlets to access the cart. <tt>CatalogServlet</tt> adds items to the cart; <tt>ShowCartServlet</tt> displays, deletes items from, and clears the cart; and <tt>CashierServlet</tt> retrieves the total cost of the books in the cart.<pre>public class CashierServlet extends HttpServlet { public void doGet (HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { // Get the user’s session and shopping cart HttpSession session = request.getSession(); ShoppingCart cart = (ShoppingCart)session. getAttribute("cart"); ... // Determine the total price of the user’s books double total = cart.getTotal();</pre> <a name="bnagp"></a><h5>Notifying Objects That Are Associated with a Session</h5> <a name="indexterm-297"></a>Recall that your application can notify web context and session listener objects of servlet life-cycle events (<a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnafi.html#bnafj">Handling Servlet Life-Cycle Events</a>). You can also notify objects of certain events related to their association with a session such as the following: <ul><li>When the object is added to or removed from a session. To receive this notification, your object must implement the <a href="http://java.sun.com/javaee/5/docs/api/javax/servlet/http/HttpSessionBindingListener.html">javax.servlet.http.HttpSessionBindingListener</a> interface.</li> <li>When the session to which the object is attached will be passivated or activated. A session will be passivated or activated when it is moved between virtual machines or saved to and restored from persistent storage. To receive this notification, your object must implement the <a href="http://java.sun.com/javaee/5/docs/api/javax/servlet/http/HttpSessionActivationListener.html">javax.servlet.http.HttpSessionActivationListener</a> interface.</li></ul> <a name="bnagq"></a><h4>Session Management</h4> Because there is no way for an HTTP client to signal that it no longer needs a session, each session has an associated timeout so that its resources can be reclaimed. The timeout period can be accessed by using a session’s <tt>[get|set]MaxInactiveInterval</tt> methods. You can also set the timeout period in the deployment descriptor using NetBeans IDE: <ol><li>Open the <tt>web.xml</tt> file in the <tt>web.xml</tt> editor.</li> <li>Click General at the top of the editor.</li> <li>Enter an integer value in the Session Timeout field. The integer value represents the number of minutes of inactivity that must pass before the session times out.</li></ol> To ensure that an active session is not timed out, you should periodically access the session by using service methods because this resets the session’s time-to-live counter.<a name="indexterm-298"></a><a name="indexterm-299"></a>When a particular client interaction is finished, you use the session’s <tt>invalidate</tt> method to invalidate a session on the server side and remove any session data. The bookstore application’s <tt>ReceiptServlet</tt> is the last servlet to access a client’s session, so it has the responsibility to invalidate the session:<pre>public class ReceiptServlet extends HttpServlet { public void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { // Get the user’s session and shopping cart HttpSession session = request.getSession(); // Payment received -- invalidate the session session.invalidate(); ...</pre> <a name="bnagr"></a><h4>Session Tracking</h4> <a name="indexterm-300"></a>A web container can use several methods to associate a session with a user, all of which involve passing an identifier between the client and the server. The identifier can be maintained on the client as a cookie, or the web component can include the identifier in every URL that is returned to the client.If your application uses session objects, you must ensure that session tracking is enabled by having the application rewrite URLs whenever the client turns off cookies. You do this by calling the response’s <tt>encodeURL(URL)</tt> method on all URLs returned by a servlet. This method includes the session ID in the URL only if cookies are disabled; otherwise, it returns the URL unchanged.The <tt>doGet</tt> method of <tt>ShowCartServlet</tt> encodes the three URLs at the bottom of the shopping cart display page as follows:<pre>out.println(" &nbsp; <a href=\"" + response.encodeURL(request.getContextPath() + "/bookcatalog") + "\">" + messages.getString("ContinueShopping") + "</a> &nbsp; &nbsp; &nbsp;" + "<a href=\"" + response.encodeURL(request.getContextPath() + "/bookcashier") + "\">" + messages.getString("Checkout") + "</a> &nbsp; &nbsp; &nbsp;" + "<a href=\"" + response.encodeURL(request.getContextPath() + "/bookshowcart?Clear=clear") + "\">" + messages.getString("ClearCart") + "</a>");</pre>If cookies are turned off, the session is encoded in the Check Out URL as follows:<pre>http://localhost:8080/bookstore1/cashier;jsessionid=c0o7fszeb1</pre>If cookies are turned on, the URL is simply<pre>http://localhost:8080/bookstore1/cashier</pre> January 20, 2008 Finalizing a Servlet When a servlet container determines that a servlet should be removed from service (for example, when a container wants to reclaim memory resources or when it is being shut down), the container calls the <tt>destroy</tt> method of the <tt>Servlet</tt> interface. In this method, you release any resources the servlet is using and save any persistent state. The following <tt>destroy</tt> method releases the database object created in the <tt>init</tt> method described in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnafu.html"> Initializing a Servlet</a>: <pre>public void destroy() { bookDB = null; }</pre> All of a servlet’s service methods should be complete when a servlet is removed. The server tries to ensure this by calling the <tt>destroy</tt> method only after all service requests have returned or after a server-specific grace period, whichever comes first. If your servlet has operations that take a long time to run (that is, operations that may run longer than the server’s grace period), the operations could still be running when <tt>destroy</tt> is called. You must make sure that any threads still handling client requests complete; the remainder of this section describes how to do the following: <ul> <li> Keep track of how many threads are currently running the <tt>service</tt> method. </li> <li> Provide a clean shutdown by having the <tt>destroy</tt> method notify long-running threads of the shutdown and wait for them to complete. </li> <li> Have the long-running methods poll periodically to check for shutdown and, if necessary, stop working, clean up, and return. </li> </ul> <a name="bnagt"></a> <h4>Tracking Service Requests</h4> <a name="indexterm-303"></a>To track service requests, include in your servlet class a field that counts the number of service methods that are running. The field should have synchronized access methods to increment, decrement, and return its value. <pre>public class ShutdownExample extends HttpServlet { private int serviceCounter = 0; ... // Access methods for serviceCounter protected synchronized void enteringServiceMethod() { serviceCounter++; } protected synchronized void leavingServiceMethod() { serviceCounter--; } protected synchronized int numServices() { return serviceCounter; } }</pre> The <tt>service</tt> method should increment the service counter each time the method is entered and should decrement the counter each time the method returns. This is one of the few times that your <tt>HttpServlet</tt> subclass should override the <tt>service</tt> method. The new method should call <tt>super.service</tt> to preserve the functionality of the original <tt>service</tt> method: <pre>protected void service(HttpServletRequest req, HttpServletResponse resp) throws ServletException,IOException { enteringServiceMethod(); try { super.service(req, resp); } finally { leavingServiceMethod(); } }</pre> <a name="bnagu"></a> <h4>Notifying Methods to Shut Down</h4> <a name="indexterm-304"></a>To ensure a clean shutdown, your <tt>destroy</tt> method should not release any shared resources until all the service requests have completed. One part of doing this is to check the service counter. Another part is to notify the long-running methods that it is time to shut down. For this notification, another field is required. The field should have the usual access methods: <pre>public class ShutdownExample extends HttpServlet { private boolean shuttingDown; ... //Access methods for shuttingDown protected synchronized void setShuttingDown(boolean flag) { shuttingDown = flag; } protected synchronized boolean isShuttingDown() { return shuttingDown; } }</pre> Here is an example of the <tt>destroy</tt> method using these fields to provide a clean shutdown: <pre>public void destroy() { /* Check to see whether there are still service methods /* /* running, and if there are, tell them to stop. */ if (numServices() > 0) { setShuttingDown(true); } /* Wait for the service methods to stop. */ while(numServices() > 0) { try { Thread.sleep(interval); } catch (InterruptedException e) { } } }</pre> <a name="bnagv"></a> <h4>Creating Polite Long-Running Methods</h4> <a name="indexterm-305"></a>The final step in providing a clean shutdown is to make any long-running methods behave politely. Methods that might run for a long time should check the value of the field that notifies them of shutdowns and should interrupt their work, if necessary. <pre>public void doPost(...) { ... for(i = 0; ((i < lotsOfStuffToDo) && !isShuttingDown()); i++) { try { partOfLongRunningOperation(i); } catch (InterruptedException e) { ... } } }</pre> January 20, 2008 JavaServer Pages Technology JavaServer Pages (JSP) technology allows you to easily create web content that has both static and dynamic components. JSP technology makes available all the dynamic capabilities of Java Servlet technology but provides a more natural approach to creating static content. The main features of JSP technology are as follows: <ul><li>A language for developing JSP pages, which are text-based documents that describe how to process a request and construct a response</li> <li>An expression language for accessing server-side objects</li> <li>Mechanisms for defining extensions to the JSP language</li></ul> JSP technology also contains an API that is used by developers of web containers, but this API is not covered in this tutorial. January 20, 2008 What Is a JSP Page? A JSP page is a text document that contains two types of text: static data, which can be expressed in any text-based format (such as <a href="http://www.w3.org/MarkUp/">HTML</a>, <a href="http://www.w3.org/TR/SVG">SVG</a>, <a href="http://xml.coverpages.org/wap-wml.html">WML</a>, and <a href="http://www.w3.org/TR/REC-xml/">XML</a>), and JSP elements, which construct dynamic content.The recommended file extension for the source file of a JSP page is <tt>.jsp</tt>. The page can be composed of a top file that includes other files that contain either a complete JSP page or a fragment of a JSP page. The recommended extension for the source file of a fragment of a JSP page is <tt>.jspf</tt>.<a name="indexterm-309"></a><a name="indexterm-310"></a>The JSP elements in a JSP page can be expressed in two syntaxes, standard and XML, though any given file can use only one syntax. A JSP page in XML syntax is an XML document and can be manipulated by tools and APIs for XML documents. This chapter and Chapters <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnakc.html">Chapter 7, JavaServer Pages Standard Tag Library</a> through <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnaon.html">Chapter 9, Scripting in JSP Pages</a> document only the standard syntax. The XML syntax is covered in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnajo.html">Chapter 6, JavaServer Pages Documents</a>. <a name="bnagz"></a><h4>A Simple JSP Page Example</h4> The web page in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnagy.html#bnaha">Figure 5-1</a> is a form that allows you to select a locale and displays the date in a manner appropriate to the locale.<a name="bnaha"></a><h6>Figure 5-1 Localized Date Form</h6><img src="http://java.sun.com/javaee/5/docs/tutorial/doc/figures/web-dateForm.gif" alt="Screen capture of localized date form. Locale drop-down shows Lithuanian. Get Date button displays the date, " antradienis,="" 2004,="" kovo="" 16.="" height="237" width="662"><a name="indexterm-311"></a>The source code for this example is in the <tt></tt>tut-install<tt>/javaeetutorial5/examples/web/date/</tt> directory. The JSP page, <tt>index.jsp</tt>, appears below; it is a typical mixture of static HTML markup and JSP elements. If you have developed web pages, you are probably familiar with the HTML document structure statements (<tt><head></tt>, <tt><body></tt>, and so on) and the HTML statements that create a form (<tt><form></tt>) and a menu (<tt><select></tt>).The lines in bold in the example code contain the following types of JSP constructs: <ul><li>A page directive (<tt><%@page ... %></tt>) sets the content type returned by the page.</li> <li>Tag library directives (<tt><%@taglib ... %></tt>) import custom tag libraries.</li> <li><tt>jsp:useBean</tt> is a standard element that creates an object containing a collection of locales and initializes an identifier that points to that object.</li> <li>JSP expression language expressions (<tt>${ }</tt>) retrieve the value of object properties. The values are used to set custom tag attribute values and create dynamic content.</li> <li>Custom tags (see <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnalj.html">Chapter 8, Custom Tags in JSP Pages</a>) set a variable (<tt>c:set</tt>), iterate over a collection of locale names (<tt>c:forEach</tt>), and conditionally insert HTML text into the response (<tt>c:if</tt>, <tt>c:choose</tt>, <tt>c:when</tt>, <tt>c:otherwise</tt>).</li> <li><tt>jsp:setProperty</tt> is another standard element that sets the value of an object property.</li> <li>A function (<tt>f:equals</tt>) tests the equality of an attribute and the current item of a collection. (A built-in <tt>==</tt> operator is usually used to test equality.)</li></ul> Here is the JSP page:<pre><%@ page contentType="text/html; charset=UTF-8" %> <%@ taglib uri="http://java.sun.com/jsp/jstl/core " prefix="c" %> <%@ taglib uri="/functions" prefix="f" %> <html> <head><title>Localized Dates</title></head> <body bgcolor="white"> <jsp:useBean id="locales" scope="application" class="mypkg.MyLocales"/> <form name="localeForm" action="index.jsp" method="post"> <c:set var="selectedLocaleString" value="${param.locale}" /> <c:set var="selectedFlag" value="${!empty selectedLocaleString}" /> Locale: <select name=locale> <c:forEach var="localeString" items="${locales.localeNames}" > <c:choose> <c:when test="${selectedFlag}"> <c:choose> <c:when test="${f:equals(selectedLocaleString, localeString)}" > <option selected>${localeString}</option> </c:when> <c:otherwise> <option>${localeString}</option> </c:otherwise> </c:choose> </c:when> <c:otherwise> <option>${localeString}</option> </c:otherwise> </c:choose> </c:forEach> </select> <input type="submit" name="Submit" value="Get Date"> </form> <c:if test="${selectedFlag}" > <jsp:setProperty name="locales" property="selectedLocaleString" value="${selectedLocaleString}" /> <jsp:useBean id="date" class="mypkg.MyDate"/> <jsp:setProperty name="date" property="locale" value="${locales.selectedLocale}"/> Date: ${date.date}</c:if> </body> </html></pre>To deploy the <tt>date</tt> application with NetBeans IDE, follow these steps: <ol><li>Start the Application Server.</li> <li>In NetBeans IDE, select File→Open Project.</li> <li>In the Open Project dialog, navigate to:<pre>tut-install/javaeetutorial5/examples/web/</pre></li> <li>Select the <tt>date</tt> folder.</li> <li>Select the Open as Main Project check box.</li> <li>Click Open Project Folder.</li> <li>In the Projects tab, right-click the <tt>date</tt> project, and select Deploy Project.</li></ol> To deploy the <tt>date</tt> application with the Ant tool, follow these steps: <ol><li>In a terminal window, go to <tt></tt>tut-install<tt>/javaeetutorial5/examples/web/date/</tt>.</li> <li>Type <tt>ant</tt>. This command will spawn any necessary compilations, copy files to the <tt></tt>tut-install<tt>/javaeetutorial5/examples/web/date/build/</tt> directory, and create a WAR file.</li> <li>Start the Application Server.</li> <li>Type <tt>ant deploy</tt>.</li></ol> To run the example, do the following: <ol><li>Set the character encoding in your browser to UTF-8.</li> <li>Open your browser to <tt>http://localhost:8080/date</tt>.</li> <li>You will see a combo box whose entries are locales. Select a locale and click Get Date. You will see the date expressed in a manner appropriate for that locale.</li></ol> Some of the characters might not display properly if you don’t have the appropriate language files installed on your machine. Consult the user guide or online help for your operating system to determine how you can install these language files. January 20, 2008 The Example JSP Pages To illustrate JSP technology, this chapter rewrites each servlet in the Duke’s Bookstore application introduced in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnaff.html">The Example Servlets</a> as a JSP page (see <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnahb.html#bnahc">Table 5-1</a>).<a name="bnahc"></a><h6>Table 5-1 Duke’s Bookstore Example JSP Pages</h6><table ID="Table1"><col width="171*"><col width="179*"><tbody><tr><th align="left" valign="top">Function</th> <th align="left" valign="top">JSP Pages</th> </tr> <tr><td align="left" valign="top">Enter the bookstore.</td> <td align="left" valign="top"><tt>bookstore.jsp</tt></td> </tr> <tr><td align="left" valign="top">Create the bookstore banner.</td> <td align="left" valign="top"><tt>banner.jsp</tt></td> </tr> <tr><td align="left" valign="top">Browse the books offered for sale.</td> <td align="left" valign="top"><tt>bookcatalog.jsp</tt></td> </tr> <tr><td align="left" valign="top">Add a book to the shopping cart.</td> <td align="left" valign="top"><tt>bookcatalog.jsp</tt> and <tt>bookdetails.jsp</tt></td> </tr> <tr><td align="left" valign="top">Get detailed information on a specific book.</td> <td align="left" valign="top"><tt>bookdetails.jsp</tt></td> </tr> <tr><td align="left" valign="top">Display the shopping cart.</td> <td align="left" valign="top"><tt>bookshowcart.jsp</tt></td> </tr> <tr><td align="left" valign="top">Remove one or more books from the shopping cart.</td> <td align="left" valign="top"><tt>bookshowcart.jsp</tt></td> </tr> <tr><td align="left" valign="top">Buy the books in the shopping cart.</td> <td align="left" valign="top"><tt>bookcashier.jsp</tt></td> </tr> <tr><td align="left" valign="top">Receive an acknowledgment for the purchase.</td> <td align="left" valign="top"><tt>bookreceipt.jsp</tt></td> </tr> </tbody></table>The data for the bookstore application is still maintained in a database and is accessed through <tt></tt>tut-install<tt>/javaeetutorial5/examples/web/bookstore2/src/java/com/sun/bookstore2/database/BookDBAO.java</tt>. However, the JSP pages access <tt>BookDBAO</tt> through the JavaBeans component <tt></tt>tut-install<tt>/javaeetutorial5/examples/web/bookstore2/src/java/com/sun/bookstore2/database/BookDB.java</tt>. This class allows the JSP pages to use JSP elements designed to work with JavaBeans components (see <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnair.html#bnais">JavaBeans Component Design Conventions</a>).The implementation of the database bean follows. The bean has two instance variables: the current book and the data access object.<pre>package database; public class BookDB { private String bookId = "0"; private BookDBAO database = null; public BookDB () throws Exception { } public void setBookId(String bookId) { this.bookId = bookId; } public void setDatabase(BookDAO database) { this.database = database; } public Book getBook() throws Exception { return (Book)database.getBook(bookId); } ... }</pre><a name="indexterm-314"></a><a name="indexterm-315"></a>This version of the Duke’s Bookstore application is organized along the Model-View-Controller (MVC) architecture. The MVC architecture is a widely used architectural approach for interactive applications that distributes functionality among application objects so as to minimize the degree of coupling between the objects. To achieve this, it divides applications into three layers: model, view, and controller. Each layer handles specific tasks and has responsibilities to the other layers: <ul><li>The model represents business data, along with business logic or operations that govern access and modification of this business data. The model notifies views when it changes and lets the view query the model about its state. It also lets the controller access application functionality encapsulated by the model. In the Duke’s Bookstore application, the shopping cart and database access object contain the business logic for the application.</li> <li>The view renders the contents of a model. It gets data from the model and specifies how that data should be presented. It updates data presentation when the model changes. A view also forwards user input to a controller. The Duke’s Bookstore JSP pages format the data stored in the session-scoped shopping cart and the page-scoped database bean.</li> <li>The controller defines application behavior. It dispatches user requests and selects views for presentation. It interprets user inputs and maps them into actions to be performed by the model. In a web application, user inputs are HTTP <tt>GET</tt> and <tt>POST</tt> requests. A controller selects the next view to display based on the user interactions and the outcome of the model operations. In the Duke’s Bookstore application, the <tt>Dispatcher</tt> servlet is the controller. It examines the request URL, creates and initializes a session-scoped JavaBeans component (the shopping cart), and dispatches requests to view JSP pages.</li></ul> <hr>Note - When employed in a web application, the MVC architecture is often referred to as a Model-2 architecture. The bookstore example discussed in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnafd.html">Chapter 4, Java Servlet Technology</a>, which intermixes presentation and business logic, follows what is known as a Model-1 architecture. The Model-2 architecture is the recommended approach to designing web applications. <hr> <a name="indexterm-316"></a>In addition, this version of the application uses several custom tags from the JavaServer Pages Standard Tag Library (JSTL), described in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnakc.html">Chapter 7, JavaServer Pages Standard Tag Library</a>: <ul><li><tt>c:if</tt>, <tt>c:choose</tt>, <tt>c:when</tt>, and <tt>c:otherwise</tt> for flow control</li> <li><tt>c:set</tt> for setting scoped variables</li> <li><tt>c:url</tt> for encoding URLs</li> <li><tt>fmt:message</tt>, <tt>fmt:formatNumber</tt>, and <tt>fmt:formatDate</tt> for providing locale-sensitive messages, numbers, and dates</li></ul> Custom tags are the preferred mechanism for performing a wide variety of dynamic processing tasks, including accessing databases, using enterprise services such as email and directories, and implementing flow control. In earlier versions of JSP technology, such tasks were performed with JavaBeans components in conjunction with scripting elements (discussed in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnaon.html">Chapter 9, Scripting in JSP Pages</a>). Although still available in JSP 2.0 technology, scripting elements tend to make JSP pages more difficult to maintain because they mix presentation and logic, something that is discouraged in page design. Custom tags are introduced in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnaiy.html">Using Custom Tags</a> and described in detail in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnalj.html">Chapter 8, Custom Tags in JSP Pages</a>.Finally, this version of the example contains an applet to generate a dynamic digital clock in the banner. See <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnaje.html">Including an Applet</a> for a description of the JSP element that generates HTML for downloading the applet.To deploy and run the application using NetBeans IDE, follow these steps: <ol><li>Perform all the operations described in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnaez.html">Accessing Databases from Web Applications</a>.</li> <li>In NetBeans IDE, select File→Open Project.</li> <li>In the Open Project dialog, navigate to:<pre>tut-install/javaeetutorial5/examples/web/</pre></li> <li>Select the <tt>bookstore2</tt> folder.</li> <li>Select the Open as Main Project check box and the Open Required Projects check box.</li> <li>Click Open Project Folder.</li> <li>In the Projects tab, right-click the <tt>bookstore2</tt> project, and select Deploy Project.</li> <li>To run the application, open the bookstore URL <tt>http://localhost:8080/bookstore2/books/bookstore</tt>.</li></ol> To deploy and run the application using Ant, follow these steps: <ol><li>In a terminal window, go to <tt></tt>tut-install<tt>/javaeetutorial5/examples/web/bookstore2/</tt>.</li> <li>Type <tt>ant</tt>. This command will spawn any necessary compilations, copy files to the <tt></tt>tut-install<tt>/javaeetutorial5/examples/web/bookstore2/build/</tt> directory, and create a WAR file and copy it to the <tt></tt>tut-install<tt>/javaeetutorial5/examples/web/bookstore2/dist/</tt> directory.</li> <li>Start the Application Server.</li> <li>Perform all the operations described in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnaez.html#bnafb">Creating a Data Source in the Application Server</a>.</li> <li>To deploy the example, type <tt>ant deploy</tt>. The deploy target outputs a URL for running the application. Ignore this URL, and instead use the one shown in the next step.</li> <li>To run the application, open the bookstore URL <tt>http://localhost:8080/bookstore2/books/bookstore</tt>.</li></ol> To learn how to configure the example, refer to the deployment descriptor (the <tt>web.xml</tt> file), which includes the following configurations: <ul><li>A <tt>display-name</tt> element that specifies the name that tools use to identify the application.</li> <li>A <tt>context-param</tt> element that specifies the JSTL resource bundle base name.</li> <li>A <tt>listener</tt> element that identifies the <tt>ContextListener</tt> class used to create and remove the database access.</li> <li>A <tt>servlet</tt> element that identifies the <tt>Dispatcher</tt> servlet instance.</li> <li>A set of <tt>servlet-mapping</tt> elements that map <tt>Dispatcher</tt> to URL patterns for each of the JSP pages in the application.</li> <li>Nested inside a <tt>jsp-config</tt> element are two <tt>jsp-property-group</tt> elements, which define the preludes and coda to be included in each page. See <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnajg.html">Setting Properties for Groups of JSP Pages</a> for more information.</li></ul> <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnahb.html#bnahd">Figure 5-2</a> shows the <tt>bookcatalog.jsp</tt> page from the Duke’s Bookstore application. This page displays a list of all the books that are available for purchase.<a name="bnahd"></a><h6>Figure 5-2 Book Catalog</h6><img src="http://java.sun.com/javaee/5/docs/tutorial/doc/figures/web-bookCatalog1.gif" alt="Screen capture of Duke‘s Bookstore book catalog, with titles, authors, prices, and " add="" cart="" links.="" titles="" are="" links="" to="" book="" details.="" height="867" width="662">See <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnaff.html#bnafh">Troubleshooting Duke‘s Bookstore Database Problems</a> for help with diagnosing common problems related to the database server. If the messages in your pages appear as strings of the form <tt>???</tt> <tt>Key</tt> <tt>???</tt>, the likely cause is that you have not provided the correct resource bundle base name as a context parameter. January 20, 2008 The Life Cycle of a JSP Page A JSP page services requests as a servlet. Thus, the life cycle and many of the capabilities of JSP pages (in particular the dynamic aspects) are determined by Java Servlet technology. You will notice that many sections in this chapter refer to classes and methods described in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnafd.html">Chapter 4, Java Servlet Technology</a>.<a name="indexterm-318"></a><a name="indexterm-319"></a>When a request is mapped to a JSP page, the web container first checks whether the JSP page’s servlet is older than the JSP page. If the servlet is older, the web container translates the JSP page into a servlet class and compiles the class. During development, one of the advantages of JSP pages over servlets is that the build process is performed automatically. <a name="bnahf"></a><h4>Translation and Compilation</h4> <a name="indexterm-320"></a>During the translation phase each type of data in a JSP page is treated differently. Static data is transformed into code that will emit the data into the response stream. JSP elements are treated as follows: <ul><li><a name="indexterm-321"></a>Directives are used to control how the web container translates and executes the JSP page.</li> <li>Scripting elements are inserted into the JSP page’s servlet class. See <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnaon.html">Chapter 9, Scripting in JSP Pages</a> for details.</li> <li>Expression language expressions are passed as parameters to calls to the JSP expression evaluator.</li> <li><tt>jsp:[set|get]Property</tt> elements are converted into method calls to JavaBeans components.</li> <li><tt>jsp:[include|forward]</tt>elements are converted into invocations of the Java Servlet API.</li> <li>The <tt>jsp:plugin</tt> element is converted into browser-specific markup for activating an applet.</li> <li>Custom tags are converted into calls to the tag handler that implements the custom tag.</li></ul> In the Application Server, the source for the servlet created from a JSP page named pageName is in this file:<pre>domain-dir/generated/jsp/j2ee-modules/WAR-NAME/pageName_jsp.java</pre>For example, the source for the index page (named <tt>index.jsp</tt>) for the <tt>date</tt> localization example discussed at the beginning of the chapter would be named:<pre><tt></tt>domain-dir<tt>/generated/jsp/j2ee-modules/date/index_jsp.java</tt></pre><a name="indexterm-322"></a><a name="indexterm-323"></a>Both the translation and the compilation phases can yield errors that are observed only when the page is requested for the first time. If an error is encountered during either phase, the server will return <tt>JasperException</tt> and a message that includes the name of the JSP page and the line where the error occurred.After the page has been translated and compiled, the JSP page’s servlet (for the most part) follows the servlet life cycle described in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnafi.html">Servlet Life Cycle</a>: <ol><li>If an instance of the JSP page’s servlet does not exist, the container: <ol><li>Loads the JSP page’s servlet class</li> <li>Instantiates an instance of the servlet class</li> <li>Initializes the servlet instance by calling the <tt>jspInit</tt> method</li></ol> </li> <li>The container invokes the <tt>_jspService</tt> method, passing request and response objects.</li></ol> If the container needs to remove the JSP page’s servlet, it calls the <tt>jspDestroy</tt> method. <a name="bnahg"></a><h4>Execution</h4> <a name="indexterm-324"></a><a name="indexterm-325"></a>You can control various JSP page execution parameters by using <tt>page</tt> directives. The directives that pertain to buffering output and handling errors are discussed here. Other directives are covered in the context of specific page-authoring tasks throughout the chapter. <a name="bnahh"></a><h5>Buffering</h5> <a name="indexterm-326"></a>When a JSP page is executed, output written to the response object is automatically buffered. You can set the size of the buffer using the following page directive:<pre><%@ page buffer="none|xxxkb" %></pre>A larger buffer allows more content to be written before anything is actually sent back to the client, thus providing the JSP page with more time to set appropriate status codes and headers or to forward to another web resource. A smaller buffer decreases server memory load and allows the client to start receiving data more quickly. <a name="bnahi"></a><h5>Handling JSP Page Errors</h5> <a name="indexterm-327"></a>Any number of exceptions can arise when a JSP page is executed. To specify that the web container should forward control to an error page if an exception occurs, include the following <tt>page</tt> directive at the beginning of your JSP page:<pre><%@ page errorPage="file-name" %></pre>The Duke’s Bookstore application page <tt></tt>tut-install<tt>/javaeetutorial5/examples/web/bookstore2/web/template/preludeErrorPage.jspf</tt> contains the directive:<pre><%@ page errorPage="errorpage.jsp"%></pre><a name="indexterm-328"></a>The following page directive at the beginning of tut-install<tt>/javaeetutorial5/examples/web/bookstore2/web/error/errorpage.jsp</tt> indicates that it is serving as an error page:<pre><%@ page isErrorPage="true" %></pre>This directive makes an object of type <a href="http://java.sun.com/javaee/5/docs/api/javax/servlet/jsp/ErrorData.html">javax.servlet.jsp.ErrorData</a> available to the error page so that you can retrieve, interpret, and possibly display information about the cause of the exception in the error page. You access the error data object in an EL (see <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnahq.html">Unified Expression Language</a>) expression by way of the page context. Thus, <tt>${pageContext.errorData.statusCode}</tt> retrieves the status code, and <tt>${pageContext.errorData.throwable}</tt> retrieves the exception. You can retrieve the cause of the exception using this expression:<pre>${pageContext.errorData.throwable.cause}</pre>For example, the error page for Duke’s Bookstore is as follows:<pre><%@ page isErrorPage="true" %> <%@ taglib uri="http://java.sun.com/jsp/jstl/core" prefix="c" %> <%@ taglib uri="http://java.sun.com/jsp/jstl/fmt" prefix="fmt" %> <html> <head> <title><fmt:message key="ServerError"/></title> </head> <body bgcolor="white"> <h3> <fmt:message key="ServerError"/> </h3> : ${pageContext.errorData.throwable.cause} </body> </html></pre> <hr>Note - <a name="indexterm-329"></a><a name="indexterm-330"></a>You can also define error pages for the WAR that contains a JSP page. If error pages are defined for both the WAR and a JSP page, the JSP page’s error page takes precedence. January 20, 2008 Creating Static Content You create static content in a JSP page simply by writing it as if you were creating a page that consisted only of that content. Static content can be expressed in any text-based format, such as HTML, Wireless Markup Language (WML), and XML. The default format is HTML. If you want to use a format other than HTML, at the beginning of your JSP page you include a <tt>page</tt> directive with the <tt>contentType</tt> attribute set to the content type. The purpose of the <tt>contentType</tt> directive is to allow the browser to correctly interpret the resulting content. So if you wanted a page to contain data expressed in WML, you would include the following directive:<pre><%@ page contentType="text/vnd.wap.wml"%></pre>A registry of content type names is kept by the IANA at <a href="http://www.iana.org/assignments/media-types/">http://www.iana.org/assignments/media-types/</a>. <a name="bnahk"></a><h4>Response and Page Encoding</h4> <a name="indexterm-332"></a>You also use the <tt>contentType</tt> attribute to specify the encoding of the response. For example, the date application specifies that the page should be encoded using UTF-8, an encoding that supports almost all locales, using the following <tt>page</tt> directive:<pre><%@ page contentType="text/html; charset=UTF-8" %></pre>If the response encoding weren’t set, the localized dates would not be rendered correctly.<a name="indexterm-333"></a>To set the source encoding of the page itself, you would use the following <tt>page</tt> directive:<pre><%@ page pageEncoding="UTF-8" %></pre>You can also set the page encoding of a set of JSP pages. The value of the page encoding varies depending on the configuration specified in the JSP configuration section of the web application deployment descriptor (see <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnajg.html#bnajk">Declaring Page Encodings</a>). January 20, 2008 Creating Dynamic Content You create dynamic content by accessing Java programming language object properties. <a name="bnahm"></a><h4>Using Objects within JSP Pages</h4> You can access a variety of objects, including enterprise beans and JavaBeans components, within a JSP page. JSP technology automatically makes some objects available, and you can also create and access application-specific objects. <a name="bnahn"></a><h5>Using Implicit Objects</h5> <a name="indexterm-335"></a>Implicit objects are created by the web container and contain information related to a particular request, page, session, or application. Many of the objects are defined by the Java servlet technology underlying JSP technology and are discussed at length in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnafd.html">Chapter 4, Java Servlet Technology</a>. The section <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnahq.html#bnaij">Implicit Objects</a> explains how you access implicit objects using the JSP expression language. <a name="bnaho"></a><h5>Using Application-Specific Objects</h5> <a name="indexterm-336"></a>When possible, application behavior should be encapsulated in objects so that page designers can focus on presentation issues. Objects can be created by developers who are proficient in the Java programming language and in accessing databases and other services. The main way to create and use application-specific objects within a JSP page is to use JSP standard tags (discussed in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnair.html">JavaBeans Components</a>) to create JavaBeans components and set their properties, and EL expressions to access their properties. You can also access JavaBeans components and other objects in scripting elements, which are described in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnaon.html">Chapter 9, Scripting in JSP Pages</a>. <a name="bnahp"></a><h5>Using Shared Objects</h5> <a name="indexterm-337"></a>The conditions affecting concurrent access to shared objects (described in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnafo.html#bnafs">Controlling Concurrent Access to Shared Resources</a>) apply to objects accessed from JSP pages that run as multithreaded servlets. You can use the following <tt>page</tt> directive to indicate how a web container should dispatch multiple client requests:<pre><%@ page isThreadSafe="true|false" %></pre><a name="indexterm-338"></a>When the <tt>isThreadSafe</tt> attribute is set to <tt>true</tt>, the web container can choose to dispatch multiple concurrent client requests to the JSP page. This is the default setting. If using <tt>true</tt>, you must ensure that you properly synchronize access to any shared objects defined at the page level. This includes objects created within declarations, JavaBeans components with page scope, and attributes of the page context object (see <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnahq.html#bnaij">Implicit Objects</a>).If <tt>isThreadSafe</tt> is set to <tt>false</tt>, requests are dispatched one at a time in the order they were received, and access to page-level objects does not have to be controlled. However, you still must ensure that access is properly synchronized to attributes of the <tt>application</tt> or <tt>session</tt> scope objects and to JavaBeans components with application or session scope. Furthermore, it is not recommended to set <tt>isThreadSafe</tt> to <tt>false</tt>. The JSP page’s generated servlet will implement the <tt>javax.servlet.SingleThreadModel</tt> interface, and because the Servlet 2.4 specification deprecates <tt>SingleThreadModel</tt>, the generated servlet will contain deprecated code. January 20, 2008 Unified Expression Language The primary new feature of JSP 2.1 is the unified expression language (unified EL), which represents a union of the expression language offered by JSP 2.0 and the expression language created for JavaServer Faces technology (see <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnaph.html">Chapter 10, JavaServer Faces Technology</a>) version 1.0.The expression language introduced in JSP 2.0 allows page authors to use simple expressions to dynamically read data from JavaBeans components. For example, the <tt>test</tt> attribute of the following conditional tag is supplied with an EL expression that compares the number of items in the session-scoped bean named <tt>cart</tt> with 0.<pre><c:if test="${sessionScope.cart.numberOfItems > 0}"> ... </c:if></pre>As explained in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnahe.html">The Life Cycle of a JSP Page</a>, JSP supports a simple request/response life cycle, during which a page is executed and the HTML markup is rendered immediately. Therefore, the simple, read-only expression language offered by JSP 2.0 was well suited to the needs of JSP applications.<a name="indexterm-340"></a>JavaServer Faces technology, on the other hand, features a multiphase life cycle designed to support its sophisticated UI component model, which allows for converting and validating component data, propagating component data to objects, and handling component events. To facilitate these functions, JavaServer Faces technology introduced its own expression language that included the following functionality: <ul><li>Deferred evaluation of expressions</li> <li>The ability to set data as well as get data</li> <li>The ability to invoke methods</li></ul> See <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnaqm.html#bnaqp">Using the Unified EL to Reference Backing Beans</a> for more information on how to use the unified EL in JavaServer Faces applications.These two expression languages have been unified for a couple reasons. One reason is so that page authors can mix JSP content with JavaServer Faces tags without worrying about conflicts caused by the different life cycles these technologies support. Another reason is so that other JSP-based technologies could make use of the additional features similarly to the way JavaServer Faces technology uses them. In fact, although the standard JSP tags and static content continue to use only those features present in JSP 2.0, authors of JSP custom tags can create tags that take advantage of the new set of features in the unified expression language.To summarize, the new, unified expression language allows page authors to use simple expressions to perform the following tasks: <ul><li>Dynamically read application data stored in JavaBeans components, various data structures, and implicit objects</li> <li>Dynamically write data, such as user input into forms, to JavaBeans components</li> <li>Invoke arbitrary static and public methods</li> <li>Dynamically perform arithmetic operations</li></ul> The unified EL also allows custom tag developers to specify which of the following kinds of expressions that a custom tag attribute will accept: <ul><li><a name="indexterm-341"></a><a name="indexterm-342"></a>Immediate evaluation expressions or deferred evaluation expressions. An immediate evaluation expression is evaluated immediately by the JSP engine. A deferred evaluation expression can be evaluated later by the underlying technology using the expression language.</li> <li><a name="indexterm-343"></a><a name="indexterm-344"></a>Value expression or method expression. A value expression references data, whereas a method expression invokes a method.</li> <li><a name="indexterm-345"></a><a name="indexterm-346"></a>Rvalue expression or Lvalue expression. An rvalue expression can only read a value, whereas an lvalue expression can both read and write that value to an external object.</li></ul> Finally, the unified EL also provides a pluggable API for resolving expressions so that application developers can implement their own resolvers that can handle expressions not already supported by the unified EL.This section gives an overview of the unified expression language features by explaining the following topics: <ul><li><a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnahq.html#bnahr">Immediate and Deferred Evaluation Syntax</a></li> <li><a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnahq.html#bnahu">Value and Method Expressions</a></li> <li><a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnahq.html#bnaia">Defining a Tag Attribute Type</a></li> <li><a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnahq.html#bnaic">Deactivating Expression Evaluation</a></li> <li><a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnahq.html#bnaid">Literal Expressions</a></li> <li><a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnahq.html#bnaif">Resolving Expressions</a></li> <li><a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnahq.html#bnaij">Implicit Objects</a></li> <li><a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnahq.html#bnaik">Operators</a></li> <li><a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnahq.html#bnail">Reserved Words</a></li> <li><a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnahq.html#bnaim">Examples of EL Expressions</a></li> <li><a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnahq.html#bnaio">Functions</a></li></ul> <a name="bnahr"></a><h4>Immediate and Deferred Evaluation Syntax</h4> <a name="indexterm-347"></a><a name="indexterm-348"></a>The unified EL supports both immediate and deferred evaluation of expressions. Immediate evaluation means that the JSP engine evaluates the expression and returns the result immediately when the page is first rendered. Deferred evaluation means that the technology using the expression language can employ its own machinery to evaluate the expression sometime later during the page’s life cycle, whenever it is appropriate to do so.Those expressions that are evaluated immediately use the <tt>${}</tt> syntax, which was introduced with the JSP 2.0 expression language. Expressions whose evaluation is deferred use the <tt>#{}</tt> syntax, which was introduced by JavaServer Faces technology.Because of its multiphase life cycle, JavaServer Faces technology uses deferred evaluation expressions. During the life cycle, component events are handled, data is validated, and other tasks are performed, all done in a particular order. Therefore, it must defer evaluation of expressions until the appropriate point in the life cycle.Other technologies using the unified EL might have different reasons for using deferred expressions. <a name="bnahs"></a><h5>Immediate Evaluation</h5> All expressions using the <tt>${}</tt> syntax are evaluated immediately. These expressions can only be used within template text or as the value of a JSP tag attribute that can accept runtime expressions.The following example shows a tag whose value attribute references an immediate evaluation expression that gets the total price from the session-scoped bean named cart:<pre><fmt:formatNumber value="${sessionScope.cart.total}"/></pre>The JSP engine evaluates the expression, <tt>${sessionScope.cart.total}</tt>, converts it, and passes the returned value to the tag handler.Immediate evaluation expressions are always read-only value expressions. The expression shown above can only get the total price from the cart bean; it cannot set the total price. <a name="bnaht"></a><h5>Deferred Evaluation</h5> Deferred evaluation expressions take the form <tt>#{expr}</tt> and can be evaluated at other phases of a page life cycle as defined by whatever technology is using the expression. In the case of JavaServer Faces technology, its controller can evaluate the expression at different phases of the life cycle depending on how the expression is being used in the page.The following example shows a JavaServer Faces <tt>inputText</tt> tag, which represents a text field component into which a user enters a value. The <tt>inputText</tt> tag’s <tt>value</tt> attribute references a deferred evaluation expression that points to the <tt>name</tt> property of the <tt>customer</tt> bean.<pre><h:inputText id="name" value="#{customer.name}" /></pre>For an initial request of the page containing this tag, the JavaServer Faces implementation evaluates the <tt>#{customer.name}</tt> expression during the render response phase of the life cycle. During this phase, the expression merely accesses the value of <tt>name</tt> from the <tt>customer</tt> bean, as is done in immediate evaluation.For a postback, the JavaServer Faces implementation evaluates the expression at different phases of the life cycle, during which the value is retrieved from the request, validated, and propagated to the <tt>customer</tt> bean.As shown in this example, deferred evaluation expressions can be value expressions that can be used to both read and write data. They can also be method expressions. Value expressions (both immediate and deferred) and method expressions are explained in the next section. <a name="bnahu"></a><h4>Value and Method Expressions</h4> The unified EL defines two kinds of expressions: value expressions and method expressions. Value expressions can either yield a value or set a value. Method expressions reference methods that can be invoked and can return a value. <a name="bnahv"></a><h5>Value Expressions</h5> <a name="indexterm-349"></a><a name="indexterm-350"></a><a name="indexterm-351"></a>Value expressions can be further categorized into rvalue and lvalue expressions. Rvalue expressions are those that can read data, but cannot write it. Lvalue expressions can both read and write data.All expressions that are evaluated immediately use the <tt>${}</tt> delimiters and are always rvalue expressions. Expressions whose evaluation can be deferred use the <tt>#{}</tt> delimiters and can act as both rvalue and lvalue expressions. Consider these two value expressions:<pre><taglib:tag value="${customer.name}" /> <taglib:tag value="#{customer.name}" /></pre>The former uses immediate evaluation syntax, whereas the latter uses deferred evaluation syntax. The first expression accesses the <tt>name</tt> property, gets its value, and the value is added to the response and rendered on the page. The same thing can happen with the second expression. However, the tag handler can defer the evaluation of this expression to a later time in the page life cycle, if the technology using this tag allows it.In the case of JavaServer Faces technology, the latter tag’s expression is evaluated immediately during an initial request for the page. In this case, this expression acts as an rvalue expression. During a postback, this expression can be used to set the value of the <tt>name</tt> property with user input. In this situation, the expression acts as an lvalue expression. <a name="bnahw"></a><h5>Referencing Objects Using Value Expressions</h5> Both rvalue and lvalue expressions can refer to the following objects and their properties or attributes: <ul><li>JavaBeans components</li> <li>Collections</li> <li>Java SE enumerated types</li> <li>Implicit objects</li></ul> See <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnahq.html#bnaij">Implicit Objects</a> for more detail on the implicit objects available with JSP technology.To refer to these objects, you write an expression using a variable name with which you created the object. The following expression references a JavaBeans component called <tt>customer</tt>.<pre>${customer}</pre>The web container evaluates a variable that appears in an expression by looking up its value according to the behavior of <tt>PageContext.findAttribute(String)</tt>, where the <tt>String</tt> argument is the name of the variable. For example, when evaluating the expression <tt>${customer}</tt>, the container will look for <tt>customer</tt> in the page, request, session, and application scopes and will return its value. If <tt>customer</tt> is not found, null is returned. A variable that matches one of the implicit objects described in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnahq.html#bnaij">Implicit Objects</a> will return that implicit object instead of the variable’s value.You can alter the way variables are resolved with a custom EL resolver, which is a new feature of the unified EL. For instance, you can provide an EL resolver that intercepts objects with the name <tt>customer</tt>, so that <tt>${customer}</tt> returns a value in the EL resolver instead. However, you cannot override implicit objects in this way. See <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnahq.html#bnaih">EL Resolvers</a> for more information on EL resolvers.You can set the variable name, <tt>customer</tt>, when you declare the bean. See <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnair.html#bnait">Creating and Using a JavaBeans Component</a> for information on how to declare a JavaBeans component for use in your JSP pages.To declare beans in JavaServer Faces applications, you use the managed bean facility. See <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnaqm.html">Backing Beans</a> for information on how to declare beans for use in JavaServer Faces applications.When referencing an enum constant with an expression, you use a <tt>String</tt> literal. For example, consider this Enum class:<pre>public enum Suit {hearts, spades, diamonds, clubs}</pre>To refer to the <tt>Suit</tt> constant, <tt>Suit.hearts</tt> with an expression, you use the <tt>String</tt> literal, <tt>"hearts"</tt>. Depending on the context, the <tt>String</tt> literal is converted to the enum constant automatically. For example, in the following expression in which <tt>mySuit</tt> is an instance of <tt>Suit</tt>, <tt>"hearts"</tt> is first converted to a <tt>Suit.hearts</tt> before it is compared to the instance.<pre>${mySuit == "hearts"}</pre> <a name="bnahx"></a><h5>Referring to Object Properties Using Value Expressions</h5> To refer to properties of a bean or an Enum instance, items of a collection, or attributes of an implicit object, you use the <tt>.</tt> or <tt>[]</tt> notation, which is similar to the notation used by ECMAScript.So, if you wanted to reference the <tt>name</tt> property of the <tt>customer</tt> bean, you could use either the expression <tt>${customer.name}</tt> or the expression <tt>${customer["name"]}</tt>. The part inside the square brackets is a <tt>String</tt> literal that is the name of the property to reference.You can use double or single quotes for the <tt>String</tt> literal. You can also combine the <tt>[]</tt> and <tt>.</tt> notations, as shown here:<pre>${customer.address["street"]}</pre>Properties of an enum can also be referenced in this way. However, as with JavaBeans component properties, the Enum class’s properties must follow JavaBeans component conventions. This means that a property must at least have an accessor method called <tt>get<Property></tt> (where <tt><Property></tt> is the name of the property) so that an expression can reference it.For example, say you have an Enum class that encapsulates the names of the planets of our galaxy and includes a method to get the mass of a planet. You can use the following expression to reference the method <tt>getMass</tt> of the <tt>Planet</tt> Enum class:<pre>${myPlanet.mass}</pre>If you are accessing an item in an array or list, you must use either a literal value that can be coerced to int or the <tt>[]</tt> notation with an int and without quotes. The following examples could all resolve to the same item in a list or array, assuming that <tt>socks</tt> can be coerced to <tt>int</tt>: <ul><li><tt>${customer.orders[1]}</tt></li> <li><tt>${customer.orders.socks}</tt></li></ul> In contrast, an item in a <tt>Map</tt> can be accessed using a string literal key; no coercion is required:<pre>${customer.orders["socks"]}</pre>An rvalue expression also refers directly to values that are not objects, such as the result of arithmetic operations and literal values, as shown by these examples: <ul><li><tt>${"literal"}</tt></li> <li><tt>${customer.age + 20}</tt></li> <li><tt>${true}</tt></li> <li><tt>${57}</tt></li></ul> <a name="indexterm-352"></a>The unified expression language defines the following literals: <ul><li>Boolean: <tt>true</tt> and <tt>false</tt></li> <li>Integer: as in Java</li> <li>Floating point: as in Java</li> <li>String: with single and double quotes; <tt>"</tt> is escaped as <tt>\"</tt>, <tt>’</tt> is escaped as <tt>\‘</tt>, and <tt>\</tt> is escaped as <tt>\\</tt></li> <li>Null: <tt>null</tt></li></ul> You can also write expressions that perform operations on an enum constant. For example, consider the following Enum class:<pre>public enum Suit {club, diamond, heart, spade }</pre>After declaring an enum constant called <tt>mySuit</tt>, you can write the following expression to test if <tt>mySuit</tt> is <tt>spade</tt>:<pre>${mySuit == "spade"}</pre>When the EL resolving mechanism resolves this expression it will invoke the <tt>valueOf</tt> method of the Enum class with the <tt>Suit</tt> class and the <tt>spade</tt> type, as shown here:<pre>mySuit.valueOf(Suit.class, "spade"}</pre>See <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnair.html">JavaBeans Components</a> for more information on using expressions to reference JavaBeans components and their properties. <a name="bnahy"></a><h5>Where Value Expressions Can Be Used</h5> Value expressions using the <tt>${}</tt> delimiters can be used in the following places: <ul><li>In static text</li> <li>In any standard or custom tag attribute that can accept an expression</li></ul> The value of an expression in static text is computed and inserted into the current output. Here is an example of an expression embedded in static text:<pre><some:tag> some text ${expr} some text </some:tag></pre>If the static text appears in a tag body, note that an expression will not be evaluated if the body is declared to be <tt>tagdependent</tt> (see <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnaln.html#bnalo">Tags with Attributes</a>).Lvalue expressions can only be used in tag attributes that can accept lvalue expressions.There are three ways to set a tag attribute value using either an rvalue or lvalue expression: <ul><li>With a single expression construct:<pre><some:tag value="${expr}"/></pre><pre><another:tag value="#{expr}"/></pre>These expressions are evaluated and the result is coerced to the attribute’s expected type.</li> <li>With one or more expressions separated or surrounded by text:<pre><some:tag value="some${expr}${expr}text${expr}"/></pre><pre><another:tag value="some#{expr}#{expr}text#{expr}"/></pre>These kinds of expression are called a composite expressions. They are evaluated from left to right. Each expression embedded in the composite expression is coerced to a <tt>String</tt> and then concatenated with any intervening text. The resulting <tt>String</tt> is then coerced to the attribute’s expected type.</li> <li>With text only:<pre><some:tag value="sometext"/></pre><a name="indexterm-353"></a>This expression is called a literal expression. In this case, the attribute’s <tt>String</tt> value is coerced to the attribute’s expected type. Literal value expressions have special syntax rules. See <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnahq.html#bnaid">Literal Expressions</a> for more information. When a tag attribute has an enum type, the expression that the attribute uses must be a literal expression. For example, the tag attribute can use the expression <tt>"hearts"</tt> to mean <tt>Suit.hearts</tt>. The literal is coerced to <tt>Suit</tt> and the attribute gets the value <tt>Suit.hearts</tt>.</li></ul> <a name="indexterm-354"></a>All expressions used to set attribute values are evaluated in the context of an expected type. If the result of the expression evaluation does not match the expected type exactly, a type conversion will be performed. For example, the expression <tt>${1.2E4}</tt> provided as the value of an attribute of type <tt>float</tt> will result in the following conversion:<pre>Float.valueOf("1.2E4").floatValue()</pre>See section 1.18 of the JavaServer Pages 2.1 Expression Language Specification (available from <a href="http://jcp.org/aboutJava/communityprocess/final/jsr245/">http://jcp.org/aboutJava/communityprocess/final/jsr245/</a>) for the complete type conversion rules. <a name="bnahz"></a><h5>Method Expressions</h5> <a name="indexterm-355"></a>Another feature of the unified expression language is its support of deferred method expressions. A method expression is used to invoke an arbitrary public method, which can return a result. A similar feature of the unified EL is functions. Method expressions differ from functions in many ways. <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnahq.html#bnaio">Functions</a> explains more about the differences between functions and method expressions.Method expressions primarily benefit JavaServer Faces technology, but they are available to any technology that can support the unified expression language. Let’s take a look at how JavaServer Faces technology employs method expressions.In JavaServer Faces technology, a component tag represents a UI component on a page. The component tag uses method expressions to invoke methods that perform some processing for the component. These methods are necessary for handling events that the components generate and validating component data, as shown in this example:<pre><h:form> <h:inputText id="name" value="#{customer.name}" validator="#{customer.validateName}"/> <h:commandButton id="submit" action="#{customer.submit}" /> </h:form></pre>The <tt>inputText</tt> tag displays a <tt>UIInput</tt> component as a text field. The <tt>validator</tt> attribute of this <tt>inputText</tt> tag references a method, called <tt>validateName</tt>, in the bean, called <tt>customer</tt>. The TLD (see <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnamu.html">Tag Library Descriptors</a>) that defines the <tt>inputText</tt> tag specifies what signature the method referred to by the <tt>validator</tt> attribute must have. The same is true of the <tt>customer.submit</tt> method referenced by the <tt>action</tt> attribute of the <tt>commandButton</tt> tag. The TLD specifies that the <tt>submit</tt> method must return an <tt>Object</tt> instance that specifies which page to navigate to next after the button represented by the <tt>commandButton</tt> tag is clicked.The <tt>validation</tt> method is invoked during the process validation phase of the life cycle, whereas the <tt>submit</tt> method is invoked during the invoke application phase of the life cycle. Because a method can be invoked during different phases of the life cycle, method expressions must always use the deferred evaluation syntax.Similarly to lvalue expressions, method expressions can use the . and <tt>[]</tt> operators. For example, <tt>#{object.method}</tt> is equivalent to <tt>#{object["method"]}</tt>. The literal inside the <tt>[]</tt> is coerced to <tt>String</tt> and is used to find the name of the method that matches it. Once the method is found, it is invoked or information about the method is returned.Method expressions can be used only in tag attributes and only in the following ways: <ul><li>With a single expression construct, where <tt>bean</tt> refers to a JavaBeans component and <tt>method</tt> refers to a method of the JavaBeans component:<pre><some:tag value="#{bean.method}"/></pre>The expression is evaluated to a method expression, which is passed to the tag handler. The method represented by the method expression can then be invoked later.</li> <li>With text only:<pre><some:tag value="sometext"/></pre>Method expressions support literals primarily to support <tt>action</tt> attributes in JavaServer Faces technology. When the method referenced by this method expression is invoked, it returns the <tt>String</tt> literal, which is then coerced to the expected return type, as defined in the tag’s TLD.</li></ul> <a name="bnaia"></a><h4>Defining a Tag Attribute Type</h4> As explained in the previous section, all kinds of expressions can be used in tag attributes. Which kind of expression and how that expression is evaluated (whether immediately or deferred) is determined by the <tt>type</tt> attribute of the tag’s definition in the TLD (see <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnamu.html">Tag Library Descriptors</a>) file that defines the tag.If you plan to create custom tags (see <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnalj.html">Chapter 8, Custom Tags in JSP Pages</a>), you need to specify for each tag in the TLD what kind of expression it accepts. <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnahq.html#bnaib">Table 5-2</a> shows the three different kinds of tag attributes that accept EL expressions, and gives examples of expressions they accept and the type definitions of the attributes that must be added to the TLD. You cannot use <tt>#{}</tt> syntax for a dynamic attribute, meaning an attribute that accepts dynamically-calculated values at runtime. Section 2.3.2 of the JavaServer Pages 2.1 specification refers to these attributes. Neither can you use the <tt>${}</tt> syntax for a deferred attribute.<a name="bnaib"></a><h6>Table 5-2 Definitions of Tag Attributes That Accept EL Expressions</h6><table ID="Table1"><col width="72*"><col width="85*"><col width="196*"><tbody><tr><th align="left" valign="top">Attribute Type</th> <th align="left" valign="top">Example Expression</th> <th align="left" valign="top">Type Attribute Definition</th> </tr> <tr><td rowspan="2" align="left" valign="top">dynamic</td> <td align="left" valign="top"><tt>"literal"</tt></td> <td align="left" valign="top"><pre><rtexprvalue>true</rtexprvalue></pre></td> </tr> <tr><td align="left" valign="top"><tt>${literal}</tt></td> <td align="left" valign="top"><pre><rtexprvalue>true</rtexprvalue></pre></td> </tr> <tr><td rowspan="2" align="left" valign="top">deferred value</td> <td align="left" valign="top"><tt>"literal"</tt></td> <td align="left" valign="top"><pre><deferred-value> <type>java.lang.String</type> </deferred-value></pre></td> </tr> <tr><td align="left" valign="top"><tt>#{customer.age}</tt></td> <td align="left" valign="top"><pre><deferred-value> <type>int</type> </deferred-value></pre></td> </tr> <tr><td rowspan="2" align="left" valign="top">deferred method</td> <td align="left" valign="top"><tt>"literal"</tt></td> <td align="left" valign="top"><pre><deferred-method> <method-signature> java.lang.String submit() </method-signature> <deferred-method></pre></td> </tr> <tr><td align="left" valign="top"><tt>#{customer.calcTotal}</tt></td> <td align="left" valign="top"><pre><deferred-method> <method-signature> double calcTotal(int, double) </method-signature> </deferred-method></pre></td> </tr> </tbody></table>In addition to the tag attribute types shown in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnahq.html#bnaib">Table 5-2</a>, you can also define an attribute to accept both dynamic and deferred expressions. In this case, the tag attribute definition contains both an <tt>rtexprvalue</tt> definition set to <tt>true</tt> and either a <tt>deferred-value</tt> or <tt>deferred-method</tt> definition. <a name="bnaic"></a><h4>Deactivating Expression Evaluation</h4> <a name="indexterm-356"></a>Because the patterns that identify EL expressions, <tt>${ }</tt> and <tt>#{ }</tt>, were not reserved in the JSP specifications before JSP 2.0, there might exist applications in which such patterns are intended to pass through verbatim. To prevent the patterns from being evaluated, you can deactivate EL evaluation using one of the following methods: <ul><li>Escape the <tt>#{</tt> or <tt>${</tt> characters in the page.</li> <li>Configure the application with a JSP Property Group.</li> <li>Configure the page with the page directive.</li></ul> To escape the <tt>#{</tt> or <tt>${</tt> characters in the page, you use the <tt>\</tt> character as follows:<pre>some text \#{ some more\${ text <my:tag someAttribute="sometext\#{more\${text" /></pre>Another way to deactivate EL evaluation is by using a JSP property group to either allow the <tt>#{</tt> characters as a <tt>String</tt> literal using the <tt>deferred-syntax-allowed-as-literal</tt> subelement, or to treat all expressions as literals using the <tt>el-ignored</tt> subelement:<pre><jsp-property-group> <deferred-syntax-allowed-as-literal> true </deferred-syntax-allowed-as-literal> </jsp-property-group></pre>or<pre><jsp-property-group> <el-ignored>true</el-ignored> </jsp-property-group></pre>Finally, you can configure the page with the <tt>page</tt> directive to either accept the <tt>#{</tt> characters as <tt>String</tt> literals with the <tt>deferredSyntaxAllowedAsLiteral</tt> attribute, or to ignore all EL expressions using the <tt>isELIgnored</tt> attribute:<pre><%@page ... deferredSyntaxAllowedAsLiteral="true" %></pre>or<pre><%@ page isELIgnored ="true" %></pre>The valid values of these attributes are <tt>true</tt> and <tt>false</tt>. If <tt>isELIgnored</tt> is <tt>true</tt>, EL expressions are ignored when they appear in static text or tag attributes. If it is <tt>false</tt>, EL expressions are evaluated by the container only if the attribute has <tt>rtexprvalue</tt> set to <tt>true</tt> or the expression is a deferred expression.The default value of <tt>isELIgnored</tt> varies depending on the version of the web application deployment descriptor. The default mode for JSP pages delivered with a Servlet 2.4 descriptor is to evaluate EL expressions; this automatically provides the default that most applications want. The default mode for JSP pages delivered using a descriptor from Servlet 2.3 or before is to ignore EL expressions; this provides backward compatibility. <a name="bnaid"></a><h4>Literal Expressions</h4> <a name="indexterm-357"></a>A literal expression evaluates to the text of the expression, which is of type <tt>String</tt>. It does not use the <tt>${}</tt> or <tt>#{}</tt> delimiters.If you have a literal expression that includes the reserved <tt>${}</tt> or <tt>#{}</tt> syntax, you need to escape these characters as follows. <ul><li>By creating a composite expression as shown here:<pre>${’${’}exprA}</pre><pre>#{’#{’}exprB}</pre>The resulting values would then be the strings <tt>${exprA}</tt> and <tt>#{exprB}</tt>.</li> <li>The escape characters <tt>\$</tt> and <tt>\#</tt> can be used to escape what would otherwise be treated as an eval-expression:<pre>\${exprA}</pre><pre>\#{exprB}</pre>The resulting values would again be the strings <tt>${exprA}</tt> and <tt>#{exprB}</tt>.</li></ul> When a literal expression is evaluated, it can be converted to another type. <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnahq.html#bnaie">Table 5-3</a> shows examples of various literal expressions and their expected types and resulting values.<a name="bnaie"></a><h6>Table 5-3 Literal Expressions</h6><table ID="Table2"><col width="75*"><col width="75*"><col width="107*"><tbody><tr><th align="left" valign="top">Expression</th> <th align="left" valign="top">Expected Type</th> <th align="left" valign="top">Result</th> </tr> <tr><td align="left" valign="top"><tt>Hi</tt></td> <td align="left" valign="top"><tt>String</tt></td> <td align="left" valign="top"><tt>Hi</tt></td> </tr> <tr><td align="left" valign="top"><tt>true</tt></td> <td align="left" valign="top"><tt>Boolean</tt></td> <td align="left" valign="top"><tt>Boolean.TRUE</tt></td> </tr> <tr><td align="left" valign="top"><tt>42</tt></td> <td align="left" valign="top"><tt>int</tt></td> <td align="left" valign="top"><tt>42</tt></td> </tr> </tbody></table>Literal expressions can be evaluated immediately or deferred and can be either value or method expressions. At what point a literal expression is evaluated depends on where it is being used. If the tag attribute that uses the literal expression is defined as accepting a deferred value expression, then the literal expression references a value and is evaluated at a point in the life cycle that is determined by where the expression is being used and to what it is referring.In the case of a method expression, the method that is referenced is invoked and returns the specified <tt>String</tt> literal. The <tt>commandButton</tt> tag of the Guess Number application uses a literal method expression as a logical outcome to tell the JavaServer Faces navigation system which page to display next. See <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnaql.html">Navigation Model</a> for more information on this example. <a name="bnaif"></a><h4>Resolving Expressions</h4> <a name="indexterm-358"></a>The unified EL introduces a new, pluggable API for resolving expressions. The main pieces of this API are: <ul><li>The <tt>ValueExpression</tt> class, which defines a value expression</li> <li>The <tt>MethodExpression</tt> class, which defines a method expression</li> <li>An <tt>ELResolver</tt> class that defines a mechanism for resolving expressions</li> <li>A set of <tt>ELResolver</tt> implementations, in which each implementation is responsible for resolving expressions that reference a particular type of object or property</li> <li>An <tt>ELContext</tt> object that saves state relating to EL resolution, holds references to EL resolvers, and contains context objects (such as <tt>JspContext</tt>) needed by the underlying technology to resolve expressions</li></ul> Most application developers will not need to use these classes directly unless they plan to write their own custom EL resolvers. Those writing JavaServer Faces custom components will definitely need to use <tt>ValueExpression</tt> and <tt>MethodExpression</tt>. This section details how expressions are resolved for the benefit of these developers. It does not explain how to create a custom resolver. For more information on creating custom resolvers, see the article The Unified Expression Language, Ryan Lubke et al., located at <a href="http://java.sun.com/products/jsp/reference/techart/unifiedEL.html">http://java.sun.com/products/jsp/reference/techart/unifiedEL.html</a>. You can also refer to <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bncmt.html#bncmy">Request Processing</a>, which explains how the Duke’s Bank application uses a custom resolver. <a name="bnaig"></a><h5>Process of Expression Evaluation</h5> When a value expression that is included in a page is parsed during an initial request for the page, a <tt>ValueExpression</tt> object is created to represent the expression. Then, the <tt>ValueExpression</tt> object’s <tt>getValue</tt> method is invoked. This method will in turn invoke the <tt>getValue</tt> method of the appropriate resolver. A similar process occurs during a postback when <tt>setValue</tt> is called if the expression is an lvalue expression.In the case of a method expression, a <tt>BeanELResolver</tt> is used to find the object that implements the method to be invoked or queried. Similarly to the process for evaluating value expressions, when a method expression is encountered, a <tt>MethodExpression</tt> object is created. Subsequently, either the <tt>invoke</tt> or <tt>getMethodInfo</tt> method of the <tt>MethodExpression</tt> object is called. This method in turn invokes the <tt>BeanELResolver</tt> object’s <tt>getValue</tt> method. The <tt>getMethodInfo</tt> is mostly for use by tools.After a resolver completes resolution of an expression, it sets the <tt>propertyResolved</tt> flag of the <tt>ELContext</tt> to <tt>true</tt> so that no more resolvers are consulted. <a name="bnaih"></a><h5>EL Resolvers</h5> <a name="indexterm-359"></a>At the center of the EL machinery is the extensible <tt>ELResolver</tt> class. A class that implements <tt>ELResolver</tt> defines how to resolve expressions referring to a particular type of object or property. In terms of the following expression, a <tt>BeanELResolver</tt> instance is called the first time to find the base object, <tt>employee</tt>, which is a JavaBeans component. Once the resolver finds the object, it is called again to resolve the property, <tt>lName</tt> of the employee object.<pre>${employee.lName}</pre>The unified EL includes a set of standard resolver implementations. <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnahq.html#bnaii">Table 5-4</a> lists these standard resolvers and includes example expressions that they can resolve.<a name="bnaii"></a><h6>Table 5-4 Standard EL Resolvers</h6><table ID="Table3"><col width="103*"><col width="87*"><col width="161*"><tbody><tr><th align="left" valign="top">Resolver</th> <th align="left" valign="top">Example Expression</th> <th align="left" valign="top">Description</th> </tr> <tr><td align="left" valign="top"><tt>ArrayELResolver</tt></td> <td align="left" valign="top"><tt>${myArray[1]}</tt></td> <td align="left" valign="top">Returns the value at index 1 in the array called <tt>myArray</tt></td> </tr> <tr><td align="left" valign="top"><tt>BeanELResolver</tt></td> <td align="left" valign="top"><tt>${employee.lName}</tt></td> <td align="left" valign="top">Returns the value of the <tt>lName</tt> property of the <tt>employee</tt> bean</td> </tr> <tr><td align="left" valign="top"><tt>ListELResolver</tt></td> <td align="left" valign="top"><tt>${myList[5]}</tt></td> <td align="left" valign="top">Returns the value at index 5 of <tt>myList</tt> list</td> </tr> <tr><td align="left" valign="top"><tt>MapELResolver</tt></td> <td align="left" valign="top"><tt>${myMap.someKey}</tt></td> <td align="left" valign="top">Returns the value stored at the key, <tt>someKey</tt>, in the <tt>Map</tt>, <tt>myMap</tt></td> </tr> <tr><td align="left" valign="top"><tt>ResourceBundleELResolver</tt></td> <td align="left" valign="top"><tt>${myRB.myKey}</tt></td> <td align="left" valign="top">Returns the message at <tt>myKey</tt> in the resource bundle called <tt>myRB</tt></td> </tr> </tbody></table>Depending on the technology using the unified EL, other resolvers might be available. In addition, application developers can add their own implementations of <tt>ELResolver</tt> to support resolution of expressions not already supported by the unified EL by registering them with an application.All of the standard and custom resolvers available to a particular application are collected in a chain in a particular order. This chain of resolvers is represented by a <tt>CompositeELResolver</tt> instance. When an expression is encountered, the <tt>CompositeELResolver</tt> instance iterates over the list of resolvers and consults each resolver until it finds one that can handle the expression.If an application is using JSP technology, the chain of resolvers includes the <tt>ImplicitObjectELResolver</tt> and the <tt>ScopedAttributeELResolver</tt>. These are described in the following section.See section JSP 2.9 of the JavaServer Pages 2.1 specification to find out the order in which resolvers are chained together in a <tt>CompositeELResolver</tt> instance.To learn how to create a custom EL resolver, see <a href="http://java.sun.com/products/jsp/reference/techart/unifiedEL.html">The Unified Expression Language</a> . <a name="bnaij"></a><h4>Implicit Objects</h4> <a name="indexterm-360"></a>The JSP expression language defines a set of implicit objects: <ul><li><tt>pageContext</tt>: The context for the JSP page. Provides access to various objects including: <ul><li><tt>servletContext</tt>: The context for the JSP page’s servlet and any web components contained in the same application. See <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnagl.html">Accessing the Web Context</a>.</li> <li><tt>session</tt>: The session object for the client. See <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnagm.html">Maintaining Client State</a>.</li> <li><tt>request</tt>: The request triggering the execution of the JSP page. See <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnafv.html#bnafw">Getting Information from Requests</a>.</li> <li><tt>response</tt>: The response returned by the JSP page. See <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnafv.html#bnafz">Constructing Responses</a>.</li></ul> </li> <li>In addition, several implicit objects are available that allow easy access to the following objects: <ul><li><tt>param</tt>: Maps a request parameter name to a single value</li> <li><tt>paramValues</tt>: Maps a request parameter name to an array of values</li> <li><tt>header</tt>: Maps a request header name to a single value</li> <li><tt>headerValues</tt>: Maps a request header name to an array of values</li> <li><tt>cookie</tt>: Maps a cookie name to a single cookie</li> <li><tt>initParam</tt>: Maps a context initialization parameter name to a single value</li></ul> </li> <li>Finally, there are objects that allow access to the various scoped variables described in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnafo.html#bnafp">Using Scope Objects</a>. <ul><li><tt>pageScope</tt>: Maps page-scoped variable names to their values</li> <li><tt>requestScope</tt>: Maps request-scoped variable names to their values</li> <li><tt>sessionScope</tt>: Maps session-scoped variable names to their values</li> <li><tt>applicationScope</tt>: Maps application-scoped variable names to their values</li></ul> </li></ul> JSP 2.1 provides two EL resolvers to handle expressions that reference these objects: <tt>ImplicitObjectELResolver</tt> and <tt>ScopedAttributeELResolver</tt>.A variable that matches one of the implicit objects is evaluated by <tt>ImplicitObjectResolver</tt>, which returns the implicit object. This resolver only handles expressions with a base of <tt>null</tt>. What this means for the following expression is that the <tt>ImplicitObjectResolver</tt> resolves the <tt>sessionScope</tt> implicit object only. Once the implicit object is found, the <tt>MapELResolver</tt> instance resolves the <tt>profile</tt> attribute because the <tt>profile</tt> object represents a map.<pre>${sessionScope.profile}</pre><tt>ScopedAttributeELResolver</tt> evaluates a single object that is stored in scope. Like <tt>ImplicitObjectELResolver</tt>, it also only evaluates expressions with a base of <tt>null</tt>. This resolver essentially looks for an object in all of the scopes until it finds it, according to the behavior of <tt>PageContext.findAttribute(String)</tt>. For example, when evaluating the expression <tt>${product}</tt>, the resolver will look for <tt>product</tt> in the page, request, session, and application scopes and will return its value. If <tt>product</tt> is not found, <tt>null</tt> is returned.When an expression references one of the implicit objects by name, the appropriate object is returned instead of the corresponding attribute. For example, <tt>${pageContext}</tt> returns the <tt>PageContext</tt> object, even if there is an existing <tt>pageContext</tt> attribute containing some other value.<a name="indexterm-361"></a> <a name="bnaik"></a><h4>Operators</h4> <a name="indexterm-362"></a>In addition to the <tt>.</tt> and <tt>[]</tt> operators discussed in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnahq.html#bnahu">Value and Method Expressions</a>, the JSP expression language provides the following operators, which can be used in rvalue expressions only: <ul><li>Arithmetic: <tt>+</tt>, <tt>-</tt> (binary), <tt>*</tt>, <tt>/</tt> and <tt>div</tt>, <tt>%</tt> and <tt>mod</tt>, <tt>-</tt> (unary)</li> <li>Logical: <tt>and</tt>, <tt>&&</tt>, <tt>or</tt>, <tt>||</tt>, <tt>not</tt>, <tt>!</tt></li> <li>Relational: <tt>==</tt>, <tt>eq</tt>, <tt>!=</tt>, <tt>ne</tt>, <tt><</tt>, <tt>lt</tt>, <tt>></tt>, <tt>gt</tt>, <tt><=</tt>, <tt>ge</tt>, <tt>>=</tt>, <tt>le</tt>. Comparisons can be made against other values, or against boolean, string, integer, or floating point literals.</li> <li>Empty: The <tt>empty</tt> operator is a prefix operation that can be used to determine whether a value is <tt>null</tt> or empty.</li> <li>Conditional: <tt>A ? B : C</tt>. Evaluate <tt>B</tt> or <tt>C</tt>, depending on the result of the evaluation of <tt>A</tt>.</li></ul> The precedence of operators highest to lowest, left to right is as follows: <ul><li><tt>[] .</tt></li> <li><tt>()</tt> (used to change the precedence of operators)</li> <li><tt>-</tt> (unary) <tt>not ! empty</tt></li> <li><tt>* / div % mod</tt></li> <li><tt>+ -</tt> (binary)</li> <li><tt>< > <= >= lt gt le ge</tt></li> <li><tt>== != eq ne</tt></li> <li><tt>&& and</tt></li> <li><tt>|| or</tt></li> <li><tt>? :</tt></li></ul> <a name="bnail"></a><h4>Reserved Words</h4> <a name="indexterm-363"></a>The following words are reserved for the JSP expression language and should not be used as identifiers.<table ID="Table4"><col width="25*"><col width="25*"><col width="25*"><col width="25*"><tbody><tr><td align="left" valign="top"><tt>and</tt></td> <td align="left" valign="top"><tt>or</tt></td> <td align="left" valign="top"><tt>not</tt></td> <td align="left" valign="top"><tt>eq</tt></td> </tr> <tr><td align="left" valign="top"><tt>ne</tt></td> <td align="left" valign="top"><tt>lt</tt></td> <td align="left" valign="top"><tt>gt</tt></td> <td align="left" valign="top"><tt>le</tt></td> </tr> <tr><td align="left" valign="top"><tt>ge</tt></td> <td align="left" valign="top"><tt>true</tt></td> <td align="left" valign="top"><tt>false</tt></td> <td align="left" valign="top"><tt>null</tt></td> </tr> <tr><td align="left" valign="top"><tt>instanceof</tt></td> <td align="left" valign="top"><tt>empty</tt></td> <td align="left" valign="top"><tt>div</tt></td> <td align="left" valign="top"><tt>mod</tt></td> </tr> </tbody></table>Note that many of these words are not in the language now, but they may be in the future, so you should avoid using them. <a name="bnaim"></a><h4>Examples of EL Expressions</h4> <a name="indexterm-364"></a><a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnahq.html#bnain">Table 5-5</a> contains example EL expressions and the result of evaluating them.<a name="bnain"></a><h6>Table 5-5 Example Expressions</h6><table ID="Table5"><col width="150*"><col width="204*"><tbody><tr><th align="left" valign="top">EL Expression</th> <th align="left" valign="top">Result</th> </tr> <tr><td align="left" valign="top"><tt>${1 > (4/2)}</tt></td> <td align="left" valign="top"><tt>false</tt></td> </tr> <tr><td align="left" valign="top"><tt>${4.0 >= 3}</tt></td> <td align="left" valign="top"><tt>true</tt></td> </tr> <tr><td align="left" valign="top"><tt>${100.0 == 100}</tt></td> <td align="left" valign="top"><tt>true</tt></td> </tr> <tr><td align="left" valign="top"><tt>${(10*10) ne 100}</tt></td> <td align="left" valign="top"><tt>false</tt></td> </tr> <tr><td align="left" valign="top"><tt>${‘a‘ < ‘b‘}</tt></td> <td align="left" valign="top"><tt>true</tt></td> </tr> <tr><td align="left" valign="top"><tt>${‘hip‘ gt ‘hit‘}</tt></td> <td align="left" valign="top"><tt>false</tt></td> </tr> <tr><td align="left" valign="top"><tt>${4 > 3}</tt></td> <td align="left" valign="top"><tt>true</tt></td> </tr> <tr><td align="left" valign="top"><tt>${1.2E4 + 1.4}</tt></td> <td align="left" valign="top"><tt>12001.4</tt></td> </tr> <tr><td align="left" valign="top"><tt>${3 div 4}</tt></td> <td align="left" valign="top"><tt>0.75</tt></td> </tr> <tr><td align="left" valign="top"><tt>${10 mod 4}</tt></td> <td align="left" valign="top"><tt>2</tt></td> </tr> <tr><td align="left" valign="top"><tt>${!empty param.Add}</tt></td> <td align="left" valign="top">False if the request parameter named <tt>Add</tt> is null or an empty string.</td> </tr> <tr><td align="left" valign="top"><tt>${pageContext.request.contextPath}</tt></td> <td align="left" valign="top">The context path.</td> </tr> <tr><td align="left" valign="top"><tt>${sessionScope.cart.numberOfItems}</tt></td> <td align="left" valign="top">The value of the <tt>numberOfItems</tt> property of the session-scoped attribute named <tt>cart</tt>.</td> </tr> <tr><td align="left" valign="top"><tt>${param[‘mycom.productId‘]}</tt></td> <td align="left" valign="top">The value of the request parameter named <tt>mycom.productId</tt>.</td> </tr> <tr><td align="left" valign="top"><tt>${header["host"]}</tt></td> <td align="left" valign="top">The host.</td> </tr> <tr><td align="left" valign="top"><tt>${departments[deptName]}</tt></td> <td align="left" valign="top">The value of the entry named <tt>deptName</tt> in the <tt>departments</tt> map.</td> </tr> <tr><td align="left" valign="top"><tt>${requestScope[’javax.servlet.forward.servlet_path’]}</tt></td> <td align="left" valign="top">The value of the request-scoped attribute named <tt>javax.servlet.forward.servlet_path</tt>.</td> </tr> <tr><td align="left" valign="top"><tt>#{customer.lName}</tt></td> <td align="left" valign="top">Gets the value of the property <tt>lName</tt> from the <tt>customer</tt> bean during an initial request. Sets the value of <tt>lName</tt> during a postback.</td> </tr> <tr><td align="left" valign="top"><tt>#{customer.calcTotal}</tt></td> <td align="left" valign="top">The return value of the method <tt>calcTotal</tt> of the <tt>customer</tt> bean.</td> </tr> </tbody></table> <a name="bnaio"></a><h4>Functions</h4> <a name="indexterm-365"></a>The JSP expression language allows you to define a function that can be invoked in an expression. Functions are defined using the same mechanisms as custom tags (see <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnaiy.html">Using Custom Tags</a> and <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnalj.html">Chapter 8, Custom Tags in JSP Pages</a>).At first glance, functions seem similar to method expressions, but they are different in the following ways: <ul><li>Functions refer to static methods that return a value. Method expressions refer to non-static, arbitrary public methods on objects.</li> <li>Functions are identified statically at translation time, whereas methods are identified dynamically at runtime.</li> <li>Function parameters and invocations are specified as part of an EL expression. A method expression only identifies a particular method. The invocation of that method is not specified by the EL expression; rather, it is specified in the tag attribute definition of the attribute using the method expression, as described in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnahq.html#bnaia">Defining a Tag Attribute Type</a>.</li></ul> <a name="bnaip"></a><h5>Using Functions</h5> <a name="indexterm-366"></a>Functions can appear in static text and tag attribute values.To use a function in a JSP page, you use a <tt>taglib</tt> directive to import the tag library containing the function. Then you preface the function invocation with the prefix declared in the directive.For example, the date example page <tt>index.jsp</tt> imports the <tt>/functions</tt> library and invokes the function <tt>equals</tt> in an expression:<pre><%@ taglib prefix="f" uri="/functions"%> ... <c:when test="${f:equals(selectedLocaleString, localeString)}" ></pre>In this example, the expression referencing the function is using immediate evaluation syntax. A page author can also use deferred evaluation syntax to reference a function in an expression, assuming that the attribute that is referencing the function can accept deferred expressions.If an attribute references a function with a deferred expression then the function is not invoked immediately; rather, it is invoked whenever the underlying technology using the function determines it should be invoked. <a name="bnaiq"></a><h5>Defining Functions</h5> <a name="indexterm-367"></a>To define a function, program it as a public static method in a public class. The <tt>mypkg.MyLocales</tt> class in the <tt>date</tt> example defines a function that tests the equality of two <tt>String</tt>s as follows:<pre>package mypkg; public class MyLocales { ... public static boolean equals( String l1, String l2 ) { return l1.equals(l2); } }</pre>Then map the function name as used in the EL expression to the defining class and function signature in a TLD (see <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnalj.html">Chapter 8, Custom Tags in JSP Pages</a>). The following <tt>functions.tld</tt> file in the date example maps the <tt>equals</tt> function to the class containing the implementation of the function <tt>equals</tt> and the signature of the function:<pre><function> <name>equals</name> <function-class>mypkg.MyLocales</function-class> <function-signature>boolean equals( java.lang.String, java.lang.String )</function-signature> </function></pre>No two functions within a tag library can have the same name. January 20, 2008 JavaBeans Components JavaBeans components are Java classes that can be easily reused and composed together into applications. Any Java class that follows certain design conventions is a JavaBeans component.JavaServer Pages technology directly supports using JavaBeans components with standard JSP language elements. You can easily create and initialize beans and get and set the values of their properties. <a name="bnais"></a><h4>JavaBeans Component Design Conventions</h4> <a name="indexterm-370"></a>JavaBeans component design conventions govern the properties of the class and govern the public methods that give access to the properties.<a name="indexterm-371"></a>A JavaBeans component property can be: <ul><li>Read/write, read-only, or write-only</li> <li>Simple, which means it contains a single value, or indexed, which means it represents an array of values</li></ul> <a name="indexterm-372"></a>A property does not have to be implemented by an instance variable. It must simply be accessible using public methods that conform to the following conventions: <ul><li>For each readable property, the bean must have a method of the form:<pre>PropertyClass getProperty() { ... }</pre></li> <li>For each writable property, the bean must have a method of the form:<pre>setProperty(PropertyClass pc) { ... }</pre></li></ul> In addition to the property methods, a JavaBeans component must define a constructor that takes no parameters.The Duke’s Bookstore application JSP pages <tt>bookstore.jsp</tt>, <tt>bookdetails.jsp</tt>, <tt>catalog.jsp</tt>, and <tt>showcart.jsp</tt>, all located at <tt></tt>tut-install<tt>/javaeetutorial5/examples/web/bookstore2/web</tt>, use the <tt></tt>tut-install<tt>/javaeetutorial5/examples/web/bookstore2/src/java/com/sun/bookstore2/database/BookDB.java</tt> JavaBeans component.<tt>BookDB</tt> provides a JavaBeans component front end to the access object <tt>BookDBAO</tt>. The JSP pages <tt>showcart.jsp</tt> and <tt>cashier.jsp</tt> access the bean <tt></tt>tut-install<tt>/javaeetutorial5/examples/web/bookstore/src/com/sun/bookstore/cart/ShoppingCart.java</tt>, which represents a user’s shopping cart.The <tt>BookDB</tt> bean has two writable properties, <tt>bookId</tt> and <tt>database</tt>, and three readable properties: <tt>bookDetails</tt>, <tt>numberOfBooks</tt>, and <tt>books</tt>. These latter properties do not correspond to any instance variables but rather are a function of the <tt>bookId</tt> and <tt>database</tt> properties.<pre>package database; public class BookDB { private String bookId = "0"; private BookDBAO database = null; public BookDB () { } public void setBookId(String bookId) { this.bookId = bookId; } public void setDatabase(BookDBAO database) { this.database = database; } public Book getBook() throws BookNotFoundException { return (Book)database.getBook(bookId); } public List getBooks() throws BooksNotFoundException { return database.getBooks(); } public void buyBooks(ShoppingCart cart) throws OrderException { database.buyBooks(cart); } public int getNumberOfBooks() throws BooksNotFoundException { return database.getNumberOfBooks(); } }<a name="indexterm-373"></a></pre> <a name="bnait"></a><h4>Creating and Using a JavaBeans Component</h4> <a name="indexterm-374"></a><a name="indexterm-375"></a>To declare that your JSP page will use a JavaBeans component, you use a <tt>jsp:useBean</tt> element. There are two forms:<pre><jsp:useBean id="beanName" class="fully-qualified-classname" scope="scope"/></pre>and<pre><jsp:useBean id="beanName" class="fully-qualified-classname" scope="scope"> <jsp:setProperty .../> </jsp:useBean></pre>The second form is used when you want to include <tt>jsp:setProperty</tt> statements, described in the next section, for initializing bean properties.<a name="indexterm-376"></a><a name="indexterm-377"></a>The <tt>jsp:useBean</tt> element declares that the page will use a bean that is stored within and is accessible from the specified scope, which can be <tt>application</tt>, <tt>session</tt>, <tt>request</tt>, or <tt>page</tt>. If no such bean exists, the statement creates the bean and stores it as an attribute of the scope object (see <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnafo.html#bnafp">Using Scope Objects</a>). The value of the <tt>id</tt> attribute determines the name of the bean in the scope and the identifier used to reference the bean in EL expressions, other JSP elements, and scripting expressions (see <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnaon.html">Chapter 9, Scripting in JSP Pages</a>). The value supplied for the <tt>class</tt> attribute must be a fully qualified class name. Note that beans cannot be in the unnamed package. Thus the format of the value must be package-name.class-name.The following element creates an instance of <tt>mypkg.myLocales</tt> if none exists, stores it as an attribute of the application scope, and makes the bean available throughout the application by the identifier <tt>locales</tt>:<pre><jsp:useBean id="locales" scope="application" class="mypkg.MyLocales"/></pre> <a name="bnaiu"></a><h4>Setting JavaBeans Component Properties</h4> <a name="indexterm-378"></a><a name="indexterm-379"></a><a name="indexterm-380"></a>The standard way to set JavaBeans component properties in a JSP page is by using the <tt>jsp:setProperty</tt> element. The syntax of the <tt>jsp:setProperty</tt> element depends on the source of the property value. <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnair.html#bnaiv">Table 5-6</a> summarizes the various ways to set a property of a JavaBeans component using the <tt>jsp:setProperty</tt> element. <hr>Note - Syntax rules of attribute values used in this table: <ol><li>beanName must be the same as that specified for the <tt>id</tt> attribute in a <tt>useBean</tt> element.</li> <li>There must be a setPropName method in the JavaBeans component.</li> <li>paramName must be a request parameter name.</li></ol> <hr> <a name="bnaiv"></a><h6>Table 5-6 Valid Bean Property Assignments from String Values</h6><table ID="Table1"><col width="115*"><col width="240*"><tbody><tr><th align="left" valign="top">Value Source</th> <th align="left" valign="top">Element Syntax</th> </tr> <tr><td align="left" valign="top">String constant</td> <td align="left" valign="top"><pre><jsp:setProperty name="beanName" property="propName" value="string-constant"/></pre></td> </tr> <tr><td align="left" valign="top">Request parameter</td> <td align="left" valign="top"><pre><jsp:setProperty name="beanName" property="propName" param="paramName"/></pre></td> </tr> <tr><td align="left" valign="top">Request parameter name that matches bean property</td> <td align="left" valign="top"><pre><jsp:setProperty name="beanName" property="propName"/> <jsp:setProperty name="beanName" property="*"/></pre></td> </tr> <tr><td align="left" valign="top">Expression</td> <td align="left" valign="top"><pre><jsp:setProperty name="beanName" property="propName" value="expression"/> <jsp:setProperty name="beanName" property="propName" > <jsp:attribute name="value"> expression </jsp:attribute> </jsp:setProperty></pre></td> </tr> </tbody></table><a name="indexterm-381"></a><a name="indexterm-382"></a><a name="indexterm-383"></a><a name="indexterm-384"></a>A property set from a constant string or request parameter must have one of the types listed in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnair.html#bnaiw">Table 5-7</a>. Because constants and request parameters are strings, the web container automatically converts the value to the property’s type; the conversion applied is shown in the table.<tt>String</tt> values can be used to assign values to a property that has a <tt>PropertyEditor</tt> class. When that is the case, the <tt>setAsText(String)</tt> method is used. A conversion failure arises if the method throws an <tt>IllegalArgumentException</tt>.The value assigned to an indexed property must be an array, and the rules just described apply to the elements.<a name="indexterm-385"></a><a name="indexterm-386"></a>You use an expression to set the value of a property whose type is a compound Java programming language type. The type returned from an expression must match or be castable to the type of the property.<a name="bnaiw"></a><h6>Table 5-7 Valid Property Value Assignments from String Values</h6><table ID="Table2"><col width="102*"><col width="252*"><tbody><tr><th align="left" valign="top">Property Type</th> <th align="left" valign="top">Conversion on String Value</th> </tr> <tr><td align="left" valign="top">Bean Property</td> <td align="left" valign="top">Uses <tt>setAsText(</tt>string-literal<tt>)</tt></td> </tr> <tr><td align="left" valign="top"><tt>boolean</tt> or <tt>Boolean</tt></td> <td align="left" valign="top">As indicated in <tt>java.lang.Boolean.valueOf(String)</tt></td> </tr> <tr><td align="left" valign="top"><tt>byte</tt> or <tt>Byte</tt></td> <td align="left" valign="top">As indicated in <tt>java.lang.Byte.valueOf(String)</tt></td> </tr> <tr><td align="left" valign="top"><tt>char</tt> or <tt>Character</tt></td> <td align="left" valign="top">As indicated in <tt>java.lang.String.charAt(0)</tt></td> </tr> <tr><td align="left" valign="top"><tt>double</tt> or <tt>Double</tt></td> <td align="left" valign="top">As indicated in <tt>java.lang.Double.valueOf(String)</tt></td> </tr> <tr><td align="left" valign="top"><tt>int</tt> or <tt>Integer</tt></td> <td align="left" valign="top">As indicated in <tt>java.lang.Integer.valueOf(String)</tt></td> </tr> <tr><td align="left" valign="top"><tt>float</tt> or <tt>Float</tt></td> <td align="left" valign="top">As indicated in <tt>java.lang.Float.valueOf(String)</tt></td> </tr> <tr><td align="left" valign="top"><tt>long</tt> or <tt>Long</tt></td> <td align="left" valign="top">As indicated in <tt>java.lang.Long.valueOf(String)</tt></td> </tr> <tr><td align="left" valign="top"><tt>short</tt> or <tt>Short</tt></td> <td align="left" valign="top">As indicated in <tt>java.lang.Short.valueOf(String)</tt></td> </tr> <tr><td align="left" valign="top"><tt>Object</tt></td> <td align="left" valign="top">new <tt>String(</tt>string-literal<tt>)</tt></td> </tr> </tbody></table>The Duke’s Bookstore application demonstrates how to use the <tt>setProperty</tt> element to set the current book from a request parameter in the database bean in <tt></tt>tut-install<tt>/javaeetutorial5/examples/web/bookstore2/web/books/bookdetails.jsp</tt>:<pre><c:set var="bid" value="${param.bookId}"/> <jsp:setProperty name="bookDB" property="bookId" value="${bid}" /></pre>The following fragment from the page <tt></tt>tut-install<tt>/javaeetutorial5/examples/web/bookstore2/web/books/bookshowcart.jsp</tt> illustrates how to initialize a <tt>BookDB</tt> bean with a <tt>database</tt> object. Because the initialization is nested in a <tt>useBean</tt> element, it is executed only when the bean is created.<pre><jsp:useBean id="bookDB" class="database.BookDB" scope="page"> <jsp:setProperty name="bookDB" property="database" value="${bookDBAO}" /> </jsp:useBean></pre> <a name="bnaix"></a><h4>Retrieving JavaBeans Component Properties</h4> <a name="indexterm-387"></a><a name="indexterm-388"></a>The main way to retrieve JavaBeans component properties is by using the unified EL expressions. Thus, to retrieve a book title, the Duke’s Bookstore application uses the following expression:<pre>${bookDB.bookDetails.title}</pre><a name="indexterm-389"></a>Another way to retrieve component properties is to use the <tt>jsp:getProperty</tt> element. This element converts the value of the property into a <tt>String</tt> and inserts the value into the response stream:<pre><jsp:getProperty name="beanName" property="propName"/></pre>Note that beanName must be the same as that specified for the <tt>id</tt> attribute in a <tt>useBean</tt> element, and there must be a <tt>getPropName</tt> method in the JavaBeans component. Although the preferred approach to getting properties is to use an EL expression, the <tt>getProperty</tt> element is available if you need to disable expression evaluation. January 20, 2008 Using Custom Tags Custom tags are user-defined JSP language elements that encapsulate recurring tasks. Custom tags are distributed in a tag library, which defines a set of related custom tags and contains the objects that implement the tags.Custom tags have the syntax<pre><prefix:tag attr1="value" ... attrN="value" /></pre>or<pre><prefix:tag attr1="value" ... attrN="value" > body</prefix:tag></pre>where <tt>prefix</tt> distinguishes tags for a library, <tt>tag</tt> is the tag identifier, and <tt>attr1 ... attrN</tt> are attributes that modify the behavior of the tag.<a name="indexterm-390"></a>To use a custom tag in a JSP page, you must <ul><li>Declare the tag library containing the tag</li> <li>Make the tag library implementation available to the web application</li></ul> See <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnalj.html">Chapter 8, Custom Tags in JSP Pages</a> for detailed information on the different types of tags and how to implement tags. <a name="bnaiz"></a><h4>Declaring Tag Libraries</h4> <a name="indexterm-391"></a><a name="indexterm-392"></a>To declare that a JSP page will use tags defined in a tag library, you include a <tt>taglib</tt> directive in the page before any custom tag from that tag library is used. If you forget to include the <tt>taglib</tt> directive for a tag library in a JSP page, the JSP compiler will treat any invocation of a custom tag from that library as static data and will simply insert the text of the custom tag call into the response.<pre><%@ taglib prefix="tt" [tagdir=/WEB-INF/tags/dir | uri=URI ] %></pre>The <tt>prefix</tt> attribute defines the prefix that distinguishes tags defined by a given tag library from those provided by other tag libraries.If the tag library is defined with tag files (see <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnama.html">Encapsulating Reusable Content Using Tag Files</a>), you supply the <tt>tagdir</tt> attribute to identify the location of the files. The value of the attribute must start with <tt>/WEB-INF/tags/</tt>. A translation error will occur if the value points to a directory that doesn’t exist or if it is used in conjunction with the <tt>uri</tt> attribute.The <tt>uri</tt> attribute refers to a URI that uniquely identifies the tag library descriptor (TLD), a document that describes the tag library (see <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnamu.html">Tag Library Descriptors</a>).<a name="indexterm-393"></a>Tag library descriptor file names must have the extension <tt>.tld</tt>. TLD files are stored in the <tt>WEB-INF</tt> directory or subdirectory of the WAR file, or in the <tt>META-INF</tt> directory or subdirectory of a tag library packaged in a JAR. You can reference a TLD directly or indirectly.<a name="indexterm-394"></a>The following <tt>taglib</tt> directive directly references a TLD file name:<pre><%@ taglib prefix="tlt" uri="/WEB-INF/iterator.tld"%></pre><a name="indexterm-395"></a>This <tt>taglib</tt> directive uses a short logical name to indirectly reference the TLD:<pre><%@ taglib prefix="tlt" uri="/tlt"%></pre>The <tt>iterator</tt> example defines and uses a simple iteration tag. The JSP pages use a logical name to reference the TLD.To deploy and run the <tt>iterator</tt> application with NetBeans IDE, follow these steps: <ol><li>In NetBeans IDE, select File→Open Project.</li> <li>In the Open Project dialog, navigate to:<pre>tut-install/javaeetutorial5/examples/web/</pre></li> <li>Select the <tt>iterator</tt> folder.</li> <li>Select the Open as Main Project check box.</li> <li>Click Open Project Folder.</li> <li>In the Projects tab, right-click the <tt>iterator</tt> project, and select Deploy Project.</li> <li>To run the application, open the bookstore URL <tt>http://localhost:8080/iterator</tt>.</li></ol> To deploy and run the <tt>iterator</tt> application with Ant, follow these steps: <ol><li>In a terminal window, go to <tt></tt>tut-install<tt>/javaeetutorial5/examples/web/iterator/</tt>.</li> <li>Type <tt>ant</tt>. This command will spawn any necessary compilations, copy files to the <tt></tt>tut-install<tt>/javaeetutorial5/examples/web/iterator/build/</tt> directory, and create a WAR file.</li> <li>Start the Application Server.</li> <li>Type <tt>ant deploy</tt>.</li> <li>To run the example, open your browser to <tt>http://localhost:8080/iterator</tt>.</li></ol> To learn how to configure the example, refer to the deployment descriptor, which includes the following configurations: <ul><li>A <tt>display-name</tt> element that specifies the name that tools use to identify the application.</li> <li>Nested inside a <tt>jsp-config</tt> element is a <tt>taglib</tt> element, which provides information on a tag library used by the pages of the application. Inside the <tt>taglib</tt> element are the <tt>taglib-uri</tt> element and the <tt>taglib-location</tt> element. The <tt>taglib-uri</tt> element identifies the logical name of the tag library. The <tt>taglib-location</tt> element gives the absolute location or the absolute URI of the tag library.</li></ul> The absolute URIs for the JSTL library are as follows: <ul><li>Core: <a href="http://java.sun.com/jsp/jstl/core">http://java.sun.com/jsp/jstl/core</a></li> <li>XML: <a href="http://java.sun.com/jsp/jstl/xml">http://java.sun.com/jsp/jstl/xml</a></li> <li>Internationalization: <a href="http://java.sun.com/jsp/jstl/fmt">http://java.sun.com/jsp/jstl/fmt</a></li> <li>SQL: <a href="http://java.sun.com/jsp/jstl/sql">http://java.sun.com/jsp/jstl/sql</a></li> <li>Functions: <a href="http://java.sun.com/jsp/jstl/functions">http://java.sun.com/jsp/jstl/functions</a></li></ul> <a name="indexterm-396"></a>When you reference a tag library with an absolute URI that exactly matches the URI declared in the <tt>taglib</tt> element of the TLD (see <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnamu.html">Tag Library Descriptors</a>), you do not have to add the <tt>taglib</tt> element to <tt>web.xml</tt>; the JSP container automatically locates the TLD inside the JSTL library implementation. <a name="bnaja"></a><h4>Including the Tag Library Implementation</h4> <a name="indexterm-397"></a><a name="indexterm-398"></a>In addition to declaring the tag library, you also must make the tag library implementation available to the web application. There are several ways to do this. Tag library implementations can be included in a WAR in an unpacked format: Tag files are packaged in the <tt>/WEB-INF/tag/</tt> directory, and tag handler classes are packaged in the <tt>/WEB-INF/classes/</tt> directory of the WAR. Tag libraries already packaged into a JAR file are included in the <tt>/WEB-INF/lib/</tt> directory of the WAR. Finally, an application server can load a tag library into all the web applications running on the server. For example, in the Application Server, the JSTL TLDs and libraries are distributed in the archive <tt>appserv-jstl.jar</tt> in <tt></tt>as-install<tt>/lib/</tt>. This library is automatically loaded into the classpath of all web applications running on the Application Server, so you don’t need to add it to your web application.The <tt>iterator</tt> tag library is implemented with tag handlers. Therefore, its implementation classes are packaged in the <tt>/WEB-INF/classes/</tt> directory. January 20, 2008 Reusing Content in JSP Pages There are many mechanisms for reusing JSP content in a JSP page. Three mechanisms that can be categorized as direct reuse are discussed here: <ul><li>The <tt>include</tt> directive</li> <li>Preludes and codas</li> <li>The <tt>jsp:include</tt> element</li></ul> An indirect method of content reuse occurs when a tag file is used to define a custom tag that is used by many web applications. Tag files are discussed in the section <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnama.html">Encapsulating Reusable Content Using Tag Files</a> in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnalj.html">Chapter 8, Custom Tags in JSP Pages</a>.<a name="indexterm-400"></a>The <tt>include</tt> directive is processed when the JSP page is translated into a servlet class. The effect of the directive is to insert the text contained in another file (either static content or another JSP page) into the including JSP page. You would probably use the <tt>include</tt> directive to include banner content, copyright information, or any chunk of content that you might want to reuse in another page. The syntax for the <tt>include</tt> directive is as follows:<pre><%@ include file="filename" %></pre>For example, all the Duke’s Bookstore application pages could include the file <tt>banner.jspf</tt>, which contains the banner content, by using the following directive:<pre><%@ include file="banner.jspf" %></pre><a name="indexterm-401"></a>Another way to do a static include is to use the prelude and coda mechanisms described in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnajg.html#bnajl">Defining Implicit Includes</a>. This is the approach used by the Duke’s Bookstore application.Because you must put an <tt>include</tt> directive in each file that reuses the resource referenced by the directive, this approach has its limitations. Preludes and codas can be applied only to the beginnings and ends of pages. For a more flexible approach to building pages out of content chunks, see <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnann.html#bnaoh">A Template Tag Library</a>.<a name="indexterm-402"></a>The <tt>jsp:include</tt> element is processed when a JSP page is executed. The <tt>include</tt> action allows you to include either a static or a dynamic resource in a JSP file. The results of including static and dynamic resources are quite different. If the resource is static, its content is inserted into the calling JSP file. If the resource is dynamic, the request is sent to the included resource, the included page is executed, and then the result is included in the response from the calling JSP page. The syntax for the <tt>jsp:include</tt> element is:<pre><jsp:include page="includedPage" /></pre>The <tt>hello1</tt> application discussed in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnadx.html#bnadz">Packaging Web Modules</a> uses the following statement to include the page that generates the response:<pre><jsp:include page="response.jsp"/></pre> January 20, 2008 Transferring Control to Another Web Component The mechanism for transferring control to another web component from a JSP page uses the functionality provided by the Java Servlet API as described in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnagm.html#bnagn">Accessing a Session</a>. You access this functionality from a JSP page by using the <tt>jsp:forward</tt> element:<pre><jsp:forward page="/main.jsp" /></pre>Note that if any data has already been returned to a client, the <tt>jsp:forward</tt> element will fail with an <tt>IllegalStateException</tt>. <a name="bnajd"></a><h4><tt>jsp:param</tt> Element</h4> <a name="indexterm-405"></a><a name="indexterm-406"></a>When an <tt>include</tt> or <tt>forward</tt> element is invoked, the original request object is provided to the target page. If you wish to provide additional data to that page, you can append parameters to the request object by using the <tt>jsp:param</tt> element:<pre><jsp:include page="..." > <jsp:param name="param1" value="value1"/> </jsp:include></pre>When <tt>jsp:include</tt> or <tt>jsp:forward</tt> is executed, the included page or forwarded page will see the original request object, with the original parameters augmented with the new parameters and new values taking precedence over existing values when applicable. For example, if the request has a parameter <tt>A=foo</tt> and a parameter <tt>A=bar</tt> is specified for forward, the forwarded request will have <tt>A=bar,foo</tt>. Note that the new parameter has precedence.The scope of the new parameters is the <tt>jsp:include</tt> or <tt>jsp:forward</tt> call; that is, in the case of an <tt>jsp:include</tt> the new parameters (and values) will not apply after the include. January 20, 2008 Setting Properties for Groups of JSP Pages It is possible to specify certain properties for a group of JSP pages: <ul><li>Expression language evaluation</li> <li>Treatment of scripting elements (see <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnaoq.html">Disabling Scripting</a>)</li> <li>Page encoding</li> <li>Automatic prelude and coda includes</li></ul> <a name="indexterm-413"></a>A JSP property group is defined by naming the group and specifying one or more URL patterns; all the properties in the group apply to the resources that match any of the URL patterns. If a resource matches URL patterns in more than one group, the pattern that is most specific applies. To define a property group in a deployment descriptor using NetBeans IDE, follow these steps: <ol><li>In NetBeans IDE, expand your project’s folder in the Projects pane.</li> <li>Expand the Web Pages node and then the WEB-INF node.</li> <li>Double-click <tt>web.xml</tt> to open it in the editor pane.</li> <li>Click Pages at the top of the editor pane.</li> <li>Click Add JSP Property Group.</li> <li>In the Add JSP Property Group dialog: <ol><li>Enter a name for the JSP property group in the Display Name field.</li> <li>Enter a URL pattern (a regular expression, such as <tt>*.jsp</tt>) or click Browse to indicate to which page or set of pages to apply the properties specified by the JSP property group.</li> <li>Click OK.</li></ol> </li></ol> Instead of performing the preceding steps, you can define a JSP property group by editing the XML by hand using NetBeans IDE by doing the following: <ol><li>Perform steps 1 through 3 in the preceding set of steps.</li> <li>Click XML at the top of the editor pane.</li> <li>Include a <tt>jsp-config</tt> element if the deployment descriptor doesn’t already have one.</li> <li>Add a <tt>jsp-property-group</tt> element inside the <tt>jsp-config</tt> element.</li> <li>Add a <tt>display-name</tt> element inside the <tt>jsp-property-group</tt> element and give it a name.</li> <li>Add a <tt>url-pattern</tt> element inside the <tt>jsp-property-group</tt> element and give it a URL pattern (a regular expression, such as <tt>*.jsp</tt>).</li></ol> The following sections discuss the properties and explain how they are interpreted for various combinations of group properties, individual page directives, and web application deployment descriptor versions. <a name="bnajh"></a><h4>Deactivating EL Expression Evaluation</h4> <a name="indexterm-414"></a>Each JSP page has a default mode for EL expression evaluation. The default value varies depending on the version of the web application deployment descriptor. The default mode for JSP pages delivered with a Servlet 2.4 descriptor is to evaluate EL expressions; this automatically provides the default that most applications want. The default mode for JSP pages delivered using a descriptor from Servlet 2.3 or before is to ignore EL expressions; this provides backward compatibility. For tag files (see <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnama.html">Encapsulating Reusable Content Using Tag Files</a>), the default is to always evaluate expressions.<a name="indexterm-415"></a>You can override the default mode through the <tt>isELIgnored</tt> attribute of the <tt>page</tt> directive in JSP pages and through the <tt>isELIgnored</tt> attribute of the <tt>tag</tt> directive in tag files. You can also explicitly change the default mode by doing one of the following: <ul><li>If you are using the Pages section of the <tt>web.xml</tt> editor pane in NetBeans IDE: <ol><li>Expand the JSP Property Group node.</li> <li>Select the Ignore Expression Language check box.</li></ol> </li> <li>If you are editing the <tt>web.xml</tt> file by hand, add an <tt>el-ignored</tt> element to the <tt>jsp-property-group</tt> element in the deployment descriptor and set it to true.</li></ul> <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnajg.html#bnaji">Table 5-8</a> summarizes the EL evaluation settings for JSP pages.<a name="bnaji"></a><h6>Table 5-8 EL Evaluation Settings for JSP Pages</h6><table ID="Table1"><col width="100*"><col width="105*"><col width="146*"><tbody><tr><th align="left" valign="top">JSP Configuration</th> <th align="left" valign="top">Page Directive <tt>isELIgnored</tt></th> <th align="left" valign="top">EL Encountered</th> </tr> <tr><td align="left" valign="top">Unspecified</td> <td align="left" valign="top">Unspecified</td> <td align="left" valign="top">Evaluated if 2.4 <tt>web.xml</tt>Ignored if <= 2.3 <tt>web.xml</tt></td> </tr> <tr><td align="left" valign="top"><tt>false</tt></td> <td align="left" valign="top">Unspecified</td> <td align="left" valign="top">Evaluated</td> </tr> <tr><td align="left" valign="top"><tt>true</tt></td> <td align="left" valign="top">Unspecified</td> <td align="left" valign="top">Ignored</td> </tr> <tr><td align="left" valign="top">Overridden by page directive</td> <td align="left" valign="top"><tt>false</tt></td> <td align="left" valign="top">Evaluated</td> </tr> <tr><td align="left" valign="top">Overridden by page directive</td> <td align="left" valign="top"><tt>true</tt></td> <td align="left" valign="top">Ignored</td> </tr> </tbody></table><a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnajg.html#bnajj">Table 5-9</a> summarizes the EL evaluation settings for tag files.<a name="bnajj"></a><h6>Table 5-9 EL Evaluation Settings for Tag Files</h6><table ID="Table2"><col width="184*"><col width="170*"><tbody><tr><th align="left" valign="top">Tag Directive <tt>isELIgnored</tt></th> <th align="left" valign="top">EL Encountered</th> </tr> <tr><td align="left" valign="top">Unspecified</td> <td align="left" valign="top">Evaluated</td> </tr> <tr><td align="left" valign="top"><tt>false</tt></td> <td align="left" valign="top">Evaluated</td> </tr> <tr><td align="left" valign="top"><tt>true</tt></td> <td align="left" valign="top">Ignored</td> </tr> </tbody></table> <a name="bnajk"></a><h5>Declaring Page Encodings</h5> <a name="indexterm-416"></a>You set the page encoding of a group of JSP pages using the JSP property group configuration in the deployment descriptor by doing one of the following: <ul><li>If you are using the Pages section of the <tt>web.xml</tt> editor pane in NetBeans IDE: <ol><li>Expand the JSP Property Group node.</li> <li>Enter the page encoding in the Page Encoding field.</li></ol> </li> <li>If you are editing the <tt>web.xml</tt> file by hand, add a <tt>page-encoding</tt> element to the <tt>jsp-property-group</tt> element in the deployment descriptor and set it to one of the valid character encoding codes, which are the same as those accepted by the <tt>pageEncoding</tt> attribute of the <tt>page</tt> directive.</li></ul> A translation-time error results if you define the page encoding of a JSP page with one value in the JSP configuration element and then give it a different value in a <tt>pageEncoding</tt> directive. <a name="bnajl"></a><h5>Defining Implicit Includes</h5> <a name="indexterm-417"></a>You can implicitly include preludes and codas for a group of JSP pages by adding items to the Include Preludes and Codas lists. Their values are context-relative paths that must correspond to elements in the web application. When the elements are present, the given paths are automatically included (as in an <tt>include</tt> directive) at the beginning and end, respectively, of each JSP page in the property group. When there is more than one include or coda element in a group, they are included in the order they appear. When more than one JSP property group applies to a JSP page, the corresponding elements will be processed in the same order as they appear in the JSP configuration section.For example, the Duke’s Bookstore application uses the files <tt>/template/prelude.jspf</tt> and <tt>/template/coda.jspf</tt> to include the banner and other boilerplate in each screen. To add these files to the Duke’s Bookstore property group using the deployment descriptor, follow these steps: <ol><li>In NetBeans IDE, expand your project’s folder in the Projects pane.</li> <li>Expand the Web Pages node and then the WEB-INF node.</li> <li>Double-click <tt>web.xml</tt> to open it in the editor pane.</li> <li>Click Pages at the top of the editor pane.</li> <li>Add a new JSP property group if you haven’t already (see <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnajg.html">Setting Properties for Groups of JSP Pages</a>) and give it the name <tt>bookstore2</tt> and the URL pattern <tt>*.jsp</tt>.</li> <li>Expand the JSP Property Group node.</li> <li>Click the Browse button to the right of the Include Preludes field to locate the file that you want to include at the beginning of all pages matching the pattern in the URL pattern field. In this case, you want the <tt>/template/prelude.jspf</tt> file.</li> <li>Click the Browse button to the right of the Include Codas field to locate the file that you want to include at the end of all pages matching the URL pattern. In this case, you want the <tt>/template/coda.jspf</tt> file.</li></ol> Instead of performing the preceding steps, you can add preludes and codas by editing the XML by hand using NetBeans IDE by doing the following: <ol><li>Perform steps 1 through 3 in the preceding set of steps.</li> <li>Click XML at the top of the editor pane.</li> <li>Add a new JSP property group (see <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnajg.html">Setting Properties for Groups of JSP Pages</a>) and give it the name <tt>bookstore2</tt> and URL pattern <tt>*.jsp</tt>.</li> <li>Add an <tt>include-prelude</tt> element to the <tt>jsp-property-group</tt> element and give it the name of the file to include, in this case, <tt>/template/prelude.jspf</tt>.</li> <li>Add an <tt>include-coda</tt> element to the <tt>jsp-property-group</tt> element and give it the name of the file to include, in this case, <tt>/template/coda.jspf</tt>.</li></ol> Preludes and codas can put the included code only at the beginning and end of each file. For a more flexible approach to building pages out of content chunks, see <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnann.html#bnaoh">A Template Tag Library</a>. <a name="bnajm"></a><h5>Eliminating Extra White Space</h5> White space included in the template text of JSP pages is preserved by default. This can have undesirable effects. For example, a carriage return added after a <tt>taglib</tt> directive would be added to the response output as an extra line.If you want to eliminate the extra white space from the page, you can add a <tt>trim-directive-whitespaces</tt> element to a <tt>jsp-property-group</tt> element in the deployment descriptor and set it to <tt>true</tt>.To set the <tt>trim-directive-whitespaces</tt> element to true using NetBeans 5.5, do the following: <ol><li>Open the deployment descriptor file in the editor.</li> <li>Click the Pages button at the top of the editor.</li> <li>Select a JSP property group.</li> <li>Select the Trim Directive Whitespaces check box.</li> <li>Save the deployment descriptor.</li></ol> Alternatively, a page author can set the value of the <tt>trimDirectiveWhitespaces</tt> attribute of the <tt>page</tt> directive to true or false. This will override the value specified in the deployment descriptor.Custom tag authors can eliminate white space from the output generated by a tag file by setting the <tt>trimDirectiveWhiteSpace</tt> attribute of the <tt>tag</tt> directive to true. January 20, 2008 Including an Applet You can include an applet or a JavaBeans component in a JSP page by using the <tt>jsp:plugin</tt> element. This element generates HTML that contains the appropriate client-browser-dependent construct (<tt><object></tt> or <tt><embed></tt>) that will result in the download of the Java Plug-in software (if required) and the client-side component, and in the subsequent execution of any client-side component. The syntax for the <tt>jsp:plugin</tt> element is as follows:<pre><jsp:plugin type="bean|applet" code="objectCode" codebase="objectCodebase" { align="alignment" } { archive="archiveList" } { height="height" } { hspace="hspace" } { jreversion="jreversion" } { name="componentName" } { vspace="vspace" } { width="width" } { nspluginurl="url" } { iepluginurl="url" } > { <jsp:params> { <jsp:param name="paramName" value= paramValue" /> }+ </jsp:params> } { <jsp:fallback> arbitrary-text </jsp:fallback> } </jsp:plugin></pre>The <tt>jsp:plugin</tt> tag is replaced by either an <tt><object></tt> or an <tt><embed></tt> tag as appropriate for the requesting client. The attributes of the <tt>jsp:plugin</tt> tag provide configuration data for the presentation of the element as well as the version of the plug-in required. The <tt>nspluginurl</tt> and <tt>iepluginurl</tt> attributes override the default URL where the plug-in can be downloaded.<a name="indexterm-409"></a><a name="indexterm-410"></a>The <tt>jsp:params</tt> element specifies parameters to the applet or JavaBeans component. The <tt>jsp:fallback</tt> element indicates the content to be used by the client browser if the plug-in cannot be started (either because <tt><object></tt> or <tt><embed></tt> is not supported by the client or because of some other problem).If the plug-in can start but the applet or JavaBeans component cannot be found or started, a plug-in-specific message will be presented to the user, most likely a pop-up window reporting a <tt>ClassNotFoundException</tt>.<a name="indexterm-411"></a>The Duke’s Bookstore page <tt>/template/prelude.jspf</tt> creates the banner that displays a dynamic digital clock generated by <tt>DigitalClock</tt> (see <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnaje.html#bnajf">Figure 5-3</a>).<a name="bnajf"></a><h6>Figure 5-3 Duke’s Bookstore with Applet</h6><img src="http://java.sun.com/javaee/5/docs/tutorial/doc/figures/web-applet.gif" alt="Screen capture of Duke‘s Bookstore with " components="" for="" web="" developers="" recommendation,="" start="" shopping="" link="" date="" and="" time="" applet.="" height="568" width="662">Here is the <tt>jsp:plugin</tt> element that is used to download the applet:<pre><jsp:plugin type="applet" code="DigitalClock.class" codebase="/bookstore2" jreversion="1.4" align="center" height="25" width="300" nspluginurl="http://java.sun.com/j2se/1.4.2/download.html" iepluginurl="http://java.sun.com/j2se/1.4.2/download.html" > <jsp:params> <jsp:param name="language" value="${pageContext.request.locale.language}" /> <jsp:param name="country" value="${pageContext.request.locale.country}" /> <jsp:param name="bgcolor" value="FFFFFF" /> <jsp:param name="fgcolor" value="CC0066" /> </jsp:params> <jsp:fallback> Unable to start plugin. </jsp:fallback> </jsp:plugin></pre> January 20, 2008 JavaServer Pages Documents A JSP document is a JSP page written in XML syntax as opposed to the standard syntax described in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnagx.html">Chapter 5, JavaServer Pages Technology</a>. Because it is written in XML syntax, a JSP document is also an XML document and therefore gives you all the benefits offered by the XML standard: <ul><li>You can author a JSP document using one of the many XML-aware tools on the market, enabling you to ensure that your JSP document is well-formed XML.</li> <li>You can validate the JSP document against a document type definition (DTD).</li> <li>You can nest and scope namespaces within a JSP document.</li> <li>You can use a JSP document for data interchange between web applications and as part of a compile-time XML pipeline.</li></ul> <a name="indexterm-420"></a>In addition to these benefits, the XML syntax gives the JSP page author less complexity and more flexibility. For example, a page author can use any XML document as a JSP document. Also, elements in XML syntax can be used in JSP pages written in standard syntax, allowing a gradual transition from JSP pages to JSP documents.This chapter gives you details on the benefits of JSP documents and uses a simple example to show you how easy it is to create a JSP document.You can also write tag files in XML syntax. This chapter covers only JSP documents. Writing tag files in XML syntax will be addressed in a future release of the tutorial. January 20, 2008 The Example JSP Document This chapter uses the Duke’s Bookstore application, version <tt>bookstore5</tt>, and the <tt>books</tt> application to demonstrate how to write JSP pages in XML syntax. The JSP pages of the <tt>bookstore5</tt> application use the JSTL XML tags (see <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnakq.html">XML Tag Library</a>) to manipulate the book data from an XML stream. The <tt>books</tt> application contains the JSP document <tt>books.jspx</tt>, which accesses the book data from the database and converts it into the XML stream. The <tt>bookstore5</tt> application accesses this XML stream to get the book data.These applications show how easy it is to generate XML data and stream it between web applications. The <tt>books</tt> application can be considered the application hosted by the book warehouse’s server. The <tt>bookstore5</tt> application can be considered the application hosted by the book retailer’s server. In this way, the customer of the bookstore web site sees the list of books currently available, according to the warehouse’s database.The source for the Duke’s Bookstore application is located in the <tt></tt>tut-install<tt>/javaeetutorial5/examples/web/bookstore5/</tt> directory, which is created when you unzip the tutorial bundle (see <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/gfiud.html">Chapter 2, Using the Tutorial Examples</a>).To deploy the <tt>books</tt> application using NetBeans IDE, follow these steps: <ol><li>Perform all the operations described in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnaez.html">Accessing Databases from Web Applications</a>.</li> <li>In NetBeans IDE, select File→Open Project.</li> <li>In the Open Project dialog, navigate to:<pre>tut-install/javaeetutorial5/examples/web/</pre></li> <li>Select the <tt>books</tt> folder.</li> <li>Select the Open as Main Project check box and the Open Required Projects check box.</li> <li>Click Open Project Folder.</li> <li>In the Projects tab, right-click the <tt>books</tt> project, and select Deploy Project.</li></ol> To deploy the <tt>books</tt> application using the Ant utility, follow these steps: <ol><li>In a terminal window, go to <tt></tt>tut-install<tt>/javaeetutorial5/examples/web/books/</tt>.</li> <li>Type <tt>ant build</tt>. This target will spawn any necessary compilations, copy files to the <tt></tt>tut-install<tt>/javaeetutorial5/examples/web/books/build/</tt> directory, build a WAR file, and copy the WAR file to the <tt></tt>tut-install<tt>/javaeetutorial5/examples/web/books/dist/</tt> directory.</li> <li>To deploy the application, type <tt>ant deploy</tt>.</li></ol> To deploy and run the <tt>bookstore5</tt> application using NetBeans IDE, follow these steps: <ol><li>Perform all the operations described in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnaez.html">Accessing Databases from Web Applications</a>.</li> <li>In NetBeans IDE, select File→Open Project.</li> <li>In the Open Project dialog, navigate to:<pre><tt></tt>tut-install<tt>/javaeetutorial5/examples/web/</tt></pre></li> <li>Select the <tt>bookstore5</tt> folder.</li> <li>Select the Open as Main Project check box and the Open Required Projects check box.</li> <li>Click Open Project Folder.</li> <li>In the Projects tab, right-click the <tt>bookstore5</tt> project, and select Deploy Project.</li> <li>To run the applications, open the bookstore URL <tt>http://localhost:8080/bookstore5/books/bookstore</tt>.</li></ol> To deploy and run the application using Ant, follow these steps: <ol><li>In a terminal window, go to <tt></tt>tut-install<tt>/javaeetutorial5/examples/web/bookstore5/</tt>.</li> <li>Type <tt>ant</tt>. This command will spawn any necessary compilations, copy files to the <tt></tt>tut-install<tt>/javaeetutorial5/examples/web/bookstore5/build/</tt> directory, and create a WAR file and copy it to the <tt></tt>tut-install<tt>/javaeetutorial5/examples/web/bookstore5/dist/</tt> directory.</li> <li>Start the Application Server.</li> <li>Perform all the operations described in <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnaez.html#bnafb">Creating a Data Source in the Application Server</a>.</li> <li>To deploy the example, type <tt>ant deploy</tt>. The <tt>deploy</tt> target outputs a URL for running the application. Ignore this URL, and instead use the one shown in the next step.</li> <li>To run the applications, open the bookstore URL <tt>http://localhost:8080/bookstore5/books/bookstore</tt>.</li></ol> To learn how to configure the <tt>bookstore5</tt> example, refer to the <tt>web.xml</tt> file, which includes the following configurations: <ul><li>A <tt>display-name</tt> element that specifies the name that tools use to identify the application.</li> <li>A <tt>context-param</tt> element that identifies the context path to the XML stream.</li> <li>A <tt>context-param</tt> element that specifies the JSTL resource bundle base name.</li> <li>A set of <tt>servlet</tt> elements that identify the JSP files in the application.</li> <li>A set of <tt>servlet-mapping</tt> elements that identify aliases to the JSP pages identified by the <tt>servlet</tt> elements.</li> <li>Nested inside a <tt>jsp-config</tt> element are two <tt>jsp-property-group</tt> elements, which define the preludes and coda to be included in each page. See <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnair.html#bnaiu">Setting JavaBeans Component Properties</a> for more information.</li></ul> To learn how to configure the <tt>books</tt> example, refer to the <tt>web.xml</tt> file, which includes the following configurations: <ul><li>A <tt>display-name</tt> element that specifies the name that tools use to identify the application.</li> <li>A <tt>listener</tt> element that identifies the <tt>ContextListener</tt> class used to create and remove the database access.</li> <li>A <tt>servlet</tt> element that identifies the JSP page.</li> <li>Nested inside a <tt>jsp-config</tt> element is a <tt>jsp-property-group</tt> element, which identifies the JSP page as an XML document. See <a href="http://java.sun.com/javaee/5/docs/tutorial/doc/bnakb.html">Identifying the JSP Document to the Container</a> for more information.</li></ul>