The Jakarta EE 8 Tutorial

Although other enterprise application models require platform-specific security measures in each application, the Jakarta 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 Jakarta EE platform provides standard declarative access control rules that are defined by the developer and interpreted when the application is deployed on the server. Jakarta EE also provides standard login mechanisms so that application developers do not have to implement these mechanisms in their applications. The same application works in a variety of security environments without changing the source code.

Jakarta EE applications are made up of components. A Jakarta EE component is a self-contained functional software unit that is assembled into a Jakarta EE application with its related classes and files and that communicates with other components.

The Jakarta EE specification defines the following Jakarta EE components:

Jakarta EE components are written in the Java programming language and are compiled in the same way as any program in the language. The differences between Jakarta EE components and "standard" Java classes are that Jakarta EE components are assembled into a Jakarta EE application, they are verified to be well formed and in compliance with the Jakarta EE specification, and they are deployed to production, where they are run and managed by the Jakarta EE server.

A Jakarta EE client is usually either a web client or an application client.

Jakarta EE web components are either servlets or web pages created using Jakarta Faces technology and/or Jakarta Server Pages technology. Servlets are Java programming language classes that dynamically process requests and construct responses. Jakarta Server Pages are text-based documents that execute as servlets but allow a more natural approach to creating static content. Jakarta Faces technology builds on servlets and Jakarta Server Pages technology and provides a user interface component framework for web applications.

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 Figure 1-3, 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.

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 either the business tier or the web tier. Figure 1-4 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.

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, Jakarta EE application components might need access to enterprise information systems for database connectivity.

Containers are the interface between a component and the low-level, platform-specific functionality that supports the component. Before it can be executed, a web, enterprise bean, or application client component must be assembled into a Jakarta EE module and deployed into its container.

The assembly process involves specifying container settings for each component in the Jakarta EE application and for the Jakarta EE application itself. Container settings customize the underlying support provided by the Jakarta EE server, including such services as security, transaction management, Java Naming and Directory Interface (JNDI) API lookups, and remote connectivity. Here are some of the highlights.

Because the Jakarta EE architecture provides configurable services, components within the same 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.

The container also manages nonconfigurable services, such as enterprise bean and servlet lifecycles, database connection resource pooling, data persistence, and access to the Jakarta EE platform APIs (see Jakarta EE 8 APIs).

The deployment process installs Jakarta EE application components in the Jakarta EE containers, as illustrated in Figure 1-5.

The server and containers are as follows:

Extensible Markup Language (XML) is a cross-platform, extensible, text-based standard for representing data. Parties that exchange XML data can 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 style sheets 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 style sheets to handle the data in a way that best suits their needs. Here are examples.

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 does the following:

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 published on the Web. Eclipse GlassFish Server provides a tool for generating the WSDL specification of a web service that uses remote procedure calls to communicate with clients.

An enterprise bean component, or enterprise bean, is a body of code that has 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 Jakarta EE server.

Enterprise beans are either session beans or message-driven beans.

The Jakarta EE 8 platform requires Jakarta Enterprise Beans 3.2 and Jakarta Interceptors 1.2.

Jakarta Servlet technology lets you define HTTP-specific servlet classes. A servlet class extends the capabilities of servers that host applications 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.

In the Jakarta EE 8 platform, new Jakarta Servlet technology features include the following:

The Jakarta EE 8 platform requires Servlet 4.0.

Jakarta Faces technology is a user interface framework for building web applications. The main components of Jakarta Faces technology are as follows:

The following features support the GUI components:

All this functionality is available using standard Java APIs and XML-based configuration files.

In the Jakarta EE 8 platform, new features of Jakarta Faces technology include the following:

The Jakarta EE 8 platform requires Jakarta Faces 2.3 and Jakarta Expression Language 3.0.

For an excellent summary of what’s new in Jakarta Faces 2.3, see https://javaserverfaces.github.io/users.html.

Jakarta Server Pages technology lets you put snippets of servlet code directly into a text-based document. A Jakarta Server Pages page is a text-based document that contains two types of text:

The Jakarta Server Pages technology is derived from and compatible with the JavaServer Pages (JSP) technology. For information about JSP technology, see The Java EE 5 Tutorial at http://docs.oracle.com/javaee/5/tutorial/doc/.

The Jakarta EE 8 platform requires Jakarta Server Pages 2.3 for compatibility with earlier releases but recommends the use of Facelets as the display technology in new applications.

The Jakarta Standard Tag Library encapsulates core functionality common to many Jakarta Server Pages applications. Instead of mixing tags from numerous vendors in your Jakarta Server Pages applications, you use a single, standard set of tags. This standardization allows you to deploy your applications on any Jakarta Server Pages container that supports Jakarta Standard Tag Library and makes it more likely that the implementation of the tags is optimized.

Jakarta Standard Tag Library has iterator and conditional tags for handling flow control, tags for manipulating XML documents, internationalization tags, tags for accessing databases using SQL, and tags for commonly used functions.

The Jakarta EE 8 platform requires Jakarta Standard Tag Library 1.2.

Jakarta Persistence 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. The Jakarta Persistence can also be used in Java SE applications outside of the Jakarta EE environment. Jakarta Persistence consists of the following areas:

The Jakarta EE 8 platform requires Jakarta Persistence 2.2.

