The Jakarta® EE Tutorial

Version: Release 9

Status: DRAFT

Release: May 2021

Copyright © 2017, 2021 Oracle and/or its affiliates. All rights reserved.

This program and the accompanying materials are made available under the terms of the Eclipse Public License v. 2.0, which is available at https://www.eclipse.org/legal/epl-2.0.

SPDX-License-Identifier: EPL-2.0

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.

Preface

This tutorial is a guide to developing enterprise applications for the Jakarta EE 9 Platform, using Eclipse GlassFish Server.

Eclipse GlassFish Server is the leading open-source and open-community platform for building and deploying next-generation applications and services. Eclipse GlassFish Server, developed by the Eclipse GlassFish project open-source community at https://projects.eclipse.org/projects/ee4j.glassfish, is a compatible implementation of the Jakarta EE 9 platform specification. This lightweight, flexible, and open-source application server enables organizations not only to leverage the new capabilities introduced within the Jakarta EE 9 specification, but also to add to their existing capabilities through a faster and more streamlined development and deployment cycle. Eclipse GlassFish Server is hereafter referred to as GlassFish Server.

Audience

This tutorial is intended for programmers interested in developing and deploying Jakarta EE 9 applications. It covers the technologies comprising the Jakarta EE platform and describes how to develop Jakarta EE components and deploy them on the Eclipse GlassFish.

Before You Read This Book

Before proceeding with this tutorial, you should have a good knowledge of the Java programming language. A good way to get to that point is to work through the Java™ Tutorials https://docs.oracle.com/javase/tutorial/index.html.

The GlassFish Server documentation set describes deployment planning and system installation. To obtain the GlassFish Server documentation, go to https://glassfish.org/docs.

The Jakarta EE 9 API specification can be viewed at https://jakarta.ee/specifications/platform/9/.

Additionally, the Jakarta EE Specifications at https://jakarta.ee/specifications might be useful.

For information about creating enterprise applications in the NetBeans Integrated Development Environment (IDE), see https://netbeans.apache.org/kb/.

For information about Apache Derby for use with GlassFish Server, see https://db.apache.org/derby/docs/10.14/adminguide/.

The GlassFish Samples project is a collection of sample applications that demonstrate a broad range of Jakarta EE technologies. The GlassFish Samples are available from the GlassFish Samples project page at https://github.com/eclipse-ee4j/glassfish-samples/.

Conventions

The following table describes the typographic conventions that are used in this book.

Convention Meaning Example

Boldface

Boldface type indicates graphical user interface elements associated with an action or terms defined in text.

From the File menu, choose Open Project.

A cache is a copy that is stored locally.

Monospace

Monospace type indicates the names of files and directories, commands within a paragraph, URLs, code in examples, text that appears on the screen, or text that you enter.

Edit your .login file.

Use ls -a to list all files.

machine_name% you have mail.

Italic

Italic type indicates book titles, emphasis, or placeholder variables for which you supply particular values.

Read Chapter 6 in the User’s Guide.

Do not save the file.

The command to remove a file is rm filename.

Default Paths and File Names

The following table describes the default paths and file names that are used in this book.

Placeholder Description Default Value

as-install

Represents the base installation directory for GlassFish Server.

Installations on the Solaris operating system, Linux operating system, and Mac operating system:

user’s-home-directory/glassfish6/glassfish

Windows, all installations:

SystemDrive:\glassfish6\glassfish

as-install-parent

Represents the parent of the base installation directory for GlassFish Server.

Installations on the Solaris operating system, Linux operating system, and Mac operating system:

user’s-home-directory/glassfish6

Windows, all installations:

SystemDrive:\glassfish6

tut-install

Represents the base installation directory for the Jakarta EE Tutorial after you download and extract it.

user’s-home-directory/jakartaee-tutorial

domain-dir

Represents the directory in which a domain’s configuration is stored.

as-install/domains/domain1

Part I: Introduction

Part I introduces the platform, the tutorial, and the examples.

Chapter 1. Overview

This chapter introduces you to Jakarta EE enterprise application development. Here you will review development basics, learn about the Jakarta EE architecture and APIs, become acquainted with important terms and concepts, and find out how to approach Jakarta EE application programming, assembly, and deployment.

Introduction to Jakarta EE