Jakarta Transactions provides a standard interface for demarcating transactions. The Jakarta 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 Jakarta Transactions to demarcate where the entire transaction, including both operations, begins, rolls back, and commits.

The Jakarta EE 8 platform requires Jakarta Transactions 1.2.

Jakarta RESTful Web Services defines APIs for the development of web services built according to the Representational State Transfer (REST) architectural style. A Jakarta RESTful application is a web application that consists of classes packaged as a servlet in a WAR file along with required libraries.

In the Jakarta EE 8 platform, new RESTful web services features include the following:

The Jakarta EE 8 platform requires Jakarta RESTful Web Services 2.1.

Jakarta Managed Beans, lightweight container-managed objects (POJOs) with minimal requirements, support a small set of basic services, such as resource injection, lifecycle callbacks, and interceptors. Managed Beans represent a generalization of the managed beans specified by Jakarta Faces technology and can be used anywhere in a Jakarta EE application, not just in web modules.

The Jakarta Managed Beans specification is part of the Jakarta EE 8 platform specification. The Jakarta EE 8 platform requires Jakarta Managed Beans 1.0.

Jakarta Contexts and Dependency Injection (CDI) defines a set of contextual services, provided by Jakarta EE containers, that make it easy for developers to use enterprise beans along with Jakarta Faces technology in web applications. Designed for use with stateful objects, CDI also has many broader uses, allowing developers a great deal of flexibility to integrate different kinds of components in a loosely coupled but typesafe way.

In the Jakarta EE 8 platform, new CDI features include the following:

The Jakarta EE 8 platform requires Jakarta Contexts and Dependency Injection 2.0.

Jakarta Dependency Injection defines a standard set of annotations (and one interface) for use on injectable classes.

In the Jakarta EE platform, CDI provides support for Dependency Injection. Specifically, you can use injection points only in a CDI-enabled application.

The Jakarta EE 8 platform requires Jakarta Dependency Injection 1.0.

The Jakarta Bean Validation specification defines a metadata model and API for validating data in JavaBeans components. Instead of distributing validation of data over several layers, such as the browser and the server side, you can define the validation constraints in one place and share them across the different layers.

In the Jakarta EE 8 platform, new Jakarta Bean Validation features include the following:

The Jakarta EE 8 platform requires Jakarta Bean Validation 2.0.

Jakarta Messaging is a messaging standard that allows Jakarta EE application components to create, send, receive, and read messages. It enables distributed communication that is loosely coupled, reliable, and asynchronous.

The Jakarta EE 8 platform requires Jakarta Messaging 2.0.

The Jakarta Connectors 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 Jakarta EE product. A resource adapter is a software component that allows Jakarta 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, a different resource adapter typically exists for each type of database or enterprise information system.

The Jakarta Connectors also provides a performance-oriented, secure, scalable, and message-based transactional integration of Jakarta EE platform-based web services with existing EISs that can be either synchronous or asynchronous. Existing applications and EISs integrated through the Jakarta Connectors into the Jakarta EE platform can be exposed as XML-based web services by using Jakarta XML Web Services and Jakarta EE component models. Thus Jakarta XML Web Services and the Jakarta Connectors are complementary technologies for enterprise application integration (EAI) and end-to-end business integration.

The Jakarta EE 8 platform requires Jakarta Connectors 1.7.

Jakarta EE applications use the Jakarta Mail to send email notifications. The Jakarta Mail has two parts:

The Jakarta EE platform includes the Jakarta Mail with a service provider that allows application components to send Internet mail.

The Jakarta EE 8 platform requires Jakarta Mail 1.6.

The Jakarta Authorization specification defines a contract between a Jakarta EE application server and an authorization policy provider. All Jakarta EE containers support this contract.

The Jakarta Authorization specification defines java.security.Permission classes that satisfy the Jakarta EE authorization model. The specification defines the binding of container-access decisions to operations on instances of these permission classes. It defines the semantics of policy providers that use the new permission classes to address the authorization requirements of the Jakarta EE platform, including the definition and use of roles.

The Jakarta EE 8 platform requires Jakarta Authorization 1.5.

The Jakarta Authentication specification defines a service provider interface (SPI) by which authentication providers that implement message authentication mechanisms may be integrated in client or server message-processing containers or runtimes. Authentication providers integrated through this interface operate on network messages provided to them by their calling containers. The authentication providers transform outgoing messages so that the source of each message can be authenticated by the receiving container, and the recipient of the message can be authenticated by the message sender. Authentication providers authenticate each incoming message and return to their calling containers the identity established as a result of the message authentication.

The Jakarta EE 8 platform requires Jakarta Authentication 1.1.

Jakarta Security specification defines portable, plug-in interfaces for HTTP authentication and identity stores, and an injectable SecurityContext interface that provides an API for programmatic security.

Implementations of the HttpAuthenticationMechanism interface can be used to authenticate callers of web applications. An application can supply its own HttpAuthenticationMechanism, or use one of the default implementations provided by the container.

Implementations of the IdentityStore interface can be used to validate user credentials and retrieve group information. An application can provide its own IdentityStore, or use the built in LDAP or Database store.

The HttpAuthenticationMechanism and IdentityStore APIs provide an advantage over container-provided implementations in that they allow an application to control the authentication process, and the identity stores used for authentication, in a standard, portable way.

The SecurityContext API is intended for use by application code to query and interact with the current security context. The specification also provides for default group-to-role mapping, and defines a principal type called CallerPrincipal that can represent the identity of an application caller.

The Jakarta EE 8 platform requires Jakarta Security 1.0.

WebSocket is an application protocol that provides full-duplex communications between two peers over TCP. Jakarta WebSocket enables Jakarta EE applications to create endpoints using annotations that specify the configuration parameters of the endpoint and designate its lifecycle callback methods.

The Jakarta EE 8 platform requires Jakarta WebSocket 1.1.

JavaScript Object Notation (JSON) is a text-based data exchange format derived from JavaScript that is used in web services and other connected applications. Jakarta JSON Processing enables Jakarta EE applications to parse, transform, and query JSON data using the object model or the streaming model.

In the Jakarta EE 8 platform, new features of Jakarta JSON Processing include support for the following:

The Jakarta EE 8 platform requires Jakarta JSON Processing 1.1.

Jakarta JSON Binding provides a binding layer for converting Java objects to and from JSON messages. Jakarta JSON Binding also supports the ability to customize the default mapping process used in this binding layer through the use of Java annotations for a given field, JavaBean property, type or package, or by providing an implementation of a property naming strategy.

Jakarta JSON Binding is new to the Jakarta EE 8 platform. The Jakarta EE 8 platform requires Jakarta JSON Binding 1.0.

Jakarta Concurrency is a standard API for providing asynchronous capabilities to Jakarta EE application components through the following types of objects: managed executor service, managed scheduled executor service, managed thread factory, and context service.

The Jakarta EE 8 platform requires Jakarta Concurrency 1.0.

Batch jobs are tasks that can be executed without user interaction. The Batch Applications for the Java Platform specification is a batch framework that provides support for creating and running batch jobs in Java applications. The batch framework consists of a batch runtime, a job specification language based on XML, a Java API to interact with the batch runtime, and a Java API to implement batch artifacts.

The Jakarta EE 8 platform requires Jakarta Batch 1.0.

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:

The Jakarta EE 8 platform requires JDBC 4.1.

The Java Naming and Directory Interface (JNDI) API provides naming and directory functionality, enabling applications to access multiple naming and directory services, such as LDAP, DNS, and NIS. The JNDI API 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 Jakarta EE application can store and retrieve any type of named Java object, allowing Jakarta EE applications to coexist with many legacy applications and systems.

Jakarta 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.

The naming environment provides four logical namespaces: java:comp, java:module, java:app, and java:global for objects available to components, modules, or applications or shared by all deployed applications. A Jakarta EE component can access named system-provided and user-defined objects. The names of some system-provided objects, such as a default JDBC DataSource object, a default JMS connection factory, and a JTA UserTransaction object, are stored in the java:comp namespace. The Jakarta EE platform allows a component to name user-defined objects, such as enterprise beans, environment entries, JDBC DataSource objects, and messaging destinations.

A Jakarta EE component can also locate its environment naming context by using JNDI interfaces. A component can create a javax.naming.InitialContext object and look up the environment naming context in InitialContext under the name java:comp/env. A component’s naming environment is stored directly in the environment naming context or in any of its direct or indirect subcontexts.

The Jakarta Activation is used by the Jakarta Mail. Jakarta Activation 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.

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 independently 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 Worldwide Web Consortium (W3C) schema. You can find information on the W3C schema at http://www.w3.org/XML/Schema.

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 Jakarta XML Web Services, in which case it provides a standard data binding for web service messages. All Jakarta EE application client containers, web containers, and Jakarta Enterprise Beans containers support the JAXB API.

The Jakarta EE 8 platform requires JAXB 2.2.

The Jakarta XML Web Services specification provides support for web services that use the JAXB API for binding XML data to Java objects. The Jakarta XML Web Services specification defines client APIs for accessing web services as well as techniques for implementing web service endpoints. The Implementing Enterprise Web Services specification describes the deployment of Jakarta XML Web Services based services and clients. The Jakarta Enterprise Beans and Jakarta Servlet specifications also describe aspects of such deployment. Jakarta XML Web Services based applications can be deployed using any of these deployment models.

The Jakarta XML Web Services 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 Jakarta XML Web Services client or endpoint component with which they are associated. These message handlers have access to the same JNDI namespace as their associated component. Custom serializers and deserializers, if supported, are treated in the same way as message handlers.

The Jakarta EE 8 platform requires Jakarta XML Web Services 2.2.

The Jakarta SOAP with Attachments is a low-level API on which Jakarta XML Web Services depends. Jakarta SOAP with Attachments enables the production and consumption of messages that conform to the SOAP 1.1 and 1.2 specifications and the Jakarta SOAP with Attachments note. Most developers do not use the Jakarta SOAP with Attachments, instead using the higher-level Jakarta XML Web Services API.

The Java Authentication and Authorization Service (JAAS) provides a way for a Jakarta 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.

Annotations enable a declarative style of programming in the Java platform.

The Jakarta EE 8 platform requires Jakarta Annotations 1.2.

To build, deploy, and run the examples, you need a copy of the Java Platform, Standard Edition Development Kit (JDK). You must use JDK 8 Update 20 or above. You can download JDK software from http://www.oracle.com/technetwork/java/javase/downloads/index.html.

GlassFish Server 5.1 is targeted as the build and runtime environment for the tutorial examples. To build, deploy, and run the examples, you need a copy of GlassFish Server and, optionally, NetBeans IDE. You can download GlassFish Server from https://eclipse-ee4j.github.io/glassfish/download.