Developers today increasingly recognize the need for distributed, transactional, and portable applications that leverage the speed, security, and reliability of server-side technology. Enterprise applications provide the business logic for an enterprise. They are centrally managed and often interact with other enterprise software. 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 Jakarta EE, development of Java enterprise applications has never been easier or faster. The aim of the Jakarta EE platform is to provide developers with a powerful set of APIs while shortening development time, reducing application complexity, and improving application performance.

The Jakarta EE platform is developed through the Jakarta EE Specification Process. Expert groups composed of interested parties have created Jakarta Specifications to define the various Jakarta EE technologies. The work of the Jakarta Community under the Jakarta EE Specification Process program helps to ensure Java technology’s standards of stability and cross-platform compatibility.

The Jakarta EE platform uses a simplified programming model. XML deployment descriptors are optional. Instead, a developer can simply enter the information as an annotation directly into a Java source file, and the Jakarta 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, you put the specification information in your code next to the program element affected.

In the Jakarta EE platform, dependency injection can be applied to all resources a component needs, effectively hiding the creation and lookup of resources from application code. Dependency injection can be used in enterprise bean containers, web containers, and application clients. Dependency injection allows the Jakarta EE container to automatically insert references to other required components or resources, using annotations.

This tutorial uses examples to describe the features available in the Jakarta EE 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.

Jakarta EE 9 Platform Highlights

The goal of the Jakarta EE 9 release is to deliver a set of specifications functionally similar to Jakarta EE 8 but in the new Jakarta EE 9 namespace jakarta.*.

In addition, the Jakarta EE 9 release removes a small set of specifications from Jakarta EE 8 that were old, optional, or deprecated in order to reduce the surface area of the APIs to ensure that it is easier for new vendors to enter the ecosystem – as well as reduce the burden on implementation, migration, and maintenance of these old APIs.

The following Jakarta EE Technologies were removed from the Jakarta EE Platform:

  • XML Registries 1.0

  • XML RPC 1.1

  • Deployment 1.7

  • Management 1.1

  • Distributed Interoperability (EJB 3.2 Core Specification, Chapter 10)

Aside from the removed technologies, some technologies in Jakarta EE 9 release are marked as optional. The reason for this is that some of the technologies originally included in Jakarta EE are no longer as relevant as they were when they were introduced to the platform.

Platform Specification Project can decide to officially "remove" the "optional" feature from the Platform in the next (or beyond) releases.

The following technologies are optional:

  • Jakarta Enterprise Beans 3.2 and earlier entity beans and associated Jakarta Enterprise Beans QL

  • Jakarta Enterprise Beans 2.x API group

  • Jakarta Enterprise Web Services 2.0

  • Jakarta SOAP with Attachments 2.0

  • Jakarta Web Services Metadata 3.0

  • Jakarta XML Web Services 3.0

  • Jakarta XML Binding 3.0

Jakarta EE Application Model

The Jakarta EE application model begins with the Java programming language and the Java virtual machine. The proven portability, security, and developer productivity they provide form the basis of the application model. Jakarta 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 Jakarta 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 the following parts:

  • The business and presentation logic to be implemented by the developer

  • The standard system services provided by the Jakarta EE platform

The developer can rely on the platform to provide solutions for the hard systems-level problems of developing a multitier service.

Distributed Multitiered Applications

The Jakarta EE platform uses a distributed multitiered application model for enterprise applications. Application logic is divided into components according to function, and the application components that make up a Jakarta EE application are installed on various machines depending on the tier in the multitiered Jakarta EE environment to which the application component belongs.

Figure 1-1 shows two multitiered Jakarta EE applications divided into the tiers described in the following list. The Jakarta EE application parts shown in Figure 1-1 are presented in Jakarta EE Components.

  • Client-tier components run on the client machine.

  • Web-tier components run on the Jakarta EE server.

  • Business-tier components run on the Jakarta EE server.

  • Enterprise information system (EIS)-tier software runs on the EIS server.

Although a Jakarta EE application can consist of all tiers shown in Figure 1-1, Jakarta EE multitiered applications are generally considered to be three-tiered applications because they are distributed over three locations: client machines, the Jakarta 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.

Diagram of multitiered application structure, including client tier, web tier, business tier, and EIS tier.
Figure 1-1 Multitiered Applications

Security

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

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:

  • Application clients and applets are components that run on the client.

  • Jakarta Servlet, Jakarta Faces, and Jakarta Server Pages technology components are web components that run on the server.

  • Enterprise bean components (enterprise beans) are business components that run on the server.

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.