The tutorial example codes are located at https://github.com/eclipse-ee4j/jakartaee-tutorial-examples.

The NetBeans integrated development environment (IDE) is a free, open-source IDE for developing Java applications, including enterprise applications. NetBeans IDE supports the Jakarta EE platform. You can build, package, deploy, and run the tutorial examples from within NetBeans IDE.

To run the tutorial examples, you need the latest version of NetBeans IDE. You can download NetBeans IDE from https://netbeans.apache.org/download/index.html. Make sure that you download the Jakarta EE bundle.

Maven is a Java technology-based build tool developed by the Apache Software Foundation and is used to build, package, and deploy the tutorial examples. To run the tutorial examples from the command line, you need Maven 3.0 or higher. If you do not already have Maven, you can install it from:

http://maven.apache.org

Be sure to add the maven-install`/bin` directory to your path.

If you are using NetBeans IDE to build and run the examples, it includes a copy of Maven.

To stop GlassFish Server using NetBeans IDE, right-click the GlassFish Server instance and select Stop.

To start GlassFish Server from the command line, open a terminal window or command prompt and execute the following:

A domain is a set of one or more GlassFish Server instances managed by one administration server. The following elements are associated with a domain:

You specify these values when you install GlassFish Server. The examples in this tutorial assume that you chose the default ports as well as the default user name and lack of password.

With no arguments, the start-domain command initiates the default domain, which is domain1. The --verbose flag causes all logging and debugging output to appear on the terminal window or command prompt. The output also goes into the server log, which is located in domain-dir`/logs/server.log`.

To stop GlassFish Server, open a terminal window or command prompt and execute:

When you start GlassFish Server using NetBeans IDE, the database server starts automatically. If you ever need to start the server manually, however, follow these steps.

Next Steps

To stop the database using NetBeans IDE, right-click Java DB and select Stop Server.

You must install the included Maven archetypes into your local Maven repository before you can create new projects based on the archetypes. You can install the archetypes using NetBeans IDE or Maven.

One way to debug applications is to look at the server log in domain-dir/logs/server.log. The log contains output from GlassFish Server and your applications. You can log messages from any Java class in your application with System.out.println and the Java Logging APIs (documented at http://docs.oracle.com/javase/8/docs/technotes/guides/logging/index.html) and from web components with the ServletContext.log method.

If you use NetBeans IDE, logging output appears in the Output window as well as the server log.

If you start GlassFish Server with the --verbose flag, all logging and debugging output will appear on the terminal window or command prompt and the server log. If you start GlassFish Server in the background, debugging information is available only in the log. You can view the server log with a text editor or with the Administration Console log viewer.

GlassFish Server supports the Java Platform Debugger Architecture (JPDA). With JPDA, you can configure GlassFish Server to communicate debugging information using a socket.

An enterprise bean JAR file is portable and can be used for various applications.

To assemble a Jakarta EE application, package one or more modules, such as enterprise bean JAR files, into an EAR file, the archive file that holds the application. When deploying the EAR file that contains the enterprise bean’s enterprise bean JAR file, you also deploy the enterprise bean to GlassFish Server. You can also deploy an enterprise bean JAR that is not contained in an EAR file. Figure 5-2 shows the contents of an enterprise bean JAR file.

Enterprise beans often provide the business logic of a web application. In these cases, packaging the enterprise bean within the web application’s WAR module simplifies deployment and application organization. Enterprise beans may be packaged within a WAR module as Java programming language class files or within a JAR file that is bundled within the WAR module.

To include enterprise bean class files in a WAR module, the class files should be in the WEB-INF/classes directory.

To include a JAR file that contains enterprise beans in a WAR module, add the JAR to the WEB-INF/lib directory of the WAR module.

WAR modules that contain enterprise beans do not require an ejb-jar.xml deployment descriptor. If the application uses ejb-jar.xml, it must be located in the WAR module’s WEB-INF directory.

JAR files that contain enterprise bean classes packaged within a WAR module are not considered enterprise bean JAR files, even if the bundled JAR file conforms to the format of an enterprise bean JAR file. The enterprise beans contained within the JAR file are semantically equivalent to enterprise beans located in the WAR module’s WEB-INF/classes directory, and the environment namespace of all the enterprise beans are scoped to the WAR module.

For example, suppose that a web application consists of a shopping cart enterprise bean, a credit card–processing enterprise bean, and a Java servlet front end. The shopping cart bean exposes a local, no-interface view and is defined as follows:

The credit card–processing bean is packaged within its own JAR file, cc.jar, exposes a local, no-interface view, and is defined as follows:

The servlet, com.example.web.StoreServlet, handles the web front end and uses both CartBean and CreditCardBean. The WAR module layout for this application is as follows:

To view the hello1 web module using NetBeans IDE:

A web module must be packaged into a WAR in certain deployment scenarios and whenever you want to distribute the web module. You can package a web module into a WAR file by using Maven or by using the IDE tool of your choice. This tutorial shows you how to use NetBeans IDE or Maven to build, package, and deploy the hello1 sample application.

You can deploy a WAR file to GlassFish Server by:

Throughout the tutorial, you will use NetBeans IDE or Maven for packaging and deploying.

GlassFish Server provides two ways to view the deployed web modules: the Administration Console and the asadmin command. You can also use NetBeans IDE to view deployed modules.

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 localhost on port 8080. The context root of the web application is hello1.

To run the deployed hello1 web module:

You can undeploy web modules and other types of enterprise applications by using either NetBeans IDE or Maven.

When it receives a request, the web container must determine which web component should handle the request. The web container 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, optionally, a URL pattern:

You set the URL pattern for a servlet by using the @WebServlet annotation in the servlet source file. For example, the GreetingServlet.java file in the hello2 application contains the following annotation, specifying the URL pattern as /greeting:

This annotation indicates that the URL pattern /greeting follows the context root. Therefore, when the servlet is deployed locally, it is accessed with the following URL:

To access the servlet by using only the context root, specify "/" as the URL pattern.

The hello2 application behaves almost identically to the hello1 application, but it is implemented using Jakarta Servlet technology instead of Jakarta Server Faces technology. You can use a text editor to view the application files, or you can use NetBeans IDE.

You can use either NetBeans IDE or Maven to build, package, deploy, and run the hello2 example.

The web components in a web module share an object that represents their application context. You can pass context parameters to the context, or you can pass initialization parameters to a servlet. Context parameters are available to the entire application. For information on initialization parameters, see Creating and Initializing a Servlet.

The welcome files mechanism allows you to specify a list of files that the web container can append to a request for a URL (called a valid partial request) that is not mapped to a web component. For example, suppose that you define a welcome file welcome.html. When a client requests a URL such as host:port/webapp/directory, where directory is not mapped to a servlet or XHTML page, the file host:port/webapp/directory/`welcome.html is returned to the client.

If a web container receives a valid partial request, the web container examines the welcome file list, 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 that matches in the WAR.

If no welcome file is specified, GlassFish Server will use a file named index.html as the default welcome file. If there is no welcome file and no file named index.html, GlassFish Server returns a directory listing.

You specify welcome files in the web.xml file. The welcome file specification for the hello1 example looks like this:

A specified welcome file must not have a leading or trailing slash (/).

The hello2 example does not specify a welcome file, because the URL request is mapped to the GreetingServlet web component through the URL pattern /greeting.

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 and any type of error screen.

You can have multiple error-page elements in your deployment descriptor. Each element identifies a different error that causes an error page to open. This error page can be the same for any number of error-page elements.

If your web component uses such objects as enterprise beans, data sources, or web services, you use Jakarta 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 Jakarta EE required.

Although resource injection using annotations can be more convenient for the developer, there are some restrictions on using it in web applications. First, you can inject resources only into container-managed objects, 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 such objects as simple JavaBeans components. However, managed beans are managed by the container; therefore, they can accept resource injections.

Components that can accept resource injections are listed in Table 6-1.

This section explains how to use a couple of the annotations supported by a web container to inject resources. Chapter 41, "Running the Persistence Examples", explains how web applications use annotations supported by Jakarta Persistence. Chapter 51, "Getting Started Securing Web Applications", explains how to use annotations to specify information about securing web applications. See Chapter 55, "Resource Adapters and Contracts", for more information on resources.

Table 6-1 Web Components That Accept Resource Injections

Jakarta Server Faces technology provides a set of UI component classes and associated behavioral interfaces that specify all the UI component functionality, such as holding component state, maintaining a reference to objects, and driving event handling and rendering for a set of standard components.

The component classes are completely extensible, allowing component writers to create their own custom components. See Chapter 15, "Creating Custom UI Components and Other Custom Objects" for more information.

The abstract base class for all components is javax.faces.component.UIComponent. Jakarta Server Faces UI component classes extend the UIComponentBase class (a subclass of UIComponent), which defines the default state and behavior of a component. The following set of component classes is included with Jakarta Server Faces technology.

In addition to extending UIComponentBase, the component classes also implement one or more behavioral interfaces, each of which defines certain behavior for a set of components whose classes implement the interface.

These behavioral interfaces, all defined in the javax.faces.component package unless otherwise stated, are as follows.

UICommand implements ActionSource2 and StateHolder. UIOutput and component classes that extend UIOutput implement StateHolder and ValueHolder. UIInput and component classes that extend UIInput implement EditableValueHolder, StateHolder, and ValueHolder. UIComponentBase implements StateHolder.

Only component writers will need to use the component classes and behavioral interfaces directly. Page authors and application developers will use a standard component by including a tag that represents it on a page. Most of the components can be rendered in different ways on a page. For example, a UICommand component can be rendered as a button or a link.

The next section explains how the rendering model works and how page authors can choose to render the components by selecting the appropriate tags.

The Jakarta Server Faces component architecture is designed such that the functionality of the components is defined by the component classes, whereas the component rendering can be defined by a separate renderer class. This design has several benefits, including the following.

A render kit defines how component classes map to component tags that are appropriate for a particular client. The Jakarta Server Faces implementation includes a standard HTML render kit for rendering to an HTML client.

The render kit defines a set of javax.faces.render.Renderer classes for each component that it supports. Each Renderer class defines a different way to render the particular component to the output defined by the render kit. For example, a UISelectOne component has three different renderers. One of them renders the component as a group of options. Another renders the component as a combo box. The third one renders the component as a list box. Similarly, a UICommand component can be rendered as a button or a link, using the h:commandButton or h:commandLink tag. The command part of each tag corresponds to the UICommand class, specifying the functionality, which is to fire an action. The Button or Link part of each tag corresponds to a separate Renderer class that defines how the component appears on the page.

Each custom tag defined in the standard HTML render kit is composed of the component functionality (defined in the UIComponent class) and the rendering attributes (defined by the Renderer class).

The section Adding Components to a Page Using HTML Tag Library Tags lists all supported component tags and illustrates how to use the tags in an example.

The Jakarta Server Faces implementation provides a custom tag library for rendering components in HTML.

A Jakarta Server Faces application can optionally associate a component with server-side object data. This object is a JavaBeans component, such as a managed bean. An application gets and sets the object data for a component by calling the appropriate object properties for that component.

When a component is bound to an object, the application has two views of the component’s data.

The Jakarta Server Faces implementation automatically converts component data between these two views when the bean property associated with the component is of one of the types supported by the component’s data. For example, if a UISelectBoolean component is associated with a bean property of type java.lang.Boolean, the Jakarta Server Faces implementation will automatically convert the component’s data from String to Boolean. In addition, some component data must be bound to properties of a particular type. For example, a UISelectBoolean component must be bound to a property of type boolean or java.lang.Boolean.

Sometimes you might want to convert a component’s data to a type other than a standard type, or you might want to convert the format of the data. To facilitate this, Jakarta Server Faces technology allows you to register a javax.faces.convert.Converter implementation on UIOutput components and components whose classes subclass UIOutput. If you register the Converter implementation on a component, the Converter implementation converts the component’s data between the two views.

You can either use the standard converters supplied with the Jakarta Server Faces implementation or create your own custom converter. Custom converter creation is covered in Chapter 15, "Creating Custom UI Components and Other Custom Objects".

The Jakarta Server Faces event and listener model is similar to the JavaBeans event model in that it has strongly typed event classes and listener interfaces that an application can use to handle events generated by components.

The Jakarta Server Faces specification defines three types of events: application events, system events, and data-model events.

Application events are tied to a particular application and are generated by a UIComponent. They represent the standard events available in previous versions of Jakarta Server Faces technology.

An event object identifies the component that generated the event and stores information about the event. To be notified of an event, an application must provide an implementation of the listener class and must register it on the component that generates the event. When the user activates a component, such as by clicking a button, an event is fired. This causes the Jakarta Server Faces implementation to invoke the listener method that processes the event.

Jakarta Server Faces supports two kinds of application events: action events and value-change events.

An action event (class javax.faces.event.ActionEvent) occurs when the user activates a component that implements ActionSource. These components include buttons and links.

A value-change event (class javax.faces.event.ValueChangeEvent) occurs when the user changes the value of a component represented by UIInput or one of its subclasses. An example is selecting a check box, an action that results in the component’s value changing to true. The component types that can generate these types of events are the UIInput, UISelectOne, UISelectMany, and UISelectBoolean components. Value-change events are fired only if no validation errors are detected.

Depending on the value of the immediate property (see The immediate Attribute) of the component emitting the event, action events can be processed during the Invoke Application phase or the Apply Request Values phase, and value-change events can be processed during the Process Validations phase or the Apply Request Values phase.

System events are generated by an Object rather than a UIComponent. They are generated during the execution of an application at predefined times. They are applicable to the entire application rather than to a specific component.

A data-model event occurs when a new row of a UIData component is selected.

There are two ways to cause your application to react to action events or value-change events that are emitted by a standard component:

See Implementing an Event Listener for information on how to implement an event listener. See Registering Listeners on Components for information on how to register the listener on a component.

See Writing a Method to Handle an Action Event and Writing a Method to Handle a Value-Change Event for information on how to implement managed bean methods that handle these events.

See Referencing a Managed Bean Method for information on how to refer to the managed bean method from the component tag.

When emitting events from custom components, you must implement the appropriate event class and manually queue the event on the component in addition to implementing an event listener class or a managed bean method that handles the event. Handling Events for Custom Components explains how to do this.

Jakarta Server Faces technology supports a mechanism for validating the local data of editable components (such as text fields). This validation occurs before the corresponding model data is updated to match the local value.

Like the conversion model, the validation model defines a set of standard classes for performing common data validation checks. The Jakarta Server Faces core tag library also defines a set of tags that correspond to the standard javax.faces.validator.Validator implementations. See Using the Standard Validators for a list of all the standard validation classes and corresponding tags.

Most of the tags have a set of attributes for configuring the validator’s properties, such as the minimum and maximum allowable values for the component’s data. The page author registers the validator on a component by nesting the validator’s tag within the component’s tag.

In addition to validators that are registered on the component, you can declare a default validator that is registered on all UIInput components in the application. For more information on default validators, see Using Default Validators.

The validation model also allows you to create your own custom validator and corresponding tag to perform custom validation. The validation model provides two ways to implement custom validation.

If you are implementing a Validator interface, you must also do the following.

In the previously described standard validation model, the validator is defined for each input component on a page. The Bean Validation model allows the validator to be applied to all fields in a page. See Chapter 23, "Introduction to Bean Validation" and Chapter 24, "Bean Validation: Advanced Topics" for more information on Bean Validation.

The lifecycle of a Jakarta Server Faces application begins when the client makes an HTTP request for a page and ends when the server responds with the page, translated to HTML.

The lifecycle can be divided into two main phases: Execute and Render. The Execute phase is further divided into subphases to support the sophisticated component tree. This structure requires that component data be converted and validated, component events be handled, and component data be propagated to beans in an orderly fashion.

A Jakarta Server Faces page is represented by a tree of components, called a view. During the lifecycle, the Jakarta Server Faces implementation must build the view while considering the state saved from a previous submission of the page. When the client requests a page, the Jakarta Server Faces implementation performs several tasks, such as validating the data input of components in the view and converting input data to types specified on the server side.

The Jakarta Server Faces implementation performs all these tasks as a series of steps in the Jakarta Server Faces request-response lifecycle. Figure 7-3 illustrates these steps.

The request-response lifecycle handles two kinds of requests: initial requests and postbacks. An initial request occurs when a user makes a request for a page for the first time. A postback request occurs when a user submits the form contained on a page that was previously loaded into the browser as a result of executing an initial request.

When the lifecycle handles an initial request, it executes only the Restore View and Render Response phases, because there is no user input or action to process. Conversely, when the lifecycle handles a postback, it executes all of the phases.

Usually, the first request for a Jakarta Server Faces page comes in from a client, as a result of clicking a link or button component on a Jakarta Server Faces page. To render a response that is another Jakarta Server Faces page, the application creates a new view and stores it in the javax.faces.context.FacesContext instance, which represents all of the information associated with processing an incoming request and creating a response. The application then acquires object references needed by the view and calls the FacesContext.renderResponse method, which forces immediate rendering of the view by skipping to the Render Response Phase of the lifecycle, as is shown by the arrows labelled Render Response in Figure 7-3.

Sometimes, an application might need to redirect to a different web application resource, such as a web service, or generate a response that does not contain Jakarta Server Faces components. In these situations, the developer must skip the Render Response phase by calling the FacesContext.responseComplete method. This situation is also shown in , with the arrows labelled Response Complete.

The most common situation is that a Jakarta Server Faces component submits a request for another Jakarta Server Faces page. In this case, the Jakarta Server Faces implementation handles the request and automatically goes through the phases in the lifecycle to perform any necessary conversions, validations, and model updates and to generate the response.

There is one exception to the lifecycle described in this section. When a component’s immediate attribute is set to true, the validation, conversion, and events associated with these components are processed during the Apply Request Values Phase rather than in a later phase.

The details of the lifecycle explained in the following sections are primarily intended for developers who need to know information such as when validations, conversions, and events are usually handled and ways to change how and when they are handled. For more information on each of the lifecycle phases, download the latest Jakarta Server Faces Specification documentation from https://jakarta.ee/specifications/faces/.

The Jakarta Server Faces application lifecycle Execute phase contains the following subphases:

When a request for a Jakarta Server Faces page is made, usually by an action, such as when a link or a button component is clicked, the Jakarta Server Faces implementation begins the Restore View phase.

During this phase, the Jakarta Server Faces implementation builds the view of the page, wires event handlers and validators to components in the view, and saves the view in the FacesContext instance, which contains all the information needed to process a single request. All the application’s components, event handlers, converters, and validators have access to the FacesContext instance.

If the request for the page is an initial request, the Jakarta Server Faces implementation creates an empty view during this phase and the lifecycle advances to the Render Response phase, during which the empty view is populated with the components referenced by the tags in the page.

If the request for the page is a postback, a view corresponding to this page already exists in the FacesContext instance. During this phase, the Jakarta Server Faces implementation restores the view by using the state information saved on the client or the server.

After the component tree is restored during a postback request, each component in the tree extracts its new value from the request parameters by using its decode (processDecodes()) method. The value is then stored locally on each component.

If any decode methods or event listeners have called the renderResponse method on the current FacesContext instance, the Jakarta Server Faces implementation skips to the Render Response phase.

If any events have been queued during this phase, the Jakarta Server Faces implementation broadcasts the events to interested listeners.

If some components on the page have their immediate attributes (see The immediate Attribute) set to true, then the validations, conversions, and events associated with these components will be processed during this phase. If any conversion fails, an error message associated with the component is generated and queued on FacesContext. This message will be displayed during the Render Response phase, along with any validation errors resulting from the Process Validations phase.

At this point, if the application needs to redirect to a different web application resource or generate a response that does not contain any Jakarta Server Faces components, it can call the FacesContext.responseComplete method.

At the end of this phase, the components are set to their new values, and messages and events have been queued.

If the current request is identified as a partial request, the partial context is retrieved from the FacesContext, and the partial processing method is applied.

During this phase, the Jakarta Server Faces implementation processes all validators registered on the components in the tree by using its validate (processValidators) method. It examines the component attributes that specify the rules for the validation and compares these rules to the local value stored for the component. The Jakarta Server Faces implementation also completes conversions for input components that do not have the immediate attribute set to true.

If the local value is invalid, or if any conversion fails, the Jakarta Server Faces implementation adds an error message to the FacesContext instance, and the lifecycle advances directly to the Render Response phase so that the page is rendered again with the error messages displayed. If there were conversion errors from the Apply Request Values phase, the messages for these errors are also displayed.

If any validate methods or event listeners have called the renderResponse method on the current FacesContext, the Jakarta Server Faces implementation skips to the Render Response phase.

At this point, if the application needs to redirect to a different web application resource or generate a response that does not contain any Jakarta Server Faces components, it can call the FacesContext.responseComplete method.

If events have been queued during this phase, the Jakarta Server Faces implementation broadcasts them to interested listeners.

If the current request is identified as a partial request, the partial context is retrieved from the FacesContext, and the partial processing method is applied.

After the Jakarta Server Faces implementation determines that the data is valid, it traverses the component tree and sets the corresponding server-side object properties to the components' local values. The Jakarta Server Faces implementation updates only the bean properties pointed at by an input component’s value attribute. If the local data cannot be converted to the types specified by the bean properties, the lifecycle advances directly to the Render Response phase so that the page is re-rendered with errors displayed. This is similar to what happens with validation errors.

If any updateModels methods or any listeners have called the renderResponse method on the current FacesContext instance, the Jakarta Server Faces implementation skips to the Render Response phase.

At this point, if the application needs to redirect to a different web application resource or generate a response that does not contain any Jakarta Server Faces components, it can call the FacesContext.responseComplete method.

If any events have been queued during this phase, the Jakarta Server Faces implementation broadcasts them to interested listeners.

If the current request is identified as a partial request, the partial context is retrieved from the FacesContext, and the partial processing method is applied.

During this phase, the Jakarta Server Faces implementation handles any application-level events, such as submitting a form or linking to another page.

At this point, if the application needs to redirect to a different web application resource or generate a response that does not contain any Jakarta Server Faces components, it can call the FacesContext.responseComplete method.

If the view being processed was reconstructed from state information from a previous request and if a component has fired an event, these events are broadcast to interested listeners.

Finally, the Jakarta Server Faces implementation transfers control to the Render Response phase.

During this phase, Jakarta Server Faces builds the view and delegates authority to the appropriate resource for rendering the pages.

If this is an initial request, the components that are represented on the page will be added to the component tree. If this is not an initial request, the components are already added to the tree and need not be added again.

If the request is a postback and errors were encountered during the Apply Request Values phase, Process Validations phase, or Update Model Values phase, the original page is rendered again during this phase. If the pages contain h:message or h:messages tags, any queued error messages are displayed on the page.

After the content of the view is rendered, the state of the response is saved so that subsequent requests can access it. The saved state is available to the Restore View phase.

The example used in this tutorial is the guessnumber-jsf application. The application presents you with a page that asks you to guess a number from 0 to 10, validates your input against a random number, and responds with another page that informs you whether you guessed the number correctly or incorrectly.

The source code for this application is in the tut-install`/examples/web/jsf/guessnumber-jsf/` directory.

Configuring a Jakarta Server Faces application involves mapping the Faces Servlet in the web deployment descriptor file, such as a web.xml file, and possibly adding managed bean declarations, navigation rules, and resource bundle declarations to the application configuration resource file, faces-config.xml.

If you are using NetBeans IDE, a web deployment descriptor file is automatically created for you. In such an IDE-created web.xml file, change the default greeting page, which is index.xhtml, to greeting.xhtml. Here is an example web.xml file, showing this change in bold.

Note the use of the context parameter PROJECT_STAGE. This parameter identifies the status of a Jakarta Server Faces application in the software lifecycle.

The stage of an application can affect the behavior of the application. For example, if the project stage is defined as Development, debugging information is automatically generated for the user. If not defined by the user, the default project stage is Production.

You can use either NetBeans IDE or Maven to build, package, deploy, and run the guessnumber-jsf example.

The hello1-rlc example modifies the simple hello1 example from A Web Module That Uses Jakarta Server Faces Technology: The hello1 Example to use two resource library contracts. Each of the two pages in the application uses a different contract.

The managed bean for hello1-rlc, Hello.java, is identical to the one for hello1 (except that it replaces the @Named and @RequestScoped annotations with @Model).

The source code for this application is in the tut-install`/examples/web/jsf/hello1-rlc/` directory.

Pass-through elements allow you to use HTML5 tags and attributes but to treat them as equivalent to Jakarta Server Faces components associated with a server-side UIComponent instance.

To make an element that is not a Jakarta Server Faces element a pass-through element, specify at least one of its attributes using the http://xmlns.jcp.org/jsf namespace. For example, the following code declares the namespace with the short name jsf:

Here, the jsf prefix is placed on the id attribute so that the HTML5 input tag’s attributes are treated as part of the Facelets page. This means that, for example, you can use EL expressions to retrieve managed bean properties.

Table 8-4 shows how pass-through elements are rendered as Facelets tags. The server faces implementation uses the element name and the identifying attribute to determine the corresponding Facelets tag that will be used in the server-side processing. The browser, however, interprets the markup that the page author has written.

Table 8-4 How Facelets Renders HTML5 Elements

Pass-through attributes are the converse of pass-through elements. They allow you to pass attributes that are not Jakarta Server Faces attributes through to the browser without interpretation. If you specify a pass-through attribute in a Jakarta Server Faces UIComponent, the attribute name and value are passed straight through to the browser without being interpreted by Jakarta Server Faces components or renderers. There are several ways to specify pass-through attributes.

The reservation example application provides a set of HTML5 input elements of various types to simulate purchasing tickets for a theatrical event. It consists of two Facelets pages, reservation.xhtml and confirmation.xhtml, and a backing bean, ReservationBean.java. The pages use both pass-through attributes and pass-through elements.

The source code for this application is in the tut-install`/examples/web/jsf/reservation/` directory.