Jakarta EE Clients

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

Web Clients

A web client consists of two parts:

  • 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

  • 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 Jakarta EE server, where they can leverage the security, speed, services, and reliability of Jakarta EE server-side technologies.

Application Clients

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. An application client typically has a graphical user interface (GUI) created from the Swing API 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 Jakarta EE servers, enabling the Jakarta EE platform to interoperate with legacy systems, clients, and non-Java languages.

Applets

A web page received from the web tier can include an embedded applet. Written in the Java programming language, an applet is a small client application 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.

The JavaBeans Component Architecture

The server and client tiers might also include components based on the JavaBeans component architecture (JavaBeans components) to manage the data flow between the following:

  • An application client or applet and components running on the Jakarta EE server

  • Server components and a database

JavaBeans components are not considered Jakarta EE components by the Jakarta EE specification.

JavaBeans components have properties and have get and set methods for accessing those 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.

Jakarta EE Server Communications

Figure 1-2 shows the various elements that can make up the client tier. The client communicates with the business tier running on the Jakarta EE server either directly or, as in the case of a client running in a browser, by going through web pages or servlets running in the web tier.

Diagram of client-server communication. Application clients access the business tier directly. Browsers, web pages, and applets access the web tier.
Figure 1-2 Server Communication

Web Components

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

Diagram of client-server communication showing detail of JavaBeans components and web pages in the web tier.
Figure 1-3 Web Tier and Jakarta EE Applications

Business Components

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.

Diagram of client-server communication showing detail of entities, session beans, and message-driven beans in the business tier.
Figure 1-4 Business and EIS Tiers

Enterprise Information System Tier

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.

Jakarta 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 Jakarta EE architecture makes applications easy to write because business logic is organized into reusable components. In addition, the Jakarta 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.

Container Services

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.

  • The Jakarta EE security model lets you configure a web component or enterprise bean so that system resources are accessed only by authorized users.

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

  • JNDI lookup services provide a unified interface to multiple naming and directory services in the enterprise so that application components can access these services.

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

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

Container Types

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

Diagram of client-server communication showing servlets and web pages in the web tier and enterprise beans in the business tier.
Figure 1-5 Jakarta EE Server and Containers

The server and containers are as follows:

  • Jakarta EE server: The runtime portion of a Jakarta EE product. A Jakarta EE server provides enterprise and web containers.

  • Jakarta Enterprise Bean container: Manages the execution of enterprise beans for Jakarta EE applications. Jakarta Enterprise Beans and their container run on the Jakarta EE server.

  • Web container: Manages the execution of web pages, servlets, and some enterprise bean components for Jakarta EE applications. Web components and their container run on the Jakarta EE server.

  • Application client container: Manages the execution of application client components. Application clients and their container run on the client.

  • Applet container: Manages the execution of applets. Consists of a web browser and a Java Plug-in running on the client together.

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 Jakarta 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 Jakarta EE XML APIs, all you need to do is pass parameter data to the method calls and process the data returned; 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 Jakarta 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.

XML

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.

  • One company might put XML pricing information through a program to translate the XML into HTML so that it can post the price lists to its intranet.

  • A partner company might put the XML pricing information through a tool to create a marketing presentation.

  • Another company might read the XML pricing information into an application for processing.

SOAP Transport Protocol

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:

  • Defines an XML-based envelope to describe what is in the message and explain how to process the message

  • Includes XML-based encoding rules to express instances of application-defined data types within the message

  • Defines an XML-based convention for representing the request to the remote service and the resulting response

WSDL Standard Format

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.

Jakarta EE Application Assembly and Deployment

A Jakarta EE application is packaged into one or more standard units for deployment to any Jakarta EE platform-compliant system. Each unit contains

  • A functional component or components, such as an enterprise bean, web page, servlet, or applet

  • An optional deployment descriptor that describes its content

Once a Jakarta 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 who can access it and the name of the local database. Once deployed on a local platform, the application is ready to run.

Jakarta EE APIs

Figure 1-6 shows the relationships among the Jakarta EE containers.

Diagram of Jakarta EE containers and their relationships
Figure 1-6 Jakarta EE Containers

Figure 1-7 shows the availability of the Jakarta EE APIs in the web container.

Diagram of Jakarta EE APIs in the web container
Figure 1-7 Jakarta EE APIs in the Web Container

Figure 1-8 shows the availability of the Jakarta EE APIs in the enterprise bean container.