diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml deleted file mode 100644 index c54a6693..00000000 --- a/.github/workflows/build.yml +++ /dev/null @@ -1,36 +0,0 @@ -name: build - -on: - push: - branches: - - master - - release/* - pull_request: - branches: - - master - -jobs: - - build: - runs-on: ubuntu-latest - steps: - - - uses: actions/checkout@v1 - - - name: Set up JDK 1.8 - uses: actions/setup-java@v1 - with: - java-version: 1.8 - - - name: Build Docs - run: mvn clean package --file pom.xml #-Ppublish-site - -# - name: Deploy 🚀 -# uses: JamesIves/github-pages-deploy-action@3.7.1 -# with: -# GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} -# BRANCH: gh-pages # The branch the action should deploy to. -# FOLDER: target/generated-docs # The folder the action should deploy. -# CLEAN: true # Automatically remove deleted files from the deploy br - - diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2f5f55bf..4dac4f77 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,30 +1,117 @@ -# Contributing to Jakarta EE Platform +# Contributing to Jakarta EE Documentation Thanks for your interest in this project. ## Project description -The Jakarta EE Platform project produces the Jakarta EE -platform specification, which is an umbrella specification that -aggregates all other Jakarta EE specifications. +The Eclipse Documentation for Jakarta EE project hosts documentation intended for programmers interested in developing and deploying Jakarta EE applications. It covers the technologies comprising the Jakarta EE platform and describes how to develop applications using Jakarta EE components and deploy them on Jakarta EE runtimes. -* [https://projects.eclipse.org/projects/ee4j.jakartaee-platform](https://projects.eclipse.org/projects/ee4j.jakartaee-platform) +Eclipse project page: https://projects.eclipse.org/projects/ee4j.jakartaee-documentation ## Developer resources -Information regarding source code management, builds, coding standards, and -more. - -* [https://projects.eclipse.org/projects/ee4j.jakartaee-platform/developer](https://projects.eclipse.org/projects/ee4j.jakartaee-platform/developer) - The project maintains the following source code repositories -* [https://github.com/eclipse-ee4j/jakartaee-platform](https://github.com/eclipse-ee4j/jakartaee-platform) -* [https://github.com/eclipse-ee4j/jakartaee-tutorial](https://github.com/eclipse-ee4j/jakartaee-tutorial) -* [https://github.com/eclipse-ee4j/jakartaee-tutorial-examples](https://github.com/eclipse-ee4j/jakartaee-tutorial-examples) -* [https://github.com/eclipse-ee4j/jakartaee-firstcup](https://github.com/eclipse-ee4j/jakartaee-firstcup) -* [https://github.com/eclipse-ee4j/jakartaee-firstcup-examples](https://github.com/eclipse-ee4j/jakartaee-firstcup-examples) -* [https://github.com/eclipse-ee4j/jakartaee-schemas](https://github.com/eclipse-ee4j/jakartaee-schemas) +* [eclipse-ee4j/jakartaee-examples](https://github.com/eclipse-ee4j/jakartaee-examples) - Contains examples used in the tutorial (and additional examples) +* [jakartaee/jakartaee-documentation](https://github.com/jakartaee/jakartaee-documentation) - builds documentation site +* [jakartaee/jakartaee-documentation-ui](https://github.com/jakartaee/jakartaee-documentation-ui) - HTML and CSS assets used for the documentation site look and feel. +* +### Coding guidelines + +#### Branches + +##### Normal Branches + +* Restrict work on a single feature or issue to a single branch +* Branch name: `feature/[issue #]_description_if_necessary` + * Example: `feature/123_this_is_an_example` + * Example: `feature/123` + * Example: `feature/remove_stale_files (no issue number)` + +##### Release Branches + +* For the main tutorial repo and any other repos with Antora content (that does not include a playbook), we’ll keep a release branch so that we maintain docs for the particular version of Jakarta EE. +* The main branch will represent the current release. All previous releases should have their own branch. +Branch name: `release/[version]` + * Example: `release/9.1` + * Example: `release/10` + +##### Commits + +* Include the issue # in the message (if applicable) + * Example: “#123 Adds a the ability to synchronize with the example repo” + * Example: “Updates #123 with changes for pom file” + * Example: “Removed stale files” + +### Creating diagrams + +Diagrams are located in `src/main/antora/modules/common/images` or in the `images` folder of the module; +for example `src/main/antora/modules/cdi/images`. +Use [draw.io](https://draw.io) to create/adjust diagrams. +This tool is primarily chosen for being free to use and the most flexible. +For portability and maintainability, make sure that the diagram is saved/exported into following three formats: + +- `*.drawio` (use the Save function) +- `*.vsdx` (use the Export function) +- Editable `*.svg` (use the Save As function) + +The `*.drawio` format ensures being able to reopen exactly the intended diagram in the original tool. +The `*.vsdx` format ensures being able to import the diagram in another tool as this is the most supported format by +various diagramming tools, just in case that draw.io stops to exist in some unpredictable future. +The `*.svg` format is ultimately used to embed the diagram in the tutorial document. + +Also, make sure you use a hyphen ("-") in the name as a delimiter; for example `persistance-mapping`. + +#### Diagram requirements + +- Font must be 'Open Sans' conform + the [Jakarta EE Brand Usage Handbook](https://jakarta.ee/legal/trademark_guidelines/jakarta-ee-branding-guidelines.pdf). + You can use Google Fonts for this. + In case you're using draw.io: + - Wherever you see a 'Font' dropdown, unfold it. + ![Select font](readme-images/drawio-font-1-select-font.png) + - If there's no 'Open Sans' option, pick 'Custom'. + ![Select custom](readme-images/drawio-font-2-select-custom.png) + - Choose the 'Google Fonts' option and set the font name to 'Open Sans' and apply. + ![Set Google Open Sans](readme-images/drawio-font-3-set-google-open-sans.png) + - Type text and verify that the font is Open Sans + ![Using Google Open Sans](readme-images/drawio-font-4-using-google-open-sans.png) +- Font size for all text should be 12pt + +- Color must be one of those defined + in [Jakarta EE Brand Usage Handbook](https://jakarta.ee/legal/trademark_guidelines/jakarta-ee-branding-guidelines.pdf), + along with black and white (you can use opacity to affect the depth of the color). + - Primary colors: + - Blue: `#1B208B` + - Orange: `#F98200` + - Black: `#3D3D3D` + - White: `#FFFFFF` + - Secondary colors: + - Yellow: `#FDB940` + - Grey: `#58595B` + - Dark blue: `#131660` + +- Arrows must be Orange (`#F98200`) + +- Background must be white (`#FFFFFF`) + +### Terminology + +| Old | New | +| --- | --- | +| Jakarta Foo Technology | Jakarta Foo API | +| JavaBeans components | beans | +| application server | Jakarta runtime | +| (web) container | servlet container | +| context root | context path | +| web context | application scope | + +* Do not use in-house abbreviations! E.g. do not use “DD” but write out fully “deployment descriptor”. +* List items should always start with capital and end with full stop. + +## Style guide + +If you're going to write documentation, please make sure you follow the [style guide](STYLE_GUIDE.adoc). ## Eclipse Contributor Agreement @@ -44,6 +131,5 @@ For more information, please see the Eclipse Committer Handbook: ## Contact -Contact the project developers via the project's "dev" list. - -* [https://accounts.eclipse.org/mailing-list/jakartaee-platform-dev](https://accounts.eclipse.org/mailing-list/jakartaee-platform-dev) +Contact the project developers via the project's "dev" list: +https://accounts.eclipse.org/mailing-list/jakartaee-documentation-dev or via the Github issue tracker. diff --git a/README.md b/README.md index 535f22ab..d89845de 100644 --- a/README.md +++ b/README.md @@ -1,81 +1,50 @@ # Jakarta EE Tutorial -![ build](https://github.com/eclipse-ee4j/jakartaee-tutorial/workflows/build/badge.svg) - This repository contains the source files that are used to build the -_Jakarta Enterprise Edition (Jakarta EE) Tutorial_. The source files -are authored in [AsciiDoc](http://asciidoc.org/). AsciiDoc is similar -to markdown but is particularly suited for user documentation. - -Note that the Jakarta EE Tutorial code examples are located in a -separate repository -[eclipse-ee4j/jakartaee-tutorial-examples](https://github.com/eclipse-ee4j/jakartaee-tutorial-examples). - -## Contributing -The easiest way to contribute is by opening an issue in this project -that contains feedback and review comments. - -The Jakarta EE Tutorial project is also open for contributions and your -help is greatly appreciated. If you have an idea for the tutorial and -want to add a section or update an existing section, then review the -following links: - -* [Contribute](CONTRIBUTING.md) -* [Pull Request Acceptance Workflow](src/main/jbake/assets/pr_doc_workflow.md) -* [License](LICENSE.md) - -## Building the Jakarta EE Tutorial +_Jakarta Enterprise Edition (Jakarta EE) Tutorial_. +The source files are authored in [AsciiDoc](https://asciidoc.org/). +AsciiDoc is similar to markdown but is particularly suited for user documentation. +The source files are processed and integrated into the Jakarta EE Documentation site using +[Antora](https://antora.org/), +which is a tool for building documentation sites. -The following directions explain how to do local builds of the -tutorial. Note that any changes that are pushed to the master branch -automatically trigger a build of the site files and tutorial sources. -The results are automatically pushed to the gh-pages branch. You can -view the published site -[here](https://eclipse-ee4j.github.io/jakartaee-tutorial). +You can always find the most recent build of the Jakarta EE Documentation site here: +https://jakartaee.github.io/jakartaee-documentation/. -### Pre-Requisites +## A Note about Images -- Maven -- JDK8+ +We keep the source files (VSD) and the published format (SVG) +for images in the `src/main/antora/modules/common/images` folder. +However, currently all the source file names don't match their corresponding SVG file. +If you modify a source image, +please help us out and rename it to match the output image. -Note that manually deploying the site requires password-less -authentication. This is done by exporting your SSH public key into your -GitHub account. +Guidelines for generating new images can be found in the [Contributing guide](CONTRIBUTING.md). -### Build the Site Locally +## Building -The site is generated under `target/staging`. Open -`file:///PATH_TO_PROJECT_DIR/target/staging` in a browser to view the -output. +The contents of this repo are built by +the [jakartaee-tutorial-playbook repository](https://github.com/jakartaee/jakartaee-documentation). +See that repo for details. -``` -mvn generate-resources -``` +## Related Repositories +* [eclipse-ee4j/jakartaee-examples](https://github.com/eclipse-ee4j/jakartaee-examples) - Contains examples used in the tutorial (and additional examples) +* [jakartaee/jakartaee-documentation](https://github.com/jakartaee/jakartaee-documentation) - builds documentation site +* [jakartaee/jakartaee-documentation-ui](https://github.com/jakartaee/jakartaee-documentation-ui) - HTML and CSS assets used for the documentation site look and feel. -### Deploy the Site to Github Pages - -If you want to manually push a build to the gh-pages branch, use: - -``` -mvn deploy -Ppublish-site -``` -Never commit changes to the *gh-pages* branch directly. - -### Produce a Zip File for Download - -To produce a zip file containing the generated HTML files, use: - -``` -mvn package -``` +## Contributing -When making a release on GitHub, this zip file should be added to the release. +This project is open for contributions, and your +help is greatly appreciated. +The easiest way to contribute is by opening an [issue](https://github.com/jakartaee/jakartaee-tutorial/issues) in this project +that contains feedback and review comments. -## Links +You can also create PRs directly while viewing the published documentation by using the Edit button in the UI. -- [Asciidoctor Maven Plugin](https://asciidoctor.org/docs/asciidoctor-maven-plugin/) +If you want to keep up with our project planning across all of the repos, see the [project board](https://github.com/orgs/jakartaee/projects/7). -- [AsciiDoc User Guide](http://asciidoc.org/userguide.html) +If you'd like to propose changes or additions to the content and/or images, +please read the [Style guide](STYLE_GUIDE.adoc) and +[Contributing guide](CONTRIBUTING.md) for more information. -- [Asciidoctor quick reference](http://asciidoctor.org/docs/asciidoc-syntax-quick-reference) diff --git a/STYLE_GUIDE.adoc b/STYLE_GUIDE.adoc new file mode 100644 index 00000000..767cb108 --- /dev/null +++ b/STYLE_GUIDE.adoc @@ -0,0 +1,112 @@ += Jakarta EE Tutorial Style Guide + +This document describes the requirements for new writing contributions to the Jakarta EE Tutorial; +it includes a mixture of writing and https://docs.asciidoctor.org/asciidoc/latest/[Asciidoc] / https://docs.antora.org/antora/latest/[Antora] guidelines. + +== Eclipse Writing Style Guide + +New contributions must follow the https://www.eclipse.org/org/documents/writing-style-guide/[Eclipse Writing Style Guide] in addition to the guidelines mentioned herein. +If there is a conflict, the guidelines in this document take precedence. + +== Tone and Voice + +Use a first-person voice but a professional tone and avoid slang. +New tutorial material should be easy to read and approachable. + +For more guidelines, see https://www.eclipse.org/org/documents/writing-style-guide/#3[Tone and Voice]. + +== Common Words, Names, and Abbreviations + +When using the following words, names, and abbreviations, consistently use the spelling and capitalization below: + +* "Basic authentication" +* "Form authentication" +* WAR +* JAR +* HTML +* Profile names should be capitalized +(Core Profile, Web Profile, etc.) + +== Using Hyphens + +Be aware of when to use a hyphen, especially for multiple-word adjectives before or after a noun. For example, "water-based paint" and "paint that is water based". See https://www.grammarly.com/blog/hyphen/[this article] and https://www.eclipse.org/org/documents/writing-style-guide/#21[Compound Words and Hyphenation] for details. + +== Lists + +For lists, use: + +* A colon before the list +* Auto-numbering Asciidoc syntax +* Avoid repeating the same word at the beginning of each bullet point +(for example, "Use" or "Execute") +* Use a period at the end of complete sentences, but don't use a period otherwise. + +For example: + +[source, asciidoc] +---- +You'll learn how to: + +. Define security constraints +. Provided authentication mechanisms +. How to set a provided identity store that uses a database +---- + +See https://www.eclipse.org/org/documents/writing-style-guide/#32[Lists] for more details. + +== Internal Links + +You can easily link to other headings in the current document. +For example, given the following heading: + +[source,asciidoc] +---- +== This is My Header +---- + +You can link to it like so: + +[source,asciidoc] +---- +Ths is a link to my header: <<_this_is_my_header>> +---- + +=== Links to Other Pages + +Links to other pages in the tutorial should be in the following format: + +[source, asciidoc] +---- +* xref:module-name/file-nameo.adoc#_anchor_name[Link Text] +---- + +For example: + +[source, asciidoc] +---- +* xref:security-intro/security-intro.adoc#_introduction_to_security_in_the_jakarta_ee_platform[Introduction to Security in the Jakarta EE Platform] +---- + +See the https://docs.antora.org/antora/latest/page/xref/[Antora xref docs^] for more information. + +TIP: If you want to give a heading a permanent identifier, you can https://docs.asciidoctor.org/asciidoc/latest/attributes/id/#add-additional-anchors-to-a-section[add an anchor to the section^] and use that instead. + +== Definitions + +Use bold for a word when defining it. +For example, "*Java* is a high-level, class-based, object-oriented programming language that is designed to have as few implementation dependencies as possible." (Wikipedia) + +== Line Breaks + +Use a line break after a substantial unit of thought, +such as a sentence or after an important comma. +For details, see https://sembr.org/[Semantic Line Breaks]. + +== Use of etc., e.g. and i.e. + +In short, don't use them etc., e.g., and i.e. +See https://www.eclipse.org/org/documents/writing-style-guide/#31[Latinisms]. + +== Conventions + +Please follow the https://jakartaee.github.io/jakartaee-documentation/jakartaee-tutorial/current/index.html#_conventions[conventions described in the tutorial]. diff --git a/antora-conversion/AddMessage.java b/antora-conversion/AddMessage.java new file mode 100644 index 00000000..23003b8b --- /dev/null +++ b/antora-conversion/AddMessage.java @@ -0,0 +1,50 @@ +import java.io.File; +import java.io.IOException; +import java.nio.charset.Charset; +import java.nio.charset.StandardCharsets; +import java.nio.file.Files; +import java.nio.file.Path; +import java.nio.file.Paths; + +/** + * Simple app to add a message partial to the top of each chapter + * + * The messages should be created under ROOT/partials + * + */ +public class AddMessage { + + public static void main(String[] args) throws IOException { + + int argc = args.length; + if (argc < 2) { + System.out.println("usage: AddMessage "); + System.out.println("\tall files under will have the named partial added"); + } else { + String partialName = args[0]; + File fileRoot = new File(args[1]); + new AddMessage().run(partialName, fileRoot); + } + } + + private void run(String partialName, File root) throws IOException { + Path dir = Paths.get(root.getAbsolutePath()); + Files.walk(dir).filter(path -> path.toString().matches(".*[^0-9]{2}.adoc")) + .filter(path -> !path.endsWith("nav.adoc")).forEach(path -> runFile(path, partialName)); + } + + static private Charset charset = StandardCharsets.UTF_8; + + private void runFile(Path path, String partialName) { + System.out.println("updating " + path.toString()); + try { + String content = new String(Files.readAllBytes(path), charset); + String partial = "include::ROOT:partial\\$" + partialName + ".adoc[]"; + String regex = "^(=\s*.*)"; + content = content.replaceAll(regex, "$1\n\n" + partial); + Files.write(path, content.getBytes(charset)); + } catch (IOException e) { + e.printStackTrace(); + } + } +} diff --git a/antora-conversion/AntoraConverter.java b/antora-conversion/AntoraConverter.java new file mode 100755 index 00000000..429fac7b --- /dev/null +++ b/antora-conversion/AntoraConverter.java @@ -0,0 +1,294 @@ +///opt/homebrew/bin/jbang jbang "$0" "$@" ; exit $? +//DEPS com.github.lalyos:jfiglet:0.0.8 + +import java.io.File; +import java.io.IOException; +import java.nio.file.Files; +import java.nio.file.Paths; +import java.util.ArrayList; +import java.util.HashMap; +import java.util.Map; +import java.util.function.BiFunction; +import java.util.function.Consumer; + +class AntoraConverter { + + record PageLocation(String path, String page, String linkText) { + public String getParentPage() { + return path + ".adoc"; + } + + public String toString() { + return path + "/" + getParentPage(); + } + } + + static Map anchorMap = new HashMap<>(); + + public static String replaceBetween(String str, String start, String end, String prefix, String fromString, String toString, + BiFunction contentUpdater) { + final var result = new StringBuilder(); + int index = 0; + int startIndex, endIndex; + + while ((startIndex = str.indexOf(start, index)) != -1 && (endIndex = str.indexOf(end, startIndex + start.length())) != -1) { + result.append(str, index, startIndex + start.length()); + var substring = str.substring(startIndex + start.length(), endIndex); + var updatedSubstring = substring.replace(fromString, toString); + + // don't add the prefix if nothing has changed + if (!substring.equals(updatedSubstring)) { + // special case for anchors + if (updatedSubstring.startsWith("#")) { + updatedSubstring = updatedSubstring.replaceFirst("#", "#" + prefix); + } else { + updatedSubstring = prefix + updatedSubstring; + } + } + if (contentUpdater != null) { + updatedSubstring = contentUpdater.apply(substring, updatedSubstring); + } + result.append(updatedSubstring); + index = endIndex; + } + result.append(str, index, str.length()); + return result.toString(); + } + + public static String replaceReferences(File file, String fileContent, String start, String end) { + StringBuilder result = new StringBuilder(); + int index = 0; + int startIndex, endIndex; + + while ((startIndex = fileContent.indexOf(start, index)) != -1 && (endIndex = fileContent.indexOf(end, startIndex + start.length())) != -1) { + result.append(fileContent, index, startIndex); + final var rawReference = fileContent.substring(startIndex, endIndex + end.length()); + var referenceBody = rawReference.substring(start.length(), rawReference.length() - end.length()); + var updatedReferenceBody = createAnchor(referenceBody); + String updatedReference; + + var pageLocation = anchorMap.get("#" + updatedReferenceBody) ; + pageLocation = pageLocation != null ? pageLocation : anchorMap.get("#" + referenceBody); + if (pageLocation == null) { + System.out.printf(" => WARNING: No page location found for anchor \"%s\" or \"%s\"; the file with the anchor may not have been within the startPath%n", + updatedReferenceBody, referenceBody); + updatedReference = rawReference; + } else { + if (isInlineReference(file, referenceBody, pageLocation)) { + updatedReference = start + updatedReferenceBody + end; + } else { + + updatedReference = String.format("xref:%s/%s#%s[%s]", pageLocation.path, + pageLocation.getParentPage(), updatedReferenceBody, pageLocation.linkText()); + } + } + System.out.printf(" => Replacing reference \"%s\" with \"%s\"%n", rawReference, updatedReference); + result.append(updatedReference); + index = endIndex + end.length(); + } + result.append(fileContent, index, fileContent.length()); + return result.toString(); + } + + public static void processBetween(String str, Integer iterations, String start, String end, Consumer updatedContentConsumer) { + int index = 0; + int count = 0; + int startIndex, endIndex; + + while ((startIndex = str.indexOf(start, index)) != -1 && (endIndex = str.indexOf(end, startIndex + start.length())) != -1) { + String substring = str.substring(startIndex + start.length(), endIndex); + updatedContentConsumer.accept(substring); + index = endIndex; + if (iterations == null || count < iterations) { + count++; + } else { + break; + } + } + } + + public static void main(String... args) throws Exception { + System.out.println("\uD83E\uDD16 Antora Converter: Convert raw Asciidoc files to Antora-compatible format"); + System.out.println("Walks through all folders and subfolders from the specified startPath and converts all .adoc files"); + + final var files = new ArrayList(); + if (args.length == 0) { + System.out.println("Usage: AntoraConverter.java [startPath] dryRun?"); + System.out.println(" Where [startPath] is the root folder to search (usually a specific Antora module or component folder)"); + System.out.println(" If 'dryRun' is specified, no files will actually be modified, but you will see information about the changes that would take place"); + System.exit(1); + } + String startPath = args[0]; + System.out.println("Start path: " + startPath); + final var dryRun = args.length > 1 && args[1].equalsIgnoreCase("dryrun"); + if (dryRun) { + System.out.println("=> dryRun is enabled; no files will be modified"); + } + Files.walk(Paths.get(startPath)).filter(Files::isRegularFile) + .filter(path -> path.toString().endsWith(".adoc")) + .forEach(path -> files.add(path.toFile())); + + System.out.println("\uD83E\uDD16 Pre-scanning files for anchors, links, etc."); + + preProcess(files); + process(files, dryRun); + } + + private static void preProcess(ArrayList files) throws IOException { + for (File file : files) { + System.out.println("\uD83D\uDD0E Pre-scanning file " + file.getAbsolutePath()); + String content = new String(Files.readAllBytes(file.toPath())); + System.out.println("=> Processing anchor names"); + + processSectionHeadings(file, content); + processAnchors(file, content); + } + } + + private static void processSectionHeadings(File file, String content) { + // Start with the first heading (level 1 and 2) + processBetween(content, 1, "= ", System.lineSeparator(), processSectionAnchor(file)); + processBetween(content, 1, "== ", System.lineSeparator(), processSectionAnchor(file)); + // Then process all lower section headings + for (int i = 3; i < 7; i++) { + final var prefix = System.lineSeparator() + "=".repeat(i) + " "; + processBetween(content, null, prefix, System.lineSeparator(), processSectionAnchor(file)); + } + } + + private static void processAnchors(File file, String content) { + processBetween(content, null, "[[", "]]", (anchor) -> { + final var pageLocation = new PageLocation(file.getParentFile().getName(), file.getName(), null); + anchorMap.put("#" + anchor, pageLocation); + System.out.printf(" => Stored anchor \"%s\" for %s%n", anchor, pageLocation); + }); + } + + private static Consumer processSectionAnchor(File file) { + return (heading) -> { + final String anchor = createAnchor(heading); + final var pageLocation = new PageLocation(file.getParentFile().getName(), file.getName(), heading); + anchorMap.put("#" + anchor, pageLocation); + System.out.printf(" => Stored anchor \"%s\" for section \"%s\" for %s%n", anchor, heading, pageLocation); + }; + } + + private static String createAnchor(String str) { + final var strWithPrefix = str.charAt(0) == '_' ? str : "_" + str; + return strWithPrefix.toLowerCase().replaceAll("[\\s-]", "_").replace(":", "").replaceAll("[?,&()]", ""); + } + + private static void process(ArrayList files, boolean dryRun) throws IOException { + System.out.println("\uD83E\uDD16 Updating files"); + for (File file : files) { + if (file.getName().equals("nav.adoc")) { + continue; + } + System.out.println("\uD83D\uDD0E Evaluating file " + file.getAbsolutePath()); + var content = new String(Files.readAllBytes(file.toPath())); + int changeCount = 0; + + if (content.contains("xrefstyle=full")) { + System.out.println("=> Removing xrefstyle=full (it is now a global attribute)"); + content = content.replace("xrefstyle=full", ""); + if (!dryRun) { + Files.write(file.toPath(), content.getBytes()); + } + changeCount++; + } + if (content.contains(("xref:"))) { + System.out.println("=> Updating xrefs to reference other files if necessary"); + content = replaceReferences(file, content, "xref:", "[]"); + if (!dryRun) { + Files.write(file.toPath(), content.getBytes()); + } + changeCount++; + } + if (content.contains(("<<"))) { + System.out.println("=> Updating in-page references"); + content = replaceReferences(file, content, "<<", ">>"); + if (!dryRun) { + Files.write(file.toPath(), content.getBytes()); + } + changeCount++; + } + if (content.contains(("[["))) { + System.out.println("=> Updating anchor names"); + content = replaceBetween(content, "[[", "]]", "_", "-", "_", null); + if (!dryRun) { + Files.write(file.toPath(), content.getBytes()); + } + changeCount++; + } + if (content.contains(("link:http"))) { + System.out.println("=> Updating external links"); + content = content.replace("link:http", "https"); + if (!dryRun) { + Files.write(file.toPath(), content.getBytes()); + } + changeCount++; + } + if (content.contains(("link:#"))) { + System.out.println("=> Changing links with anchors to xrefs"); + content = replaceBetween(content, "link:", "[", "_", "-", "_", (originalLink, newLink) -> { + var pageLocation = anchorMap.get(originalLink); + if (pageLocation == null) { + pageLocation = anchorMap.get(newLink); + } + if (pageLocation == null) { + System.out.printf(" => WARNING: No page location found for anchor %s or %s; the file with the anchor may not have been within the startPath%n", + originalLink, newLink); + return newLink; + } + if (isInlineReference(file, newLink, pageLocation)) { + return newLink; + } + final var updatedLink = pageLocation + newLink; + System.out.printf(" => Updating anchor reference from %s to %s%n", originalLink, updatedLink); + return updatedLink; + }); + if (!dryRun) { + Files.write(file.toPath(), content.getBytes()); + } + changeCount++; + } + if (content.contains("link:")) { + System.out.println("=> Converting links without anchors to xrefs"); + content = content.replace("link:", "xref:"); + if (!dryRun) { + Files.write(file.toPath(), content.getBytes()); + } + changeCount++; + } + if (content.contains("image::") && !content.contains("image::common:")) { + System.out.println("=> Converting inline image references to block image references and adding module prefix"); + content = content.replace("image::", "image::common:"); + if (!dryRun) { + Files.write(file.toPath(), content.getBytes()); + } + changeCount++; + } + if (content.contains((".png["))) { + System.out.println("=> Removing newlines from image captions"); + content = replaceBetween(content, ".png[", "]", "", System.getProperty("line.separator"), " ", null); + if (!dryRun) { + Files.write(file.toPath(), content.getBytes()); + } + changeCount++; + } + if (changeCount == 0) { + System.out.println("=> (no changes necessary)"); + } else { + System.out.println("=> " + changeCount + " changes made"); + } + } + } + + /** + * If this page name contains the parent's page name, it's either the parent page itself or an included page, + * so it's an internal reference. + **/ + private static boolean isInlineReference(File file, String newLink, PageLocation pageLocation) { + return file.getName().contains(pageLocation.path); + } +} diff --git a/antora-conversion/CONVERTING_TO_ANTORA.adoc b/antora-conversion/CONVERTING_TO_ANTORA.adoc new file mode 100644 index 00000000..c27203b9 --- /dev/null +++ b/antora-conversion/CONVERTING_TO_ANTORA.adoc @@ -0,0 +1,105 @@ += Antora Migration Notes + +As part of the documentation upgrade process, we're migrating the existing content to Antora. This will allow us to go back to previous versions of the docs from within the docs site. + +== Setup + +The conversion script is xref:AntoraConverter.java[]. You can run it with https://jbang.dev[JBang] or just using plain vanilla Java or your favorite IDE. The instructions below use jbang. + +== Migration Process + +> TIP: Commit your changes after each step; that way you can easily rollback any mistakes. + +Here’s the current process for migrating an individual module (i.e. security, bean validation, etc). + +=== Migrating the Jakarta EE 9.1 branch + +. Check out the release/9.1 branch and create a new branch from it for your work with the name "feature/_description". For example, "feature/JETUT-123_convert_bean_validation". + +. Select the module to migrate. We consider each Part of the current https://eclipse-ee4j.github.io/jakartaee-tutorial/[Jakata EE Tutorial] to be a module (for example, Introduction, Web Tier, Bean Validation, etc). + +. Create a new folder in the `src/main/antora/modules` folder with the name of the module you're migrating. For example, for the Security module, you would create a `security` folder. + * Inside this folder, create a `pages` folder. + +. Move all the folders for the module you're migrating into the new `pages` folder. For example, for the Security module, you would move all of the `src/main/asciidoc/security-*` folders into the `src/main/antora/modules/security/pages`. (Copy the entire folders, not just the `.adoc` files). + +> NOTE: It's essential that you _move_ rather than copy the folders so that we keep the history intact. + +. Run the migration script from the root project folder. For example, for the Security module, you would run: + +[source,shell] +---- +jbang antora-conversion/AntoraConverter.java src/main/antora/modules/security +---- + +> TIP: You can use the `dryRun` parameter to see what changes will be made without actually making them. + +> NOTE: References to chapters that haven't yet been converted will not work until they've been converted. + +. Create a new file called `nav.adoc` in the root of the module folder. For example, for the Security module, you would create `security/nav.adoc`. + +. Copy all the `include` statements from the corresponding "part" file in the `src/main/asciidoc/` folder. For example, for the Security module, you would copy the `include` statements of `src/main/asciidoc/partsecurity.adoc` into the `security/nav.adoc` file. Here are the `include` statements for the Security module: + +[source,asciidoc] +---- +\include::security-intro/security-intro.adoc[] + +\include::security-webtier/security-webtier.adoc[] + +\include::security-jakartaee/security-jakartaee.adoc[] + +\include::security-api/security-api.adoc[] + +\include::security-advanced/security-advanced.adoc[] +---- + +After copying these into `nav.adoc`, replace "include::" with "* xref:" and add a header with the module name: + +[source,asciidoc] +---- +.Security +* xref:security-intro/security-intro.adoc[] + +* xref:security-webtier/security-webtier.adoc[] + +* xref:security-jakartaee/security-jakartaee.adoc[] + +* xref:security-api/security-api.adoc[] + +* xref:security-advanced/security-advanced.adoc[] +---- + +. Add this module to the `src/main/antora/antora.yml`. For example, for the Security module, you would add this line to the end of `src/main/antora/antora.yml` file: + +[source,yaml] +---- + - modules/security/nav.adoc +---- + +. Test out your changes by building the playbook from the `jakartaee-tutorial-playbook` repo. +In your `local-antora-playbook.yaml` file, change `release/XX` to the name of your feature branch, +so you can test locally. +Then, run Maven using the `author-mode` profile like so: + +---- +mvn package -P author-mode +---- + +Make sure you try several different pages and test out links. + +. If there are any required changes the script didn't make, +either make them manually or update the script to handle them. +If you're updating the script, +usually your best bet is to revert the changes from the previous run and then run it again after you update the script. +Don't forget you can use the `dryRun` parameter while testing. + +> TIP: If you're using the Antora IDE plugin, it helps to review its errors and updating before committing. With IntellJ, +these are run automatically before pushing. + +. Commit your changes and push. + +. Raise a PR to merge into the `release/9.1` branch. + +. Once your PR has been approved and merged, raise a PR to merge `release/9.1` into `main`. + +. You're done! Rinse and repeat for remaining modules. diff --git a/antora-conversion/LinkChecker.java b/antora-conversion/LinkChecker.java new file mode 100644 index 00000000..0a11c956 --- /dev/null +++ b/antora-conversion/LinkChecker.java @@ -0,0 +1,339 @@ +import java.io.File; +import java.io.IOException; +import java.nio.file.Files; +import java.util.ArrayList; +import java.util.Arrays; +import java.util.HashMap; +import java.util.List; +import java.util.Map; +import java.util.regex.Matcher; +import java.util.regex.Pattern; +import java.util.stream.Collectors; + +/** + * + * CLI application to check + fix links in antora source + * + * Runs on the root folder e.g. src/main/antora and makes a 1st pass to index + * all anchors. The second pass checks all links, making recommendations on + * fixes when possible. Setting the "--overwrite" flag will write these + * recommendations in place to the given file + * + */ +public class LinkChecker { + + class Location { + public String mmodule; + public String msubmod; + public String mfile; + + // data structure to refer to a file location + public Location(String module, String submod, String file) { + mmodule = module; + msubmod = submod; + mfile = file; + } + + @Override + public String toString() { + return mmodule + ":" + msubmod + "/" + msubmod + ".adoc"; + } + + public boolean sameSubmod(Location other) { + return mmodule.equals(other.mmodule) && msubmod.equals(other.msubmod); + } + + boolean sameFile(Location other) { + return mmodule.equals(other.mmodule) && msubmod.equals(other.msubmod) && mfile.equals(other.mfile); + } + + } + + // data structure to hold information about an anchor + class Reference extends Location { + public String manchor; + public String mtext; + public boolean mheader; + + public Reference(String module, String submod, String file, String anchor, String text, boolean header) { + super(module, submod, file); + manchor = anchor; + mtext = text; + mheader = header; + } + + public String makeLink(boolean local) { + String newlink = "xref:"; + if (!local) { + newlink += mmodule + ":"; + } + newlink += msubmod + "/" + msubmod + ".adoc#" + manchor + "[" + mtext + "]"; + return newlink; + } + } + + public static void main(String[] args) throws IOException { + + int argc = args.length; + if (argc < 2) { + System.out.println("usage: LinkChecker [--overwrite] basepath module"); + System.out.println("\tbasepath is e.g. src/main/antora"); + System.out.println("\tmodule is the module to be checked e.g. 'cdi'"); + System.out.println("\toverwrite flag will fix links in place"); + } else { + String checkMod = args[argc - 1]; + String startPath = args[argc - 2]; + File modulesDir = checkExists(new File(startPath + "/modules")); + boolean overwrite = args[0].equals("--overwrite"); + + LinkChecker checker = new LinkChecker(); + checker.run(modulesDir, checkMod, overwrite); + } + } + + private Map> refmap = new HashMap>(); + private boolean showIndex = false; + + private void run(File modulesDir, String checkMod, boolean overwrite) throws IOException { + // index anchors + File[] modules = modulesDir.listFiles(); + for (File module : modules) { + String moduleName = module.getName(); + File pagesDir = new File(module, "pages"); + if (pagesDir.exists()) { + System.out.println("= Index module " + moduleName); + for (File submod : pagesDir.listFiles()) { + if (submod.isDirectory()) { + for (File file : submod.listFiles()) { + indexFile(moduleName, submod.getName(), file); + } + } + } + } + } + + File checkDir = new File(modulesDir, checkMod); + File checkFilesDir = checkExists(new File(checkDir, "pages")); + for (File submod : checkFilesDir.listFiles()) { + File[] files = submod.listFiles(); + Arrays.sort(files); + for (File file : files) { + if (file.getName().endsWith(".adoc")) { + checkFile(checkMod, submod.getName(), file, overwrite); + } + } + } + } + + private void indexFile(String module, String submod, File file) throws IOException { + if (showIndex) { + System.out.println("== Indexing file: " + file.getCanonicalPath()); + } + String content = new String(Files.readAllBytes(file.toPath())); + // index headers + Pattern p = Pattern.compile("(?m)^=+\s*(.+)"); + Matcher m = p.matcher(content); + while (m.find()) { + addAnchor(module, submod, file.getName(), anchorKey(m.group(1)), m.group(1), true); + } + // index inline [anchors] + p = Pattern.compile("\\[\\[([^,\\]]+),?\\s*([^\\]]*)\\]\\]"); + m = p.matcher(content); + while (m.find()) { + String title = m.group(2).length() > 0 ? m.group(2) : anchor2title(m.group(1)); + addAnchor(module, submod, file.getName(), m.group(1), title, false); + } + } + + private void addAnchor(String module, String submod, String filename, String key, String text, boolean header) { + Reference reference = new Reference(module, submod, filename, key, text, header); + List current = refmap.get(key); + if (current == null) { + current = new ArrayList(); + refmap.put(key, current); + } + current.add(reference); + if (showIndex) { + System.out.println(key); + } + } + + private static String anchorKey(String str) { + final var strWithPrefix = str.charAt(0) == '_' ? str : "_" + str; + return strWithPrefix.toLowerCase().replaceAll("[\\s-\\.]", "_").replaceAll("[@?,&()/':]", ""); + } + + public static String anchor2title(String str) { + str = str.replace("_", " "); + String ret = ""; + String words[] = str.split("\\s"); + for (String word : words) { + if (word.length() > 0) { + String first = word.substring(0, 1); + String rest = word.substring(1); + ret += first.toUpperCase() + rest + " "; + } + } + return ret.trim(); + } + + private void checkFile(String module, String submod, File file, boolean overwrite) throws IOException { + System.out.println("== Checking file: " + file.getName()); + var content = new String(Files.readAllBytes(file.toPath())); + // xref style + Location checkfileloc = new Location(module, submod, file.getName()); + Pattern xrefBasicPattern = Pattern.compile("xref:([^\\[]*)\\[[^\\]]*\\]"); + Pattern xrefFullPattern = Pattern.compile("xref:((([^:]+):)?([^/]+)/(([^\\.]+)\\.adoc)#(.*))\\[([^\\]]*)\\]"); + Matcher m = xrefBasicPattern.matcher(content); + Map replacements = new HashMap(); + while (m.find()) { + Matcher fm = xrefFullPattern.matcher(m.group()); + if (!fm.matches() || !fm.group(4).equals(fm.group(6))) { + // is it a simple xref:_anchor[] + List reflist = resolve(m.group(1)); + if (reflist != null) { + if (reflist.size() == 1) { + warn("xref link incomplete: " + m.group()); + Reference ref = reflist.get(0); + String newlink = ref.makeLink(ref.mmodule.equals(checkfileloc.mmodule)); + replaceLink(replacements, m.group(), newlink); + } else { + error("xref link ambiguous: " + m.group()); + for (Reference ref : reflist) { + String newlink = ref.makeLink(ref.mmodule.equals(checkfileloc.mmodule)); + System.out.println("\t? " + newlink); + } + } + } else { + error("xref could not be resolved: " + m.group()); + } + } else { + String anchor = fm.group(7); + List reflist = resolve(anchor); + if (reflist != null) { + String linkmod = fm.group(3) != null ? fm.group(3) : module; + Location linkloc = new Location(linkmod, fm.group(4), fm.group(5)); // , anchor, linkmod) + if (reflist.size() == 1) { + // check everything lines up! + Reference ref = reflist.get(0); + if (linkloc.sameSubmod(ref)) { + if (!ref.mtext.equals(fm.group(8)) && ref.mheader) { + warn("mismatch link text: expected '" + ref.mtext + "' in " + fm.group()); + } else { + ok("xref resolves: " + fm.group(1)); + } + } else { + error("xref location mismatch: " + ref + " vs " + linkloc + "#" + ref.manchor); + } + } else { + boolean resolved = false; + boolean titlematch = false; + for (Reference ref : reflist) { + if (linkloc.sameSubmod(ref)) { + resolved = true; + if (ref.mtext.equals(fm.group(8)) || !ref.mheader) { + ok("xref resolves: " + fm.group(1)); + titlematch = true; + } + } + } + if (!resolved) { + error("xref could not be resolved: " + m.group()); + } else if (!titlematch) { + warn("check link text: " + fm.group()); + } + } + } else { + error("failed to resolve xref: " + fm.group(1)); + } + } + } + Pattern linkPattern = Pattern.compile("<<([^<>]+)>>"); + m = linkPattern.matcher(content); + while (m.find()) { + String anchor = m.group(1); + List reflist = resolve(anchor); + if (reflist != null) { + if (reflist.size() == 1) { + Reference ref = reflist.get(0); + if (ref.sameFile(checkfileloc)) { + if (!ref.manchor.equals(anchor)) { + error("local anchor does not exist: " + anchor); + String newlink = "<<" + ref.manchor + ">>"; + replaceLink(replacements, m.group(), newlink); + } else { + ok("anchor exists: " + anchor); + } + } else { + warn("local anchor '" + anchor + "' from a different file: " + ref.mfile); + String newlink = ref.makeLink(ref.mmodule.equals(checkfileloc.mmodule)); + replaceLink(replacements, m.group(), newlink); + } + } else { + // if it exists locally, all is good, otherwise it's ambiguous + List local = reflist.stream().filter(e -> e.sameFile(checkfileloc)) + .collect(Collectors.toList()); + if (local.size() > 0) { + Reference ref = local.get(0); + if (!ref.manchor.equals(anchor)) { + error("local anchor does not exist: " + anchor); + String newlink = "<<" + ref.manchor + ">>"; + replaceLink(replacements, m.group(), newlink); + } else { + ok("anchor exists: " + anchor); + } + } else { + error("local anchor ambiguous: " + m.group()); + for (Reference ref : reflist) { + String newlink = ref.makeLink(ref.mmodule.equals(checkfileloc.mmodule)); + System.out.println("\t? " + newlink); + } + } + } + } else { + error("failed to resolve local anchor: " + anchor); + } + } + if (overwrite && replacements.size() > 0) { + for (String str : replacements.keySet()) { + content = content.replace(str, replacements.get(str)); + } + Files.write(file.toPath(), content.getBytes()); + System.out.println("\uD83D\uDCBE writing " + file.toPath()); + } + } + + private void replaceLink(Map replacements, String link, String newlink) { + replacements.put(link, newlink); + System.out.println(" -> recommended replacement: " + newlink); + } + + private static void warn(String string) { + System.out.println("\u270B " + string); + } + + private static void error(String string) { + System.out.println("\u274C " + string); + } + + private static void ok(String string) { + System.out.println("\u2705 " + string); + } + + private List resolve(String reference) { + List ret = refmap.get(reference); + if (ret == null) { + ret = refmap.get(anchorKey(reference)); + } + return ret; + } + + private static File checkExists(File file) throws IOException { + if (!file.exists()) { + System.err.println("Folder does not exist " + file.getCanonicalPath()); + System.exit(1); + } + return file; + } + +} diff --git a/antora-conversion/renamer.sh b/antora-conversion/renamer.sh new file mode 100755 index 00000000..859c9f28 --- /dev/null +++ b/antora-conversion/renamer.sh @@ -0,0 +1,16 @@ +#!/usr/bin/env bash + +# Simple utility to replace the string "jsf" with "faces" for all .adoc files in the specified folder +# Uses the git "mv" command to retain history. + +find "$1" -name "*.adoc" -type f -exec sh -c ' + for file do + dir=$(dirname "$file") + new_dir=$(echo "$dir" | rev | sed "s/fsj/\secaf/" | rev) + echo "DIR: $file => $new_name" + + filename=$(basename "$file") + new_name=$(echo "$filename" | rev | sed "s/fsj/\secaf/" | rev) + echo "FILE: $file => $new_name" + git mv "$file" "$dir/$new_name" + done' sh {} + diff --git a/pom.xml b/pom.xml deleted file mode 100644 index 6c660b57..00000000 --- a/pom.xml +++ /dev/null @@ -1,140 +0,0 @@ - - - - - org.eclipse.ee4j - project - 1.0.6 - - 4.0.0 - jakarta.tutorial - tutorial - pom - 10 - Jakarta EE Tutorial - - - UTF-8 - true - 2.1.0 - - - scm:git:git@github.com:eclipse-ee4j/jakartaee-tutorial.git - scm:git:git@github.com:eclipse-ee4j/jakartaee-tutorial.git - https://github.com/eclipse-ee4j/jakartaee-tutorial - HEAD - - - - scm:git:git@github.com:eclipse-ee4j/jakartaee-tutorial.git - - - - package - - - org.asciidoctor - asciidoctor-maven-plugin - ${asciidoctor.maven.plugin.version} - - src/main/asciidoc - index.adoc - - ./src/main/ruby/autoxref-treeprocessor.rb - - - - - asciidoc-to-html - generate-resources - - process-asciidoc - - - html5 - - book - font - left - font - true - - - - images - coderay - images - - true - - - - - - org.apache.maven.plugins - maven-release-plugin - - forked-path - false - ${release.arguments} - - - - org.apache.maven.scm - maven-scm-provider-gitexe - 1.9.4 - - - - - - - - - publish-site - - ${project.build.directory}/generated-docs - true - true - - - - - org.apache.maven.plugins - maven-scm-publish-plugin - 1.1 - - - deploy-site - deploy - - publish-scm - - - gh-pages - false - Update site - - - - - - - - - diff --git a/readme-images/drawio-font-1-select-font.png b/readme-images/drawio-font-1-select-font.png new file mode 100644 index 00000000..0ce39113 Binary files /dev/null and b/readme-images/drawio-font-1-select-font.png differ diff --git a/readme-images/drawio-font-2-select-custom.png b/readme-images/drawio-font-2-select-custom.png new file mode 100644 index 00000000..af9ed7ee Binary files /dev/null and b/readme-images/drawio-font-2-select-custom.png differ diff --git a/readme-images/drawio-font-3-set-google-open-sans.png b/readme-images/drawio-font-3-set-google-open-sans.png new file mode 100644 index 00000000..6f402877 Binary files /dev/null and b/readme-images/drawio-font-3-set-google-open-sans.png differ diff --git a/readme-images/drawio-font-4-using-google-open-sans.png b/readme-images/drawio-font-4-using-google-open-sans.png new file mode 100644 index 00000000..4e8d3d84 Binary files /dev/null and b/readme-images/drawio-font-4-using-google-open-sans.png differ diff --git a/src/main/antora/antora.yml b/src/main/antora/antora.yml new file mode 100644 index 00000000..cb5a63fb --- /dev/null +++ b/src/main/antora/antora.yml @@ -0,0 +1,10 @@ +name: jakartaee-tutorial +title: Jakarta EE Tutorial +version: 10 +asciidoc: + attributes: + source-language: asciidoc@ + table-caption: false + xrefstyle: full +nav: + - modules/ROOT/nav.adoc diff --git a/src/main/antora/modules/ROOT/nav.adoc b/src/main/antora/modules/ROOT/nav.adoc new file mode 100644 index 00000000..88e9c751 --- /dev/null +++ b/src/main/antora/modules/ROOT/nav.adoc @@ -0,0 +1,175 @@ + +xref:index.adoc[] + +.Introduction + +* xref:intro:overview/overview.adoc[] + +* xref:intro:usingexamples/usingexamples.adoc[] + +.Platform Basics + +* xref:platform:resource-creation/resource-creation.adoc[] + +* xref:platform:injection/injection.adoc[] + +* xref:platform:packaging/packaging.adoc[] + +.Jakarta EE Core Profile + +* Jakarta CDI Lite + +** xref:cdi:cdi-basic/cdi-basic.adoc[] + +** xref:cdi:cdi-basicexamples/cdi-basicexamples.adoc[] + +** xref:supporttechs:interceptors/interceptors.adoc[] + +* Jakarta REST + +** xref:websvcs:jaxrs/jaxrs.adoc[] + +** xref:websvcs:jaxrs-client/jaxrs-client.adoc[] + +** xref:websvcs:jaxrs-advanced/jaxrs-advanced.adoc[] + +* Jakarta JSON + +** xref:web:jsonb/jsonb.adoc[] + +** xref:web:jsonp/jsonp.adoc[] + + +.Jakarta EE Web Profile + +* Jakarta CDI Full + +** xref:cdi:cdi-adv/cdi-adv.adoc[] + +** xref:cdi:cdi-bootstrap-se8/cdi-bootstrap-se8.adoc[] + +** xref:cdi:cdi-adv-examples/cdi-adv-examples.adoc[] + +* Jakarta Validation + +** xref:beanvalidation:bean-validation/bean-validation.adoc[] + +** xref:beanvalidation:bean-validation-advanced/bean-validation-advanced.adoc[] + +* xref:security:security.adoc[] + +* Jakarta Servlets + +** xref:web:webapp/webapp.adoc[] + +** xref:web:servlets/servlets.adoc[] + +* Jakarta Faces + +** xref:web:faces-intro/faces-intro.adoc[] + +** xref:web:faces-facelets/faces-facelets.adoc[] + +** xref:web:faces-page/faces-page.adoc[] + +** xref:web:faces-page-core/faces-page-core.adoc[] + +** xref:web:faces-develop/faces-develop.adoc[] + +** xref:web:faces-ajax/faces-ajax.adoc[] + +** xref:web:faces-advanced-cc/faces-advanced-cc.adoc[] + +** xref:web:faces-custom/faces-custom.adoc[] + +** xref:web:faces-configure/faces-configure.adoc[] + +** xref:web:faces-ws/faces-ws.adoc[] + +** xref:web:webi18n/webi18n.adoc[] + +* xref:web:websocket/websocket.adoc[] + +* Jakarta Persistence + +** xref:persist:persistence-intro/persistence-intro.adoc[] + +** xref:persist:persistence-basicexamples/persistence-basicexamples.adoc[] + +** xref:persist:persistence-querylanguage/persistence-querylanguage.adoc[] + +** xref:persist:persistence-criteria/persistence-criteria.adoc[] + +** xref:persist:persistence-string-queries/persistence-string-queries.adoc[] + +** xref:persist:persistence-locking/persistence-locking.adoc[] + +** xref:persist:persistence-entitygraphs/persistence-entitygraphs.adoc[] + +** xref:persist:persistence-cache/persistence-cache.adoc[] + +* Jakarta Enterprise Beans Lite + +** xref:entbeans:ejb-intro/ejb-intro.adoc[] + +** xref:entbeans:ejb-gettingstarted/ejb-gettingstarted.adoc[] + +** xref:entbeans:ejb-basicexamples/ejb-basicexamples.adoc[] + +** xref:entbeans:ejb-async/ejb-async.adoc[] + + +.Jakarta EE Platform + +* xref:messaging:mail-api/mail-api.adoc[] + +* Jakarta Messaging + +** xref:messaging:jms-concepts/jms-concepts.adoc[] + +** xref:messaging:jms-examples/jms-examples.adoc[] + +* xref:supporttechs:batch-processing/batch-processing.adoc[] + + +.Advanced + +* Web Profile + +** xref:security:security-authentication/security-authentication.adoc[] + +** xref:security:security-authorization/security-authorization.adoc[] + +** xref:supporttechs:transactions/transactions.adoc[] + +** xref:supporttechs:concurrency-utilities/concurrency-utilities.adoc[] + + +* Jakarta EE Platform + +** xref:supporttechs:connectors/connectors.adoc[] + + +* Optional Components + +** xref:web:faces-el/faces-el.adoc[] + +** Jakarta XML Binding + + +.Archived + +* Web Profile + +** xref:web:jakarta-pages/jakarta-pages.adoc[] + +** xref:web:jakarta-tags/jakarta-tags.adoc[] + + +* Jakarta EE Platform + +** xref:websvcs:xml-websvcs/xml-websvcs.adoc[] + +** xref:entbeans:ejb-full/ejb-full.adoc[] + + diff --git a/src/main/antora/modules/ROOT/pages/index.adoc b/src/main/antora/modules/ROOT/pages/index.adoc new file mode 100644 index 00000000..7f8b543a --- /dev/null +++ b/src/main/antora/modules/ROOT/pages/index.adoc @@ -0,0 +1,89 @@ +[preface] + += Preface + +include::ROOT:partial$draft.adoc[] + +== Legal + +This documentation 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. + +== About this Tutorial + +This tutorial explains how to use the features of the Jakarta EE Platform to build cloud-native applications, +such as microservices, "right sized" services, and server-based web applications. + +== Prerequisites + +Jakarta EE applications use the Java Platform, and are usually written in the Java programming language. +All the examples in this tutorial are written in Java. +If you're new to Java, spend some time getting up to speed on the language and platform; +a good place to start is https://dev.java/learn/[dev.java/learn]. + +Each topic in this tutorial provides some background information, +but in general, +we assume you have a basic understanding of the technologies each Jakarta EE feature works with. +For example, in the Jakarta Persistence chapter, +we assume you have a basic understanding of relational databases. + +== Conventions + +Throughout this tutorial, we use the following typographic conventions: + +[width="99%",cols="20%,38%,37%"] +|=== +|Convention |Meaning |Example + +|*Boldface* |Boldface type indicates a term defined in text or graphical user interface elements associated with an action. |A *cache* is a copy stored locally. + +From the *File* menu, choose *Open Project*. + +|`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 + +include::ROOT:partial$not_updated.adoc[] + +The following table describes the default paths and file names that are +used in this book. + +[width="99%",cols="20%,38%,38%"] +|=== +|Placeholder |Description |Default Value + +|`_as-install_` |Represents the base installation directory for GlassFish Server. | Installations on the Linux, UNIX, or macOS: + +`_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 UNIX/Linux/macOS: + +`_user's-home-directory_/glassfish6` + +Windows: + +`_SystemDrive_:\glassfish6` + +|`_jakartaee-examples_` |Represents the base installation directory for the Jakarta EE Tutorial examples project after you download or clone it. |`_user's-home-directory_/jakartaee-examples` + +|`_domain-dir_` |Represents the directory in which a domain's configuration is stored. |`_as-install_/domains/domain1` +|=== diff --git a/src/main/antora/modules/ROOT/partials/draft.adoc b/src/main/antora/modules/ROOT/partials/draft.adoc new file mode 100644 index 00000000..acd02433 --- /dev/null +++ b/src/main/antora/modules/ROOT/partials/draft.adoc @@ -0,0 +1,4 @@ +[NOTE] +==== +This section is currently a draft, and is subject to change. +==== diff --git a/src/main/antora/modules/ROOT/partials/not_updated.adoc b/src/main/antora/modules/ROOT/partials/not_updated.adoc new file mode 100644 index 00000000..d2b84609 --- /dev/null +++ b/src/main/antora/modules/ROOT/partials/not_updated.adoc @@ -0,0 +1,4 @@ +[NOTE] +==== +We are working on a fresh, updated Jakarta EE Tutorial. This section hasn't yet been updated. +==== \ No newline at end of file diff --git a/src/main/asciidoc/bean-validation-advanced/bean-validation-advanced.adoc b/src/main/antora/modules/beanvalidation/pages/bean-validation-advanced/bean-validation-advanced.adoc similarity index 89% rename from src/main/asciidoc/bean-validation-advanced/bean-validation-advanced.adoc rename to src/main/antora/modules/beanvalidation/pages/bean-validation-advanced/bean-validation-advanced.adoc index c61e5484..9f10c674 100644 --- a/src/main/asciidoc/bean-validation-advanced/bean-validation-advanced.adoc +++ b/src/main/antora/modules/beanvalidation/pages/bean-validation-advanced/bean-validation-advanced.adoc @@ -1,5 +1,7 @@ = Bean Validation: Advanced Topics +include::ROOT:partial$not_updated.adoc[] + This chapter describes how to create custom constraints, custom validator messages, and constraint groups using the Jakarta Bean Validation (Bean Validation). include::bean-validation-advanced001.adoc[] diff --git a/src/main/asciidoc/bean-validation-advanced/bean-validation-advanced001.adoc b/src/main/antora/modules/beanvalidation/pages/bean-validation-advanced/bean-validation-advanced001.adoc similarity index 99% rename from src/main/asciidoc/bean-validation-advanced/bean-validation-advanced001.adoc rename to src/main/antora/modules/beanvalidation/pages/bean-validation-advanced/bean-validation-advanced001.adoc index d79168c1..31e12298 100644 --- a/src/main/asciidoc/bean-validation-advanced/bean-validation-advanced001.adoc +++ b/src/main/antora/modules/beanvalidation/pages/bean-validation-advanced/bean-validation-advanced001.adoc @@ -144,7 +144,7 @@ public class Employee extends Person { } ---- -The constraint definition `@USPhoneNumber` is define in the sample listed under <>. +The constraint definition `@USPhoneNumber` is define in the sample listed under <<_using_the_built_in_constraints_to_make_a_new_constraint>>. In the sample, another constraint `@Pattern` is used to validate the phone number. == Using In-Built Value Extractors in Custom Containers diff --git a/src/main/asciidoc/bean-validation-advanced/bean-validation-advanced002.adoc b/src/main/antora/modules/beanvalidation/pages/bean-validation-advanced/bean-validation-advanced002.adoc similarity index 100% rename from src/main/asciidoc/bean-validation-advanced/bean-validation-advanced002.adoc rename to src/main/antora/modules/beanvalidation/pages/bean-validation-advanced/bean-validation-advanced002.adoc diff --git a/src/main/asciidoc/bean-validation-advanced/bean-validation-advanced003.adoc b/src/main/antora/modules/beanvalidation/pages/bean-validation-advanced/bean-validation-advanced003.adoc similarity index 100% rename from src/main/asciidoc/bean-validation-advanced/bean-validation-advanced003.adoc rename to src/main/antora/modules/beanvalidation/pages/bean-validation-advanced/bean-validation-advanced003.adoc diff --git a/src/main/asciidoc/bean-validation-advanced/bean-validation-advanced004.adoc b/src/main/antora/modules/beanvalidation/pages/bean-validation-advanced/bean-validation-advanced004.adoc similarity index 100% rename from src/main/asciidoc/bean-validation-advanced/bean-validation-advanced004.adoc rename to src/main/antora/modules/beanvalidation/pages/bean-validation-advanced/bean-validation-advanced004.adoc diff --git a/src/main/asciidoc/bean-validation/bean-validation.adoc b/src/main/antora/modules/beanvalidation/pages/bean-validation/bean-validation.adoc similarity index 90% rename from src/main/asciidoc/bean-validation/bean-validation.adoc rename to src/main/antora/modules/beanvalidation/pages/bean-validation/bean-validation.adoc index 31642d65..e31ea6bb 100644 --- a/src/main/asciidoc/bean-validation/bean-validation.adoc +++ b/src/main/antora/modules/beanvalidation/pages/bean-validation/bean-validation.adoc @@ -1,5 +1,7 @@ = Introduction to Jakarta Bean Validation +include::ROOT:partial$not_updated.adoc[] + This chapter describes Jakarta Bean Validation available as part of the Jakarta EE platform and the facility for validating objects, object members, methods, and constructors. include::bean-validation001.adoc[] diff --git a/src/main/asciidoc/bean-validation/bean-validation001.adoc b/src/main/antora/modules/beanvalidation/pages/bean-validation/bean-validation001.adoc similarity index 75% rename from src/main/asciidoc/bean-validation/bean-validation001.adoc rename to src/main/antora/modules/beanvalidation/pages/bean-validation/bean-validation001.adoc index 60403a5b..f8a40a5f 100644 --- a/src/main/asciidoc/bean-validation/bean-validation001.adoc +++ b/src/main/antora/modules/beanvalidation/pages/bean-validation/bean-validation001.adoc @@ -1,7 +1,7 @@ == Overview of Jakarta Bean Validation Validating input received from the user to maintain data integrity is an important part of application logic. -Validation of data can take place at different layers in even the simplest of applications, as shown in <>. +Validation of data can take place at different layers in even the simplest of applications, as shown in xref:web:faces-facelets/faces-facelets.adoc#_developing_a_simple_facelets_application_the_guessnumber_jsf_example_application[Developing a Simple Facelets Application: The guessnumber-jsf Example Application]. The `guessnumber-faces` example application validates the user input (in the `h:inputText` tag) for numerical data at the presentation layer and for a valid range of numbers at the business layer. Jakarta Bean Validation provides a facility for validating objects, object members, methods, and constructors. diff --git a/src/main/asciidoc/bean-validation/bean-validation002.adoc b/src/main/antora/modules/beanvalidation/pages/bean-validation/bean-validation002.adoc similarity index 91% rename from src/main/asciidoc/bean-validation/bean-validation002.adoc rename to src/main/antora/modules/beanvalidation/pages/bean-validation/bean-validation002.adoc index 88d568ff..bfd0cee8 100644 --- a/src/main/asciidoc/bean-validation/bean-validation002.adoc +++ b/src/main/antora/modules/beanvalidation/pages/bean-validation/bean-validation002.adoc @@ -5,10 +5,10 @@ The Jakarta Bean Validation model is supported by constraints in the form of ann Constraints can be built in or user defined. User-defined constraints are called custom constraints. Several built-in constraints are available in the `jakarta.validation.constraints` package. -<> lists all the built-in constraints. -See <> for information on creating custom constraints. +<> lists all the built-in constraints. +See xref:bean-validation-advanced/bean-validation-advanced.adoc#_creating_custom_constraints[Creating Custom Constraints] for information on creating custom constraints. -[[built-in-jakarta-bean-validation-constraints]] +[[built_in_jakarta_bean_validation_constraints]] .Built-In Jakarta Bean Validation Constraints [width="99%",cols="22%,59%,18%a"] |=== @@ -328,8 +328,8 @@ Any managed bean that contains Bean Validation annotations automatically gets va For more information on using validation constraints, see the following: -* xref:bean-validation-advanced-topics[xrefstyle=full] +* xref:bean-validation-advanced/bean-validation-advanced.adoc#_bean_validation_advanced_topics[Bean Validation: Advanced Topics] -* <> +* xref:websvcs:jaxrs-advanced/jaxrs-advanced.adoc#_validating_resource_data_with_bean_validation[Validating Resource Data with Bean Validation] -* <> +* xref:persist:persistence-intro/persistence-intro.adoc#_validating_persistent_fields_and_properties[Validating Persistent Fields and Properties] diff --git a/src/main/asciidoc/bean-validation/bean-validation003.adoc b/src/main/antora/modules/beanvalidation/pages/bean-validation/bean-validation003.adoc similarity index 100% rename from src/main/asciidoc/bean-validation/bean-validation003.adoc rename to src/main/antora/modules/beanvalidation/pages/bean-validation/bean-validation003.adoc diff --git a/src/main/asciidoc/bean-validation/bean-validation004.adoc b/src/main/antora/modules/beanvalidation/pages/bean-validation/bean-validation004.adoc similarity index 89% rename from src/main/asciidoc/bean-validation/bean-validation004.adoc rename to src/main/antora/modules/beanvalidation/pages/bean-validation/bean-validation004.adoc index 5c4c8a3b..72e4b667 100644 --- a/src/main/asciidoc/bean-validation/bean-validation004.adoc +++ b/src/main/antora/modules/beanvalidation/pages/bean-validation/bean-validation004.adoc @@ -26,7 +26,7 @@ The amount of the salary for the employee must not be null, cannot be greater th The currency type must not be null and is validated using a custom constraint. If you add method constraints to classes in an object hierarchy, special care must be taken to avoid unintended behavior by subtypes. -See <> for more information. +See xref:bean-validation-advanced/bean-validation-advanced.adoc#_using_method_constraints_in_type_hierarchies[Using Method Constraints in Type Hierarchies] for more information. === Cross-Parameter Constraints @@ -66,7 +66,7 @@ public Map<@NotNull String, @USPhoneNumber String> getAddressesByType() { } ---- In this sample, `@Email` is an in-built constraint supported by Bean Validation, and `@USPhoneNumber` is a user-defined constraint. -See <>. +See xref:bean-validation-advanced/bean-validation-advanced.adoc#_using_the_built_in_constraints_to_make_a_new_constraint[Using the Built-In Constraints to Make a New Constraint]. `@USPhoneNumber` has `ElementType.TYPE_USE` as one of its `@Target`, and therefore it is possible to use `@USPhoneNumber` constraint for validating type arguments of parameterized types. @@ -95,4 +95,4 @@ To avoid this ambiguity, add a `validationAppliesTo` element to the constraint a public Employee getManager(Employee employee) { ... } ---- -See <> for more information. +See xref:bean-validation-advanced/bean-validation-advanced.adoc#_removing_ambiguity_in_constraint_targets[Removing Ambiguity in Constraint Targets] for more information. diff --git a/src/main/asciidoc/bean-validation/bean-validation005.adoc b/src/main/antora/modules/beanvalidation/pages/bean-validation/bean-validation005.adoc similarity index 100% rename from src/main/asciidoc/bean-validation/bean-validation005.adoc rename to src/main/antora/modules/beanvalidation/pages/bean-validation/bean-validation005.adoc diff --git a/src/main/antora/modules/casestudies/nav.adoc b/src/main/antora/modules/casestudies/nav.adoc new file mode 100644 index 00000000..d68259ac --- /dev/null +++ b/src/main/antora/modules/casestudies/nav.adoc @@ -0,0 +1,7 @@ +.Case Studies + +* xref:dukes-bookstore/dukes-bookstore.adoc[] + +* xref:dukes-tutoring/dukes-tutoring.adoc[] + +* xref:dukes-forest/dukes-forest.adoc[] \ No newline at end of file diff --git a/src/main/asciidoc/dukes-bookstore/dukes-bookstore.adoc b/src/main/antora/modules/casestudies/pages/dukes-bookstore/dukes-bookstore.adoc similarity index 92% rename from src/main/asciidoc/dukes-bookstore/dukes-bookstore.adoc rename to src/main/antora/modules/casestudies/pages/dukes-bookstore/dukes-bookstore.adoc index 21f2ab4f..232274d3 100644 --- a/src/main/asciidoc/dukes-bookstore/dukes-bookstore.adoc +++ b/src/main/antora/modules/casestudies/pages/dukes-bookstore/dukes-bookstore.adoc @@ -1,5 +1,7 @@ = Duke's Bookstore Case Study Example +include::ROOT:partial$not_updated.adoc[] + The Duke's Bookstore example is a simple e-commerce application that illustrates some of the more advanced features of Jakarta Faces technology in combination with Jakarta Contexts and Dependency Injection (CDI), enterprise beans, and the Jakarta Persistence. Users can select books from an image map, view the bookstore catalog, and purchase books. No security is used in this application. diff --git a/src/main/asciidoc/dukes-bookstore/dukes-bookstore001.adoc b/src/main/antora/modules/casestudies/pages/dukes-bookstore/dukes-bookstore001.adoc similarity index 94% rename from src/main/asciidoc/dukes-bookstore/dukes-bookstore001.adoc rename to src/main/antora/modules/casestudies/pages/dukes-bookstore/dukes-bookstore001.adoc index d17a75b9..11da1657 100644 --- a/src/main/asciidoc/dukes-bookstore/dukes-bookstore001.adoc +++ b/src/main/antora/modules/casestudies/pages/dukes-bookstore/dukes-bookstore001.adoc @@ -26,7 +26,7 @@ This listener saves the name in a parameter so the following page, `bookreceipt. * A Jakarta Persistence entity -The packages of the Duke's Bookstore application, located in the `_tut-install_/examples/case-studies/dukes-bookstore/src/main/java/ee/jakarta/tutorial/dukesbookstore/` directory, are as follows: +The packages of the Duke's Bookstore application, located in the `_jakartaee-examples_/tutorial/case-studies/dukes-bookstore/src/main/java/jakarta/tutorial/dukesbookstore/` directory, are as follows: * `components`: Includes the custom UI component classes, `MapComponent` and `AreaComponent` diff --git a/src/main/asciidoc/dukes-bookstore/dukes-bookstore002.adoc b/src/main/antora/modules/casestudies/pages/dukes-bookstore/dukes-bookstore002.adoc similarity index 82% rename from src/main/asciidoc/dukes-bookstore/dukes-bookstore002.adoc rename to src/main/antora/modules/casestudies/pages/dukes-bookstore/dukes-bookstore002.adoc index 38486a97..8dc7e955 100644 --- a/src/main/asciidoc/dukes-bookstore/dukes-bookstore002.adoc +++ b/src/main/antora/modules/casestudies/pages/dukes-bookstore/dukes-bookstore002.adoc @@ -45,7 +45,7 @@ The Duke's Bookstore application uses Facelets and its templating features to di The Facelets pages interact with a set of CDI managed beans that act as backing beans, providing the underlying properties and methods for the user interface. The front page also interacts with the custom components used by the application. -The application uses the following Facelets pages, which are located in the `_tut-install_/examples/case-studies/dukes-bookstore/src/main/webapp/` directory. +The application uses the following Facelets pages, which are located in the `_jakartaee-examples_/tutorial/case-studies/dukes-bookstore/src/main/webapp/` directory. * `bookstoreTemplate.xhtml`: The template file, which specifies a header used on every page as well as the style sheet used by all the pages. The template also retrieves the language set in the web browser. @@ -80,7 +80,7 @@ Uses the `CashierBean` managed bean. * `bookordererror.xhtml`: Page rendered by `CashierBean` if the bookstore has no more copies of a book that was ordered. -The application uses the following managed beans, which are located in the `_tut-install_/examples/case-studies/dukes-bookstore/src/main/java/ee/jakarta/tutorial/dukesbookstore/web/managedbeans/` directory. +The application uses the following managed beans, which are located in the `_jakartaee-examples_/tutorial/case-studies/dukes-bookstore/src/main/java/jakarta/tutorial/dukesbookstore/web/managedbeans/` directory. * `AbstractBean`: Contains utility methods called by other managed beans. @@ -107,32 +107,31 @@ Specifies the name `showcart`. === Custom Components and Other Custom Objects Used in Duke's Bookstore -The map and area custom components for Duke's Bookstore, along with associated renderer, listener, and model classes, are defined in the following packages in the `_tut-install_/examples/case-studies/dukes-bookstore/src/main/java/ee/jakarta/tutorial/dukesbookstore/` directory. +The map and area custom components for Duke's Bookstore, along with associated renderer, listener, and model classes, are defined in the following packages in the `_jakartaee-examples_/tutorial/case-studies/dukes-bookstore/src/main/java/jakarta/tutorial/dukesbookstore/` directory. * `components`: Contains the `MapComponent` and `AreaComponent` classes. -See <>. +See xref:web:faces-custom/faces-custom.adoc#_creating_custom_component_classes[Creating Custom Component Classes]. * `listeners`: Contains the `AreaSelectedEvent` class, along with other listener classes. -See <>. +See xref:web:faces-custom/faces-custom.adoc#_handling_events_for_custom_components[Handling Events for Custom Components]. * `model`: Contains the `ImageArea` class. -See <> for more information. * `renderers`: Contains the `MapRenderer` and `AreaRenderer` classes. -See <>. +See xref:web:faces-custom/faces-custom.adoc#_delegating_rendering_to_a_renderer[Delegating Rendering to a Renderer]. -The `_tut-install_/examples/case-studies/dukes-bookstore/src/java/dukesbookstore/` directory also contains a custom converter and other custom listeners not specifically tied to the custom components. +The `_jakartaee-examples_/tutorial/case-studies/dukes-bookstore/src/main/java/jakarta/tutorial/dukesbookstore/` directory also contains a custom converter and other custom listeners not specifically tied to the custom components. * `converters`: Contains the `CreditCardConverter` class. -See <>. +See xref:web:faces-custom/faces-custom.adoc#_creating_and_using_a_custom_converter[Creating and Using a Custom Converter]. * `listeners`: Contains the `LinkBookChangeListener`, `MapBookChangeListener`, and `NameChanged` classes. -See <>. +See xref:web:faces-custom/faces-custom.adoc#_implementing_an_event_listener[Implementing an Event Listener]. === Properties Files Used in Duke's Bookstore The strings used in the Duke's Bookstore application are encapsulated into resource bundles to allow the display of localized strings in multiple locales. -The properties files, located in the `_tut-install_/examples/case-studies/dukes-bookstore/src/main/java/ee/jakarta/tutorial/dukesbookstore/web/messages/` directory, consist of a default file containing English strings and three additional files for other locales. +The properties files, located in the `_jakartaee-examples_/tutorial/case-studies/dukes-bookstore/src/main/java/jakarta/tutorial/dukesbookstore/web/messages/` directory, consist of a default file containing English strings and three additional files for other locales. The files are as follows: * `Messages.properties`: Default file, containing English strings @@ -152,7 +151,7 @@ The `html` tag in `bookstoreTemplate.xhtml` retrieves the language setting from ... ---- -For more information about resource bundles, see xref:internationalizing-and-localizing-web-applications[xrefstyle=full]. +For more information about resource bundles, see xref:web:webi18n/webi18n.adoc#_internationalizing_and_localizing_web_applications[Internationalizing and Localizing Web Applications]. The resource bundle is configured as follows in the `faces-config.xml` file: diff --git a/src/main/asciidoc/dukes-bookstore/dukes-bookstore003.adoc b/src/main/antora/modules/casestudies/pages/dukes-bookstore/dukes-bookstore003.adoc similarity index 62% rename from src/main/asciidoc/dukes-bookstore/dukes-bookstore003.adoc rename to src/main/antora/modules/casestudies/pages/dukes-bookstore/dukes-bookstore003.adoc index 850df970..f57fd02a 100644 --- a/src/main/asciidoc/dukes-bookstore/dukes-bookstore003.adoc +++ b/src/main/antora/modules/casestudies/pages/dukes-bookstore/dukes-bookstore003.adoc @@ -4,14 +4,14 @@ You can use either NetBeans IDE or Maven to build, package, deploy, and run the === To Build and Deploy Duke's Bookstore Using NetBeans IDE -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . From the File menu, choose Open Project. . In the Open Project dialog box, navigate to: + ---- -tut-install/examples/case-studies +jakartaee-examples/tutorial/case-studies ---- . Select the `dukes-bookstore` folder. @@ -24,12 +24,12 @@ This will build, package, and deploy Duke's Bookstore to GlassFish Server. === To Build and Deploy Duke's Bookstore Using Maven -. Make sure that GlassFish Server has been started (see <>), as well as the database server (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]), as well as the database server (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_apache_derby[Starting and Stopping Apache Derby]). . In a terminal window, go to: + ---- -tut-install/examples/case-studies/dukes-bookstore/ +jakartaee-examples/tutorial/case-studies/dukes-bookstore/ ---- . Enter the following command: @@ -39,7 +39,7 @@ tut-install/examples/case-studies/dukes-bookstore/ mvn install ---- + -This command builds the application and packages it in a WAR file in the `_tut-install_/examples/case-studies/dukes-bookstore/target/` directory. +This command builds the application and packages it in a WAR file in the `_jakartaee-examples_/tutorial/case-studies/dukes-bookstore/target/` directory. It then deploys the application to GlassFish Server. === To Run Duke's Bookstore diff --git a/src/main/asciidoc/dukes-forest/dukes-forest.adoc b/src/main/antora/modules/casestudies/pages/dukes-forest/dukes-forest.adoc similarity index 88% rename from src/main/asciidoc/dukes-forest/dukes-forest.adoc rename to src/main/antora/modules/casestudies/pages/dukes-forest/dukes-forest.adoc index 1ae30b98..9ef69c12 100644 --- a/src/main/asciidoc/dukes-forest/dukes-forest.adoc +++ b/src/main/antora/modules/casestudies/pages/dukes-forest/dukes-forest.adoc @@ -1,5 +1,7 @@ = Duke's Forest Case Study Example +include::ROOT:partial$not_updated.adoc[] + This chapter describes Duke's Forest, a simple e-commerce application that contains several web applications and illustrates the use of multiple Jakarta EE APIs. include::dukes-forest001.adoc[] diff --git a/src/main/asciidoc/dukes-forest/dukes-forest001.adoc b/src/main/antora/modules/casestudies/pages/dukes-forest/dukes-forest001.adoc similarity index 100% rename from src/main/asciidoc/dukes-forest/dukes-forest001.adoc rename to src/main/antora/modules/casestudies/pages/dukes-forest/dukes-forest001.adoc diff --git a/src/main/asciidoc/dukes-forest/dukes-forest002.adoc b/src/main/antora/modules/casestudies/pages/dukes-forest/dukes-forest002.adoc similarity index 92% rename from src/main/asciidoc/dukes-forest/dukes-forest002.adoc rename to src/main/antora/modules/casestudies/pages/dukes-forest/dukes-forest002.adoc index 7eea1da8..9acf959b 100644 --- a/src/main/asciidoc/dukes-forest/dukes-forest002.adoc +++ b/src/main/antora/modules/casestudies/pages/dukes-forest/dukes-forest002.adoc @@ -1,12 +1,12 @@ == Design and Architecture of Duke's Forest Duke's Forest is a complex application consisting of three main projects and three subprojects. -<> shows the architecture of the three main projects that you will deploy: Duke's Store, Duke's Shipment, and Duke's Payment. +<<_architecture_of_the_dukes_forest_example_application>> shows the architecture of the three main projects that you will deploy: Duke's Store, Duke's Shipment, and Duke's Payment. It also shows how Duke's Store makes use of the Events and Entities projects. -[[architecture-of-the-dukes-forest-example-application]] +[[_architecture_of_the_dukes_forest_example_application]] .Architecture of the Duke's Forest Example Application -image::jakartaeett_dt_062.svg["This figure shows the architecture of the main Duke's Forest projects and how they use the Events and Entities projects."] +image::common:jakartaeett_dt_062.svg["This figure shows the architecture of the main Duke's Forest projects and how they use the Events and Entities projects."] Duke's Forest uses the following Jakarta EE platform features: @@ -68,13 +68,13 @@ The Duke's Forest application has two main user interfaces, both packaged within The Duke's Shipment application also has a user interface, accessible to administrators. -<> shows how the web applications and the web service interact. +<<_interactions_between_dukes_forest_components>> shows how the web applications and the web service interact. -[[interactions-between-dukes-forest-components]] +[[_interactions_between_dukes_forest_components]] .Interactions between Duke's Forest Components -image::jakartaeett_dt_063.svg["This figure shows the interactions between the Duke's Store and Duke's Shipment projects (using REST and HTTP), and between the Duke's Store and Duke's Payment projects (using REST and HTTP)."] +image::common:jakartaeett_dt_063.svg["This figure shows the interactions between the Duke's Store and Duke's Shipment projects (using REST and HTTP), and between the Duke's Store and Duke's Payment projects (using REST and HTTP)."] -As illustrated in <>, the customer interacts with the main interface of Duke's Store, while the administrator interacts with the administration interface. +As illustrated in <<_interactions_between_dukes_forest_components>>, the customer interacts with the main interface of Duke's Store, while the administrator interacts with the administration interface. Both interfaces access a façade consisting of managed beans and stateless session beans, which in turn interact with the entities that represent database tables. The façade also interacts with web services APIs that access the Duke's Payment web service. When the payment for an order is approved, Duke's Store sends the order to a Jakarta Messaging queue. @@ -125,12 +125,12 @@ To enable users to add more events to the project easily or update an event clas === The entities Project The `entities` project is a Jakarta Persistence project used by both Duke's Store and Duke's Shipment. -It is generated from the database schema shown in <> and is also used as a base for the entities consumed and produced by the web services through Jakarta XML Binding. +It is generated from the database schema shown in <<_dukes_forest_database_table_and_their_relationships>> and is also used as a base for the entities consumed and produced by the web services through Jakarta XML Binding. Each entity has validation rules based on business requirements, specified using Jakarta Bean Validation. -[[dukes-forest-database-table-and-their-relationships]] +[[_dukes_forest_database_table_and_their_relationships]] .Duke's Forest Database Tables and Their Relationships -image:jakartaeett_dt_064.svg["This figure shows the database tables in Duke's Forest and their relationships."] +image::common:jakartaeett_dt_064.svg["This figure shows the database tables in Duke's Forest and their relationships."] The database schema contains eight tables: @@ -237,7 +237,7 @@ The administration interface of Duke's Store allows administrators to perform th * Group maintenance (create, edit, update, delete) -The project also uses stateless session beans as façades for interactions with the Jakarta Persistence entities described in <>, and CDI managed beans as controllers for interactions with Facelets pages. +The project also uses stateless session beans as façades for interactions with the Jakarta Persistence entities described in <<_the_entities_project>>, and CDI managed beans as controllers for interactions with Facelets pages. The project thus follows the MVC (Model-View-Controller) pattern and applies the same pattern to all entities and pages, as in the following example. * `AbstractFacade` is an abstract class that receives a `Type` and implements the common operations (CRUD) for this type, where `` is a Persistence entity. @@ -322,7 +322,7 @@ It divides the screen into several areas and specifies the client page for each * `login.xhtml`: Login page specified in `web.xml`. The main login interface is provided in `topbar.xhtml`, but this page appears if there is a login error. -* `admin` directory: Pages related to the administration interface, described in <>. +* `admin` directory: Pages related to the administration interface, described in <<_facelets_files_used_in_the_administration_interface_of_dukes_store>>. * `customer` directory: Pages related to customers (`Create.xhtml`, `Edit.xhtml`, `List.xhtml`, `Profile.xhtml`, `View.xhtml`). @@ -397,7 +397,7 @@ Duke's Store defines the following qualifiers in the `com.forest.qualifiers` pac ==== Event Handlers Used in Duke's Store -Duke's Store defines event handlers related to the `OrderEvent` class packaged in the `events` project (see <>). +Duke's Store defines event handlers related to the `OrderEvent` class packaged in the `events` project (see <<_the_events_project>>). The event handlers are in the `com.forest.handlers` package. * `IOrderHandler`: The `IOrderHandler` interface defines a method, `onNewOrder`, implemented by the two handler classes. @@ -483,7 +483,7 @@ The Duke's Shipment managed beans use only one helper class, found in the `com.f ==== Qualifier Used in Duke's Shipment -Duke's Shipment includes the `@LoggedIn` qualifier described in <>. +Duke's Shipment includes the `@LoggedIn` qualifier described in <<_qualifiers_used_in_dukes_store>>. ==== Deployment Descriptors Used in Duke's Shipment diff --git a/src/main/asciidoc/dukes-forest/dukes-forest003.adoc b/src/main/antora/modules/casestudies/pages/dukes-forest/dukes-forest003.adoc similarity index 65% rename from src/main/asciidoc/dukes-forest/dukes-forest003.adoc rename to src/main/antora/modules/casestudies/pages/dukes-forest/dukes-forest003.adoc index a19d3cd9..f4e6e686 100644 --- a/src/main/asciidoc/dukes-forest/dukes-forest003.adoc +++ b/src/main/antora/modules/casestudies/pages/dukes-forest/dukes-forest003.adoc @@ -4,14 +4,14 @@ You can use NetBeans IDE or Maven to build and deploy Duke's Forest. === To Build and Deploy the Duke's Forest Application Using NetBeans IDE -. Make sure that GlassFish Server has been started (see <>), as well as the database server (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]), as well as the database server (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_apache_derby[Starting and Stopping Apache Derby]). . From the File menu, choose Open Project. . In the Open Project dialog box, navigate to: + ---- -tut-install/examples/case-studies +jakartaee-examples/tutorial/case-studies ---- . Select the `dukes-forest` folder. @@ -26,12 +26,12 @@ To configure the server, this task creates a JDBC security realm named `jdbcReal === To Build and Deploy the Duke's Forest Application Using Maven -. Make sure that GlassFish Server has been started (see <>), as well as the database server (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]), as well as the database server (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_apache_derby[Starting and Stopping Apache Derby]). . In a terminal window, go to: + ---- -tut-install/examples/case-studies/dukes-forest/ +jakartaee-examples/tutorial/case-studies/dukes-forest/ ---- . Enter the following command to configure the server, create and populate the database, build all the subprojects, assemble them into JAR and WAR files, and deploy the `dukes-payment`, `dukes-store,` and `dukes-shipment` applications: diff --git a/src/main/asciidoc/dukes-forest/dukes-forest004.adoc b/src/main/antora/modules/casestudies/pages/dukes-forest/dukes-forest004.adoc similarity index 100% rename from src/main/asciidoc/dukes-forest/dukes-forest004.adoc rename to src/main/antora/modules/casestudies/pages/dukes-forest/dukes-forest004.adoc diff --git a/src/main/asciidoc/dukes-tutoring/dukes-tutoring.adoc b/src/main/antora/modules/casestudies/pages/dukes-tutoring/dukes-tutoring.adoc similarity index 92% rename from src/main/asciidoc/dukes-tutoring/dukes-tutoring.adoc rename to src/main/antora/modules/casestudies/pages/dukes-tutoring/dukes-tutoring.adoc index e3f4b537..1449c668 100644 --- a/src/main/asciidoc/dukes-tutoring/dukes-tutoring.adoc +++ b/src/main/antora/modules/casestudies/pages/dukes-tutoring/dukes-tutoring.adoc @@ -1,5 +1,7 @@ = Duke's Tutoring Case Study Example +include::ROOT:partial$not_updated.adoc[] + The Duke's Tutoring example application is a tracking system for a tutoring center for students. Students can be checked in and out and can visit the park. The tutoring center can track attendance and status updates and can store contact information for guardians and students. diff --git a/src/main/asciidoc/dukes-tutoring/dukes-tutoring001.adoc b/src/main/antora/modules/casestudies/pages/dukes-tutoring/dukes-tutoring001.adoc similarity index 83% rename from src/main/asciidoc/dukes-tutoring/dukes-tutoring001.adoc rename to src/main/antora/modules/casestudies/pages/dukes-tutoring/dukes-tutoring001.adoc index 068e4b35..29c22255 100644 --- a/src/main/asciidoc/dukes-tutoring/dukes-tutoring001.adoc +++ b/src/main/antora/modules/casestudies/pages/dukes-tutoring/dukes-tutoring001.adoc @@ -4,11 +4,11 @@ Duke's Tutoring is a web application that incorporates several Jakarta EE techno It exposes both a main interface (for students, guardians, and tutoring center staff) and an administration interface (for staff to maintain the system). The business logic for both interfaces is provided by enterprise beans. The enterprise beans use the Jakarta Persistence to create and store the application's data in the database. -<> illustrates the architecture of the application. +<<_architecture_of_the_dukes_tutoring_example_application>> illustrates the architecture of the application. -[[architecture-of-the-dukes-tutoring-example-application]] +[[_architecture_of_the_dukes_tutoring_example_application]] .Architecture of the Duke's Tutoring Example Application -image::jakartaeett_dt_061.svg["Architecture diagram of the Duke's Tutoring example application. Two clients access the main interface and the admin interface deployed in the web container. These interfaces communicate with enterprise beans deployed in the Jakarta Enterprise Beans container. The enterprise beans communicate with the database."] +image::common:jakartaeett_dt_061.svg["Architecture diagram of the Duke's Tutoring example application. Two clients access the main interface and the admin interface deployed in the web container. These interfaces communicate with enterprise beans deployed in the Jakarta Enterprise Beans container. The enterprise beans communicate with the database."] The Duke's Tutoring application is organized into two main projects: the `dukes-tutoring-common` library and the `dukes-tutoring-war` web application. The `dukes-tutoring-common` library project contains the entity classes and helper classes used by the `dukes-tutoring-war` web application, and `dukes-tutoring-common` is packaged and deployed with `dukes-tutoring-war`. diff --git a/src/main/asciidoc/dukes-tutoring/dukes-tutoring002.adoc b/src/main/antora/modules/casestudies/pages/dukes-tutoring/dukes-tutoring002.adoc similarity index 85% rename from src/main/asciidoc/dukes-tutoring/dukes-tutoring002.adoc rename to src/main/antora/modules/casestudies/pages/dukes-tutoring/dukes-tutoring002.adoc index 559500e2..c4b2ad50 100644 --- a/src/main/asciidoc/dukes-tutoring/dukes-tutoring002.adoc +++ b/src/main/antora/modules/casestudies/pages/dukes-tutoring/dukes-tutoring002.adoc @@ -29,8 +29,8 @@ A particular tutoring session tracks which students attended that day, and which Students' statuses change when they check in to a tutoring session, when they go to the park, and when they check out. The status entry allows the tutoring center staff to track exactly which students attended a tutoring session, when they checked in and out, which students went to the park while they were at the tutoring center, and when they went to and came back from the park. -For information on creating Jakarta Persistence entities, see xref:introduction-to-jakarta-persistence[xrefstyle=full]. -For information on validating entity data, see <> and xref:bean-validation-advanced-topics[xrefstyle=full]. +For information on creating Jakarta Persistence entities, see xref:persist:persistence-intro/persistence-intro.adoc#_introduction_to_jakarta_persistence[Introduction to Jakarta Persistence]. +For information on validating entity data, see xref:persist:persistence-intro/persistence-intro.adoc#_validating_persistent_fields_and_properties[Validating Persistent Fields and Properties] and xref:beanvalidation:bean-validation-advanced/bean-validation-advanced.adoc#_bean_validation_advanced_topics[Bean Validation: Advanced Topics]. === Enterprise Beans Used in the Main Interface @@ -44,9 +44,9 @@ These business methods use strongly typed Criteria API queries to retrieve data `RequestBean` also injects a CDI event instance, `StatusEvent`. This event is fired from the business methods when the status of a student changes. -For information on creating and using enterprise beans, see xref:enterprise-beans[xrefstyle=full]. -For information on creating strongly typed Criteria API queries, see xref:using-the-criteria-api-to-create-queries[xrefstyle=full]. -For information on CDI events, see <>. +For information on creating and using enterprise beans, see xref:entbeans:ejb-intro/ejb-intro.adoc#_enterprise_beans[Enterprise Beans]. +For information on creating strongly typed Criteria API queries, see xref:persist:persistence-criteria/persistence-criteria.adoc#_using_the_criteria_api_to_create_queries[Using the Criteria API to Create Queries]. +For information on CDI events, see xref:cdi:cdi-adv/cdi-adv.adoc#_using_events_in_cdi_applications[Using Events in CDI Applications]. === WebSocket Endpoint Used in the Main Interface @@ -58,13 +58,13 @@ The `updateStatus` observer method is called by the container, and pushes out th The `index.xhtml` Jakarta Faces page contains JavaScript code to connect to the WebSocket endpoint. The `onMessage` method on this page clicks a Jakarta Faces button, which makes an Ajax request to refresh the table that shows the current status of the students. -For more information on WebSocket endpoints, see xref:jakarta-websocket-2[xrefstyle=full]. -For information on CDI events, see <>. +For more information on WebSocket endpoints, see xref:web:websocket/websocket.adoc#_jakarta_websocket[Jakarta WebSocket]. +For information on CDI events, see xref:cdi:cdi-adv/cdi-adv.adoc#_using_events_in_cdi_applications[Using Events in CDI Applications]. === Facelets Files Used in the Main Interface The Duke's Tutoring application uses Facelets to display the user interface, making extensive use of the templating features of Facelets. -Facelets, the default display technology for Jakarta Faces technology, consists of XHTML files located in the `_tut-install_/examples/case-studies/dukes-tutoring-war/src/main/webapp/` directory. +Facelets, the default display technology for Jakarta Faces technology, consists of XHTML files located in the `_jakartaee-examples_/tutorial/case-studies/dukes-tutoring/dukes-tutoring-war/src/main/webapp/` directory. The following Facelets files are used in the main interface: @@ -90,7 +90,7 @@ The following Facelets files are used in the main interface: * `WEB-INF/includes/mainNav.xhtml`: XHTML fragment for the main interface's navigation bar -For information on using Facelets, see xref:introduction-to-facelets[xrefstyle=full]. +For information on using Facelets, see xref:web:faces-facelets/faces-facelets.adoc#_introduction_to_facelets[Introduction to Facelets]. === Helper Classes Used in the Main Interface @@ -128,7 +128,7 @@ For example, the strings for German-speaking locales are located in `ValidationM Each supported locale has a property file of the form `Messages___locale prefix__.properties` containing the localized strings. For example, the strings for simplified Chinese-speaking locales are located in `Messages_zh.properties`. -For information on localizing web applications, see <>. +For information on localizing web applications, see xref:web:faces-configure/faces-configure.adoc#_registering_application_messages[Registering Application Messages]. === Deployment Descriptors Used in Duke's Tutoring diff --git a/src/main/asciidoc/dukes-tutoring/dukes-tutoring003.adoc b/src/main/antora/modules/casestudies/pages/dukes-tutoring/dukes-tutoring003.adoc similarity index 100% rename from src/main/asciidoc/dukes-tutoring/dukes-tutoring003.adoc rename to src/main/antora/modules/casestudies/pages/dukes-tutoring/dukes-tutoring003.adoc diff --git a/src/main/asciidoc/dukes-tutoring/dukes-tutoring004.adoc b/src/main/antora/modules/casestudies/pages/dukes-tutoring/dukes-tutoring004.adoc similarity index 84% rename from src/main/asciidoc/dukes-tutoring/dukes-tutoring004.adoc rename to src/main/antora/modules/casestudies/pages/dukes-tutoring/dukes-tutoring004.adoc index cdb10435..a4629217 100644 --- a/src/main/asciidoc/dukes-tutoring/dukes-tutoring004.adoc +++ b/src/main/antora/modules/casestudies/pages/dukes-tutoring/dukes-tutoring004.adoc @@ -10,18 +10,18 @@ You can use either NetBeans IDE or Maven to build, package, deploy, and run Duke ===== Before You Begin -You must have already configured GlassFish Server as a Jakarta EE server in NetBeans IDE, as described in <>. +You must have already configured GlassFish Server as a Jakarta EE server in NetBeans IDE, as described in xref:intro:usingexamples/usingexamples.adoc#_to_add_glassfish_server_as_a_server_using_netbeans_ide[To Add GlassFish Server as a Server Using NetBeans IDE]. -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). -. If the database server is not already running, start it as described in <>. +. If the database server is not already running, start it as described in xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_apache_derby[Starting and Stopping Apache Derby]. . From the File menu, choose Open Project. . In the Open Project dialog box, navigate to: + ---- -tut-install/examples/case-studies +jakartaee-examples/tutorial/case-studies ---- . Select the `dukes-tutoring` folder. @@ -38,14 +38,14 @@ This command creates a JDBC security realm named tutoringRealm, builds and packa ==== To Build and Deploy Duke's Tutoring Using Maven -. Make sure that GlassFish Server has started (see <>). +. Make sure that GlassFish Server has started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). -. If the database server is not already running, start it as described in <>. +. If the database server is not already running, start it as described in xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_apache_derby[Starting and Stopping Apache Derby]. . In a terminal window, go to: + ---- -tut-install/examples/case-studies/dukes-tutoring/ +jakartaee-examples/tutorial/case-studies/dukes-tutoring/ ---- . Enter the following command: diff --git a/src/main/asciidoc/cdi-adv-examples/cdi-adv-examples.adoc b/src/main/antora/modules/cdi/pages/cdi-adv-examples/cdi-adv-examples.adoc similarity index 90% rename from src/main/asciidoc/cdi-adv-examples/cdi-adv-examples.adoc rename to src/main/antora/modules/cdi/pages/cdi-adv-examples/cdi-adv-examples.adoc index 290ee94d..0f5b4c90 100644 --- a/src/main/asciidoc/cdi-adv-examples/cdi-adv-examples.adoc +++ b/src/main/antora/modules/cdi/pages/cdi-adv-examples/cdi-adv-examples.adoc @@ -1,5 +1,7 @@ = Running the Advanced Contexts and Dependency Injection Examples +include::ROOT:partial$not_updated.adoc[] + This chapter describes in detail how to build and run several advanced examples that use CDI. include::cdi-adv-examples001.adoc[] diff --git a/src/main/antora/modules/cdi/pages/cdi-adv-examples/cdi-adv-examples001.adoc b/src/main/antora/modules/cdi/pages/cdi-adv-examples/cdi-adv-examples001.adoc new file mode 100644 index 00000000..ca825cea --- /dev/null +++ b/src/main/antora/modules/cdi/pages/cdi-adv-examples/cdi-adv-examples001.adoc @@ -0,0 +1,10 @@ +== Building and Running the CDI Advanced Examples + +The examples are in the `_jakartaee-examples_/tutorial/cdi/` directory. +To build and run the examples, you will do the following. + +. Use NetBeans IDE or the Maven tool to compile, package, and deploy the example. + +. Run the example in a web browser. + +See xref:intro:usingexamples/usingexamples.adoc#_using_the_tutorial_examples[Using the Tutorial Examples], for basic information on installing, building, and running the examples. diff --git a/src/main/asciidoc/cdi-adv-examples/cdi-adv-examples002.adoc b/src/main/antora/modules/cdi/pages/cdi-adv-examples/cdi-adv-examples002.adoc similarity index 91% rename from src/main/asciidoc/cdi-adv-examples/cdi-adv-examples002.adoc rename to src/main/antora/modules/cdi/pages/cdi-adv-examples/cdi-adv-examples002.adoc index 3010f940..b703d704 100644 --- a/src/main/asciidoc/cdi-adv-examples/cdi-adv-examples002.adoc +++ b/src/main/antora/modules/cdi/pages/cdi-adv-examples/cdi-adv-examples002.adoc @@ -1,9 +1,9 @@ == The encoder Example: Using Alternatives -The `encoder` example shows how to use alternatives to choose between two beans at deployment time, as described in <>. +The `encoder` example shows how to use alternatives to choose between two beans at deployment time, as described in xref:cdi-adv/cdi-adv.adoc#_using_alternatives_in_cdi_applications[Using Alternatives in CDI Applications]. The example includes an interface and two implementations of it, a managed bean, a Facelets page, and configuration files. -The source files are located in the `_tut-install_/examples/cdi/encoder/src/main/java/ee/jakarta/tutorial/encoder/` directory. +The source files are located in the `_jakartaee-examples_/tutorial/cdi/encoder/src/main/java/jakarta/tutorial/encoder/` directory. === The Coder Interface and Implementations @@ -144,14 +144,14 @@ You can use either NetBeans IDE or Maven to build, package, deploy, and run the ==== To Build, Package, and Deploy the encoder Example Using NetBeans IDE -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . From the *File* menu, choose *Open Project*. . In the *Open Project* dialog box, navigate to: + ---- -tut-install/examples/cdi +jakartaee-examples/tutorial/cdi ---- . Select the `encoder` folder. @@ -211,12 +211,12 @@ Result: input string is Java, shift value is 4 ==== To Build, Package, and Deploy the encoder Example Using Maven -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . In a terminal window, go to: + ---- -tut-install/examples/cdi/encoder/ +jakartaee-examples/tutorial/cdi/encoder/ ---- . Enter the following command to deploy the application: @@ -248,7 +248,7 @@ For example, if you enter `Java` and `4`, the result is `Neze`. .. In a text editor, open the following file: + ---- -tut-install/examples/cdi/encoder/src/main/webapp/WEB-INF/beans.xml +jakartaee-examples/tutorial/cdi/encoder/src/main/webapp/WEB-INF/beans.xml ---- .. Remove the comment characters that surround the `alternatives` element, so that it looks like this: diff --git a/src/main/asciidoc/cdi-adv-examples/cdi-adv-examples003.adoc b/src/main/antora/modules/cdi/pages/cdi-adv-examples/cdi-adv-examples003.adoc similarity index 83% rename from src/main/asciidoc/cdi-adv-examples/cdi-adv-examples003.adoc rename to src/main/antora/modules/cdi/pages/cdi-adv-examples/cdi-adv-examples003.adoc index ba754435..d50a99ef 100644 --- a/src/main/asciidoc/cdi-adv-examples/cdi-adv-examples003.adoc +++ b/src/main/antora/modules/cdi/pages/cdi-adv-examples/cdi-adv-examples003.adoc @@ -1,7 +1,7 @@ == The producermethods Example: Using a Producer Method to Choose a Bean Implementation -The `producermethods` example shows how to use a producer method to choose between two beans at runtime, as described in <>. -It is very similar to the `encoder` example described in <>. +The `producermethods` example shows how to use a producer method to choose between two beans at runtime, as described in xref:cdi-adv/cdi-adv.adoc#_using_producer_methods_producer_fields_and_disposer_methods_in_cdi_applications[Using Producer Methods, Producer Fields, and Disposer Methods in CDI Applications]. +It is very similar to the `encoder` example described in xref:cdi-adv-examples/cdi-adv-examples.adoc#_the_encoder_example_using_alternatives[The encoder Example: Using Alternatives]. The example includes the same interface and two implementations of it, a managed bean, a Facelets page, and configuration files. It also contains a qualifier type. When you run it, you do not need to edit the `beans.xml` file and redeploy the application to change its behavior. @@ -86,14 +86,14 @@ You can use either NetBeans IDE or Maven to build, package, deploy, and run the ==== To Build, Package, and Deploy the producermethods Example Using NetBeans IDE -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . From the *File* menu, choose *Open Project*. . In the *Open Project* dialog box, navigate to: + ---- -tut-install/examples/cdi +jakartaee-examples/tutorial/cdi ---- . Select the `producermethods` folder. @@ -106,12 +106,12 @@ This command builds and packages the application into a WAR file, `producermetho ==== To Build, Package, and Deploy the producermethods Example Using Maven -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . In a terminal window, go to: + ---- -tut-install/examples/cdi/producermethods/ +jakartaee-examples/tutorial/cdi/producermethods/ ---- . Enter the following command to deploy the application: diff --git a/src/main/asciidoc/cdi-adv-examples/cdi-adv-examples004.adoc b/src/main/antora/modules/cdi/pages/cdi-adv-examples/cdi-adv-examples004.adoc similarity index 90% rename from src/main/asciidoc/cdi-adv-examples/cdi-adv-examples004.adoc rename to src/main/antora/modules/cdi/pages/cdi-adv-examples/cdi-adv-examples004.adoc index ed500360..2ca50ce2 100644 --- a/src/main/asciidoc/cdi-adv-examples/cdi-adv-examples004.adoc +++ b/src/main/antora/modules/cdi/pages/cdi-adv-examples/cdi-adv-examples004.adoc @@ -7,7 +7,7 @@ The `producerfields` example is the simplest possible entity example. It also contains a qualifier and a class that generates the entity manager. It also contains a single entity, a stateful session bean, a Facelets page, and a managed bean. -The source files are located in the `_tut-install_/examples/cdi/producerfields/src/main/java/ee/jakarta/tutorial/producerfields/` directory. +The source files are located in the `_jakartaee-examples_/tutorial/cdi/producerfields/src/main/java/jakarta/tutorial/producerfields/` directory. === The Producer Field for the producerfields Example @@ -89,7 +89,6 @@ The `EntityManagerFactory` declarations also allow applications to use an applic The `producerfields` example contains a simple entity class, `entity.ToDo`, and a stateful session bean, `ejb.RequestBean`, that uses it. The entity class contains three fields: an autogenerated `id` field, a string specifying the task, and a timestamp. -The timestamp field, `timeCreated`, is annotated with `@Temporal`, which is required for persistent `Date` fields. [source,java] ---- @@ -101,13 +100,12 @@ public class ToDo implements Serializable { @GeneratedValue(strategy = GenerationType.AUTO) private Long id; protected String taskText; - @Temporal(TIMESTAMP) - protected Date timeCreated; + protected LocalDateTime timeCreated; public ToDo() { } - public ToDo(Long id, String taskText, Date timeCreated) { + public ToDo(Long id, String taskText, LocalDateTime timeCreated) { this.id = id; this.taskText = taskText; this.timeCreated = timeCreated; @@ -137,17 +135,14 @@ It then defines two methods, one that creates and persists a single `ToDo` list [source,java] ---- public ToDo createToDo(String inputString) { - ToDo toDo = null; - Date currentTime = Calendar.getInstance().getTime(); - try { - toDo = new ToDo(); + ToDo toDo = new ToDo(); toDo.setTaskText(inputString); - toDo.setTimeCreated(currentTime); + toDo.setTimeCreated(LocalDateTime.now()); em.persist(toDo); return toDo; } catch (Exception e) { - throw new EJBException(e.getMessage()); + throw new EJBException(e); } } @@ -280,16 +275,16 @@ You can use either NetBeans IDE or Maven to build, package, deploy, and run the ==== To Build, Package, and Deploy the producerfields Example Using NetBeans IDE -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). -. If the database server is not already running, start it by following the instructions in <>. +. If the database server is not already running, start it by following the instructions in xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_apache_derby[Starting and Stopping Apache Derby]. . From the *File* menu, choose *Open Project*. . In the *Open Project* dialog box, navigate to: + ---- -tut-install/examples/cdi +jakartaee-examples/tutorial/cdi ---- . Select the `producerfields` folder. @@ -302,14 +297,14 @@ This command builds and packages the application into a WAR file, `producerfield ==== To Build, Package, and Deploy the producerfields Example Using Maven -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). -. If the database server is not already running, start it by following the instructions in <>. +. If the database server is not already running, start it by following the instructions in xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_apache_derby[Starting and Stopping Apache Derby]. . In a terminal window, go to: + ---- -tut-install/examples/cdi/producerfields/ +jakartaee-examples/tutorial/cdi/producerfields/ ---- . Enter the following command to deploy the application: diff --git a/src/main/asciidoc/cdi-adv-examples/cdi-adv-examples005.adoc b/src/main/antora/modules/cdi/pages/cdi-adv-examples/cdi-adv-examples005.adoc similarity index 94% rename from src/main/asciidoc/cdi-adv-examples/cdi-adv-examples005.adoc rename to src/main/antora/modules/cdi/pages/cdi-adv-examples/cdi-adv-examples005.adoc index bbb7c0e7..3f4b8d73 100644 --- a/src/main/asciidoc/cdi-adv-examples/cdi-adv-examples005.adoc +++ b/src/main/antora/modules/cdi/pages/cdi-adv-examples/cdi-adv-examples005.adoc @@ -2,7 +2,7 @@ The `billpayment` example shows how to use both events and interceptors. -The source files are located in the `_tut-install_/examples/cdi/billpayment/src/main/java/ee/jakarta/tutorial/billpayment/` directory. +The source files are located in the `_jakartaee-examples_/tutorial/cdi/billpayment/src/main/java/jakarta/tutorial/billpayment/` directory. === Overview of the billpayment Example @@ -72,7 +72,7 @@ public class PaymentHandler implements Serializable { Each observer method takes as an argument the event, annotated with `@Observes` and with the qualifier for the type of payment. In a real application, the observer methods would pass the event information on to another component that would perform business logic on the payment. -The qualifiers are defined in the `payment` package, described in <>. +The qualifiers are defined in the `payment` package, described in <<_the_billpayment_facelets_pages_and_managed_bean>>. The `PaymentHandler` bean is annotated `@Logged` so that all its methods can be intercepted. @@ -163,7 +163,7 @@ It then fires the event. ---- @Logged public String pay() { - this.setDatetime(Calendar.getInstance().getTime()); + this.setDatetime(LocalDateTime.now()); switch (paymentOption) { case DEBIT: PaymentEvent debitPayload = new PaymentEvent(); @@ -285,14 +285,14 @@ You can use either NetBeans IDE or Maven to build, package, deploy, and run the ==== To Build, Package, and Deploy the billpayment Example Using NetBeans IDE -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . From the *File* menu, choose *Open Project*. . In the *Open Project* dialog box, navigate to: + ---- -tut-install/examples/cdi +jakartaee-examples/tutorial/cdi ---- . Select the `billpayment` folder. @@ -305,12 +305,12 @@ This command builds and packages the application into a WAR file, `billpayment.w ==== To Build, Package, and Deploy the billpayment Example Using Maven -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . In a terminal window, go to: + ---- -tut-install/examples/cdi/billpayment/ +jakartaee-examples/tutorial/cdi/billpayment/ ---- . Enter the following command to deploy the application: diff --git a/src/main/asciidoc/cdi-adv-examples/cdi-adv-examples006.adoc b/src/main/antora/modules/cdi/pages/cdi-adv-examples/cdi-adv-examples006.adoc similarity index 85% rename from src/main/asciidoc/cdi-adv-examples/cdi-adv-examples006.adoc rename to src/main/antora/modules/cdi/pages/cdi-adv-examples/cdi-adv-examples006.adoc index 9cac0325..e7af129c 100644 --- a/src/main/asciidoc/cdi-adv-examples/cdi-adv-examples006.adoc +++ b/src/main/antora/modules/cdi/pages/cdi-adv-examples/cdi-adv-examples006.adoc @@ -2,7 +2,7 @@ The `decorators` example, which is yet another variation on the `encoder` example, shows how to use a decorator to implement additional business logic for a bean. -The source files are located in the `_tut-install_/examples/cdi/decorators/src/main/java/ee/jakarta/tutorial/decorators/` directory. +The source files are located in the `_jakartaee-examples_/tutorial/cdi/decorators/src/main/java/jakarta/tutorial/decorators/` directory. === Overview of the decorators Example @@ -12,7 +12,7 @@ The example includes an interface, an implementation of it, a decorator, an inte === Components of the decorators Example -The `decorators` example is very similar to the `encoder` example described in <>. +The `decorators` example is very similar to the `encoder` example described in xref:cdi-adv-examples/cdi-adv-examples.adoc#_the_encoder_example_using_alternatives[The encoder Example: Using Alternatives]. Instead of providing two implementations of the `Coder` interface, however, this example provides only the `CoderImpl` class. The decorator class, `CoderDecorator`, rather than simply return the coded string, displays the input and output strings' values and length. @@ -63,14 +63,14 @@ You can use either NetBeans IDE or Maven to build, package, deploy, and run the ==== To Build, Package, and Deploy the decorators Example Using NetBeans IDE -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . From the *File* menu, choose *Open Project*. . In the *Open Project* dialog box, navigate to: + ---- -tut-install/examples/cdi +jakartaee-examples/tutorial/cdi ---- . Select the `decorators` folder. @@ -83,12 +83,12 @@ This command builds and packages the application into a WAR file, `decorators.wa ==== To Build, Package, and Deploy the decorators Example Using Maven -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . In a terminal window, go to: + ---- -tut-install/examples/cdi/decorators/ +jakartaee-examples/tutorial/cdi/decorators/ ---- . Enter the following command to deploy the application: diff --git a/src/main/asciidoc/cdi-adv/cdi-adv.adoc b/src/main/antora/modules/cdi/pages/cdi-adv/cdi-adv.adoc similarity index 81% rename from src/main/asciidoc/cdi-adv/cdi-adv.adoc rename to src/main/antora/modules/cdi/pages/cdi-adv/cdi-adv.adoc index 0d425c53..00967135 100644 --- a/src/main/asciidoc/cdi-adv/cdi-adv.adoc +++ b/src/main/antora/modules/cdi/pages/cdi-adv/cdi-adv.adoc @@ -1,7 +1,9 @@ = Jakarta Contexts and Dependency Injection: Advanced Topics +include::ROOT:partial$not_updated.adoc[] + This chapter describes more advanced features of Jakarta Contexts and Dependency Injection. -Specifically, it covers additional features CDI provides to enable loose coupling of components with strong typing, in addition to those described in <>. +Specifically, it covers additional features CDI provides to enable loose coupling of components with strong typing, in addition to those described in xref:cdi-basic/cdi-basic.adoc#_overview_of_cdi[Overview of CDI]. include::cdi-adv001.adoc[] diff --git a/src/main/asciidoc/cdi-adv/cdi-adv001.adoc b/src/main/antora/modules/cdi/pages/cdi-adv/cdi-adv001.adoc similarity index 100% rename from src/main/asciidoc/cdi-adv/cdi-adv001.adoc rename to src/main/antora/modules/cdi/pages/cdi-adv/cdi-adv001.adoc diff --git a/src/main/asciidoc/cdi-adv/cdi-adv002.adoc b/src/main/antora/modules/cdi/pages/cdi-adv/cdi-adv002.adoc similarity index 93% rename from src/main/asciidoc/cdi-adv/cdi-adv002.adoc rename to src/main/antora/modules/cdi/pages/cdi-adv/cdi-adv002.adoc index 6f303aec..e3c5e66f 100644 --- a/src/main/asciidoc/cdi-adv/cdi-adv002.adoc +++ b/src/main/antora/modules/cdi/pages/cdi-adv/cdi-adv002.adoc @@ -1,6 +1,6 @@ == Using Alternatives in CDI Applications -When you have more than one version of a bean that you use for different purposes, you can choose between them during the development phase by injecting one qualifier or another, as shown in <>. +When you have more than one version of a bean that you use for different purposes, you can choose between them during the development phase by injecting one qualifier or another, as shown in xref:cdi-basicexamples/cdi-basicexamples.adoc#_the_simplegreeting_cdi_example[The simplegreeting CDI Example]. Instead of having to change the source code of your application, however, you can make the choice at deployment time by using alternatives. @@ -15,7 +15,7 @@ Alternatives are commonly used for purposes such as the following: To make a bean available for lookup, injection, or EL resolution using this mechanism, give it a `jakarta.enterprise.inject.Alternative` annotation and then use the `alternatives` element to specify it in the `beans.xml` file. For example, you might want to create a full version of a bean and also a simpler version that you use only for certain kinds of testing. -The example described in <> contains two such beans, `CoderImpl` and `TestCoderImpl`. +The example described in xref:cdi-adv-examples/cdi-adv-examples.adoc#_the_encoder_example_using_alternatives[The encoder Example: Using Alternatives] contains two such beans, `CoderImpl` and `TestCoderImpl`. The test bean is annotated as follows: [source,java] diff --git a/src/main/asciidoc/cdi-adv/cdi-adv003.adoc b/src/main/antora/modules/cdi/pages/cdi-adv/cdi-adv003.adoc similarity index 79% rename from src/main/asciidoc/cdi-adv/cdi-adv003.adoc rename to src/main/antora/modules/cdi/pages/cdi-adv/cdi-adv003.adoc index a77db984..b2c9fc46 100644 --- a/src/main/asciidoc/cdi-adv/cdi-adv003.adoc +++ b/src/main/antora/modules/cdi/pages/cdi-adv/cdi-adv003.adoc @@ -8,7 +8,7 @@ A producer method generates an object that can then be injected.Typically, you u * When the object requires some custom initialization that the bean constructor does not perform -For more information on producer methods, see <>. +For more information on producer methods, see xref:cdi-basic/cdi-basic.adoc#_injecting_objects_by_using_producer_methods[Injecting Objects by Using Producer Methods]. A producer field is a simpler alternative to a producer method; it is a field of a bean that generates an object. It can be used instead of a simple getter method. @@ -19,7 +19,7 @@ A producer method or field is annotated with the `jakarta.enterprise.inject.Prod === Using Producer Methods A producer method can allow you to select a bean implementation at runtime instead of at development time or deployment time. -For example, in the example described in <>, the managed bean defines the following producer method: +For example, in the example described in xref:cdi-adv-examples/cdi-adv-examples.adoc#_the_producermethods_example_using_a_producer_method_to_choose_a_bean_implementation[The producermethods Example: Using a Producer Method to Choose a Bean Implementation], the managed bean defines the following producer method: [source,java] ---- @@ -54,7 +54,7 @@ Without it, the CDI implementation would not be able to choose between `CoderImp === Using Producer Fields to Generate Resources -A common use of a producer field is to generate an object such as a JDBC `DataSource` or a Jakarta Persistence `EntityManager` (see xref:introduction-to-jakarta-persistence[xrefstyle=full], for more information). +A common use of a producer field is to generate an object such as a JDBC `DataSource` or a Jakarta Persistence `EntityManager` (see xref:persist:persistence-intro/persistence-intro.adoc#_introduction_to_jakarta_persistence[Introduction to Jakarta Persistence], for more information). The object can then be managed by the container. For example, you could create a `@UserDatabase` qualifier and then declare a producer field for an entity manager as follows: @@ -76,7 +76,7 @@ The `@UserDatabase` qualifier can be used when you inject the object into anothe ... ---- -<> shows how to use producer fields to generate an entity manager. +xref:cdi-adv-examples/cdi-adv-examples.adoc#_the_producerfields_example_using_producer_fields_to_generate_resources[The producerfields Example: Using Producer Fields to Generate Resources] shows how to use producer fields to generate an entity manager. You can use a similar mechanism to inject `@Resource`, `@EJB`, or `@WebServiceRef` objects. To minimize the reliance on resource injection, specify the producer field for the resource in one place in the application, and then inject the object wherever in the application you need it. diff --git a/src/main/asciidoc/cdi-adv/cdi-adv004.adoc b/src/main/antora/modules/cdi/pages/cdi-adv/cdi-adv004.adoc similarity index 95% rename from src/main/asciidoc/cdi-adv/cdi-adv004.adoc rename to src/main/antora/modules/cdi/pages/cdi-adv/cdi-adv004.adoc index 58651d9a..7509c764 100644 --- a/src/main/asciidoc/cdi-adv/cdi-adv004.adoc +++ b/src/main/antora/modules/cdi/pages/cdi-adv/cdi-adv004.adoc @@ -27,7 +27,7 @@ The bean that implements this interface enables a servlet to access information To inject a predefined bean, create an injection point to obtain an instance of the bean by using the `jakarta.annotation.Resource` annotation for resources or the `jakarta.inject.Inject` annotation for CDI beans. For the bean type, specify the class name of the interface the bean implements. -[[injection-of-predefined-beans]] +[[_injection_of_predefined_beans]] .Injection of Predefined Beans [width="80%",cols="20%,20%,40%"] |=== @@ -50,7 +50,7 @@ For the bean type, specify the class name of the interface the bean implements. Predefined beans are injected with dependent scope and the predefined default qualifier `@Default`. -For more information about injecting resources, see <>. +For more information about injecting resources, see xref:platform:injection/injection.adoc#_resource_injection[Resource Injection]. The following code snippet shows how to use the `@Resource` and `@Inject` annotations to inject predefined beans. This code snippet injects a user transaction and a context object into the servlet class `TransactionServlet`. diff --git a/src/main/asciidoc/cdi-adv/cdi-adv005.adoc b/src/main/antora/modules/cdi/pages/cdi-adv/cdi-adv005.adoc similarity index 95% rename from src/main/asciidoc/cdi-adv/cdi-adv005.adoc rename to src/main/antora/modules/cdi/pages/cdi-adv/cdi-adv005.adoc index 685dc98b..4967c6b8 100644 --- a/src/main/asciidoc/cdi-adv/cdi-adv005.adoc +++ b/src/main/antora/modules/cdi/pages/cdi-adv/cdi-adv005.adoc @@ -13,7 +13,7 @@ An event consists of the following: * Zero or more qualifier types, the event qualifiers -For example, in the `billpayment` example described in <>, a `PaymentEvent` bean defines an event using three properties, which have setter and getter methods: +For example, in the `billpayment` example described in xref:cdi-adv-examples/cdi-adv-examples.adoc#_the_billpayment_example_using_events_and_interceptors[The billpayment Example: Using Events and Interceptors], a `PaymentEvent` bean defines an event using three properties, which have setter and getter methods: [source,java] ---- diff --git a/src/main/asciidoc/cdi-adv/cdi-adv006.adoc b/src/main/antora/modules/cdi/pages/cdi-adv/cdi-adv006.adoc similarity index 93% rename from src/main/asciidoc/cdi-adv/cdi-adv006.adoc rename to src/main/antora/modules/cdi/pages/cdi-adv/cdi-adv006.adoc index bee91868..8f720ca8 100644 --- a/src/main/asciidoc/cdi-adv/cdi-adv006.adoc +++ b/src/main/antora/modules/cdi/pages/cdi-adv/cdi-adv006.adoc @@ -7,7 +7,7 @@ Interceptors allow you to specify the code for these tasks in one place for easy When interceptors were first introduced to the Jakarta EE platform, they were specific to enterprise beans. On the Jakarta EE platform, you can use them with Jakarta EE managed objects of all kinds, including managed beans. -For information on Jakarta EE interceptors, see xref:using-jakarta-ee-interceptors[xrefstyle=full]. +For information on Jakarta EE interceptors, see xref:supporttechs:interceptors/interceptors.adoc#_using_jakarta_ee_interceptors[Using Jakarta EE Interceptors]. An interceptor class often contains a method annotated `@AroundInvoke`, which specifies the tasks the interceptor will perform when intercepted methods are invoked. It can also contain a method annotated `@PostConstruct`, `@PreDestroy`, `@PrePassivate`, or `@PostActivate`, to specify lifecycle callback interceptors, and a method annotated `@AroundTimeout`, to specify enterprise bean timeout interceptors. @@ -33,7 +33,7 @@ The `@Inherited` annotation also applies to custom scopes (not discussed in this An interceptor binding type may declare other interceptor bindings. The interceptor class is annotated with the interceptor binding as well as with the `@Interceptor` annotation. -For an example, see <>. +For an example, see xref:cdi-adv-examples/cdi-adv-examples.adoc#_the_loggedinterceptor_interceptor_class[The LoggedInterceptor Interceptor Class]. Every `@AroundInvoke` method takes a `jakarta.interceptor.InvocationContext` argument, returns a `java.lang.Object`, and throws an `Exception`. It can call `InvocationContext` methods. diff --git a/src/main/asciidoc/cdi-adv/cdi-adv007.adoc b/src/main/antora/modules/cdi/pages/cdi-adv/cdi-adv007.adoc similarity index 94% rename from src/main/asciidoc/cdi-adv/cdi-adv007.adoc rename to src/main/antora/modules/cdi/pages/cdi-adv/cdi-adv007.adoc index 457a674c..64271ac5 100644 --- a/src/main/asciidoc/cdi-adv/cdi-adv007.adoc +++ b/src/main/antora/modules/cdi/pages/cdi-adv/cdi-adv007.adoc @@ -32,7 +32,7 @@ public abstract class CoderDecorator implements Coder { } ---- -See <> for an example that uses this decorator. +See xref:cdi-adv-examples/cdi-adv-examples.adoc#_the_decorators_example_decorating_a_bean[The decorators Example: Decorating a Bean] for an example that uses this decorator. This simple decorator returns more detailed output than the encoded string returned by the `CoderImpl.codeString` method. A more complex decorator could store information in a database or perform some other business logic. diff --git a/src/main/asciidoc/cdi-adv/cdi-adv008.adoc b/src/main/antora/modules/cdi/pages/cdi-adv/cdi-adv008.adoc similarity index 100% rename from src/main/asciidoc/cdi-adv/cdi-adv008.adoc rename to src/main/antora/modules/cdi/pages/cdi-adv/cdi-adv008.adoc diff --git a/src/main/asciidoc/cdi-adv/cdi-adv009.adoc b/src/main/antora/modules/cdi/pages/cdi-adv/cdi-adv009.adoc similarity index 100% rename from src/main/asciidoc/cdi-adv/cdi-adv009.adoc rename to src/main/antora/modules/cdi/pages/cdi-adv/cdi-adv009.adoc diff --git a/src/main/asciidoc/cdi-adv/cdi-adv010.adoc b/src/main/antora/modules/cdi/pages/cdi-adv/cdi-adv010.adoc similarity index 100% rename from src/main/asciidoc/cdi-adv/cdi-adv010.adoc rename to src/main/antora/modules/cdi/pages/cdi-adv/cdi-adv010.adoc diff --git a/src/main/asciidoc/cdi-basic/cdi-basic.adoc b/src/main/antora/modules/cdi/pages/cdi-basic/cdi-basic.adoc similarity index 94% rename from src/main/asciidoc/cdi-basic/cdi-basic.adoc rename to src/main/antora/modules/cdi/pages/cdi-basic/cdi-basic.adoc index e5516147..93ed6269 100644 --- a/src/main/asciidoc/cdi-basic/cdi-basic.adoc +++ b/src/main/antora/modules/cdi/pages/cdi-basic/cdi-basic.adoc @@ -1,5 +1,7 @@ = Introduction to Jakarta Contexts and Dependency Injection +include::ROOT:partial$not_updated.adoc[] + This chapter describes Jakarta Contexts and Dependency Injection (CDI) which is one of several Jakarta EE features that help to knit together the web tier and the transactional tier of the Jakarta EE platform. include::cdi-basic001.adoc[] diff --git a/src/main/asciidoc/cdi-basic/cdi-basic001.adoc b/src/main/antora/modules/cdi/pages/cdi-basic/cdi-basic001.adoc similarity index 74% rename from src/main/asciidoc/cdi-basic/cdi-basic001.adoc rename to src/main/antora/modules/cdi/pages/cdi-basic/cdi-basic001.adoc index 0d4a35a3..70965202 100644 --- a/src/main/asciidoc/cdi-basic/cdi-basic001.adoc +++ b/src/main/antora/modules/cdi/pages/cdi-basic/cdi-basic001.adoc @@ -75,15 +75,15 @@ This is specified using the `jakarta.enterprise.context.RequestScoped` annotatio public class MessageB implements Message { ... } ---- -For more information on scopes, see <>. +For more information on scopes, see xref:cdi-basic/cdi-basic.adoc#_using_scopes[Using Scopes]. The `MessageB` class is a CDI bean. CDI beans are classes that CDI can instantiate, manage, and inject automatically to satisfy the dependencies of other objects. Almost any Java class can be managed and injected by CDI. -For more information on beans, see <>. +For more information on beans, see xref:cdi-basic/cdi-basic.adoc#_about_beans[About Beans]. A JAR or WAR file that contains a CDI bean is a bean archive. -For more information on packaging bean archives, see <> in this chapter and <> in xref:jakarta-contexts-and-dependency-injection-advanced-topics[xrefstyle=full]. +For more information on packaging bean archives, see xref:cdi-basic/cdi-basic.adoc#_configuring_a_cdi_application[Configuring a CDI Application] in this chapter and xref:cdi-adv/cdi-adv.adoc#_packaging_cdi_applications[Packaging CDI Applications] in xref:cdi-adv/cdi-adv.adoc#_jakarta_contexts_and_dependency_injection_advanced_topics[Jakarta Contexts and Dependency Injection: Advanced Topics]. In this example, `MessageB` is the only class that implements the `Message` interface. If an application has more than one implementation of an interface, CDI provides mechanisms that you can use to select which implementation to inject. -For more information, see <> in this chapter and <> in xref:jakarta-contexts-and-dependency-injection-advanced-topics[xrefstyle=full]. +For more information, see xref:cdi-basic/cdi-basic.adoc#_using_qualifiers[Using Qualifiers] in this chapter and xref:cdi-adv/cdi-adv.adoc#_using_alternatives_in_cdi_applications[Using Alternatives in CDI Applications] in xref:cdi-adv/cdi-adv.adoc#_jakarta_contexts_and_dependency_injection_advanced_topics[Jakarta Contexts and Dependency Injection: Advanced Topics]. diff --git a/src/main/asciidoc/cdi-basic/cdi-basic002.adoc b/src/main/antora/modules/cdi/pages/cdi-basic/cdi-basic002.adoc similarity index 100% rename from src/main/asciidoc/cdi-basic/cdi-basic002.adoc rename to src/main/antora/modules/cdi/pages/cdi-basic/cdi-basic002.adoc diff --git a/src/main/asciidoc/cdi-basic/cdi-basic003.adoc b/src/main/antora/modules/cdi/pages/cdi-basic/cdi-basic003.adoc similarity index 80% rename from src/main/asciidoc/cdi-basic/cdi-basic003.adoc rename to src/main/antora/modules/cdi/pages/cdi-basic/cdi-basic003.adoc index b62aad04..996f408a 100644 --- a/src/main/asciidoc/cdi-basic/cdi-basic003.adoc +++ b/src/main/antora/modules/cdi/pages/cdi-basic/cdi-basic003.adoc @@ -8,11 +8,11 @@ More specifically, a bean has the following attributes: * A (nonempty) set of bean types -* A (nonempty) set of qualifiers (see <>) +* A (nonempty) set of qualifiers (see xref:cdi-basic/cdi-basic.adoc#_using_qualifiers[Using Qualifiers]) -* A scope (see <>) +* A scope (see xref:cdi-basic/cdi-basic.adoc#_using_scopes[Using Scopes]) -* Optionally, a bean EL name (see <>) +* Optionally, a bean EL name (see xref:cdi-basic/cdi-basic.adoc#_giving_beans_el_names[Giving Beans EL Names]) * A set of interceptor bindings diff --git a/src/main/asciidoc/cdi-basic/cdi-basic004.adoc b/src/main/antora/modules/cdi/pages/cdi-basic/cdi-basic004.adoc similarity index 100% rename from src/main/asciidoc/cdi-basic/cdi-basic004.adoc rename to src/main/antora/modules/cdi/pages/cdi-basic/cdi-basic004.adoc diff --git a/src/main/asciidoc/cdi-basic/cdi-basic005.adoc b/src/main/antora/modules/cdi/pages/cdi-basic/cdi-basic005.adoc similarity index 89% rename from src/main/asciidoc/cdi-basic/cdi-basic005.adoc rename to src/main/antora/modules/cdi/pages/cdi-basic/cdi-basic005.adoc index 5e596291..680474fd 100644 --- a/src/main/asciidoc/cdi-basic/cdi-basic005.adoc +++ b/src/main/antora/modules/cdi/pages/cdi-basic/cdi-basic005.adoc @@ -37,4 +37,4 @@ public class Greeting { This class becomes a bean that you can then inject into another class. This bean is not exposed to the EL in this form. -<> explains how you can make a bean accessible to the EL. +xref:cdi-basic/cdi-basic.adoc#_giving_beans_el_names[Giving Beans EL Names] explains how you can make a bean accessible to the EL. diff --git a/src/main/asciidoc/cdi-basic/cdi-basic006.adoc b/src/main/antora/modules/cdi/pages/cdi-basic/cdi-basic006.adoc similarity index 100% rename from src/main/asciidoc/cdi-basic/cdi-basic006.adoc rename to src/main/antora/modules/cdi/pages/cdi-basic/cdi-basic006.adoc diff --git a/src/main/asciidoc/cdi-basic/cdi-basic007.adoc b/src/main/antora/modules/cdi/pages/cdi-basic/cdi-basic007.adoc similarity index 100% rename from src/main/asciidoc/cdi-basic/cdi-basic007.adoc rename to src/main/antora/modules/cdi/pages/cdi-basic/cdi-basic007.adoc diff --git a/src/main/asciidoc/cdi-basic/cdi-basic008.adoc b/src/main/antora/modules/cdi/pages/cdi-basic/cdi-basic008.adoc similarity index 96% rename from src/main/asciidoc/cdi-basic/cdi-basic008.adoc rename to src/main/antora/modules/cdi/pages/cdi-basic/cdi-basic008.adoc index dc47d921..ac274ec3 100644 --- a/src/main/asciidoc/cdi-basic/cdi-basic008.adoc +++ b/src/main/antora/modules/cdi/pages/cdi-basic/cdi-basic008.adoc @@ -2,9 +2,9 @@ For a web application to use a bean that injects another bean class, the bean needs to be able to hold state over the duration of the user's interaction with the application. The way to define this state is to give the bean a scope. -You can give an object any of the scopes described in <>, depending on how you are using it. +You can give an object any of the scopes described in <<_scopes>>, depending on how you are using it. -[[scopes]] +[[_scopes]] .Scopes [width="99%",cols="25%,25%,50%"] |=== diff --git a/src/main/asciidoc/cdi-basic/cdi-basic009.adoc b/src/main/antora/modules/cdi/pages/cdi-basic/cdi-basic009.adoc similarity index 100% rename from src/main/asciidoc/cdi-basic/cdi-basic009.adoc rename to src/main/antora/modules/cdi/pages/cdi-basic/cdi-basic009.adoc diff --git a/src/main/asciidoc/cdi-basic/cdi-basic010.adoc b/src/main/antora/modules/cdi/pages/cdi-basic/cdi-basic010.adoc similarity index 100% rename from src/main/asciidoc/cdi-basic/cdi-basic010.adoc rename to src/main/antora/modules/cdi/pages/cdi-basic/cdi-basic010.adoc diff --git a/src/main/asciidoc/cdi-basic/cdi-basic011.adoc b/src/main/antora/modules/cdi/pages/cdi-basic/cdi-basic011.adoc similarity index 100% rename from src/main/asciidoc/cdi-basic/cdi-basic011.adoc rename to src/main/antora/modules/cdi/pages/cdi-basic/cdi-basic011.adoc diff --git a/src/main/asciidoc/cdi-basic/cdi-basic012.adoc b/src/main/antora/modules/cdi/pages/cdi-basic/cdi-basic012.adoc similarity index 100% rename from src/main/asciidoc/cdi-basic/cdi-basic012.adoc rename to src/main/antora/modules/cdi/pages/cdi-basic/cdi-basic012.adoc diff --git a/src/main/asciidoc/cdi-basic/cdi-basic013.adoc b/src/main/antora/modules/cdi/pages/cdi-basic/cdi-basic013.adoc similarity index 71% rename from src/main/asciidoc/cdi-basic/cdi-basic013.adoc rename to src/main/antora/modules/cdi/pages/cdi-basic/cdi-basic013.adoc index f70eecda..f553efa5 100644 --- a/src/main/asciidoc/cdi-basic/cdi-basic013.adoc +++ b/src/main/antora/modules/cdi/pages/cdi-basic/cdi-basic013.adoc @@ -1,12 +1,12 @@ == Configuring a CDI Application When your beans are annotated with a scope type, the server recognizes the application as a bean archive and no additional configuration is required. -The possible scope types for CDI beans are listed in <>. +The possible scope types for CDI beans are listed in xref:cdi-basic/cdi-basic.adoc#_using_scopes[Using Scopes]. CDI uses an optional deployment descriptor named `beans.xml`. Like other Jakarta EE deployment descriptors, the configuration settings in `beans.xml` are used in addition to annotation settings in CDI classes. The settings in `beans.xml` override the annotation settings if there is a conflict. -An archive must contain the `beans.xml` deployment descriptor only in certain limited situations, described in xref:jakarta-contexts-and-dependency-injection-advanced-topics[xrefstyle=full]. +An archive must contain the `beans.xml` deployment descriptor only in certain limited situations, described in xref:cdi-adv/cdi-adv.adoc#_jakarta_contexts_and_dependency_injection_advanced_topics[Jakarta Contexts and Dependency Injection: Advanced Topics]. For a web application, the `beans.xml` deployment descriptor, if present, must be in the `WEB-INF` directory. For EJB modules or JAR files, the `beans.xml` deployment descriptor, if present, must be in the `META-INF` directory. diff --git a/src/main/asciidoc/cdi-basic/cdi-basic014.adoc b/src/main/antora/modules/cdi/pages/cdi-basic/cdi-basic014.adoc similarity index 90% rename from src/main/asciidoc/cdi-basic/cdi-basic014.adoc rename to src/main/antora/modules/cdi/pages/cdi-basic/cdi-basic014.adoc index e9c6a439..03935de9 100644 --- a/src/main/asciidoc/cdi-basic/cdi-basic014.adoc +++ b/src/main/antora/modules/cdi/pages/cdi-basic/cdi-basic014.adoc @@ -16,7 +16,7 @@ When the managed bean is injected into a component, CDI calls the method after a [NOTE] As mandated in Jakarta Annotations, if the annotated method is declared in a superclass, the method is called unless a subclass of the declaring class overrides the method. -The `UserNumberBean` managed bean in <> uses `@PostConstruct` to annotate a method that resets all bean fields: +The `UserNumberBean` managed bean in xref:cdi-basicexamples/cdi-basicexamples.adoc#_the_guessnumber_cdi_cdi_example[The guessnumber-cdi CDI Example] uses `@PostConstruct` to annotate a method that resets all bean fields: [source,java] ---- diff --git a/src/main/asciidoc/cdi-basic/cdi-basic015.adoc b/src/main/antora/modules/cdi/pages/cdi-basic/cdi-basic015.adoc similarity index 100% rename from src/main/asciidoc/cdi-basic/cdi-basic015.adoc rename to src/main/antora/modules/cdi/pages/cdi-basic/cdi-basic015.adoc diff --git a/src/main/asciidoc/cdi-basicexamples/cdi-basicexamples.adoc b/src/main/antora/modules/cdi/pages/cdi-basicexamples/cdi-basicexamples.adoc similarity index 86% rename from src/main/asciidoc/cdi-basicexamples/cdi-basicexamples.adoc rename to src/main/antora/modules/cdi/pages/cdi-basicexamples/cdi-basicexamples.adoc index f88dbf95..4d526d36 100644 --- a/src/main/asciidoc/cdi-basicexamples/cdi-basicexamples.adoc +++ b/src/main/antora/modules/cdi/pages/cdi-basicexamples/cdi-basicexamples.adoc @@ -1,5 +1,7 @@ = Running the Basic Contexts and Dependency Injection Examples +include::ROOT:partial$not_updated.adoc[] + This chapter describes in detail how to build and run simple examples that use CDI. include::cdi-basicexamples001.adoc[] diff --git a/src/main/asciidoc/cdi-basicexamples/cdi-basicexamples001.adoc b/src/main/antora/modules/cdi/pages/cdi-basicexamples/cdi-basicexamples001.adoc similarity index 52% rename from src/main/asciidoc/cdi-basicexamples/cdi-basicexamples001.adoc rename to src/main/antora/modules/cdi/pages/cdi-basicexamples/cdi-basicexamples001.adoc index 9acdf995..6bd84ee9 100644 --- a/src/main/asciidoc/cdi-basicexamples/cdi-basicexamples001.adoc +++ b/src/main/antora/modules/cdi/pages/cdi-basicexamples/cdi-basicexamples001.adoc @@ -1,6 +1,6 @@ == Building and Running the CDI Samples -The examples are in the `_tut-install_/examples/cdi/` directory. +The examples are in the `_jakartaee-examples_/tutorial/cdi/` directory. To build and run the examples, you will do the following: @@ -10,4 +10,4 @@ To build and run the examples, you will do the following: . Run the example in a web browser. -See xref:using-the-tutorial-examples[xrefstyle=full], for basic information on installing, building, and running the examples. +See xref:intro:usingexamples/usingexamples.adoc#_using_the_tutorial_examples[Using the Tutorial Examples], for basic information on installing, building, and running the examples. diff --git a/src/main/asciidoc/cdi-basicexamples/cdi-basicexamples002.adoc b/src/main/antora/modules/cdi/pages/cdi-basicexamples/cdi-basicexamples002.adoc similarity index 58% rename from src/main/asciidoc/cdi-basicexamples/cdi-basicexamples002.adoc rename to src/main/antora/modules/cdi/pages/cdi-basicexamples/cdi-basicexamples002.adoc index f760250c..58598078 100644 --- a/src/main/asciidoc/cdi-basicexamples/cdi-basicexamples002.adoc +++ b/src/main/antora/modules/cdi/pages/cdi-basicexamples/cdi-basicexamples002.adoc @@ -8,13 +8,13 @@ The example includes four source files, a Facelets page and template, and config The four source files for the `simplegreeting` example are: -* The default `Greeting` class, shown in <> +* The default `Greeting` class, shown in xref:cdi-basic/cdi-basic.adoc#_beans_as_injectable_objects[Beans as Injectable Objects] -* The `@Informal` qualifier interface definition and the `InformalGreeting` class that implements the interface, both shown in <> +* The `@Informal` qualifier interface definition and the `InformalGreeting` class that implements the interface, both shown in xref:cdi-basic/cdi-basic.adoc#_using_qualifiers[Using Qualifiers] -* The `Printer` managed bean class, which injects one of the two interfaces, shown in full in <> +* The `Printer` managed bean class, which injects one of the two interfaces, shown in full in xref:cdi-basic/cdi-basic.adoc#_adding_setter_and_getter_methods[Adding Setter and Getter Methods] -The source files are located in the `_tut-install_/examples/cdi/simplegreeting/src/main/java/ee/jakarta/tutorial/simplegreeting` directory. +The source files are located in the `_jakartaee-examples_/tutorial/cdi/simplegreeting/src/main/java/jakarta/tutorial/simplegreeting` directory. === The Facelets Template and Page @@ -22,38 +22,33 @@ To use the managed bean in a simple Facelets application: . Use a very simple template file and `index.xhtml` page. + -The template page, `template.xhtml`, looks like this: +The template page, `/WEB-INF/templates/template.xhtml`, looks like this: + [source,xml] ---- - - + - - <ui:insert name="title">Default Title</ui:insert> + - - -
- - -
-

-
- -
- -
-
- + +
+
+

+ + Default Header + +

+
+ +
+ +
+
+ ---- @@ -61,29 +56,32 @@ The template page, `template.xhtml`, looks like this: + [source,xml] ---- - - - - - - Simple Greeting - Simple Greeting - - -

-

-

-

- - - - - + + Simple Greeting + + +
+ + +
+
+ + + +
+
+

+ +

+
+ + + ---- + The form asks the user to enter a name. @@ -99,12 +97,12 @@ Hello, name. Hi, name! ---- + -The Facelets page and template are located in the `_tut-install_/examples/cdi/simplegreeting/src/main/webapp/` directory. +The Facelets page and template are located in the `_jakartaee-examples_/tutorial/cdi/simplegreeting/src/main/webapp/` directory. + The simple CSS file that is used by the Facelets page is in the following location: + ---- -tut-install/examples/cdi/simplegreeting/src/main/webapp/resources/css/default.css +jakartaee-examples/tutorial/cdi/simplegreeting/src/main/webapp/resources/css/default.css ---- === Running the simplegreeting Example @@ -113,14 +111,14 @@ You can use either NetBeans IDE or Maven to build, package, deploy, and run the ==== To Build, Package, and Run the simplegreeting Example Using NetBeans IDE -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . From the *File* menu, choose *Open Project*. . In the *Open Project* dialog box, navigate to: + ---- -tut-install/examples/cdi +jakartaee-examples/tutorial/cdi ---- . Select the `simplegreeting` folder. @@ -152,12 +150,12 @@ This command builds and packages the application into a WAR file, `simplegreetin ==== To Build, Package, and Deploy the simplegreeting Example Using Maven -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . In a terminal window, go to: + ---- -tut-install/examples/cdi/simplegreeting/ +jakartaee-examples/tutorial/cdi/simplegreeting/ ---- . Enter the following command to deploy the application: diff --git a/src/main/asciidoc/cdi-basicexamples/cdi-basicexamples003.adoc b/src/main/antora/modules/cdi/pages/cdi-basicexamples/cdi-basicexamples003.adoc similarity index 64% rename from src/main/asciidoc/cdi-basicexamples/cdi-basicexamples003.adoc rename to src/main/antora/modules/cdi/pages/cdi-basicexamples/cdi-basicexamples003.adoc index 6fbdfdb3..89537a0e 100644 --- a/src/main/asciidoc/cdi-basicexamples/cdi-basicexamples003.adoc +++ b/src/main/antora/modules/cdi/pages/cdi-basicexamples/cdi-basicexamples003.adoc @@ -2,7 +2,7 @@ The `guessnumber-cdi` example, somewhat more complex than the `simplegreeting` example, illustrates the use of producer methods and of session and application scope. The example is a game in which you try to guess a number in fewer than ten attempts. -It is similar to the `guessnumber-faces` example described in xref:introduction-to-facelets[xrefstyle=full], except that you can keep guessing until you get the right answer or until you use up your ten attempts. +It is similar to the `guessnumber-faces` example described in xref:web:faces-facelets/faces-facelets.adoc#_introduction_to_facelets[Introduction to Facelets], except that you can keep guessing until you get the right answer or until you use up your ten attempts. The example includes four source files, a Facelets page and template, and configuration files. The configuration files and the template are the same as those used for the `simplegreeting` example. @@ -19,7 +19,7 @@ The four source files for the `guessnumber-cdi` example are: * The `UserNumberBean` managed bean -The source files are located in the `_tut-install_/examples/cdi/guessnumber-cdi/src/main/java/ee/jakarta/tutorial/guessnumber` directory. +The source files are located in the `_jakartaee-examples_/tutorial/cdi/guessnumber-cdi/src/main/java/jakarta/tutorial/guessnumber` directory. ==== The @MaxNumber and @Random Qualifier Interfaces @@ -87,7 +87,7 @@ import jakarta.enterprise.inject.Produces; @ApplicationScoped public class Generator implements Serializable { - private static final long serialVersionUID = -7213673465118041882L; + private static final long serialVersionUID = 1L; private final java.util.Random random = new java.util.Random( System.currentTimeMillis() ); @@ -132,7 +132,7 @@ package guessnumber; import java.io.Serializable; import jakarta.annotation.PostConstruct; -import jakarta.enterprise.context.SessionScoped; +import jakarta.faces.view.ViewScoped; import jakarta.enterprise.inject.Instance; import jakarta.faces.application.FacesMessage; import jakarta.faces.component.UIComponent; @@ -142,10 +142,10 @@ import jakarta.inject.Inject; import jakarta.inject.Named; @Named -@SessionScoped +@ViewScoped public class UserNumberBean implements Serializable { - private static final long serialVersionUID = -7698506329160109476L; + private static final long serialVersionUID = 1L; private int number; private Integer userNumber; @@ -162,42 +162,16 @@ public class UserNumberBean implements Serializable { @Inject Instance randomInt; - public UserNumberBean() { - } - - public int getNumber() { - return number; - } - - public void setUserNumber(Integer user_number) { - userNumber = user_number; - } - - public Integer getUserNumber() { - return userNumber; - } - - public int getMaximum() { - return (this.maximum); - } - - public void setMaximum(int maximum) { - this.maximum = maximum; - } - - public int getMinimum() { - return (this.minimum); - } - - public void setMinimum(int minimum) { - this.minimum = minimum; - } - - public int getRemainingGuesses() { - return remainingGuesses; + @PostConstruct + public void init() { + minimum = 0; + userNumber = 0; + remainingGuesses = 10; + maximum = maxNumber; + number = randomInt.get(); } - public String check() throws InterruptedException { + public void check() { if (userNumber > number) { maximum = userNumber - 1; } @@ -209,16 +183,10 @@ public class UserNumberBean implements Serializable { new FacesMessage("Correct!")); } remainingGuesses--; - return null; } - @PostConstruct public void reset() { - this.minimum = 0; - this.userNumber = 0; - this.remainingGuesses = 10; - this.maximum = maxNumber; - this.number = randomInt.get(); + init(); } public void validateNumberRange(FacesContext context, @@ -227,12 +195,30 @@ public class UserNumberBean implements Serializable { int input = (Integer) value; if (input < minimum || input > maximum) { - ((UIInput) toValidate).setValid(false); - - FacesMessage message = new FacesMessage("Invalid guess"); - context.addMessage(toValidate.getClientId(context), message); + throw new ValidatorException(new FacesMessage("Invalid guess")); } } + + public void setUserNumber(Integer userNumber) { + this.userNumber = userNumber; + } + + public Integer getUserNumber() { + return userNumber; + } + + public int getMaximum() { + return maximum; + } + + public int getMinimum() { + return minimum; + } + + public int getRemainingGuesses() { + return remainingGuesses; + } + } ---- @@ -243,59 +229,64 @@ The `index.xhtml` file, however, is more complex. [source,xml] ---- - - - - - - Guess My Number - Guess My Number - - -
-

I'm thinking of a number from - #{userNumberBean.minimum} - to - #{userNumberBean.maximum}. - You have - - #{userNumberBean.remainingGuesses} - - guesses.

-
- - Number: - - - - - - - -
- -
- - - - - + + Guess My Number + + +

+ I'm thinking of a number from #{userNumberBean.minimum} + to #{userNumberBean.maximum}. You have + + guesses. +

+
+ + +
+
+ + + + + + +
+ + + + + + + + ---- The Facelets page presents the user with the minimum and maximum values and the number of guesses remaining. @@ -309,7 +300,7 @@ You can use either NetBeans IDE or Maven to build, package, deploy, and run the ==== To Build, Package, and Deploy the guessnumber-cdi Example Using NetBeans IDE -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . From the *File* menu, choose *Open Project*. @@ -317,7 +308,7 @@ You can use either NetBeans IDE or Maven to build, package, deploy, and run the + [source,java] ---- -tut-install/examples/cdi +jakartaee-examples/tutorial/cdi ---- . Select the `guessnumber-cdi` folder. @@ -330,13 +321,13 @@ This command builds and packages the application into a WAR file, `guessnumber-c ==== To Build, Package, and Deploy the guessnumber-cdi Example Using Maven -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . In a terminal window, change to the following directory: + [source,java] ---- -tut-install/examples/cdi/guessnumber-cdi/ +jakartaee-examples/tutorial/cdi/guessnumber-cdi/ ---- . Enter the following command to deploy the application: diff --git a/src/main/asciidoc/cdi-bootstrap-se8/cdi-bootstrap-se8.adoc b/src/main/antora/modules/cdi/pages/cdi-bootstrap-se8/cdi-bootstrap-se8.adoc similarity index 100% rename from src/main/asciidoc/cdi-bootstrap-se8/cdi-bootstrap-se8.adoc rename to src/main/antora/modules/cdi/pages/cdi-bootstrap-se8/cdi-bootstrap-se8.adoc diff --git a/src/main/asciidoc/cdi-bootstrap-se8/cdi-bootstrap-se8001.adoc b/src/main/antora/modules/cdi/pages/cdi-bootstrap-se8/cdi-bootstrap-se8001.adoc similarity index 100% rename from src/main/asciidoc/cdi-bootstrap-se8/cdi-bootstrap-se8001.adoc rename to src/main/antora/modules/cdi/pages/cdi-bootstrap-se8/cdi-bootstrap-se8001.adoc diff --git a/src/main/asciidoc/cdi-bootstrap-se8/cdi-bootstrap-se8002.adoc b/src/main/antora/modules/cdi/pages/cdi-bootstrap-se8/cdi-bootstrap-se8002.adoc similarity index 100% rename from src/main/asciidoc/cdi-bootstrap-se8/cdi-bootstrap-se8002.adoc rename to src/main/antora/modules/cdi/pages/cdi-bootstrap-se8/cdi-bootstrap-se8002.adoc diff --git a/src/main/antora/modules/common/images/Figure_10_1.vsd b/src/main/antora/modules/common/images/Figure_10_1.vsd new file mode 100644 index 00000000..89e97244 Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_10_1.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_10_2.vsd b/src/main/antora/modules/common/images/Figure_10_2.vsd new file mode 100644 index 00000000..95c3a6cc Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_10_2.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_10_3.vsd b/src/main/antora/modules/common/images/Figure_10_3.vsd new file mode 100644 index 00000000..a2021d79 Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_10_3.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_10_4.vsd b/src/main/antora/modules/common/images/Figure_10_4.vsd new file mode 100644 index 00000000..448476d5 Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_10_4.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_16_1.vsd b/src/main/antora/modules/common/images/Figure_16_1.vsd new file mode 100644 index 00000000..a266f7ee Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_16_1.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_18_1.vsd b/src/main/antora/modules/common/images/Figure_18_1.vsd new file mode 100644 index 00000000..ba3b54c9 Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_18_1.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_31_1.vsd b/src/main/antora/modules/common/images/Figure_31_1.vsd new file mode 100644 index 00000000..5570781b Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_31_1.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_35_1.vsd b/src/main/antora/modules/common/images/Figure_35_1.vsd new file mode 100644 index 00000000..e8d3ef1d Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_35_1.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_35_2.vsd b/src/main/antora/modules/common/images/Figure_35_2.vsd new file mode 100644 index 00000000..07bce8c8 Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_35_2.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_35_3.vsd b/src/main/antora/modules/common/images/Figure_35_3.vsd new file mode 100644 index 00000000..c1c9d43a Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_35_3.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_35_4.vsd b/src/main/antora/modules/common/images/Figure_35_4.vsd new file mode 100644 index 00000000..a8020482 Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_35_4.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_41_1.vsd b/src/main/antora/modules/common/images/Figure_41_1.vsd new file mode 100644 index 00000000..e04832c0 Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_41_1.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_41_2.vsd b/src/main/antora/modules/common/images/Figure_41_2.vsd new file mode 100644 index 00000000..007e61e9 Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_41_2.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_48_1.vsd b/src/main/antora/modules/common/images/Figure_48_1.vsd new file mode 100644 index 00000000..0d3a530c Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_48_1.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_48_2.vsd b/src/main/antora/modules/common/images/Figure_48_2.vsd new file mode 100644 index 00000000..405898a4 Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_48_2.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_48_3.vsd b/src/main/antora/modules/common/images/Figure_48_3.vsd new file mode 100644 index 00000000..2b769aba Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_48_3.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_48_4.vsd b/src/main/antora/modules/common/images/Figure_48_4.vsd new file mode 100644 index 00000000..162c8471 Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_48_4.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_48_5.vsd b/src/main/antora/modules/common/images/Figure_48_5.vsd new file mode 100644 index 00000000..784c188f Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_48_5.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_48_6.vsd b/src/main/antora/modules/common/images/Figure_48_6.vsd new file mode 100644 index 00000000..e51cb0c8 Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_48_6.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_48_7.vsd b/src/main/antora/modules/common/images/Figure_48_7.vsd new file mode 100644 index 00000000..3219ca30 Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_48_7.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_48_8.vsd b/src/main/antora/modules/common/images/Figure_48_8.vsd new file mode 100644 index 00000000..c5002e5d Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_48_8.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_49_1.vsd b/src/main/antora/modules/common/images/Figure_49_1.vsd new file mode 100644 index 00000000..211a9224 Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_49_1.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_49_2.vsd b/src/main/antora/modules/common/images/Figure_49_2.vsd new file mode 100644 index 00000000..e20fc6da Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_49_2.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_49_3.vsd b/src/main/antora/modules/common/images/Figure_49_3.vsd new file mode 100644 index 00000000..a8a151aa Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_49_3.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_49_4.vsd b/src/main/antora/modules/common/images/Figure_49_4.vsd new file mode 100644 index 00000000..a515391d Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_49_4.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_49_5.vsd b/src/main/antora/modules/common/images/Figure_49_5.vsd new file mode 100644 index 00000000..3e0ac43c Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_49_5.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_50_1.vsd b/src/main/antora/modules/common/images/Figure_50_1.vsd new file mode 100644 index 00000000..c9dd63dc Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_50_1.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_50_2.vsd b/src/main/antora/modules/common/images/Figure_50_2.vsd new file mode 100644 index 00000000..9a8962e2 Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_50_2.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_50_3.vsd b/src/main/antora/modules/common/images/Figure_50_3.vsd new file mode 100644 index 00000000..a006831a Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_50_3.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_50_4.vsd b/src/main/antora/modules/common/images/Figure_50_4.vsd new file mode 100644 index 00000000..cebf7551 Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_50_4.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_50_5.vsd b/src/main/antora/modules/common/images/Figure_50_5.vsd new file mode 100644 index 00000000..53858f2e Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_50_5.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_50_6.vsd b/src/main/antora/modules/common/images/Figure_50_6.vsd new file mode 100644 index 00000000..4de922c2 Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_50_6.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_51_1.vsd b/src/main/antora/modules/common/images/Figure_51_1.vsd new file mode 100644 index 00000000..a8855aad Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_51_1.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_51_2.vsd b/src/main/antora/modules/common/images/Figure_51_2.vsd new file mode 100644 index 00000000..e5501e65 Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_51_2.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_52_1.vsd b/src/main/antora/modules/common/images/Figure_52_1.vsd new file mode 100644 index 00000000..42d4b781 Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_52_1.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_53_1.vsd b/src/main/antora/modules/common/images/Figure_53_1.vsd new file mode 100644 index 00000000..66f79dd6 Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_53_1.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_53_2.vsd b/src/main/antora/modules/common/images/Figure_53_2.vsd new file mode 100644 index 00000000..1a2d7865 Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_53_2.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_54_1.vsd b/src/main/antora/modules/common/images/Figure_54_1.vsd new file mode 100644 index 00000000..f63edeb0 Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_54_1.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_54_2.vsd b/src/main/antora/modules/common/images/Figure_54_2.vsd new file mode 100644 index 00000000..ccd8a4bc Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_54_2.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_54_3.vsd b/src/main/antora/modules/common/images/Figure_54_3.vsd new file mode 100644 index 00000000..c22fef92 Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_54_3.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_55_1.vsd b/src/main/antora/modules/common/images/Figure_55_1.vsd new file mode 100644 index 00000000..e5931a64 Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_55_1.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_56_1.vsd b/src/main/antora/modules/common/images/Figure_56_1.vsd new file mode 100644 index 00000000..4e4cd3d7 Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_56_1.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_56_2.vsd b/src/main/antora/modules/common/images/Figure_56_2.vsd new file mode 100644 index 00000000..51810cee Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_56_2.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_56_3.vsd b/src/main/antora/modules/common/images/Figure_56_3.vsd new file mode 100644 index 00000000..398a000a Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_56_3.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_56_4.vsd b/src/main/antora/modules/common/images/Figure_56_4.vsd new file mode 100644 index 00000000..db799d26 Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_56_4.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_58_1.vsd b/src/main/antora/modules/common/images/Figure_58_1.vsd new file mode 100644 index 00000000..c20222fa Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_58_1.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_58_2.vsd b/src/main/antora/modules/common/images/Figure_58_2.vsd new file mode 100644 index 00000000..ad3d786e Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_58_2.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_59_1.vsd b/src/main/antora/modules/common/images/Figure_59_1.vsd new file mode 100644 index 00000000..5a0a193d Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_59_1.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_5_1.vsd b/src/main/antora/modules/common/images/Figure_5_1.vsd new file mode 100644 index 00000000..a49119e4 Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_5_1.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_5_2.vsd b/src/main/antora/modules/common/images/Figure_5_2.vsd new file mode 100644 index 00000000..4405eaa9 Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_5_2.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_5_3.vsd b/src/main/antora/modules/common/images/Figure_5_3.vsd new file mode 100644 index 00000000..724dfe35 Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_5_3.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_61_1.vsd b/src/main/antora/modules/common/images/Figure_61_1.vsd new file mode 100644 index 00000000..64b8892b Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_61_1.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_62_1.vsd b/src/main/antora/modules/common/images/Figure_62_1.vsd new file mode 100644 index 00000000..7325729f Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_62_1.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_62_2.vsd b/src/main/antora/modules/common/images/Figure_62_2.vsd new file mode 100644 index 00000000..3824bf49 Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_62_2.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_62_3.vsd b/src/main/antora/modules/common/images/Figure_62_3.vsd new file mode 100644 index 00000000..01f86b80 Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_62_3.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_6_1.vsd b/src/main/antora/modules/common/images/Figure_6_1.vsd new file mode 100644 index 00000000..964e20e3 Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_6_1.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_7_1.vsd b/src/main/antora/modules/common/images/Figure_7_1.vsd new file mode 100644 index 00000000..a291cc78 Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_7_1.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_7_2.vsd b/src/main/antora/modules/common/images/Figure_7_2.vsd new file mode 100644 index 00000000..1dfe6e63 Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_7_2.vsd differ diff --git a/src/main/antora/modules/common/images/Figure_7_3.vsd b/src/main/antora/modules/common/images/Figure_7_3.vsd new file mode 100644 index 00000000..44987670 Binary files /dev/null and b/src/main/antora/modules/common/images/Figure_7_3.vsd differ diff --git a/src/main/asciidoc/images/eclipse_foundation_logo_tiny.png b/src/main/antora/modules/common/images/eclipse_foundation_logo_tiny.png similarity index 100% rename from src/main/asciidoc/images/eclipse_foundation_logo_tiny.png rename to src/main/antora/modules/common/images/eclipse_foundation_logo_tiny.png diff --git a/src/main/asciidoc/images/jakartaeett_dt_010.svg b/src/main/antora/modules/common/images/jakartaeett_dt_010.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_010.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_010.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_011.svg b/src/main/antora/modules/common/images/jakartaeett_dt_011.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_011.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_011.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_012.svg b/src/main/antora/modules/common/images/jakartaeett_dt_012.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_012.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_012.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_013.svg b/src/main/antora/modules/common/images/jakartaeett_dt_013.svg similarity index 99% rename from src/main/asciidoc/images/jakartaeett_dt_013.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_013.svg index 09834bdd..aae9804a 100644 --- a/src/main/asciidoc/images/jakartaeett_dt_013.svg +++ b/src/main/antora/modules/common/images/jakartaeett_dt_013.svg @@ -117,12 +117,11 @@ Foglio.13 - JavaBeans Components + Beans - JavaBeans Components + Beans Foglio.20 Database diff --git a/src/main/asciidoc/images/jakartaeett_dt_014.svg b/src/main/antora/modules/common/images/jakartaeett_dt_014.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_014.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_014.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_015.svg b/src/main/antora/modules/common/images/jakartaeett_dt_015.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_015.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_015.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_016.svg b/src/main/antora/modules/common/images/jakartaeett_dt_016.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_016.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_016.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_017.svg b/src/main/antora/modules/common/images/jakartaeett_dt_017.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_017.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_017.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_018.svg b/src/main/antora/modules/common/images/jakartaeett_dt_018.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_018.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_018.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_019.svg b/src/main/antora/modules/common/images/jakartaeett_dt_019.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_019.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_019.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_020.svg b/src/main/antora/modules/common/images/jakartaeett_dt_020.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_020.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_020.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_021.svg b/src/main/antora/modules/common/images/jakartaeett_dt_021.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_021.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_021.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_022.svg b/src/main/antora/modules/common/images/jakartaeett_dt_022.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_022.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_022.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_023.svg b/src/main/antora/modules/common/images/jakartaeett_dt_023.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_023.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_023.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_024.svg b/src/main/antora/modules/common/images/jakartaeett_dt_024.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_024.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_024.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_025.svg b/src/main/antora/modules/common/images/jakartaeett_dt_025.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_025.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_025.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_026.svg b/src/main/antora/modules/common/images/jakartaeett_dt_026.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_026.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_026.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_027.svg b/src/main/antora/modules/common/images/jakartaeett_dt_027.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_027.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_027.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_028.svg b/src/main/antora/modules/common/images/jakartaeett_dt_028.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_028.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_028.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_029.svg b/src/main/antora/modules/common/images/jakartaeett_dt_029.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_029.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_029.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_030.svg b/src/main/antora/modules/common/images/jakartaeett_dt_030.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_030.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_030.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_031.svg b/src/main/antora/modules/common/images/jakartaeett_dt_031.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_031.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_031.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_032.svg b/src/main/antora/modules/common/images/jakartaeett_dt_032.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_032.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_032.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_033.svg b/src/main/antora/modules/common/images/jakartaeett_dt_033.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_033.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_033.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_034.svg b/src/main/antora/modules/common/images/jakartaeett_dt_034.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_034.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_034.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_035.svg b/src/main/antora/modules/common/images/jakartaeett_dt_035.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_035.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_035.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_036.svg b/src/main/antora/modules/common/images/jakartaeett_dt_036.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_036.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_036.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_037.svg b/src/main/antora/modules/common/images/jakartaeett_dt_037.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_037.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_037.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_038.svg b/src/main/antora/modules/common/images/jakartaeett_dt_038.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_038.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_038.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_039.svg b/src/main/antora/modules/common/images/jakartaeett_dt_039.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_039.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_039.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_040.svg b/src/main/antora/modules/common/images/jakartaeett_dt_040.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_040.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_040.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_041.svg b/src/main/antora/modules/common/images/jakartaeett_dt_041.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_041.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_041.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_042.svg b/src/main/antora/modules/common/images/jakartaeett_dt_042.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_042.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_042.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_043.svg b/src/main/antora/modules/common/images/jakartaeett_dt_043.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_043.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_043.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_044.svg b/src/main/antora/modules/common/images/jakartaeett_dt_044.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_044.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_044.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_045.svg b/src/main/antora/modules/common/images/jakartaeett_dt_045.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_045.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_045.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_046.svg b/src/main/antora/modules/common/images/jakartaeett_dt_046.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_046.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_046.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_047.svg b/src/main/antora/modules/common/images/jakartaeett_dt_047.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_047.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_047.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_048.svg b/src/main/antora/modules/common/images/jakartaeett_dt_048.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_048.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_048.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_049.svg b/src/main/antora/modules/common/images/jakartaeett_dt_049.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_049.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_049.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_050.svg b/src/main/antora/modules/common/images/jakartaeett_dt_050.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_050.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_050.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_051.svg b/src/main/antora/modules/common/images/jakartaeett_dt_051.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_051.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_051.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_052.svg b/src/main/antora/modules/common/images/jakartaeett_dt_052.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_052.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_052.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_053.svg b/src/main/antora/modules/common/images/jakartaeett_dt_053.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_053.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_053.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_054.svg b/src/main/antora/modules/common/images/jakartaeett_dt_054.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_054.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_054.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_055.svg b/src/main/antora/modules/common/images/jakartaeett_dt_055.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_055.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_055.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_056.svg b/src/main/antora/modules/common/images/jakartaeett_dt_056.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_056.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_056.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_057.svg b/src/main/antora/modules/common/images/jakartaeett_dt_057.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_057.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_057.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_058.svg b/src/main/antora/modules/common/images/jakartaeett_dt_058.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_058.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_058.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_059.svg b/src/main/antora/modules/common/images/jakartaeett_dt_059.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_059.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_059.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_060.svg b/src/main/antora/modules/common/images/jakartaeett_dt_060.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_060.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_060.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_061.svg b/src/main/antora/modules/common/images/jakartaeett_dt_061.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_061.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_061.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_062.svg b/src/main/antora/modules/common/images/jakartaeett_dt_062.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_062.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_062.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_063.svg b/src/main/antora/modules/common/images/jakartaeett_dt_063.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_063.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_063.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_064.svg b/src/main/antora/modules/common/images/jakartaeett_dt_064.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_064.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_064.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_065_frmcmpnt.svg b/src/main/antora/modules/common/images/jakartaeett_dt_065_frmcmpnt.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_065_frmcmpnt.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_065_frmcmpnt.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_066_slctmny.svg b/src/main/antora/modules/common/images/jakartaeett_dt_066_slctmny.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_066_slctmny.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_066_slctmny.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_067_slctn.svg b/src/main/antora/modules/common/images/jakartaeett_dt_067_slctn.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_067_slctn.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_067_slctn.svg diff --git a/src/main/asciidoc/images/jakartaeett_dt_068_txtcmpnts.svg b/src/main/antora/modules/common/images/jakartaeett_dt_068_txtcmpnts.svg similarity index 100% rename from src/main/asciidoc/images/jakartaeett_dt_068_txtcmpnts.svg rename to src/main/antora/modules/common/images/jakartaeett_dt_068_txtcmpnts.svg diff --git a/src/main/antora/modules/entbeans/nav.adoc b/src/main/antora/modules/entbeans/nav.adoc new file mode 100644 index 00000000..e433f871 --- /dev/null +++ b/src/main/antora/modules/entbeans/nav.adoc @@ -0,0 +1,4 @@ +.Enterprise Beans + +* xref:ejb-embedded/ejb-embedded.adoc[] + diff --git a/src/main/asciidoc/ejb-async/ejb-async.adoc b/src/main/antora/modules/entbeans/pages/ejb-async/ejb-async.adoc similarity index 85% rename from src/main/asciidoc/ejb-async/ejb-async.adoc rename to src/main/antora/modules/entbeans/pages/ejb-async/ejb-async.adoc index 873796a4..ca7a7c59 100644 --- a/src/main/asciidoc/ejb-async/ejb-async.adoc +++ b/src/main/antora/modules/entbeans/pages/ejb-async/ejb-async.adoc @@ -1,5 +1,7 @@ = Using Asynchronous Method Invocation in Session Beans +include::ROOT:partial$not_updated.adoc[] + This chapter discusses how to implement asynchronous business methods in session beans and call them from enterprise bean clients. include::ejb-async001.adoc[] diff --git a/src/main/asciidoc/ejb-async/ejb-async001.adoc b/src/main/antora/modules/entbeans/pages/ejb-async/ejb-async001.adoc similarity index 100% rename from src/main/asciidoc/ejb-async/ejb-async001.adoc rename to src/main/antora/modules/entbeans/pages/ejb-async/ejb-async001.adoc diff --git a/src/main/asciidoc/ejb-async/ejb-async002.adoc b/src/main/antora/modules/entbeans/pages/ejb-async/ejb-async002.adoc similarity index 93% rename from src/main/asciidoc/ejb-async/ejb-async002.adoc rename to src/main/antora/modules/entbeans/pages/ejb-async/ejb-async002.adoc index f06c3591..60c05815 100644 --- a/src/main/asciidoc/ejb-async/ejb-async002.adoc +++ b/src/main/antora/modules/entbeans/pages/ejb-async/ejb-async002.adoc @@ -79,14 +79,14 @@ You can use either NetBeans IDE or Maven to build, package, deploy, and run the ==== To Run the async Example Application Using NetBeans IDE -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . From the *File* menu, choose *Open Project*. . In the *Open Project* dialog box, navigate to: + ---- -tut-install/examples/ejb +jakartaee-examples/tutorial/ejb ---- . Select the `async` folder, select *Open Required Projects*, and click *Open Project*. @@ -127,12 +127,12 @@ The async-smptd output window in NetBeans IDE shows the resulting email message, ==== To Run the async Example Application Using Maven -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . In a terminal window, go to: + ---- -tut-install/examples/ejb/async/async-smtpd/ +jakartaee-examples/tutorial/ejb/async/async-smtpd/ ---- . Enter the following command to build and package the SMTP server simulator: @@ -160,7 +160,7 @@ Keep this terminal window open. . In a new terminal window, go to: + ---- -tut-install/examples/ejb/async/async-war +jakartaee-examples/tutorial/ejb/async/async-war ---- . Enter the following command to configure the Jakarta Mail resource and to build, package, and deploy the `async-war` module: diff --git a/src/main/asciidoc/ejb-basicexamples/ejb-basicexamples.adoc b/src/main/antora/modules/entbeans/pages/ejb-basicexamples/ejb-basicexamples.adoc similarity index 92% rename from src/main/asciidoc/ejb-basicexamples/ejb-basicexamples.adoc rename to src/main/antora/modules/entbeans/pages/ejb-basicexamples/ejb-basicexamples.adoc index 1361091b..8bdbce7e 100644 --- a/src/main/asciidoc/ejb-basicexamples/ejb-basicexamples.adoc +++ b/src/main/antora/modules/entbeans/pages/ejb-basicexamples/ejb-basicexamples.adoc @@ -1,5 +1,7 @@ = Running the Enterprise Bean Examples +include::ROOT:partial$not_updated.adoc[] + This chapter describes the Jakarta Enterprise Beans examples. Session beans provide a simple but powerful way to encapsulate business logic within an application. They can be accessed from remote Java clients, web service clients, and components running in the same server. diff --git a/src/main/asciidoc/ejb-basicexamples/ejb-basicexamples001.adoc b/src/main/antora/modules/entbeans/pages/ejb-basicexamples/ejb-basicexamples001.adoc similarity index 67% rename from src/main/asciidoc/ejb-basicexamples/ejb-basicexamples001.adoc rename to src/main/antora/modules/entbeans/pages/ejb-basicexamples/ejb-basicexamples001.adoc index 2276c82a..dc7ee509 100644 --- a/src/main/asciidoc/ejb-basicexamples/ejb-basicexamples001.adoc +++ b/src/main/antora/modules/entbeans/pages/ejb-basicexamples/ejb-basicexamples001.adoc @@ -1,6 +1,6 @@ == Overview of the Jakarta Enterprise Beans Examples -In xref:getting-started-with-enterprise-beans[xrefstyle=full], you built a stateless session bean named `ConverterBean`. +In xref:ejb-gettingstarted/ejb-gettingstarted.adoc#_getting_started_with_enterprise_beans[Getting Started with Enterprise Beans], you built a stateless session bean named `ConverterBean`. This chapter examines the source code of four more session beans: * `CartBean`: a stateful session bean that is accessed by a remote client diff --git a/src/main/asciidoc/ejb-basicexamples/ejb-basicexamples002.adoc b/src/main/antora/modules/entbeans/pages/ejb-basicexamples/ejb-basicexamples002.adoc similarity index 94% rename from src/main/asciidoc/ejb-basicexamples/ejb-basicexamples002.adoc rename to src/main/antora/modules/entbeans/pages/ejb-basicexamples/ejb-basicexamples002.adoc index c647af75..66aea407 100644 --- a/src/main/asciidoc/ejb-basicexamples/ejb-basicexamples002.adoc +++ b/src/main/antora/modules/entbeans/pages/ejb-basicexamples/ejb-basicexamples002.adoc @@ -11,9 +11,9 @@ To assemble `cart`, you need the following code: All session beans require a session bean class. All enterprise beans that permit remote access must have a remote business interface. To meet the needs of a specific application, an enterprise bean may also need some helper classes. -The `CartBean` session bean uses two helper classes, `BookException` and `IdVerifier`, which are discussed in the section <>. +The `CartBean` session bean uses two helper classes, `BookException` and `IdVerifier`, which are discussed in the section <<_helper_classes>>. -The source code for this example is in the `_tut-install_/examples/ejb/cart/` directory. +The source code for this example is in the `_jakartaee-examples_/tutorial/ejb/cart/` directory. === The Business Interface @@ -254,14 +254,14 @@ You can use either NetBeans IDE or Maven to build, package, deploy, and run the ==== To Run the cart Example Using NetBeans IDE -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . From the *File* menu, choose *Open Project*. . In the *Open Project* dialog box, navigate to: + ---- -tut-install/examples/ejb +jakartaee-examples/tutorial/ejb ---- . Select the `cart` folder. @@ -272,7 +272,7 @@ tut-install/examples/ejb . In the *Projects* tab, right-click the `cart` project and select *Build*. + -This builds and packages the application into `cart.ear`, located in `_tut-install_/examples/ejb/cart/cart-ear/target/`, and deploys this EAR file to your GlassFish Server instance. +This builds and packages the application into `cart.ear`, located in `_jakartaee-examples_/tutorial/ejb/cart/cart-ear/target/`, and deploys this EAR file to your GlassFish Server instance. + You will see the output of the `cart-app-client` application client in the Output tab: + @@ -288,12 +288,12 @@ Caught a BookException: "Gravity's Rainbow" not in cart. ==== To Run the cart Example Using Maven . Make sure that GlassFish Server has been started (see -<>). +xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . In a terminal window, go to: + ---- -tut-install/examples/ejb/cart/ +jakartaee-examples/tutorial/ejb/cart/ ---- . Enter the following command: diff --git a/src/main/asciidoc/ejb-basicexamples/ejb-basicexamples003.adoc b/src/main/antora/modules/entbeans/pages/ejb-basicexamples/ejb-basicexamples003.adoc similarity index 96% rename from src/main/asciidoc/ejb-basicexamples/ejb-basicexamples003.adoc rename to src/main/antora/modules/entbeans/pages/ejb-basicexamples/ejb-basicexamples003.adoc index dc03942f..e2b95d57 100644 --- a/src/main/asciidoc/ejb-basicexamples/ejb-basicexamples003.adoc +++ b/src/main/antora/modules/entbeans/pages/ejb-basicexamples/ejb-basicexamples003.adoc @@ -312,7 +312,7 @@ public class Count implements Serializable { ---- The `template.xhtml` and `index.xhtml` files are used to render a Facelets view that displays the number of hits to that view. -The `index.xhtml` file uses an expression language statement, `#{count.hitCount}`, to access the `hitCount` property of the `Count` managed bean. +The `index.xhtml` file uses an expression language statement, `#{count.hitCount}`, to access the `hitCount` property of the `Count` managed bean. Here is the content of `index.xhtml`: [source,xml] @@ -338,14 +338,14 @@ You can use either NetBeans IDE or Maven to build, package, deploy, and run the ==== To Run the counter Example Using NetBeans IDE -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . From the *File* menu, choose *Open Project*. . In the *Open Project* dialog box, navigate to: + ---- -tut-install/examples/ejb +jakartaee-examples/tutorial/ejb ---- . Select the `counter` folder. @@ -360,12 +360,12 @@ A web browser will open the URL http://localhost:8080/counter[^], which displays ==== To Run the counter Example Using Maven -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . In a terminal window, go to: + ---- -tut-install/examples/ejb/counter/ +jakartaee-examples/tutorial/ejb/counter/ ---- . Enter the following command: diff --git a/src/main/asciidoc/ejb-basicexamples/ejb-basicexamples004.adoc b/src/main/antora/modules/entbeans/pages/ejb-basicexamples/ejb-basicexamples004.adoc similarity index 81% rename from src/main/asciidoc/ejb-basicexamples/ejb-basicexamples004.adoc rename to src/main/antora/modules/entbeans/pages/ejb-basicexamples/ejb-basicexamples004.adoc index 5099fb44..12c515c9 100644 --- a/src/main/asciidoc/ejb-basicexamples/ejb-basicexamples004.adoc +++ b/src/main/antora/modules/entbeans/pages/ejb-basicexamples/ejb-basicexamples004.adoc @@ -2,7 +2,8 @@ This example demonstrates a simple web service that generates a response based on information received from the client. `HelloServiceBean` is a stateless session bean that implements a single method: `sayHello`. -This method matches the `sayHello` method invoked by the client described in <>. +This method matches the `sayHello` method invoked by the client described in "A Simple XML Web Services Application Client" +(xref:9.1@websvcs:jaxws/jaxws.adoc#_a_simple_xml_web_services_application_client[available in a previous version of the tutorial,window=_blank]↗). === The Web Service Endpoint Implementation Class @@ -19,7 +20,7 @@ If no `endpointInterface` is specified in `@WebService`, an SEI is implicitly de * Business methods that are exposed to web service clients must be annotated with `jakarta.jws.WebMethod`. * Business methods that are exposed to web service clients must have Jakarta XML Binding-compatible parameters and return types. -See the list of Jakarta XML Binding default data type bindings at <>. +See the list of Jakarta XML Binding default data type bindings at "Types Supported by XML Web Services" (xref:9.1@websvcs:jaxws/jaxws.adoc#_types_supported_by_xml_web_services[available in a previous version of the tutorial,window=_blank]↗). * The implementing class must not be declared `final` and must not be `abstract`. @@ -69,14 +70,14 @@ You can then use the Administration Console to test the web service endpoint met ==== To Build, Package, and Deploy the helloservice Example Using NetBeans IDE -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . From the *File* menu, choose *Open Project*. . In the *Open Project* dialog box, navigate to: + ---- -tut-install/examples/ejb +jakartaee-examples/tutorial/ejb ---- . Select the `helloservice` folder. @@ -85,16 +86,16 @@ tut-install/examples/ejb . In the *Projects* tab, right-click the `helloservice` project and select *Build*. + -This builds and packages the application into `helloservice.ear`, located in `_tut-install_/examples/ejb/helloservice/target/`, and deploys this EAR file to GlassFish Server. +This builds and packages the application into `helloservice.ear`, located in `_jakartaee-examples_/tutorial/ejb/helloservice/target/`, and deploys this EAR file to GlassFish Server. ==== To Build, Package, and Deploy the helloservice Example Using Maven -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . In a terminal window, go to: + ---- -tut-install/examples/ejb/helloservice/ +jakartaee-examples/tutorial/ejb/helloservice/ ---- . Enter the following command: @@ -104,7 +105,7 @@ tut-install/examples/ejb/helloservice/ mvn install ---- + -This compiles the source files and packages the application into an enterprise bean JAR file located at `_tut-install_/examples/ejb/helloservice/target/helloservice.jar`. +This compiles the source files and packages the application into an enterprise bean JAR file located at `_jakartaee-examples_/tutorial/ejb/helloservice/target/helloservice.jar`. Then the enterprise bean JAR file is deployed to GlassFish Server. + Upon deployment, GlassFish Server generates additional artifacts required for web service invocation, including the WSDL file. @@ -127,7 +128,7 @@ http://localhost:4848/ . In the *Modules and Components* table, click the *View Endpoint* link. -. On the *Web Service Endpoint Information* page, click the *Tester* link: +. On the *Web Service Endpoint Information* page, click the *Tester* xref: + ---- /HelloServiceBeanService/HelloServiceBean?Tester diff --git a/src/main/asciidoc/ejb-basicexamples/ejb-basicexamples005.adoc b/src/main/antora/modules/entbeans/pages/ejb-basicexamples/ejb-basicexamples005.adoc similarity index 93% rename from src/main/asciidoc/ejb-basicexamples/ejb-basicexamples005.adoc rename to src/main/antora/modules/entbeans/pages/ejb-basicexamples/ejb-basicexamples005.adoc index 51b442d3..5cdee123 100644 --- a/src/main/asciidoc/ejb-basicexamples/ejb-basicexamples005.adoc +++ b/src/main/antora/modules/entbeans/pages/ejb-basicexamples/ejb-basicexamples005.adoc @@ -12,9 +12,9 @@ Automatic timers are created upon the successful deployment of an enterprise bea === Creating Calendar-Based Timer Expressions Timers can be set according to a calendar-based schedule, expressed using a syntax similar to the UNIX `cron` utility. -Both programmatic and automatic timers can use calendar-based timer expressions. <> shows the calendar-based timer attributes. +Both programmatic and automatic timers can use calendar-based timer expressions. <<_calendar_based_timer_attributes>> shows the calendar-based timer attributes. -[[calendar-based-timer-attributes]] +[[_calendar_based_timer_attributes]] .Calendar-Based Timer Attributes [width="99%",cols="15%,35%,15%,35%"] |=== @@ -213,7 +213,7 @@ Timer timer = timerService.createSingleActionTimer(date, new TimerConfig()); ---- For calendar-based timers, the expiration of the timer is expressed as a `jakarta.ejb.ScheduleExpression` object, passed as a parameter to the `TimerService.createCalendarTimer` method. -The `ScheduleExpression` class represents calendar-based timer expressions and has methods that correspond to the attributes described in <>. +The `ScheduleExpression` class represents calendar-based timer expressions and has methods that correspond to the attributes described in <<_creating_calendar_based_timer_expressions>>. The following code creates a programmatic timer using the `ScheduleExpression` helper class: @@ -227,7 +227,7 @@ Timer timer = timerService.createCalendarTimer(schedule); For details on the method signatures, see the `TimerService` API documentation at https://jakarta.ee/specifications/platform/9/apidocs/jakarta/ejb/TimerService.html[^]. -The bean described in <> creates a timer as follows: +The bean described in <<_the_timersession_example>> creates a timer as follows: [source,java] ---- @@ -256,7 +256,7 @@ Automatic timers can be configured through annotations or through the `ejb-jar.x Adding a `@Schedule` annotation on an enterprise bean marks that method as a timeout method according to the calendar schedule specified in the attributes of `@Schedule`. -The `@Schedule` annotation has elements that correspond to the calendar expressions detailed in <> and the `persistent`, `info`, and `timezone` elements. +The `@Schedule` annotation has elements that correspond to the calendar expressions detailed in <<_creating_calendar_based_timer_expressions>> and the `persistent`, `info`, and `timezone` elements. The optional `persistent` element takes a Boolean value and is used to specify whether the automatic timer should survive a server restart or crash. By default, all automatic timers are persistent. @@ -338,7 +338,7 @@ If the transaction is rolled back, the container will call the `@Timeout` method === The timersession Example -The source code for this example is in the `_tut-install_/examples/ejb/timersession/src/main/java/` directory. +The source code for this example is in the `_jakartaee-examples_/tutorial/ejb/timersession/src/main/java/` directory. `TimerSessionBean` is a singleton session bean that shows how to set both an automatic timer and a programmatic timer. In the source code listing of `TimerSessionBean` that follows, the `setTimer` and `@Timeout` methods are used to set a programmatic timer. @@ -476,14 +476,14 @@ You can use either NetBeans IDE or Maven to build, package, deploy, and run the ==== To Run the timersession Example Using NetBeans IDE -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . From the *File* menu, choose *Open Project*. . In the *Open Project* dialog box, navigate to: + ---- -tut-install/examples/ejb +jakartaee-examples/tutorial/ejb ---- . Select the `timersession` folder. @@ -492,16 +492,16 @@ tut-install/examples/ejb . From the *Run* menu, choose *Run Project*. + -This builds and packages the application into a WAR file located at `_tut-install_/examples/ejb/timersession/target/timersession.war`, deploys this WAR file to your GlassFish Server instance, and then runs the web client. +This builds and packages the application into a WAR file located at `_jakartaee-examples_/tutorial/ejb/timersession/target/timersession.war`, deploys this WAR file to your GlassFish Server instance, and then runs the web client. ==== To Build, Package, and Deploy the timersession Example Using Maven -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . In a terminal window, go to: + ---- -tut-install/examples/ejb/timersession/ +jakartaee-examples/tutorial/ejb/timersession/ ---- . Enter the following command: @@ -511,7 +511,7 @@ tut-install/examples/ejb/timersession/ mvn install ---- + -This builds and packages the application into a WAR file located at `_tut-install_/examples/ejb/timersession/target/timersession.war` and deploys this WAR file to your GlassFish Server instance. +This builds and packages the application into a WAR file located at `_jakartaee-examples_/tutorial/ejb/timersession/target/timersession.war` and deploys this WAR file to your GlassFish Server instance. ==== To Run the Web Client diff --git a/src/main/asciidoc/ejb-basicexamples/ejb-basicexamples006.adoc b/src/main/antora/modules/entbeans/pages/ejb-basicexamples/ejb-basicexamples006.adoc similarity index 100% rename from src/main/asciidoc/ejb-basicexamples/ejb-basicexamples006.adoc rename to src/main/antora/modules/entbeans/pages/ejb-basicexamples/ejb-basicexamples006.adoc diff --git a/src/main/antora/modules/entbeans/pages/ejb-full/ejb-full.adoc b/src/main/antora/modules/entbeans/pages/ejb-full/ejb-full.adoc new file mode 100644 index 00000000..aadc50b4 --- /dev/null +++ b/src/main/antora/modules/entbeans/pages/ejb-full/ejb-full.adoc @@ -0,0 +1,5 @@ += Jakarta Enterprise Beans Full + +You can find information about Jakarta Enterprise Beans Full in a previous version of the tutorial: + +*** xref:9.1@entbeans:ejb-embedded/ejb-embedded.adoc[window=_blank]↗ diff --git a/src/main/asciidoc/ejb-gettingstarted/ejb-gettingstarted.adoc b/src/main/antora/modules/entbeans/pages/ejb-gettingstarted/ejb-gettingstarted.adoc similarity index 92% rename from src/main/asciidoc/ejb-gettingstarted/ejb-gettingstarted.adoc rename to src/main/antora/modules/entbeans/pages/ejb-gettingstarted/ejb-gettingstarted.adoc index 79b30e34..26033ad5 100644 --- a/src/main/asciidoc/ejb-gettingstarted/ejb-gettingstarted.adoc +++ b/src/main/antora/modules/entbeans/pages/ejb-gettingstarted/ejb-gettingstarted.adoc @@ -1,5 +1,7 @@ = Getting Started with Enterprise Beans +include::ROOT:partial$not_updated.adoc[] + This chapter shows how to develop, deploy, and run a simple Jakarta EE application named `converter` that uses an enterprise bean for its business logic. The purpose of `converter` is to calculate currency conversions among Japanese yen, euros, and US dollars. The `converter` application consists of an enterprise bean, which performs the calculations, and a web client. diff --git a/src/main/antora/modules/entbeans/pages/ejb-gettingstarted/ejb-gettingstarted001.adoc b/src/main/antora/modules/entbeans/pages/ejb-gettingstarted/ejb-gettingstarted001.adoc new file mode 100644 index 00000000..09dd34fc --- /dev/null +++ b/src/main/antora/modules/entbeans/pages/ejb-gettingstarted/ejb-gettingstarted001.adoc @@ -0,0 +1,19 @@ +== Starting With Enterprise Beans + +Here's an overview of the steps you'll follow: + +. Create the enterprise bean: `ConverterBean`. + +. Create the web client. + +. Deploy `converter` onto the server. + +. Using a browser, run the web client. + +Before proceeding, make sure that you've done the following: + +* Read xref:intro:overview/overview.adoc#_overview[Overview] + +* Become familiar with enterprise beans (see xref:ejb-intro/ejb-intro.adoc#_enterprise_beans[Enterprise Beans]) + +* Started the server (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]) diff --git a/src/main/asciidoc/ejb-gettingstarted/ejb-gettingstarted002.adoc b/src/main/antora/modules/entbeans/pages/ejb-gettingstarted/ejb-gettingstarted002.adoc similarity index 85% rename from src/main/asciidoc/ejb-gettingstarted/ejb-gettingstarted002.adoc rename to src/main/antora/modules/entbeans/pages/ejb-gettingstarted/ejb-gettingstarted002.adoc index fb683422..b9836ea2 100644 --- a/src/main/asciidoc/ejb-gettingstarted/ejb-gettingstarted002.adoc +++ b/src/main/antora/modules/entbeans/pages/ejb-gettingstarted/ejb-gettingstarted002.adoc @@ -1,7 +1,7 @@ == Creating the Enterprise Bean The enterprise bean in our example is a stateless session bean called `ConverterBean`. -The source code for `ConverterBean` is in the `_tut-install_/examples/ejb/converter/src/main/java/` directory. +The source code for `ConverterBean` is in the `_jakartaee-examples_/tutorial/ejb/converter/src/main/java/` directory. Creating `ConverterBean` requires these steps: @@ -46,7 +46,7 @@ This annotation lets the container know that `ConverterBean` is a stateless sess === Creating the converter Web Client -The web client is contained in the following servlet class under the `_tut-install_/examples/ejb/converter/src/main/java/` directory: +The web client is contained in the following servlet class under the `_jakartaee-examples_/tutorial/ejb/converter/src/main/java/` directory: ---- converter/web/ConverterServlet.java @@ -100,14 +100,14 @@ You can use either NetBeans IDE or Maven to build, package, deploy, and run the ==== To Run the converter Example Using NetBeans IDE -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . From the *File* menu, choose *Open Project*. . In the *Open Project* dialog box, navigate to: + ---- -tut-install/examples/ejb +jakartaee-examples/tutorial/ejb ---- . Select the `converter` folder. @@ -128,12 +128,12 @@ A second page opens, showing the converted values. ==== To Run the converter Example Using Maven -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . In a terminal window, go to: + ---- -tut-install/examples/ejb/converter/ +jakartaee-examples/tutorial/ejb/converter/ ---- . Enter the following command: @@ -144,7 +144,7 @@ mvn install ---- + This command compiles the source files for the enterprise bean and the servlet, packages the project into a WAR module (`converter.war`), and deploys the WAR to the server. -For more information about Maven, see <>. +For more information about Maven, see xref:intro:usingexamples/usingexamples.adoc#_building_the_examples[Building the Examples]. . Open a web browser to the following URL: + diff --git a/src/main/asciidoc/ejb-gettingstarted/ejb-gettingstarted003.adoc b/src/main/antora/modules/entbeans/pages/ejb-gettingstarted/ejb-gettingstarted003.adoc similarity index 91% rename from src/main/asciidoc/ejb-gettingstarted/ejb-gettingstarted003.adoc rename to src/main/antora/modules/entbeans/pages/ejb-gettingstarted/ejb-gettingstarted003.adoc index 2c779249..ba987c4e 100644 --- a/src/main/asciidoc/ejb-gettingstarted/ejb-gettingstarted003.adoc +++ b/src/main/antora/modules/entbeans/pages/ejb-gettingstarted/ejb-gettingstarted003.adoc @@ -20,7 +20,7 @@ This recompiles the `ConverterBean.java` file, replaces the old class file in th .. Recompile `ConverterBean.java` using Maven. -... In a terminal window, go to the `_tut-install_/examples/ejb/converter/` directory. +... In a terminal window, go to the `_jakartaee-examples_/tutorial/ejb/converter/` directory. ... Enter the following command: + diff --git a/src/main/asciidoc/ejb-intro/ejb-intro.adoc b/src/main/antora/modules/entbeans/pages/ejb-intro/ejb-intro.adoc similarity index 82% rename from src/main/asciidoc/ejb-intro/ejb-intro.adoc rename to src/main/antora/modules/entbeans/pages/ejb-intro/ejb-intro.adoc index 4dc9e3a0..50824103 100644 --- a/src/main/asciidoc/ejb-intro/ejb-intro.adoc +++ b/src/main/antora/modules/entbeans/pages/ejb-intro/ejb-intro.adoc @@ -1,7 +1,9 @@ = Enterprise Beans +include::ROOT:partial$not_updated.adoc[] + Enterprise beans are Jakarta EE components that implement Jakarta Enterprise Beans technology. -Enterprise beans run in the Enterprise Bean container, a runtime environment within GlassFish Server (see <>). +Enterprise beans run in the Enterprise Bean container, a runtime environment within GlassFish Server (see xref:intro:overview/overview.adoc#_container_types[Container Types]). Although transparent to the application developer, the Enterprise Bean container provides system-level services, such as transactions and security, to its enterprise beans. These services enable you to quickly build and deploy enterprise beans, which form the core of transactional Jakarta EE applications. diff --git a/src/main/asciidoc/ejb-intro/ejb-intro001.adoc b/src/main/antora/modules/entbeans/pages/ejb-intro/ejb-intro001.adoc similarity index 96% rename from src/main/asciidoc/ejb-intro/ejb-intro001.adoc rename to src/main/antora/modules/entbeans/pages/ejb-intro/ejb-intro001.adoc index 1eedc409..04214970 100644 --- a/src/main/asciidoc/ejb-intro/ejb-intro001.adoc +++ b/src/main/antora/modules/entbeans/pages/ejb-intro/ejb-intro001.adoc @@ -35,10 +35,10 @@ These clients can be thin, various, and numerous. === Types of Enterprise Beans -<> summarizes the two types of enterprise beans. +<<_enterprise_bean_types>> summarizes the two types of enterprise beans. The following sections discuss each type in more detail. -[[enterprise-bean-types]] +[[_enterprise_bean_types]] .Enterprise Bean Types [width="75%",cols="35%,65%"] |=== diff --git a/src/main/asciidoc/ejb-intro/ejb-intro002.adoc b/src/main/antora/modules/entbeans/pages/ejb-intro/ejb-intro002.adoc similarity index 97% rename from src/main/asciidoc/ejb-intro/ejb-intro002.adoc rename to src/main/antora/modules/entbeans/pages/ejb-intro/ejb-intro002.adoc index f12b60bc..56708610 100644 --- a/src/main/asciidoc/ejb-intro/ejb-intro002.adoc +++ b/src/main/antora/modules/entbeans/pages/ejb-intro/ejb-intro002.adoc @@ -7,7 +7,7 @@ The session bean performs work for its client, shielding it from complexity by e A session bean is not persistent. (That is, its data is not saved to a database.) -For code samples, see xref:running-the-enterprise-bean-examples[xrefstyle=full]. +For code samples, see xref:ejb-basicexamples/ejb-basicexamples.adoc#_running_the_enterprise_bean_examples[Running the Enterprise Bean Examples]. === Types of Session Beans diff --git a/src/main/asciidoc/ejb-intro/ejb-intro003.adoc b/src/main/antora/modules/entbeans/pages/ejb-intro/ejb-intro003.adoc similarity index 89% rename from src/main/asciidoc/ejb-intro/ejb-intro003.adoc rename to src/main/antora/modules/entbeans/pages/ejb-intro/ejb-intro003.adoc index 72fe6bbc..4f0278d4 100644 --- a/src/main/asciidoc/ejb-intro/ejb-intro003.adoc +++ b/src/main/antora/modules/entbeans/pages/ejb-intro/ejb-intro003.adoc @@ -8,7 +8,7 @@ Message-driven beans can process Jakarta Messaging messages or other kinds of me === What Makes Message-Driven Beans Different from Session Beans? The most visible difference between message-driven beans and session beans is that clients do not access message-driven beans through interfaces. -Interfaces are described in the section <>. +Interfaces are described in the section xref:ejb-intro/ejb-intro.adoc#_accessing_enterprise_beans[Accessing Enterprise Beans]. Unlike a session bean, a message-driven bean has only a bean class. In several respects, a message-driven bean resembles a stateless session bean. @@ -46,7 +46,7 @@ The `onMessage` method can call helper methods or can invoke a session bean to p A message can be delivered to a message-driven bean within a transaction context, so all operations within the `onMessage` method are part of a single transaction. If message processing is rolled back, the message will be redelivered. -For more information, see <> and xref:transactions[xrefstyle=full]. +For more information, see xref:messaging:jms-examples/jms-examples.adoc#_receiving_messages_asynchronously_using_a_message_driven_bean[Receiving Messages Asynchronously Using a Message-Driven Bean] and xref:supporttechs:transactions/transactions.adoc#_transactions[Transactions]. === When to Use Message-Driven Beans diff --git a/src/main/asciidoc/ejb-intro/ejb-intro004.adoc b/src/main/antora/modules/entbeans/pages/ejb-intro/ejb-intro004.adoc similarity index 95% rename from src/main/asciidoc/ejb-intro/ejb-intro004.adoc rename to src/main/antora/modules/entbeans/pages/ejb-intro/ejb-intro004.adoc index ad168422..28f9a3b5 100644 --- a/src/main/asciidoc/ejb-intro/ejb-intro004.adoc +++ b/src/main/antora/modules/entbeans/pages/ejb-intro/ejb-intro004.adoc @@ -225,11 +225,11 @@ public class BeanName implements InterfaceName { ... } The remote interface defines the business and lifecycle methods that are specific to the bean. For example, the remote interface of a bean named `BankAccountBean` might have business methods named `deposit` and `credit`. -<> shows how the interface controls the client's view of an enterprise bean. +<<_interfaces_for_an_enterprise_bean_with_remote_access>> shows how the interface controls the client's view of an enterprise bean. -[[interfaces-for-an-enterprise-bean-with-remote-access]] +[[_interfaces_for_an_enterprise_bean_with_remote_access]] .Interfaces for an Enterprise Bean with Remote Access -image::jakartaeett_dt_020.svg["Diagram showing a remote client accessing an enterprise bean's methods through its remote interface."] +image::common:jakartaeett_dt_020.svg["Diagram showing a remote client accessing an enterprise bean's methods through its remote interface."] Client access to an enterprise bean that implements a remote business interface is accomplished through either dependency injection or JNDI lookup. @@ -253,7 +253,7 @@ ExampleRemote example = (ExampleRemote) A web service client can access a Jakarta EE application in two ways. First, the client can access a web service created with Jakarta XML Web Services. -(For more information on Jakarta XML Web Services, see xref:building-web-services-with-jakarta-xml-web-services[xrefstyle=full].) +(For more information on Jakarta XML Web Services, see "Building Web Services with Jakarta XML Web Services", xref:9.1@websvcs:jaxws/jaxws.adoc#_building_web_services_with_jakarta_xml_web_services[available in a previous version of the tutorial,window=_blank]↗.) Second, a web service client can invoke the business methods of a stateless session bean. Message beans cannot be accessed by web service clients. @@ -267,7 +267,7 @@ By default, all public methods in the bean class are accessible to web service c The `@WebMethod` annotation may be used to customize the behavior of web service methods. If the `@WebMethod` annotation is used to decorate the bean class's methods, only those methods decorated with `@WebMethod` are exposed to web service clients. -For a code sample, see <>. +For a code sample, see xref:ejb-basicexamples/ejb-basicexamples.adoc#_a_web_service_example_helloservice[A Web Service Example: helloservice]. === Method Parameters and Access diff --git a/src/main/asciidoc/ejb-intro/ejb-intro005.adoc b/src/main/antora/modules/entbeans/pages/ejb-intro/ejb-intro005.adoc similarity index 69% rename from src/main/asciidoc/ejb-intro/ejb-intro005.adoc rename to src/main/antora/modules/entbeans/pages/ejb-intro/ejb-intro005.adoc index 9235d111..5d6e43fa 100644 --- a/src/main/asciidoc/ejb-intro/ejb-intro005.adoc +++ b/src/main/antora/modules/entbeans/pages/ejb-intro/ejb-intro005.adoc @@ -10,4 +10,4 @@ A business interface is not required if the enterprise bean exposes a local, no- * Helper classes: Other classes needed by the enterprise bean class, such as exception and utility classes. Package the programming artifacts in the preceding list either into an Enterprise Bean JAR file (a stand-alone module that stores the enterprise bean) or within a web application archive (WAR) module. -See <> and <> for more information. +See xref:platform:packaging/packaging.adoc#_packaging_enterprise_beans_in_enterprise_bean_jar_modules[Packaging Enterprise Beans in enterprise bean JAR Modules] and xref:platform:packaging/packaging.adoc#_packaging_enterprise_beans_in_war_modules[Packaging Enterprise Beans in WAR Modules] for more information. diff --git a/src/main/asciidoc/ejb-intro/ejb-intro006.adoc b/src/main/antora/modules/entbeans/pages/ejb-intro/ejb-intro006.adoc similarity index 72% rename from src/main/asciidoc/ejb-intro/ejb-intro006.adoc rename to src/main/antora/modules/entbeans/pages/ejb-intro/ejb-intro006.adoc index 025a844c..c57804f0 100644 --- a/src/main/asciidoc/ejb-intro/ejb-intro006.adoc +++ b/src/main/antora/modules/entbeans/pages/ejb-intro/ejb-intro006.adoc @@ -1,9 +1,9 @@ == Naming Conventions for Enterprise Beans Because enterprise beans are composed of multiple parts, it's useful to follow a naming convention for your applications. -<> summarizes the conventions for the example beans in this tutorial. +<<_naming_conventions_for_enterprise_beans_2>> summarizes the conventions for the example beans in this tutorial. -[[naming-conventions-for-enterprise-beans-2]] +[[_naming_conventions_for_enterprise_beans_2]] .Naming Conventions for Enterprise Beans [width="63%",cols="40%,30%,30%"] |=== diff --git a/src/main/asciidoc/ejb-intro/ejb-intro007.adoc b/src/main/antora/modules/entbeans/pages/ejb-intro/ejb-intro007.adoc similarity index 78% rename from src/main/asciidoc/ejb-intro/ejb-intro007.adoc rename to src/main/antora/modules/entbeans/pages/ejb-intro/ejb-intro007.adoc index cbdf76ac..9bc6ccf5 100644 --- a/src/main/asciidoc/ejb-intro/ejb-intro007.adoc +++ b/src/main/antora/modules/entbeans/pages/ejb-intro/ejb-intro007.adoc @@ -8,14 +8,14 @@ If you are new to enterprise beans, you should skip this section and run the cod === The Lifecycle of a Stateful Session Bean -<> illustrates the stages that a stateful session bean passes through during its lifetime. +<<_lifecycle_of_a_stateful_session_bean>> illustrates the stages that a stateful session bean passes through during its lifetime. The client initiates the lifecycle by obtaining a reference to a stateful session bean. The container performs any dependency injection and then invokes the method annotated with `@PostConstruct`, if any. The bean is now ready to have its business methods invoked by the client. -[[lifecycle-of-a-stateful-session-bean]] +[[_lifecycle_of_a_stateful_session_bean]] .Lifecycle of a Stateful Session Bean -image::jakartaeett_dt_021.svg["Diagram showing the lifecycle of a stateful session bean."] +image::common:jakartaeett_dt_021.svg["Diagram showing the lifecycle of a stateful session bean."] While in the ready stage, the Enterprise Bean container may decide to deactivate, or passivate, the bean by moving it from memory to secondary storage. (Typically, the Enterprise Bean container uses a least-recently-used algorithm to select a bean for passivation.) @@ -26,17 +26,17 @@ At the end of the lifecycle, the client invokes a method annotated `@Remove`, an The bean's instance is then ready for garbage collection. Your code controls the invocation of only one lifecycle method: the method annotated `@Remove`. -All other methods in <> are invoked by the Enterprise Bean container. -See xref:resource-adapters-and-contracts[xrefstyle=full] for more information. +All other methods in <<_lifecycle_of_a_stateful_session_bean>> are invoked by the Enterprise Bean container. +See xref:supporttechs:resources/resources.adoc#_resource_adapters_and_contracts[Resource Adapters and Contracts] for more information. === The Lifecycle of a Stateless Session Bean Because a stateless session bean is never passivated, its lifecycle has only two stages: nonexistent and ready for the invocation of business methods. -<> illustrates the stages of a stateless session bean. +<<_lifecycle_of_a_stateless_or_singleton_session_bean>> illustrates the stages of a stateless session bean. -[[lifecycle-of-a-stateless-or-singleton-session-bean]] +[[_lifecycle_of_a_stateless_or_singleton_session_bean]] .Lifecycle of a Stateless or Singleton Session Bean -image::jakartaeett_dt_022.svg["Diagram showing the lifecycle of a stateless or singleton session bean."] +image::common:jakartaeett_dt_022.svg["Diagram showing the lifecycle of a stateless or singleton session bean."] The Enterprise Bean container typically creates and maintains a pool of stateless session beans, beginning the stateless session bean's lifecycle. The container performs any dependency injection and then invokes the method annotated `@PostConstruct`, if it exists. @@ -47,7 +47,7 @@ The bean's instance is then ready for garbage collection. === The Lifecycle of a Singleton Session Bean -Like a stateless session bean, a singleton session bean is never passivated and has only two stages, nonexistent and ready for the invocation of business methods, as shown in <>. +Like a stateless session bean, a singleton session bean is never passivated and has only two stages, nonexistent and ready for the invocation of business methods, as shown in <<_lifecycle_of_a_stateless_or_singleton_session_bean>>. The Enterprise Bean container initiates the singleton session bean lifecycle by creating the singleton instance. This occurs upon application deployment if the singleton is annotated with the `@Startup` annotation. @@ -59,11 +59,11 @@ The singleton session bean is now ready for garbage collection. === The Lifecycle of a Message-Driven Bean -<> illustrates the stages in the lifecycle of a message-driven bean. +<<_lifecycle_of_a_message_driven_bean>> illustrates the stages in the lifecycle of a message-driven bean. -[[lifecycle-of-a-message-driven-bean]] +[[_lifecycle_of_a_message_driven_bean]] .Lifecycle of a Message-Driven Bean -image::jakartaeett_dt_023.svg["Diagram showing the lifecycle of a message-driven bean."] +image::common:jakartaeett_dt_023.svg["Diagram showing the lifecycle of a message-driven bean."] The Enterprise Bean container usually creates a pool of message-driven bean instances. For each instance, the Enterprise Bean container performs these tasks. diff --git a/src/main/asciidoc/ejb-intro/ejb-intro008.adoc b/src/main/antora/modules/entbeans/pages/ejb-intro/ejb-intro008.adoc similarity index 100% rename from src/main/asciidoc/ejb-intro/ejb-intro008.adoc rename to src/main/antora/modules/entbeans/pages/ejb-intro/ejb-intro008.adoc diff --git a/src/main/antora/modules/intro/images/container-services.drawio b/src/main/antora/modules/intro/images/container-services.drawio new file mode 100644 index 00000000..4bb302b8 --- /dev/null +++ b/src/main/antora/modules/intro/images/container-services.drawio @@ -0,0 +1,19 @@ + + + + + + + + + + + + + + + + + + + diff --git a/src/main/antora/modules/intro/images/container-services.svg b/src/main/antora/modules/intro/images/container-services.svg new file mode 100644 index 00000000..ba61cec0 --- /dev/null +++ b/src/main/antora/modules/intro/images/container-services.svg @@ -0,0 +1,4 @@ + + + +















Jakarta EE Server or
Executable "fat" JAR file
Jakarta EE Server or...









Container (Web, CDI, Enterprise Bean services)
Container (Web, CDI, Enterpr...
Application Code
Application C...Text is not SVG - cannot display \ No newline at end of file diff --git a/src/main/antora/modules/intro/images/container-services.vsdx b/src/main/antora/modules/intro/images/container-services.vsdx new file mode 100644 index 00000000..73edf31b Binary files /dev/null and b/src/main/antora/modules/intro/images/container-services.vsdx differ diff --git a/src/main/antora/modules/intro/images/multitier-app.drawio b/src/main/antora/modules/intro/images/multitier-app.drawio new file mode 100644 index 00000000..315d7154 --- /dev/null +++ b/src/main/antora/modules/intro/images/multitier-app.drawio @@ -0,0 +1,117 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/main/antora/modules/intro/images/multitier-app.svg b/src/main/antora/modules/intro/images/multitier-app.svg new file mode 100644 index 00000000..f50bcda1 --- /dev/null +++ b/src/main/antora/modules/intro/images/multitier-app.svg @@ -0,0 +1,4 @@ + + + +















Jakarta EE Server or
Executable "fat" JAR file
Jakarta EE Server or...









Container (Web, CDI, Enterprise Bean services)
Container (Web, CDI, Enterprise Bean services)...
Application 1
Application 1
Data Store
Data Store
Client
(Web Service, Browser, so on)
Client...
Application 2
Application 2
Application 2
Application 2















Jakarta EE Server or
Executable "fat" JAR file
Jakarta EE Server or...









Container (Web, CDI, Enterprise Bean services)
Container (Web, CDI, Enterpr...
Application
Application















Jakarta EE Server or
Executable "fat" JAR file
Jakarta EE Server or...









Container (Web, CDI, Enterprise Bean services)
Container (Web, CDI, Enterpr...
Application
Application
Data Store
Data Store
Messaging Server
Messaging ServerText is not SVG - cannot display \ No newline at end of file diff --git a/src/main/antora/modules/intro/images/multitier-app.vsdx b/src/main/antora/modules/intro/images/multitier-app.vsdx new file mode 100644 index 00000000..1a30ab7c Binary files /dev/null and b/src/main/antora/modules/intro/images/multitier-app.vsdx differ diff --git a/src/main/antora/modules/intro/images/simple-app.drawio b/src/main/antora/modules/intro/images/simple-app.drawio new file mode 100644 index 00000000..1b3c635b --- /dev/null +++ b/src/main/antora/modules/intro/images/simple-app.drawio @@ -0,0 +1,41 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/main/antora/modules/intro/images/simple-app.svg b/src/main/antora/modules/intro/images/simple-app.svg new file mode 100644 index 00000000..f2a6d263 --- /dev/null +++ b/src/main/antora/modules/intro/images/simple-app.svg @@ -0,0 +1,4 @@ + + + +















Jakarta EE Server or
Executable "fat" JAR file
Jakarta EE Server or...









Container (Web, CDI, Enterprise Bean services)
Container (Web, CDI, Enterpr...
Application Code
Application C...
Data Store
Data Store
Client
(Web Service, Browser, so on)
Client...Text is not SVG - cannot display \ No newline at end of file diff --git a/src/main/antora/modules/intro/images/simple-app.vsdx b/src/main/antora/modules/intro/images/simple-app.vsdx new file mode 100644 index 00000000..1d04fb22 Binary files /dev/null and b/src/main/antora/modules/intro/images/simple-app.vsdx differ diff --git a/src/main/antora/modules/intro/nav.adoc b/src/main/antora/modules/intro/nav.adoc new file mode 100644 index 00000000..66bdc9b3 --- /dev/null +++ b/src/main/antora/modules/intro/nav.adoc @@ -0,0 +1,5 @@ +.Introduction + +* xref:overview/overview.adoc[] + +* xref:usingexamples/usingexamples.adoc[] diff --git a/src/main/antora/modules/intro/pages/overview/overview-containers.adoc b/src/main/antora/modules/intro/pages/overview/overview-containers.adoc new file mode 100644 index 00000000..1a3a7274 --- /dev/null +++ b/src/main/antora/modules/intro/pages/overview/overview-containers.adoc @@ -0,0 +1,45 @@ +== Jakarta EE Containers and Servers + +The services we discussed in <<_jakarta_ee_services>> section are provided by *container{empty}footnote:[Technically, there are multiple containers (Web, CDI, Enterprise Beans), but the distinction about which container is providing the services isn't terribly important. Jakarta EE also supports an Application Client container for Java clients, but this is rarely used. ]*. +A *Jakarta EE Server* is software that runs the container, deploys applications into it, and provides administration and additional features. +Jakarta EE Servers run stand-alone, but many implementations also support the ability to generate a single "fat", +executable Java Archive (JAR) file that includes all the code necessary to run the application. + +.Jakarta EE Containers vs Docker Containers +**** +_Container_ is a commonly used term in computing, but it basically means "that which holds something". +In the case of Jakarta EE, the container "holds," or more accurately, +executes your code and provides low-level application services, +such as dependency injection, transactions, HTTP request handling, REST support, and so on. +In the case of Docker container (which is technically an Object Computing Initiative, +or OCI container) your application is executed inside it, +but the container provides operating system services, such as disk and network I/O. + +While the two container types are different, +it's entirely possible (and common) to run a Jakarta EE application inside a Docker container. +**** +The figure below shows how the application code, container, and Jakarta EE Server are related: + +image::container-services.svg[ "Relationship between containers, serveris, and your code."] + +In a simple case, an application might look like this: + +image::simple-app.svg[ "Simple Jakarta EE Application"] + +However, a single Jakarta EE Server can run multiple applications, +and applications can communicate with each other remotely. +So you can create more complicated scenarios, as shown below: + +image::multitier-app.svg[ "More Complex Jakarta EE Application"] + +NOTE: Even though the figures above show communication between multiple Jakarta EE applications, +they can and often do communicate with non-Jakarta EE applications via messaging or streaming servers, REST, and so on. + +Regardless of how simple or complicated your system architecture is, +a key benefit of Jakarta EE is that container services are configurable. +This means the same component can behave differently based on where it's deployed. +The container also manages non-configurable services, such as the lifecycle of components, +database connection resource pooling, data persistence, and access to the Jakarta EE APIs. + + + diff --git a/src/main/antora/modules/intro/pages/overview/overview-highlights.adoc b/src/main/antora/modules/intro/pages/overview/overview-highlights.adoc new file mode 100644 index 00000000..4d152ee7 --- /dev/null +++ b/src/main/antora/modules/intro/pages/overview/overview-highlights.adoc @@ -0,0 +1,30 @@ +// This file should always contain the highlights for the current version of Jakarta EE. + +== Jakarta EE 10 Platform Highlights + +Jakarta EE 10 is the first feature release of the platform since it moved to the Eclipse Foundation in 2017. +The key emphasis of this release is better alignment with Java SE and creation of a new lightweight Core profile, +which can be easily consumed by other standards such as https://microprofile.io/[MicroProfile^]. + +Here are some highlights: + +* CDI Alignment +** `@Asynchronous` in Jakarta Concurrency +** Better CDI support in Jakarta Batch +* Java SE Alignment +** Support for Java SE 11 and 17 +** `CompletionStage`, `ForkJoinPool`, parallel streams in Jakarta Concurrency +** Bootstrap APIs for Jakarta REST +* Closing standardization gaps +** OpenID Connect support in Jakarta Security +** UUID as entity keys, more SQL support in Jakarta Persistence queries +** Multipart/form-data support in Jakarta REST +** `@ClientWindowScoped` and Facelet pure Java views in Jakarta Faces +** New Core Profile that includes Jakarta CDI Light to enable next generation cloud native runtimes; used by MicroProfile +** Jakarta Concurrency has moved to the Web Profile +* Deprecation/removal +** `@Context` annotation in Jakarta REST +** EJB Entity Beans +** Embeddable EJB container +** Deprecated features in Jakarta Servlet, Jakarta Faces, and Jakarta CDI + diff --git a/src/main/antora/modules/intro/pages/overview/overview-how-do-i-get-it.adoc b/src/main/antora/modules/intro/pages/overview/overview-how-do-i-get-it.adoc new file mode 100644 index 00000000..3d5835bf --- /dev/null +++ b/src/main/antora/modules/intro/pages/overview/overview-how-do-i-get-it.adoc @@ -0,0 +1,13 @@ +== How do I get Jakarta EE? + +Since Jakarta EE is an open-source industry standard, there are multiple implementations. +A good place to start is the https://start.jakarta.ee/[Jakarta EE Starter], +which lets you quickly generate a sample starter app using one of the supported Jakarta EE servers. +You can also find the most recent list of servers on the https://jakarta.ee/compatibility/[Jakarta EE website]. + +If you are working with a Open Container Initiative (OCI)-compliant (i.e., Docker-compatible) containers, +most of these vendors also provide images. + +If you are using a cloud provider, +you may also want to check to see if they have additional support, guides, or managed Jakarta EE servers. + diff --git a/src/main/antora/modules/intro/pages/overview/overview-jakartaee-components.adoc b/src/main/antora/modules/intro/pages/overview/overview-jakartaee-components.adoc new file mode 100644 index 00000000..c55c2dda --- /dev/null +++ b/src/main/antora/modules/intro/pages/overview/overview-jakartaee-components.adoc @@ -0,0 +1,21 @@ +=== Jakarta EE Components + +Jakarta EE applications are made up of components. A *Jakarta EE component* is a self-contained functional unit that +makes use of one or more container services. +That usage could be as simple as injecting a single dependency +or responding to REST requests, or as complicated as +injecting multiple dependencies, querying a database, firing and event, and participating in distributed transactions. + +Jakarta EE supports the following components: + +* *Web components{empty}footnote:[Not to be confused with the web browser standard, https://developer.mozilla.org/en-US/docs/Web/API/Web_Components[Web Components], or user interface widgets in general, which are often called UI components.]* interact with web standards (HTTPS, HTML, WebSocket, and so on) using Jakarta Servlet, Jakarta Faces, Jakarta WebSocket, and related technologies. +* Business components implement logic necessary to support the business domain using either *Enterprise bean components (enterprise beans)*{empty}footnote:[Enterprise Beans previously supported persistence via Entity Beans, but that has been deprecated in favor of Jakarta Persistence] or CDI managed beans. +** For new applications, business components should be implemented using CDI managed beans, +unless you need Enterprise bean-specific features such as transactions, role-based security, +messaging driven beans, or remote execution. +The two technologies play well together. + +All of these components run on the *server{empty}footnote:[Application Clients are +technically supported as well, although they are rarely used.]*, +and are ordinary Java classes written with Jakarta EE annotations (or optionally, +external configuration files called deployment descriptors). diff --git a/src/main/antora/modules/intro/pages/overview/overview-jakartaee-services.adoc b/src/main/antora/modules/intro/pages/overview/overview-jakartaee-services.adoc new file mode 100644 index 00000000..308b0a3f --- /dev/null +++ b/src/main/antora/modules/intro/pages/overview/overview-jakartaee-services.adoc @@ -0,0 +1,86 @@ +== Jakarta EE Services + +Jakarta EE provides a wide range of services, organized into three main categories. +Each category is implemented by one of three profiles. +The Core profile contains the foundational services. +The Web profile contains the Core profile plus services for writing web applications. +The Platform contains the Core and Web profiles, plus additional services for mail, batch processing, +and messaging, and more. + +The table below lists each high-level service, the specification that provides it, and the profile that contains it: + +[cols="1,1,1"] +|=== +|Service |Specification |Profile + +|Dependency injection +|Jakarta Contexts and Dependency Injection (CDI) Lite +|Core + +|RESTful web services +|Jakarta REST (formerly JAX-RS) +|Core + +|JSON processing +|Jakarta JSON Binding (JSON-B) and Jakarta JSON Processing (JSON-P) +|Core + +|Advanced dependency injection +|Jakarta Contexts and Dependency Injection (CDI) Full +|Web + +|Validation +|Jakarta Validation (Bean Validation) +|Web + +|Security +|Jakarta Security +|Web + +|HTTP request handling +|Jakarta Servlet +|Web + +|Server-side web applications +|Jakarta Faces (formerly JavaServer Faces, or JSF) +|Web + +|WebSocket request handling +|Jakarta WebSocket +|Web + +|Relational data persistence +|Jakarta Persistence (formerly JPA) +|Web + +|Application components +|Jakarta Enterprise Beans Lite (formerly EJB Lite) +|Web + +|Transactions +|Jakarta Transactions +|Web + +|Managed concurrency +|Jakarta Concurrency +|Web + +|Email handling +|Jakarta Mail +|Platform + +|Messaging +|Jakarta Messaging +|Platform + +|Batch processing +|Jakarta Batch +|Platform + +|=== + +As you work with Jakarta EE, you'll encounter other services that support the ones listed above. + +Each service is provided by one or more APIs, which are defined in Jakarta EE specifications. +The specifications provide details for users and implementors of the service. +You can find a https://jakarta.ee/specifications/[full list of the Jakarta EE specifications] on the Jakarta EE site. diff --git a/src/main/antora/modules/intro/pages/overview/overview-javase-dependencies.adoc b/src/main/antora/modules/intro/pages/overview/overview-javase-dependencies.adoc new file mode 100644 index 00000000..63af4d7c --- /dev/null +++ b/src/main/antora/modules/intro/pages/overview/overview-javase-dependencies.adoc @@ -0,0 +1,31 @@ +== Usage of Java Standard Edition (SE) APIs + +In addition to many of the core Java programming language APIs, +there are a couple of key APIs you may encounter when working with Jakarta EE: +Java Database Connectivity (JDBC) and Java Naming and Directory Interface (JNDI). + +=== Java Database Connectivity API + +The Java Database Connectivity (JDBC) API lets you work with SQL databases. +You can use the JDBC API directly from within a Jakarta EE component, +but most Jakarta EE applications use xref:persist:persistence-intro/persistence-intro.adoc[Jakarta Persistence] +to map between objects and database tables. +Jakarta EE servers also support managed JDBC data sources, which can be configured for one or more applications. + +=== Java Naming and Directory Interface API + +The Java Naming and Directory Interface (JNDI) API allows you to work with multiple naming and directory services, +such as LDAP, DNS, and NIS. +The API has 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 servers provide a naming environment for Jakarta EE components. +This 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 Messaging connection factory, and a Transactions `UserTransaction` object, are stored in the `java:comp` namespace. + +You can also create your own objects, such as enterprise beans, environment entries, JDBC `DataSource` objects, and messaging destinations. + diff --git a/src/main/antora/modules/intro/pages/overview/overview-what-is-jakarta-ee.adoc b/src/main/antora/modules/intro/pages/overview/overview-what-is-jakarta-ee.adoc new file mode 100644 index 00000000..239e803d --- /dev/null +++ b/src/main/antora/modules/intro/pages/overview/overview-what-is-jakarta-ee.adoc @@ -0,0 +1,28 @@ +== What is Jakarta EE? + +Jakarta EE is a collection of services that help you write enterprise applications that run on the Java Platform. +It provides the infrastructure often required for these applications +so you that you can focus on core features and business logic. + +*Enterprise applications* support the high levels of security, +scalability, and reliability that large organizations typically require. +They can be web services, web applications, batch processes, and so on. + +The *Java Platform* consists of the Java Virtual Machine, compiler, +standard APIs, and several tools that help you build, deploy, and debug Java applications. +Java is the primary programming language, although the Java Platform supports several others, including Kotlin and Scala. +Most Jakarta EE applications, however, are written in Java. The *Java Platform* is also called *Java Standard Edition (SE)*. + +With Jakarta EE, you can pick and choose which services you need, +and you use them with or without other frameworks and libraries. +One framework commonly used with Jakarta EE is https://microprofile.io[MicroProfile^], +which provides additional features commonly used in microservices. + +A key benefit of Jakarta EE is that it's a set of open source standards supported by multiple vendors. +Each vendor has their own implementation of the standards, +and the vendors work together to update the standards over time. +This means that you aren't locked into a particular vendor, +and each standard is well-thought-out and based on existing patterns and practices. + +Jakarta EE is stable and mature, and used in tens of thousands of mission-critical enterprises applications worldwide; +yet it has evolved over time to keep up with modern computing trends, such as cloud computing. diff --git a/src/main/antora/modules/intro/pages/overview/overview.adoc b/src/main/antora/modules/intro/pages/overview/overview.adoc new file mode 100644 index 00000000..9b36726c --- /dev/null +++ b/src/main/antora/modules/intro/pages/overview/overview.adoc @@ -0,0 +1,26 @@ += Overview + +include::ROOT:partial$draft.adoc[] + +This chapter explains what Jakarta EE is, what features it provides, common terms, +and how Jakarta EE applications are structured. + +include::overview-highlights.adoc[] + +include::overview-what-is-jakarta-ee.adoc[] + +include::overview-jakartaee-services.adoc[] + +include::overview-containers.adoc[] + +include::overview-jakartaee-components.adoc[] + +include::overview-javase-dependencies.adoc[] + +include::overview-how-do-i-get-it.adoc[] + +== Further Reading + +* https://jakarta.ee/[Jakarta EE Home Page] +* https://jakarta.ee/about/jesp/[Jakarta EE Specification Process] +* https://jakarta.ee/specifications/[Jakarta EE Specifications] diff --git a/src/main/asciidoc/usingexamples/usingexamples.adoc b/src/main/antora/modules/intro/pages/usingexamples/usingexamples.adoc similarity index 93% rename from src/main/asciidoc/usingexamples/usingexamples.adoc rename to src/main/antora/modules/intro/pages/usingexamples/usingexamples.adoc index dbfe8b49..6e9a569a 100644 --- a/src/main/asciidoc/usingexamples/usingexamples.adoc +++ b/src/main/antora/modules/intro/pages/usingexamples/usingexamples.adoc @@ -1,5 +1,7 @@ = Using the Tutorial Examples +include::ROOT:partial$not_updated.adoc[] + This chapter tells you everything you need to know to install, build, and run the tutorial examples. For additional samples, see the GlassFish samples at https://github.com/eclipse-ee4j/glassfish-samples/tree/master/ws/jakartaee9 diff --git a/src/main/asciidoc/usingexamples/usingexamples001.adoc b/src/main/antora/modules/intro/pages/usingexamples/usingexamples001.adoc similarity index 90% rename from src/main/asciidoc/usingexamples/usingexamples001.adoc rename to src/main/antora/modules/intro/pages/usingexamples/usingexamples001.adoc index 2724717b..1c4c32fa 100644 --- a/src/main/asciidoc/usingexamples/usingexamples001.adoc +++ b/src/main/antora/modules/intro/pages/usingexamples/usingexamples001.adoc @@ -2,15 +2,15 @@ The following software is required to run the examples: -* <> +* <<_java_platform_standard_edition>> -* <> +* <<_eclipse_glassfish_server>> -* <> +* <<_jakarta_ee_tutorial_examples>> -* <> +* <<_apache_netbeans_ide>> -* <> +* <<_apache_maven>> === Java Platform, Standard Edition @@ -44,13 +44,9 @@ as-install/bin === Jakarta EE Tutorial Examples -The tutorial example codes are located at https://github.com/eclipse-ee4j/jakartaee-tutorial-examples. +The tutorial example codes are located at https://github.com/eclipse-ee4j/jakartaee-examples -Download the examples and extract it to the following location: - ----- -tut-install/examples/ ----- +Clone or download this repository to your preferred location, this path is referenced in the tutorial as the _jakartaee-examples_ directory. === Apache NetBeans IDE diff --git a/src/main/asciidoc/usingexamples/usingexamples002.adoc b/src/main/antora/modules/intro/pages/usingexamples/usingexamples002.adoc similarity index 100% rename from src/main/asciidoc/usingexamples/usingexamples002.adoc rename to src/main/antora/modules/intro/pages/usingexamples/usingexamples002.adoc diff --git a/src/main/asciidoc/usingexamples/usingexamples003.adoc b/src/main/antora/modules/intro/pages/usingexamples/usingexamples003.adoc similarity index 100% rename from src/main/asciidoc/usingexamples/usingexamples003.adoc rename to src/main/antora/modules/intro/pages/usingexamples/usingexamples003.adoc diff --git a/src/main/asciidoc/usingexamples/usingexamples004.adoc b/src/main/antora/modules/intro/pages/usingexamples/usingexamples004.adoc similarity index 100% rename from src/main/asciidoc/usingexamples/usingexamples004.adoc rename to src/main/antora/modules/intro/pages/usingexamples/usingexamples004.adoc diff --git a/src/main/asciidoc/usingexamples/usingexamples005.adoc b/src/main/antora/modules/intro/pages/usingexamples/usingexamples005.adoc similarity index 100% rename from src/main/asciidoc/usingexamples/usingexamples005.adoc rename to src/main/antora/modules/intro/pages/usingexamples/usingexamples005.adoc diff --git a/src/main/asciidoc/usingexamples/usingexamples006.adoc b/src/main/antora/modules/intro/pages/usingexamples/usingexamples006.adoc similarity index 100% rename from src/main/asciidoc/usingexamples/usingexamples006.adoc rename to src/main/antora/modules/intro/pages/usingexamples/usingexamples006.adoc diff --git a/src/main/asciidoc/usingexamples/usingexamples007.adoc b/src/main/antora/modules/intro/pages/usingexamples/usingexamples007.adoc similarity index 93% rename from src/main/asciidoc/usingexamples/usingexamples007.adoc rename to src/main/antora/modules/intro/pages/usingexamples/usingexamples007.adoc index 7159e78b..a8ae22ea 100644 --- a/src/main/asciidoc/usingexamples/usingexamples007.adoc +++ b/src/main/antora/modules/intro/pages/usingexamples/usingexamples007.adoc @@ -15,7 +15,7 @@ You can install the archetypes using NetBeans IDE or Maven. . In the Open Project dialog box, navigate to: + ---- -tut-install/examples +jakartaee-examples/tutorial ---- . Select the `archetypes` folder. @@ -28,7 +28,7 @@ tut-install/examples . In a terminal window, go to: + ---- -tut-install/examples/archetypes/ +jakartaee-examples/tutorial/archetypes/ ---- . Enter the following command: + diff --git a/src/main/asciidoc/usingexamples/usingexamples008.adoc b/src/main/antora/modules/intro/pages/usingexamples/usingexamples008.adoc similarity index 100% rename from src/main/asciidoc/usingexamples/usingexamples008.adoc rename to src/main/antora/modules/intro/pages/usingexamples/usingexamples008.adoc diff --git a/src/main/asciidoc/usingexamples/usingexamples009.adoc b/src/main/antora/modules/intro/pages/usingexamples/usingexamples009.adoc similarity index 100% rename from src/main/asciidoc/usingexamples/usingexamples009.adoc rename to src/main/antora/modules/intro/pages/usingexamples/usingexamples009.adoc diff --git a/src/main/asciidoc/jms-concepts/jms-concepts.adoc b/src/main/antora/modules/messaging/pages/jms-concepts/jms-concepts.adoc similarity index 91% rename from src/main/asciidoc/jms-concepts/jms-concepts.adoc rename to src/main/antora/modules/messaging/pages/jms-concepts/jms-concepts.adoc index 1cd5d8bb..2df62cf3 100644 --- a/src/main/asciidoc/jms-concepts/jms-concepts.adoc +++ b/src/main/antora/modules/messaging/pages/jms-concepts/jms-concepts.adoc @@ -1,5 +1,7 @@ = Jakarta Messaging Concepts +include::ROOT:partial$not_updated.adoc[] + This chapter provides an introduction to Jakarta Messaging, a Java API that allows applications to create, send, receive, and read messages using reliable, asynchronous, loosely coupled communication. include::jms-concepts001.adoc[] diff --git a/src/main/asciidoc/jms-concepts/jms-concepts001.adoc b/src/main/antora/modules/messaging/pages/jms-concepts/jms-concepts001.adoc similarity index 96% rename from src/main/asciidoc/jms-concepts/jms-concepts001.adoc rename to src/main/antora/modules/messaging/pages/jms-concepts/jms-concepts001.adoc index 9c10e816..00ecf09b 100644 --- a/src/main/asciidoc/jms-concepts/jms-concepts001.adoc +++ b/src/main/antora/modules/messaging/pages/jms-concepts/jms-concepts001.adoc @@ -60,11 +60,11 @@ For example, components of an enterprise application for an automobile manufactu * The business can publish updated catalog items to its sales force. Using messaging for these tasks allows the various components to interact with one another efficiently, without tying up network or other resources. -<> illustrates how this simple example might work. +<<_messaging_in_an_enterpise_application>> illustrates how this simple example might work. -[[messaging-in-an-enterpise-application]] +[[_messaging_in_an_enterpise_application]] .Messaging in an Enterprise Application -image::jakartaeett_dt_026.svg["Diagram showing messaging between various departments in an enterprise"] +image::common:jakartaeett_dt_026.svg["Diagram showing messaging between various departments in an enterprise"] Manufacturing is only one example of how an enterprise can use the Jakarta Messaging API. Retail applications, financial services applications, health services applications, and many others can make use of messaging. diff --git a/src/main/asciidoc/jms-concepts/jms-concepts002.adoc b/src/main/antora/modules/messaging/pages/jms-concepts/jms-concepts002.adoc similarity index 79% rename from src/main/asciidoc/jms-concepts/jms-concepts002.adoc rename to src/main/antora/modules/messaging/pages/jms-concepts/jms-concepts002.adoc index 1ac1c4f3..71ed4a1b 100644 --- a/src/main/asciidoc/jms-concepts/jms-concepts002.adoc +++ b/src/main/antora/modules/messaging/pages/jms-concepts/jms-concepts002.adoc @@ -10,7 +10,7 @@ Later sections cover more advanced concepts, including the ones you need in orde A Jakarta Messaging application is composed of the following parts. * A Jakarta Messaging provider is a messaging system that implements the Messaging interfaces and provides administrative and control features. -An implementation of the Jakarta EE platform that supports the full profile includes a Messaging provider. +A Jakarta EE implementation that supports the Jakarta EE Platform also includes a Messaging provider. * Jakarta Messaging clients are the programs or components, written in the Java programming language, that produce and consume messages. Any Jakarta EE application component can act as a Messaging client. @@ -20,16 +20,16 @@ Java SE applications can also act as Jakarta Messaging clients; the Message Queu * Messages are the objects that communicate information between Jakarta Messaging clients. * Administered objects are Jakarta Messaging objects configured for the use of clients. -The two kinds of Jakarta Messaging administered objects are destinations and connection factories, described in <>. +The two kinds of Jakarta Messaging administered objects are destinations and connection factories, described in xref:jms-concepts/jms-concepts.adoc#_jakarta_messaging_administered_objects[Jakarta Messaging Administered Objects]. An administrator can create objects that are available to all applications that use a particular installation of GlassFish Server; alternatively, a developer can use annotations to create objects that are specific to a particular application. -<> illustrates the way these parts interact. +<<_jakarta_messaging_architecture_2>> illustrates the way these parts interact. Administrative tools or annotations allow you to bind destinations and connection factories into a JNDI namespace. A Messaging client can then use resource injection to access the administered objects in the namespace and then establish a logical connection to the same objects through the Jakarta Messaging provider. -[[jakarta-messaging-architecture-2]] +[[_jakarta_messaging_architecture_2]] .Jakarta Messaging Architecture -image::jakartaeett_dt_027.svg["Diagram of Jakarta Messaging architecture, showing administrative tool, Jakarta Messaging client, JNDI namespace, and JMS provider"] +image::common:jakartaeett_dt_027.svg["Diagram of Jakarta Messaging architecture, showing administrative tool, Jakarta Messaging client, JNDI namespace, and JMS provider"] === Messaging Styles @@ -50,15 +50,15 @@ A point-to-point (PTP) product or application is built on the concept of message Each message is addressed to a specific queue, and receiving clients extract messages from the queues established to hold their messages. Queues retain all messages sent to them until the messages are consumed or expire. -PTP messaging, illustrated in <>, has the following characteristics. +PTP messaging, illustrated in <<_point_to_point_messaging>>, has the following characteristics. * Each message has only one consumer. * The receiver can fetch the message whether or not it was running when the client sent the message. -[[point-to-point-messaging]] +[[_point_to_point_messaging]] .Point-to-Point Messaging -image::jakartaeett_dt_028.svg["Diagram of point-to-point messaging, showing Client 1 sending a message to a queue, and Client 2 consuming and acknowledging the message"] +image::common:jakartaeett_dt_028.svg["Diagram of point-to-point messaging, showing Client 1 sending a message to a queue, and Client 2 consuming and acknowledging the message"] Use PTP messaging when every message you send must be processed successfully by one consumer. @@ -72,8 +72,8 @@ Topics retain messages only as long as it takes to distribute them to subscriber With pub/sub messaging, it is important to distinguish between the consumer that subscribes to a topic (the subscriber) and the subscription that is created. The consumer is a Jakarta Messaging object within an application, while the subscription is an entity within the Jakarta Messaging provider. Normally, a topic can have many consumers, but a subscription has only one subscriber. -It is possible, however, to create shared subscriptions; see <> for details. -See <> for details on the semantics of pub/sub messaging. +It is possible, however, to create shared subscriptions; see xref:jms-concepts/jms-concepts.adoc#_creating_shared_subscriptions[Creating Shared Subscriptions] for details. +See xref:jms-concepts/jms-concepts.adoc#_consuming_messages_from_topics[Consuming Messages from Topics] for details on the semantics of pub/sub messaging. Pub/sub messaging has the following characteristics. @@ -83,13 +83,13 @@ Pub/sub messaging has the following characteristics. + The Jakarta Messaging relaxes this requirement to some extent by allowing applications to create durable subscriptions, which receive messages sent while the consumers are not active. Durable subscriptions provide the flexibility and reliability of queues but still allow clients to send messages to many recipients. -For more information about durable subscriptions, see <>. +For more information about durable subscriptions, see xref:jms-concepts/jms-concepts.adoc#_creating_durable_subscriptions[Creating Durable Subscriptions]. -Use pub/sub messaging when each message can be processed by any number of consumers (or none). <> illustrates pub/sub messaging. +Use pub/sub messaging when each message can be processed by any number of consumers (or none). <<_publish_subscribe_messaging>> illustrates pub/sub messaging. -[[publish-subscribe-messaging]] +[[_publish_subscribe_messaging]] .Publish/Subscribe Messaging -image::jakartaeett_dt_029.svg["Diagram of pub/sub messaging, showing Client 1 sending a message to a topic, and the message being delivered to two consumers to the topic"] +image::common:jakartaeett_dt_029.svg["Diagram of pub/sub messaging, showing Client 1 sending a message to a topic, and the message being delivered to two consumers to the topic"] === Message Consumption diff --git a/src/main/asciidoc/jms-concepts/jms-concepts003.adoc b/src/main/antora/modules/messaging/pages/jms-concepts/jms-concepts003.adoc similarity index 82% rename from src/main/asciidoc/jms-concepts/jms-concepts003.adoc rename to src/main/antora/modules/messaging/pages/jms-concepts/jms-concepts003.adoc index 85db0300..62404668 100644 --- a/src/main/asciidoc/jms-concepts/jms-concepts003.adoc +++ b/src/main/antora/modules/messaging/pages/jms-concepts/jms-concepts003.adoc @@ -16,18 +16,18 @@ The basic building blocks of a Jakarta Messaging application are * Messages -<> shows how all these objects fit together in a Messaging client application. +<<_jakarta_messaging_programming_model_2>> shows how all these objects fit together in a Messaging client application. -[[jakarta-messaging-programming-model-2]] +[[_jakarta_messaging_programming_model_2]] .Jakarta Messaging Programming Model -image::jakartaeett_dt_030.svg["Diagram of Jakarta Messaging programming model: connection factory, JMSContext, connection, session, message producer, message consumer, messages, and destinations"] +image::common:jakartaeett_dt_030.svg["Diagram of Jakarta Messaging programming model: connection factory, JMSContext, connection, session, message producer, message consumer, messages, and destinations"] Jakarta Messaging also provides queue browsers, objects that allow an application to browse messages on a queue. This section describes all these objects briefly and provides sample commands and code snippets that show how to create and use the objects. The last subsection briefly describes Jakarta Messaging API exception handling. -Examples that show how to combine all these objects in applications appear in xref:jakarta-messaging-examples[xrefstyle=full] beginning with <>. +Examples that show how to combine all these objects in applications appear in xref:jms-examples/jms-examples.adoc#_jakarta_messaging_examples[Jakarta Messaging Examples] beginning with xref:jms-examples/jms-examples.adoc#_writing_simple_jakarta_messaging_applications[Writing Simple Jakarta Messaging Applications]. For more detail, see Jakarta Messaging documentation, part of the Jakarta EE API documentation. === Jakarta Messaging Administered Objects @@ -43,11 +43,11 @@ With GlassFish Server, you can use the `asadmin create-jms-resource` command or You can also specify the resources in a file named `glassfish-resources.xml` that you can bundle with an application. NetBeans IDE provides a wizard that allows you to create Jakarta Messaging resources for GlassFish Server. -See <> for details. +See xref:jms-examples/jms-examples.adoc#_creating_jakarta_messaging_administered_objects[Creating Jakarta Messaging Administered Objects] for details. The Jakarta EE platform specification allows a developer to create administered objects using annotations or deployment descriptor elements. Objects created in this way are specific to the application for which they are created. -See <> for details. +See xref:jms-concepts/jms-concepts.adoc#_creating_resources_for_jakarta_ee_applications[Creating Resources for Jakarta EE Applications] for details. Definitions in a deployment descriptor override those specified by annotations. ==== Jakarta Messaging Connection Factories @@ -55,7 +55,7 @@ Definitions in a deployment descriptor override those specified by annotations. A connection factory is the object a client uses to create a connection to a provider. A connection factory encapsulates a set of connection configuration parameters that has been defined by an administrator. Each connection factory is an instance of the `ConnectionFactory`, `QueueConnectionFactory`, or `TopicConnectionFactory` interface. -To learn how to create connection factories, see <>. +To learn how to create connection factories, see xref:jms-examples/jms-examples.adoc#_creating_jakarta_messaging_administered_objects[Creating Jakarta Messaging Administered Objects]. At the beginning of a Messaging client program, you usually inject a connection factory resource into a `ConnectionFactory` object. A Jakarta EE server must provide a Jakarta Messaging connection factory with the logical JNDI name `java:comp/DefaultJMSConnectionFactory`. @@ -75,7 +75,7 @@ A destination is the object a client uses to specify the target of messages it p In the PTP messaging style, destinations are called queues. In the pub/sub messaging style, destinations are called topics. A Jakarta Messaging application can use multiple queues or topics (or both). -To learn how to create destination resources, see <>. +To learn how to create destination resources, see xref:jms-examples/jms-examples.adoc#_creating_jakarta_messaging_administered_objects[Creating Jakarta Messaging Administered Objects]. To create a destination using GlassFish Server, you create a Jakarta Messaging destination resource that specifies a JNDI name for the destination. @@ -115,20 +115,20 @@ In the Jakarta EE platform, the ability to create multiple sessions from a singl In web and enterprise bean components, a connection can create no more than one session. You normally create a connection by creating a `JMSContext` object. -See <> for details. +See <<_jmscontext_objects>> for details. === Sessions A session is a single-threaded context for producing and consuming messages. You normally create a session (as well as a connection) by creating a `JMSContext` object. -See <> for details. +See <<_jmscontext_objects>> for details. You use sessions to create message producers, message consumers, messages, queue browsers, and temporary destinations. -Sessions serialize the execution of message listeners; for details, see <>. +Sessions serialize the execution of message listeners; for details, see <<_jakarta_messaging_message_listeners>>. A session provides a transactional context with which to group a set of sends and receives into an atomic unit of work. -For details, see <>. +For details, see xref:jms-concepts/jms-concepts.adoc#_using_jakarta_messaging_local_transactions[Using Jakarta Messaging Local Transactions]. === JMSContext Objects @@ -145,7 +145,7 @@ You use the `JMSContext` to create the following objects: * Queue browsers -* Temporary queues and topics (see <>) +* Temporary queues and topics (see xref:jms-concepts/jms-concepts.adoc#_creating_temporary_destinations[Creating Temporary Destinations]) You can create a `JMSContext` in a `try`-with-resources block. @@ -158,7 +158,7 @@ JMSContext context = connectionFactory.createContext(); When called with no arguments from an application client or a Java SE client, or from the Jakarta EE web or Enterprise Beans container when there is no active Jakarta Transactions transaction in progress, the `createContext` method creates a non-transacted session with an acknowledgment mode of `JMSContext.AUTO_ACKNOWLEDGE`. When called with no arguments from the web or Enterprise Beans container when there is an active JTA transaction in progress, the `createContext` method creates a transacted session. -For information about the way Jakarta Messaging transactions work in Jakarta EE applications, see <>. +For information about the way Jakarta Messaging transactions work in Jakarta EE applications, see xref:jms-concepts/jms-concepts.adoc#_using_jakarta_messaging_in_jakarta_ee_applications[Using Jakarta Messaging in Jakarta EE Applications]. From an application client or a Java SE client, you can also call the `createContext` method with the argument `JMSContext.SESSION_TRANSACTED` to create a transacted session: @@ -168,12 +168,12 @@ JMSContext context = connectionFactory.createContext(JMSContext.SESSION_TRANSACTED); ---- -The session uses local transactions; see <> for details. +The session uses local transactions; see xref:jms-concepts/jms-concepts.adoc#_using_jakarta_messaging_local_transactions[Using Jakarta Messaging Local Transactions] for details. -Alternatively, you can specify a non-default acknowledgment mode; see <> for more information. +Alternatively, you can specify a non-default acknowledgment mode; see xref:jms-concepts/jms-concepts.adoc#_controlling_message_acknowledgment[Controlling Message Acknowledgment] for more information. When you use a `JMSContext`, message delivery normally begins as soon as you create a consumer. -See <> for more information. +See <<_jakarta_messaging_message_consumers>> for more information. If you create a `JMSContext` in a `try`-with-resources block, you do not need to close it explicitly. It will be closed when the `try` block comes to an end. @@ -205,7 +205,7 @@ context.createProducer().send(dest, message); ---- You can create the message in a variable before sending it, as shown here, or you can create it within the `send` call. -See <> for more information. +See <<_jakarta_messaging_messages>> for more information. === Jakarta Messaging Message Consumers @@ -252,8 +252,8 @@ To enable asynchronous message delivery from an application client or a Java SE You can use the `JMSContext.createDurableConsumer` method to create a durable topic subscription. This method is valid only if you are using a topic. -For details, see <>. -For topics, you can also create shared consumers; see <>. +For details, see <<_creating_durable_subscriptions>>. +For topics, you can also create shared consumers; see <<_creating_shared_subscriptions>>. ==== Jakarta Messaging Message Listeners @@ -271,23 +271,23 @@ consumer.setMessageListener(myListener); ---- When message delivery begins, the Messaging provider automatically calls the message listener's `onMessage` method whenever a message is delivered. -The `onMessage` method takes one argument of type `Message`, which your implementation of the method can cast to another message subtype as needed (see <>). +The `onMessage` method takes one argument of type `Message`, which your implementation of the method can cast to another message subtype as needed (see <<_message_bodies>>). In the Jakarta EE web or Enterprise Beans container, you use message-driven beans for asynchronous message delivery. A message-driven bean also implements the `MessageListener` interface and contains an `onMessage` method. -For details, see <>. +For details, see xref:jms-concepts/jms-concepts.adoc#_using_message_driven_beans_to_receive_messages_asynchronously[Using Message-Driven Beans to Receive Messages Asynchronously]. Your `onMessage` method should handle all exceptions. Throwing a `RuntimeException` is considered a programming error. -For a simple example of the use of a message listener, see <>. -xref:jakarta-messaging-examples[xrefstyle=full] contains several more examples of message listeners and message-driven beans. +For a simple example of the use of a message listener, see xref:jms-examples/jms-examples.adoc#_using_a_message_listener_for_asynchronous_message_delivery[Using a Message Listener for Asynchronous Message Delivery]. +xref:jms-examples/jms-examples.adoc#_jakarta_messaging_examples[Jakarta Messaging Examples] contains several more examples of message listeners and message-driven beans. ==== Jakarta Messaging Message Selectors If your messaging application needs to filter the messages it receives, you can use a Jakarta Messaging message selector, which allows a message consumer for a destination to specify the messages that interest it. Message selectors assign the work of filtering messages to the Messaging provider rather than to the application. -For an example of an application that uses a message selector, see <>. +For an example of an application that uses a message selector, see xref:jms-examples/jms-examples.adoc#_sending_messages_from_a_session_bean_to_an_mdb[Sending Messages from a Session Bean to an MDB]. A message selector is a `String` that contains an expression. The syntax of the expression is based on a subset of the SQL92 conditional expression syntax. @@ -301,7 +301,7 @@ NewsType = 'Sports' OR NewsType = 'Opinion' The `createConsumer` and `createDurableConsumer` methods, as well as the methods for creating shared consumers, allow you to specify a message selector as an argument when you create a message consumer. The message consumer then receives only messages whose headers and properties match the selector. -(See <> and <>.) +(See <<_message_headers>> and <<_message_properties>>.) A message selector cannot select messages on the basis of the content of the message body. ==== Consuming Messages from Topics @@ -338,11 +338,11 @@ The `JMSContext.createConsumer` method creates a consumer on an unshared nondura * A shared nondurable subscription is identified by name and an optional client identifier, and may have several consumer objects consuming messages from it. It is created automatically when the first consumer object is created. It is not persisted and is deleted automatically when the last consumer object is closed. -See <> for more information. +See <<_creating_shared_subscriptions>> for more information. At the cost of higher overhead, a subscription may be durable. A durable subscription is persisted and continues to accumulate messages until explicitly deleted, even if there are no consumer objects consuming messages from it. -See <> for details. +See <<_creating_durable_subscriptions>> for details. ==== Creating Durable Subscriptions @@ -401,24 +401,24 @@ context.unsubscribe(subName); The `unsubscribe` method deletes the state the provider maintains for the subscription. -<> show the difference between a nondurable and a durable subscription. +<<_consumers_on_a_durable_subscription>> show the difference between a nondurable and a durable subscription. With an ordinary, nondurable subscription, the consumer and the subscription begin and end at the same point and are, in effect, identical. When the consumer is closed, the subscription also ends. Here, `create` stands for a call to `JMSContext.createConsumer` with a `Topic` argument, and `close` stands for a call to `JMSConsumer.close`. Any messages sent to the topic between the time of the first `close` and the time of the second `create` are not added to either subscription. -In <>, the consumers receive messages M1, M2, M5, and M6, but they do not receive messages M3 and M4. +In <<_nondurable_subscriptions_and_consumers>>, the consumers receive messages M1, M2, M5, and M6, but they do not receive messages M3 and M4. -[[nondurable-subscriptions-and-consumers]] +[[_nondurable_subscriptions_and_consumers]] .Nondurable Subscriptions and Consumers -image::jakartaeett_dt_031.svg["Diagram showing messages being lost when nondurable subscriptions are used"] +image::common:jakartaeett_dt_031.svg["Diagram showing messages being lost when nondurable subscriptions are used"] With a durable subscription, the consumer can be closed and re-created, but the subscription continues to exist and to hold messages until the application calls the `unsubscribe` method. -In <>, `create` stands for a call to `JMSContext.createDurableConsumer`, `close` stands for a call to `JMSConsumer.close`, and `unsubscribe` stands for a call to `JMSContext.unsubscribe`. +In <<_consumers_on_a_durable_subscription>>, `create` stands for a call to `JMSContext.createDurableConsumer`, `close` stands for a call to `JMSConsumer.close`, and `unsubscribe` stands for a call to `JMSContext.unsubscribe`. Messages sent after the first consumer is closed are received when the second consumer is created (on the same durable subscription), so even though messages M2, M4, and M5 arrive while there is no consumer, they are not lost. -[[consumers-on-a-durable-subscription]] +[[_consumers_on_a_durable_subscription]] .Consumers on a Durable Subscription -image::jakartaeett_dt_032.svg["Diagram showing messages being preserved when durable subscriptions are used"] +image::common:jakartaeett_dt_032.svg["Diagram showing messages being preserved when durable subscriptions are used"] A shared durable subscription allows you to use multiple consumers to receive messages from a durable subscription. If you use a shared durable subscription, the connection factory you use does not need to have a client identifier. @@ -430,7 +430,7 @@ JMSConsumer consumer = context.createSharedDurableConsumer(topic, "MakeItLast"); ---- -See <>, <>, <>, and <> for examples of Jakarta EE applications that use durable subscriptions. +See xref:jms-examples/jms-examples.adoc#_acknowledging_messages[Acknowledging Messages], xref:jms-examples/jms-examples.adoc#_using_durable_subscriptions[Using Durable Subscriptions], xref:jms-examples/jms-examples.adoc#_using_shared_durable_subscriptions[Using Shared Durable Subscriptions], and xref:jms-examples/jms-examples.adoc#_sending_messages_from_a_session_bean_to_an_mdb[Sending Messages from a Session Bean to an MDB] for examples of Jakarta EE applications that use durable subscriptions. ==== Creating Shared Subscriptions @@ -450,10 +450,10 @@ A shared subscription can be useful if you want to share the message load among This feature can improve the scalability of Jakarta EE application client applications and Java SE applications. (Message-driven beans share the work of processing messages from a topic among multiple threads.) -See <> for a simple example of using shared nondurable consumers. +See xref:jms-examples/jms-examples.adoc#_using_shared_nondurable_subscriptions[Using Shared Nondurable Subscriptions] for a simple example of using shared nondurable consumers. You can also create shared durable subscriptions by using the `JMSContext.createSharedDurableConsumer` method. -For details, see <>. +For details, see <<_creating_durable_subscriptions>>. === Jakarta Messaging Messages @@ -465,12 +465,12 @@ Only the header is required. The following sections describe these parts. For complete documentation of message headers, properties, and bodies, see the documentation of the `Message` interface in the API documentation. -For a list of possible message types, see <>. +For a list of possible message types, see <<_message_bodies>>. ==== Message Headers A Jakarta Messaging message header contains a number of predefined fields that contain values used by both clients and providers to identify and route messages. -<> lists and describes the Jakarta Messaging message header fields and indicates how their values are set. +<<_how_jakarta_messaging_message_header_field_values_are_set>> lists and describes the Jakarta Messaging message header fields and indicates how their values are set. For example, every message has a unique identifier, which is represented in the header field `JMSMessageID`. The value of another header field, `JMSDestination`, represents the queue or the topic to which the message is sent. Other fields include a timestamp and a priority level. @@ -478,7 +478,7 @@ Other fields include a timestamp and a priority level. Each header field has associated setter and getter methods, which are documented in the description of the `Message` interface. Some header fields are intended to be set by a client, but many are set automatically by the `send` method, which overrides any client-set values. -[[how-jakarta-messaging-message-header-field-values-are-set]] +[[_how_jakarta_messaging_message_header_field_values_are_set]] .How Jakarta Messaging Message Header Field Values Are Set [width="99%",cols="20%,60%,20%"] |=== @@ -486,13 +486,13 @@ Some header fields are intended to be set by a client, but many are set automati |`JMSDestination` |Destination to which the message is being sent |JMS provider `send` method -|`JMSDeliveryMode` |Delivery mode specified when the message was sent (see <>) |Messaging provider `send` method +|`JMSDeliveryMode` |Delivery mode specified when the message was sent (see xref:jms-concepts/jms-concepts.adoc#_specifying_message_persistence[Specifying Message Persistence]) |Messaging provider `send` method -|`JMSDeliveryTime` |The time the message was sent plus the delivery delay specified when the message was sent (see <> |JMS provider `send` method +|`JMSDeliveryTime` |The time the message was sent plus the delivery delay specified when the message was sent (see xref:jms-concepts/jms-concepts.adoc#_specifying_a_delivery_delay[Specifying a Delivery Delay] |JMS provider `send` method -|`JMSExpiration` |Expiration time of the message (see <>) |JMS provider `send` method +|`JMSExpiration` |Expiration time of the message (see xref:jms-concepts/jms-concepts.adoc#_allowing_messages_to_expire[Allowing Messages to Expire]) |JMS provider `send` method -|`JMSPriority` |The priority of the message (see <>) |Jakarta Messaging provider `send` method +|`JMSPriority` |The priority of the message (see xref:jms-concepts/jms-concepts.adoc#_setting_message_priority_levels[Setting Message Priority Levels]) |Jakarta Messaging provider `send` method |`JMSMessageID` |Value that uniquely identifies each message sent by a provider |Messaging provider `send` method @@ -510,8 +510,8 @@ Some header fields are intended to be set by a client, but many are set automati ==== Message Properties You can create and set properties for messages if you need values in addition to those provided by the header fields. -You can use properties to provide compatibility with other messaging systems, or you can use them to create message selectors (see <>). -For an example of setting a property to be used as a message selector, see <>. +You can use properties to provide compatibility with other messaging systems, or you can use them to create message selectors (see <<_jakarta_messaging_message_selectors>>). +For an example of setting a property to be used as a message selector, see xref:jms-examples/jms-examples.adoc#_sending_messages_from_a_session_bean_to_an_mdb[Sending Messages from a Session Bean to an MDB]. Jakarta Messaging provides some predefined property names that begin with `JMSX`. A Messaging provider is required to implement only one of these, `JMSXDeliveryCount` (which specifies the number of times a message has been delivered); the rest are optional. @@ -522,9 +522,9 @@ The use of these predefined properties or of user-defined properties in applicat Jakarta Messaging defines six different types of messages. Each message type corresponds to a different message body. These message types allow you to send and receive data in many different forms. -<> describes these message types. +<<_jakarta_messaging_message_types>> describes these message types. -[[jakarta-messaging-message-types]] +[[_jakarta_messaging_message_types]] .Jakarta Messaging Message Types [width="75%",cols="15%,60%"] |=== @@ -598,7 +598,7 @@ String message = receiver.receiveBody(String.class); You can use the `receiveBody` method to receive any type of message except `StreamMessage` and `Message`, as long as the body of the message can be assigned to a particular type. An empty `Message` can be useful if you want to send a message that is simply a signal to the application. -Some of the examples in xref:jakarta-messaging-examples[xrefstyle=full], send an empty message after sending a series of text messages. +Some of the examples in xref:jms-examples/jms-examples.adoc#_jakarta_messaging_examples[Jakarta Messaging Examples], send an empty message after sending a series of text messages. For example: [source,java] @@ -608,7 +608,7 @@ context.createProducer().send(dest, context.createMessage()); The consumer code can then interpret a non-text message as a signal that all the messages sent have now been received. -The examples in xref:jakarta-messaging-examples[xrefstyle=full], use messages of type `TextMessage`, `MapMessage`, and `Message`. +The examples in xref:jms-examples/jms-examples.adoc#_jakarta_messaging_examples[Jakarta Messaging Examples], use messages of type `TextMessage`, `MapMessage`, and `Message`. === Jakarta Messaging Queue Browsers @@ -623,10 +623,10 @@ For example: QueueBrowser browser = context.createBrowser(queue); ---- -See <> for an example of using a `QueueBrowser` object. +See xref:jms-examples/jms-examples.adoc#_browsing_messages_on_a_queue[Browsing Messages on a Queue] for an example of using a `QueueBrowser` object. The `createBrowser` method allows you to specify a message selector as a second argument when you create a `QueueBrowser`. -For information on message selectors, see <>. +For information on message selectors, see <<_jakarta_messaging_message_selectors>>. Jakarta Messaging provides no mechanism for browsing a topic. Messages usually disappear from a topic as soon as they appear: If there are no message consumers to consume them, the Messaging provider removes them. diff --git a/src/main/asciidoc/jms-concepts/jms-concepts004.adoc b/src/main/antora/modules/messaging/pages/jms-concepts/jms-concepts004.adoc similarity index 86% rename from src/main/asciidoc/jms-concepts/jms-concepts004.adoc rename to src/main/antora/modules/messaging/pages/jms-concepts/jms-concepts004.adoc index b7d58d98..be30cd44 100644 --- a/src/main/asciidoc/jms-concepts/jms-concepts004.adoc +++ b/src/main/antora/modules/messaging/pages/jms-concepts/jms-concepts004.adoc @@ -7,27 +7,27 @@ Jakarta Messaging provides this functionality. The most reliable way to produce a message is to send a `PERSISTENT` message, and to do so within a transaction. Jakarta Messaging messages are `PERSISTENT` by default; `PERSISTENT` messages will not be lost in the event of Messaging provider failure. -For details, see <>. +For details, see <<_specifying_message_persistence>>. Transactions allow multiple messages to be sent or received in an atomic operation.In the Jakarta EE platform they also allow message sends and receives to be combined with database reads and writes in an atomic transaction. A transaction is a unit of work into which you can group a series of operations, such as message sends and receives, so that the operations either all succeed or all fail. -For details, see <>. +For details, see <<_using_jakarta_messaging_local_transactions>>. The most reliable way to consume a message is to do so within a transaction, either from a queue or from a durable subscription to a topic. -For details, see <>, <>, and <>. +For details, see xref:jms-concepts/jms-concepts.adoc#_creating_durable_subscriptions[Creating Durable Subscriptions], <<_creating_temporary_destinations>>, and <<_using_jakarta_messaging_local_transactions>>. Some features primarily allow an application to improve performance. -For example, you can set messages to expire after a certain length of time (see <>), so that consumers do not receive unnecessary outdated information. -You can send messages asynchronously; see <>. +For example, you can set messages to expire after a certain length of time (see <<_allowing_messages_to_expire>>), so that consumers do not receive unnecessary outdated information. +You can send messages asynchronously; see <<_sending_messages_asynchronously>>. -You can also specify various levels of control over message acknowledgment; see <>. +You can also specify various levels of control over message acknowledgment; see <<_controlling_message_acknowledgment>>. Other features can provide useful capabilities unrelated to reliability. For example, you can create temporary destinations that last only for the duration of the connection in which they are created. -See <> for details. +See <<_creating_temporary_destinations>> for details. The following sections describe these features as they apply to application clients or Java SE clients. -Some of the features work differently in the Jakarta EE web or enterprise bean container; in these cases, the differences are noted here and are explained in detail in <>. +Some of the features work differently in the Jakarta EE web or enterprise bean container; in these cases, the differences are noted here and are explained in detail in xref:jms-concepts/jms-concepts.adoc#_using_jakarta_messaging_in_jakarta_ee_applications[Using Jakarta Messaging in Jakarta EE Applications]. === Controlling Message Acknowledgment @@ -41,7 +41,7 @@ The successful consumption of a message ordinarily takes place in three stages. . The message is acknowledged. + Acknowledgment is initiated either by the Messaging provider or by the client, depending on the session acknowledgment mode. -In locally transacted sessions (see <>), a message is acknowledged when the session is committed. +In locally transacted sessions (see <<_using_jakarta_messaging_local_transactions>>), a message is acknowledged when the session is committed. If a transaction is rolled back, all consumed messages are redelivered. In a Jakarta transaction (in the Jakarta EE web or enterprise bean container) a message is acknowledged when the transaction is committed. @@ -69,7 +69,7 @@ This option can reduce session overhead by minimizing the work the session does If messages have been received from a queue but not acknowledged when a `JMSContext` is closed, the Messaging provider retains them and redelivers them when a consumer next accesses the queue. The provider also retains unacknowledged messages if an application closes a `JMSContext` that has been consuming messages from a durable subscription. -(See <>.) +(See xref:jms-concepts/jms-concepts.adoc#_creating_durable_subscriptions[Creating Durable Subscriptions].) Unacknowledged messages that have been received from a nondurable subscription will be dropped when the `JMSContext` is closed. If you use a queue or a durable subscription, you can use the `JMSContext.recover` method to stop a nontransacted `JMSContext` and restart it with its first unacknowledged message. @@ -77,22 +77,22 @@ In effect, the ``JMSContext``'s series of delivered messages is reset to the poi The messages it now delivers may be different from those that were originally delivered, if messages have expired or if higher-priority messages have arrived. For a consumer on a nondurable subscription, the provider may drop unacknowledged messages when the `JMSContext.recover` method is called. -The sample program in <> demonstrates two ways to ensure that a message will not be acknowledged until processing of the message is complete. +The sample program in xref:jms-examples/jms-examples.adoc#_acknowledging_messages[Acknowledging Messages] demonstrates two ways to ensure that a message will not be acknowledged until processing of the message is complete. === Specifying Options for Sending Messages You can set a number of options when you send a message. These options enable you to perform the tasks described in the following topics: -* <> - Specify that messages are persistent, meaning they must not be lost in the event of a provider failure. +* <<_specifying_message_persistence>> - Specify that messages are persistent, meaning they must not be lost in the event of a provider failure. -* <> - Set priority levels for messages, which can affect the order in which the messages are delivered. +* <<_setting_message_priority_levels>> - Set priority levels for messages, which can affect the order in which the messages are delivered. -* <> - Specify an expiration time for messages so they will not be delivered if they are obsolete. +* <<_allowing_messages_to_expire>> - Specify an expiration time for messages so they will not be delivered if they are obsolete. -* <> - Specify a delivery delay for messages so that they will not be delivered until a specified amount of time has expired. +* <<_specifying_a_delivery_delay>> - Specify a delivery delay for messages so that they will not be delivered until a specified amount of time has expired. -* <> - Method chaining allows you to specify more than one of these options when you create a producer and call the `send` method. +* <<_using_jmsproducer_method_chaining>> - Method chaining allows you to specify more than one of these options when you create a producer and call the `send` method. ==== Specifying Message Persistence @@ -219,7 +219,7 @@ replyMsg.setJMSCorrelationID(msg.getJMSMessageID()); context.createProducer().send((Topic) msg.getJMSReplyTo(), replyMsg); ---- -For an example, see <>. +For an example, see xref:jms-examples/jms-examples.adoc#_using_an_entity_to_join_messages_from_two_mdbs[Using an Entity to Join Messages from Two MDBs]. === Using Jakarta Messaging Local Transactions @@ -233,7 +233,7 @@ You can send multiple messages in a transaction, and the messages will not be ad If you receive multiple messages in a transaction, they will not be acknowledged until the transaction is committed. You can use the `JMSContext.rollback` method to roll back a transaction. -A transaction rollback means that all produced messages are destroyed and all consumed messages are recovered and redelivered unless they have expired (see <>). +A transaction rollback means that all produced messages are destroyed and all consumed messages are recovered and redelivered unless they have expired (see <<_allowing_messages_to_expire>>). A transacted session is always involved in a transaction. To create a transacted session, call the `createContext` method as follows: @@ -248,7 +248,7 @@ As soon as the `commit` or the `rollback` method is called, one transaction ends Closing a transacted session rolls back its transaction in progress, including any pending sends and receives. In an application running in the Jakarta EE web or enterprise bean container, you cannot use local transactions. -Instead, you use Jakarta Transactions, described in <>. +Instead, you use Jakarta Transactions, described in xref:jms-concepts/jms-concepts.adoc#_using_jakarta_messaging_in_jakarta_ee_applications[Using Jakarta Messaging in Jakarta EE Applications]. You can combine several sends and receives in a single Jakarta Messaging local transaction, so long as they are all performed using the same `JMSContext`. @@ -270,11 +270,11 @@ Because a message sent during a transaction is not actually sent until the trans The production and the consumption of a message cannot both be part of the same transaction. The reason is that the transactions take place between the clients and the Messaging provider, which intervenes between the production and the consumption of the message. -<> illustrates this interaction. +<<_using_jakarta_messaging_local_transactions_2>> illustrates this interaction. -[[using-jakarta-messaging-local-transactions-2]] +[[_using_jakarta_messaging_local_transactions_2]] .Using Jakarta Messaging Local Transactions -image::jakartaeett_dt_033.svg["Diagram of local transactions, showing separate transactions for sending and consuming a message"] +image::common:jakartaeett_dt_033.svg["Diagram of local transactions, showing separate transactions for sending and consuming a message"] The sending of one or more messages to one or more destinations by Client 1 can form a single transaction, because it forms a single set of interactions with the Messaging provider using a single `JMSContext`. Similarly, the receiving of one or more messages from one or more destinations by Client 2 also forms a single transaction using a single `JMSContext`. @@ -302,7 +302,7 @@ The `commit` and the `rollback` methods for local transactions are associated wi You can combine operations on more than one queue or topic, or on a combination of queues and topics, in a single transaction if you use the same session to perform the operations. For example, you can use the same `JMSContext` to receive a message from a queue and send a message to a topic in the same transaction. -The example in <> shows how to use Jakarta Messaging local transactions. +The example in xref:jms-examples/jms-examples.adoc#_using_local_transactions[Using Local Transactions] shows how to use Jakarta Messaging local transactions. === Sending Messages Asynchronously diff --git a/src/main/asciidoc/jms-concepts/jms-concepts005.adoc b/src/main/antora/modules/messaging/pages/jms-concepts/jms-concepts005.adoc similarity index 86% rename from src/main/asciidoc/jms-concepts/jms-concepts005.adoc rename to src/main/antora/modules/messaging/pages/jms-concepts/jms-concepts005.adoc index a539f605..9438bae7 100644 --- a/src/main/asciidoc/jms-concepts/jms-concepts005.adoc +++ b/src/main/antora/modules/messaging/pages/jms-concepts/jms-concepts005.adoc @@ -17,7 +17,7 @@ The resources you create in this way are visible only to the application for whi You can also use deployment descriptor elements to create these resources. Elements specified in the deployment descriptor override elements specified in annotations. -See <> for basic information about deployment descriptors. +See xref:platform:packaging/packaging.adoc#_packaging_applications[Packaging Applications] for basic information about deployment descriptors. You must use a deployment descriptor to create application-specific resources for application clients. To create a destination, use a `@JMSDestinationDefinition` annotation like the following on a class: @@ -75,7 +75,7 @@ Which ones you can use depends on how your application is packaged. * `java:comp`: Makes the resource available to a single component only (except in a web application, where it is equivalent to `java:module`) See the API documentation for details on these annotations. -The examples in <>, <>, and <> all use the `@JMSDestinationDefinition` annotation. +The examples in xref:jms-examples/jms-examples.adoc#_sending_and_receiving_messages_using_a_simple_web_application[Sending and Receiving Messages Using a Simple Web Application], xref:jms-examples/jms-examples.adoc#_sending_messages_from_a_session_bean_to_an_mdb[Sending Messages from a Session Bean to an MDB], and xref:jms-examples/jms-examples.adoc#_using_an_entity_to_join_messages_from_two_mdbs[Using an Entity to Join Messages from Two MDBs] all use the `@JMSDestinationDefinition` annotation. The other JMS examples do not use these annotations. The examples that consist only of application clients are not deployed in the application server and must therefore communicate with each other using administratively created resources that exist outside of individual applications. @@ -136,12 +136,12 @@ private JMSContext context2; === Using Jakarta EE Components to Produce and to Synchronously Receive Messages An application that produces messages or synchronously receives them can use a Jakarta EE web or Jakarta Enterprise Beans component, such as a managed bean, a servlet, or a session bean, to perform these operations. -The example in <> uses a stateless session bean to send messages to a topic. -The example in <> uses managed beans to produce and to consume messages. +The example in xref:jms-examples/jms-examples.adoc#_sending_messages_from_a_session_bean_to_an_mdb[Sending Messages from a Session Bean to an MDB] uses a stateless session bean to send messages to a topic. +The example in xref:jms-examples/jms-examples.adoc#_sending_and_receiving_messages_using_a_simple_web_application[Sending and Receiving Messages Using a Simple Web Application] uses managed beans to produce and to consume messages. Because a synchronous receive with no specified timeout ties up server resources, this mechanism usually is not the best application design for a web or Jakarta Enterprise Beans component. Instead, use a synchronous receive that specifies a timeout value, or use a message-driven bean to receive messages asynchronously. -For details about synchronous receives, see <>. +For details about synchronous receives, see xref:jms-concepts/jms-concepts.adoc#_jakarta_messaging_message_consumers[Jakarta Messaging Message Consumers]. Using Jakarta Messaging in a Jakarta EE component is in many ways similar to using it in an application client. The main differences are the areas of resource management and transactions. @@ -154,7 +154,7 @@ Here are some useful practices to follow. * If you wish to maintain a Messaging resource only for the life span of a business method, use a `try`-with-resources statement to create the `JMSContext` so that it will be closed automatically at the end of the `try` block. -* To maintain a Messaging resource for the duration of a transaction or request, inject the `JMSContext` as described in <>. +* To maintain a Messaging resource for the duration of a transaction or request, inject the `JMSContext` as described in <<_injecting_a_jmscontext_object>>. This will also cause the resource to be released when it is no longer needed. * If you would like to maintain a Messaging resource for the life span of an enterprise bean instance, you can use a `@PostConstruct` callback method to create the resource and a `@PreDestroy` callback method to close the resource. @@ -174,7 +174,7 @@ This tutorial does not provide any examples of bean-managed transactions. === Using Message-Driven Beans to Receive Messages Asynchronously -The sections <> and <> describe how the Jakarta EE platform supports a special kind of enterprise bean, the message-driven bean, which allows Jakarta EE applications to process Jakarta Messaging messages asynchronously. +The sections xref:entbeans:ejb-intro/ejb-intro.adoc#_what_is_a_message_driven_bean[What Is a Message-Driven Bean?] and xref:jms-concepts/jms-concepts.adoc#_how_does_jakarta_messaging_work_with_the_jakarta_ee_platform[How Does Jakarta Messaging Work with the Jakarta EE Platform?] describe how the Jakarta EE platform supports a special kind of enterprise bean, the message-driven bean, which allows Jakarta EE applications to process Jakarta Messaging messages asynchronously. Other Jakarta EE web and Jakarta Enterprise Beans components allow you to send messages and to receive them synchronously but not asynchronously. A message-driven bean is a message listener to which messages can be delivered from either a queue or a topic. @@ -207,7 +207,7 @@ For a message-driven bean, you need only define the class and annotate it, and t * The bean class uses the `@MessageDriven` annotation, which typically contains an `activationConfig` element containing `@ActivationConfigProperty` annotations that specify properties used by the bean or the connection factory. These properties can include the connection factory, a destination type, a durable subscription, a message selector, or an acknowledgment mode. -Some of the examples in xref:jakarta-messaging-examples[xrefstyle=full] set these properties. +Some of the examples in xref:jms-examples/jms-examples.adoc#_jakarta_messaging_examples[Jakarta Messaging Examples] set these properties. You can also set the properties in the deployment descriptor. * The application client container has only one instance of a `MessageListener`, which is called on a single thread at a time. @@ -217,9 +217,9 @@ Message-driven beans may therefore allow much faster processing of messages than * You do not need to specify a message acknowledgment mode unless you use bean-managed transactions. The message is consumed in the transaction in which the `onMessage` method is invoked. -<> lists the activation configuration properties defined by the Jakarta Messaging specification. +<<_activationconfigproperty_settings_for_message_driven_beans>> lists the activation configuration properties defined by the Jakarta Messaging specification. -[[activationconfigproperty-settings-for-message-driven-beans]] +[[_activationconfigproperty_settings_for_message_driven_beans]] .@ActivationConfigProperty Settings for Message-Driven Beans [width="80%",cols="20%,60%"] |=== @@ -231,18 +231,18 @@ The message is consumed in the transaction in which the `onMessage` method is in |`destinationType` |Either `jakarta.jms.Queue` or `jakarta.jms.Topic` -|`subscriptionDurability` |For durable subscriptions, set the value to `Durable`; see <> for more information +|`subscriptionDurability` |For durable subscriptions, set the value to `Durable`; see xref:jms-concepts/jms-concepts.adoc#_creating_durable_subscriptions[Creating Durable Subscriptions] for more information |`clientId` |For durable subscriptions, the client ID for the connection (optional) |`subscriptionName` |For durable subscriptions, the name of the subscription -|`messageSelector` |A string that filters messages; see <> for information +|`messageSelector` |A string that filters messages; see xref:jms-concepts/jms-concepts.adoc#_jakarta_messaging_message_selectors[Jakarta Messaging Message Selectors] for information |`connectionFactoryLookup` |The lookup name of the connection factory to be used to connect to the Messaging provider from which the bean will receive messages |=== -For example, here is the message-driven bean used in <>: +For example, here is the message-driven bean used in xref:jms-examples/jms-examples.adoc#_receiving_messages_asynchronously_using_a_message_driven_bean[Receiving Messages Asynchronously Using a Message-Driven Bean]: [source,java] ---- @@ -305,11 +305,11 @@ The container can pool these instances to allow streams of messages to be proces The container attempts to deliver messages in chronological order when that would not impair the concurrency of message processing, but no guarantees are made as to the exact order in which messages are delivered to the instances of the message-driven bean class. If message order is essential to your application, you may want to configure your application server to use just one instance of the message-driven bean. -For details on the lifecycle of a message-driven bean, see <>. +For details on the lifecycle of a message-driven bean, see xref:entbeans:ejb-intro/ejb-intro.adoc#_the_lifecycle_of_a_message_driven_bean[The Lifecycle of a Message-Driven Bean]. === Managing Jakarta Transactions -Jakarta EE application clients and Java SE clients use JMS local transactions (described in <>), which allow the grouping of sends and receives within a specific Messaging session. +Jakarta EE application clients and Java SE clients use JMS local transactions (described in xref:jms-concepts/jms-concepts.adoc#_using_jakarta_messaging_local_transactions[Using Jakarta Messaging Local Transactions]), which allow the grouping of sends and receives within a specific Messaging session. Jakarta EE applications that run in the web or enterprise bean container commonly use Jakarta Transactions to ensure the integrity of accesses to external resources. The key difference between a Jakarta transaction and a Jakarta Messaging local transaction is that a Jakarta transaction is controlled by the application server's transaction managers. Jakarta transactions may be distributed, which means that they can encompass multiple resources in the same transaction, such as a Messaging provider and a database. @@ -329,7 +329,7 @@ You can specify appropriate transaction attributes for your enterprise bean meth + Use the `Required` transaction attribute (the default) to ensure that a method is always part of a transaction. If a transaction is in progress when the method is called, the method will be part of that transaction; if not, a new transaction will be started before the method is called and will be committed when the method returns. -See <> for more information. +See xref:supporttechs:transactions/transactions.adoc#_transaction_attributes[Transaction Attributes] for more information. * Bean-managed transactions: You can use these in conjunction with the `jakarta.transaction.UserTransaction` interface, which provides its own `commit` and `rollback` methods you can use to delimit transaction boundaries. Bean-managed transactions are recommended only for those who are experienced in programming transactions. diff --git a/src/main/asciidoc/jms-concepts/jms-concepts006.adoc b/src/main/antora/modules/messaging/pages/jms-concepts/jms-concepts006.adoc similarity index 100% rename from src/main/asciidoc/jms-concepts/jms-concepts006.adoc rename to src/main/antora/modules/messaging/pages/jms-concepts/jms-concepts006.adoc diff --git a/src/main/asciidoc/jms-examples/jms-examples.adoc b/src/main/antora/modules/messaging/pages/jms-examples/jms-examples.adoc similarity index 91% rename from src/main/asciidoc/jms-examples/jms-examples.adoc rename to src/main/antora/modules/messaging/pages/jms-examples/jms-examples.adoc index 212616db..11547248 100644 --- a/src/main/asciidoc/jms-examples/jms-examples.adoc +++ b/src/main/antora/modules/messaging/pages/jms-examples/jms-examples.adoc @@ -1,5 +1,7 @@ = Jakarta Messaging Examples +include::ROOT:partial$not_updated.adoc[] + This chapter provides examples that show how to use Jakarta Messaging in various kinds of Jakarta EE applications. include::jms-examples001.adoc[] diff --git a/src/main/asciidoc/jms-examples/jms-examples001.adoc b/src/main/antora/modules/messaging/pages/jms-examples/jms-examples001.adoc similarity index 77% rename from src/main/asciidoc/jms-examples/jms-examples001.adoc rename to src/main/antora/modules/messaging/pages/jms-examples/jms-examples001.adoc index 0508e1b5..6886494f 100644 --- a/src/main/asciidoc/jms-examples/jms-examples001.adoc +++ b/src/main/antora/modules/messaging/pages/jms-examples/jms-examples001.adoc @@ -1,6 +1,6 @@ == Building and Running Jakarta Messaging Examples -The examples are in the `_tut-install_/examples/jms/` directory. +The examples are in the `_jakartaee-examples_/tutorial/jms/` directory. To build and run each example: @@ -12,4 +12,4 @@ Before you deploy or run the examples, you need to create resources for them. Some examples have a `glassfish-resources.xml` file that is used to create resources for that example and others. You can use the `asadmin` command to create the resources. -To use the `asadmin` and `appclient` commands, you need to put the GlassFish Server `bin` directories in your command path, as described in <>. +To use the `asadmin` and `appclient` commands, you need to put the GlassFish Server `bin` directories in your command path, as described in xref:intro:usingexamples/usingexamples.adoc#_glassfish_server_installation_tips[GlassFish Server Installation Tips]. diff --git a/src/main/antora/modules/messaging/pages/jms-examples/jms-examples002.adoc b/src/main/antora/modules/messaging/pages/jms-examples/jms-examples002.adoc new file mode 100644 index 00000000..968d35e7 --- /dev/null +++ b/src/main/antora/modules/messaging/pages/jms-examples/jms-examples002.adoc @@ -0,0 +1,42 @@ +== Overview of the Jakarta Messaging Examples + +The following tables list the examples used in this chapter, describe what they do, and link to the section that describes them fully. +The example directory for each example is relative to the `_jakartaee-examples_/tutorial/jms/` directory. + +.Jakarta Messaging Examples That Show the Use of Jakarta EE Application Clients +[width="80%",cols="20%,60%"] +|=== +|Example Directory |Description + +|`simple/producer` |Using an application client to send messages; see xref:web:websocket/websocket.adoc#_sending_messages[Sending Messages] + +|`simple/synchconsumer` |Using an application client to receive messages synchronously; see xref:jms-examples/jms-examples.adoc#_receiving_messages_synchronously[Receiving Messages Synchronously] + +|`simple/asynchconsumer` |Using an application client to receive messages asynchronously; see xref:jms-examples/jms-examples.adoc#_using_a_message_listener_for_asynchronous_message_delivery[Using a Message Listener for Asynchronous Message Delivery] + +|`simple/messagebrowser` |Using an application client to use a `QueueBrowser` to browse a queue; see xref:jms-examples/jms-examples.adoc#_browsing_messages_on_a_queue[Browsing Messages on a Queue] + +|`simple/clientackconsumer` |Using an application client to acknowledge messages received synchronously; see xref:jms-examples/jms-examples.adoc#_acknowledging_messages[Acknowledging Messages] + +|`durablesubscriptionexample` |Using an application client to create a durable subscription on a topic; see xref:jms-examples/jms-examples.adoc#_using_durable_subscriptions[Using Durable Subscriptions] + +|`transactedexample` |Using an application client to send and receive messages in local transactions (also uses request-reply messaging); see xref:jms-examples/jms-examples.adoc#_using_local_transactions[Using Local Transactions] + +|`shared/sharedconsumer` |Using an application client to create shared nondurable topic subscriptions; see xref:jms-examples/jms-examples.adoc#_using_shared_nondurable_subscriptions[Using Shared Nondurable Subscriptions] + +|`shared/shareddurableconsumer` |Using an application client to create shared durable topic subscriptions; see xref:jms-examples/jms-examples.adoc#_using_shared_durable_subscriptions[Using Shared Durable Subscriptions] +|=== + +.Jakarta Messaging Examples That Show the Use of Jakarta EE Web and Enterprise Bean Components +[width="80%",cols="20%,60%"] +|=== +|Example Directory |Description + +|`websimplemessage` |Using managed beans to send messages and to receive messages synchronously; see xref:jms-examples/jms-examples.adoc#_sending_and_receiving_messages_using_a_simple_web_application[Sending and Receiving Messages Using a Simple Web Application] + +|`simplemessage` |Using an application client to send messages, and using a message-driven bean to receive messages asynchronously; see xref:jms-examples/jms-examples.adoc#_receiving_messages_asynchronously_using_a_message_driven_bean[Receiving Messages Asynchronously Using a Message-Driven Bean] + +|`clientsessionmdb` |Using a session bean to send messages, and using a message-driven bean to receive messages; see xref:jms-examples/jms-examples.adoc#_sending_messages_from_a_session_bean_to_an_mdb[Sending Messages from a Session Bean to an MDB] + +|`clientmdbentity` |Using an application client, two message-driven beans, and JPA persistence to create a simple HR application; see xref:jms-examples/jms-examples.adoc#_using_an_entity_to_join_messages_from_two_mdbs[Using an Entity to Join Messages from Two MDBs] +|=== diff --git a/src/main/asciidoc/jms-examples/jms-examples003.adoc b/src/main/antora/modules/messaging/pages/jms-examples/jms-examples003.adoc similarity index 91% rename from src/main/asciidoc/jms-examples/jms-examples003.adoc rename to src/main/antora/modules/messaging/pages/jms-examples/jms-examples003.adoc index 4d2bcea0..ae0e8fe8 100644 --- a/src/main/asciidoc/jms-examples/jms-examples003.adoc +++ b/src/main/antora/modules/messaging/pages/jms-examples/jms-examples003.adoc @@ -17,9 +17,9 @@ You can run the clients in two terminal windows. When you write a Messaging client to run in an enterprise bean application, you use many of the same methods in much the same sequence as for an application client. However, there are some significant differences. -<> describes these differences, and this chapter provides examples that illustrate them. +xref:jms-concepts/jms-concepts.adoc#_using_jakarta_messaging_in_jakarta_ee_applications[Using Jakarta Messaging in Jakarta EE Applications] describes these differences, and this chapter provides examples that illustrate them. -The examples for this section are in the `_tut-install_/examples/jms/simple/` directory, under the following subdirectories: +The examples for this section are in the `_jakartaee-examples_/tutorial/jms/simple/` directory, under the following subdirectories: `producer/` + `synchconsumer/` + @@ -32,7 +32,7 @@ Before running the examples, you need to start GlassFish Server and create admin === Starting the Jakarta Messaging Provider When you use GlassFish Server, your Messaging provider is GlassFish Server. -Start the server as described in <>. +Start the server as described in xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]. === Creating Jakarta Messaging Administered Objects @@ -54,13 +54,13 @@ You can also use the `asadmin create-jms-resource` command to create resources, A `glassfish-resources.xml` file in one of the Maven projects can create all the resources needed for the simple examples. -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . In a command window, go to the `Producer` example. + [source,shell] ---- -cd tut-install/jms/simple/producer +cd jakartaee-examples/tutorial/jms/simple/producer ---- . Create the resources using the `asadmin add-resources` command: @@ -104,7 +104,7 @@ You can build the examples using either NetBeans IDE or Maven. . In the *Open Project* dialog box, navigate to: + ---- -tut-install/examples/jms +jakartaee-examples/tutorial/jms ---- . Expand the `jms` node and select the `simple` folder. @@ -121,7 +121,7 @@ This command places the application client JAR files in the `target` directories + [source,shell] ---- -cd tut-install/jms/simple/ +cd jakartaee-examples/tutorial/jms/simple/ ---- . Enter the following command to build all the projects: @@ -147,7 +147,7 @@ General steps this example performs are as follows. . Accept and verify command-line arguments. You can use this example to send any number of messages to either a queue or a topic, so you specify the destination type and the number of messages on the command line when you run the program. -. Create a `JMSContext`, then send the specified number of text messages in the form of strings, as described in <>. +. Create a `JMSContext`, then send the specified number of text messages in the form of strings, as described in xref:jms-concepts/jms-concepts.adoc#_message_bodies[Message Bodies]. . Send a final message of type `Message` to indicate that the consumer should expect no more messages. @@ -257,7 +257,7 @@ If you do not specify a number of messages, the client sends one message. You will use the client to send three messages to a queue. -. Make sure that GlassFish Server has been started (see <>) and that you have created resources and built the simple Jakarta Messaging examples (see <> and <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]) and that you have created resources and built the simple Jakarta Messaging examples (see <<_creating_jakarta_messaging_administered_objects>> and <<_building_all_the_simple_examples>>). . In a terminal window, go to the `producer` directory: + @@ -385,7 +385,7 @@ The client displays the destination type and then waits for messages. + [source,shell] ---- -cd tut-install/jms/simple/producer +cd jakartaee-examples/tutorial/jms/simple/producer appclient -client target/producer.jar queue 3 ---- + @@ -418,7 +418,7 @@ appclient -client target/synchconsumer.jar topic + The result, however, is different. Because you are using a subscription on a topic, messages that were sent before you created the subscription on the topic will not be added to the subscription and delivered to the consumer. -(See <> and <> for details.) +(See xref:jms-concepts/jms-concepts.adoc#_publishsubscribe_messaging_style[Publish/Subscribe Messaging Style] and xref:jms-concepts/jms-concepts.adoc#_consuming_messages_from_topics[Consuming Messages from Topics] for details.) Instead of receiving the messages, the client waits for messages to arrive. . Leave the `SynchConsumer` client running and run the `Producer` client again: @@ -452,7 +452,7 @@ To allow asynchronous message delivery in a web or enterprise bean application, ==== Writing the AsynchConsumer.java and TextListener.java Clients -The sending client is `Producer.java`, the same client used in <>. +The sending client is `Producer.java`, the same client used in <<_receiving_messages_synchronously>>. An asynchronous consumer normally runs indefinitely. This one runs until the user types the character `q` or `Q` to stop the client. @@ -503,19 +503,19 @@ public void onMessage(Message m) { } ---- -For this example, you will use the same connection factory and destinations you created in <>. +For this example, you will use the same connection factory and destinations you created in <<_to_create_resources_for_the_simple_examples>>. The steps assume that you have already built and packaged all the examples using NetBeans IDE or Maven. ==== To Run the AsynchConsumer and Producer Clients -You will need two terminal windows, as you did in <>. +You will need two terminal windows, as you did in <<_receiving_messages_synchronously>>. . In the terminal window where you ran the `SynchConsumer` client, go to the `asynchconsumer` example directory: + [source,shell] ---- -cd tut-install/jms/simple/asynchconsumer +cd jakartaee-examples/tutorial/jms/simple/asynchconsumer ---- . Run the `AsynchConsumer` client, specifying the `topic` destination type: @@ -610,7 +610,7 @@ Message is not a TextMessage === Browsing Messages on a Queue -This section describes an example that creates a `QueueBrowser` object to examine messages on a queue, as described in <>. +This section describes an example that creates a `QueueBrowser` object to examine messages on a queue, as described in xref:jms-concepts/jms-concepts.adoc#_jakarta_messaging_queue_browsers[Jakarta Messaging Queue Browsers]. This section then explains how to compile, package, and run the example using GlassFish Server. ==== The MessageBrowser.java Client @@ -678,7 +678,7 @@ Properties: {JMSXDeliveryCount=0} Instead of displaying the message contents this way, you can call some of the `Message` interface's getter methods to retrieve the parts of the message you want to see. -For this example, you will use the connection factory and queue you created for <>. +For this example, you will use the connection factory and queue you created for <<_receiving_messages_synchronously>>. It is assumed that you have already built and packaged all the examples. ==== To Run the QueueBrowser Client @@ -693,7 +693,7 @@ To run the clients, you need two terminal windows. + [source,shell] ---- -cd tut-install/examples/jms/simple/producer/ +cd jakartaee-examples/tutorial/jms/simple/producer/ ---- . Run the `Producer` client, sending one message to the queue, along with the non-text control message: @@ -716,7 +716,7 @@ Text messages sent: 1 + [source,shell] ---- -cd tut-install/jms/simple/messagebrowser +cd jakartaee-examples/tutorial/jms/simple/messagebrowser ---- . Run the `MessageBrowser` client using the following command: @@ -844,9 +844,9 @@ Jakarta Messaging provides two alternative ways for a consuming client to ensure In the Jakarta EE platform, `CLIENT_ACKNOWLEDGE` sessions can be used only in application clients, as in this example. The `clientackconsumer` example demonstrates the first alternative, in which a synchronous consumer uses client acknowledgment. -The `asynchconsumer` example described in <> demonstrates the second alternative. +The `asynchconsumer` example described in <<_using_a_message_listener_for_asynchronous_message_delivery>> demonstrates the second alternative. -For information about message acknowledgment, see <>. +For information about message acknowledgment, see xref:jms-concepts/jms-concepts.adoc#_controlling_message_acknowledgment[Controlling Message Acknowledgment]. The following table describes four possible interactions between types of consumers and types of acknowledgment. @@ -864,7 +864,7 @@ The following table describes four possible interactions between types of consum |Asynchronous |Auto |Message is automatically acknowledged when `onMessage` method returns |=== -The example is under the `_tut-install_/examples/jms/simple/clientackconsumer/` directory. +The example is under the `_jakartaee-examples_/tutorial/jms/simple/clientackconsumer/` directory. The example client, `ClientAckConsumer.java`, creates a `JMSContext` that specifies client acknowledgment: @@ -885,7 +885,7 @@ context.acknowledge(); The example uses the following objects: -* The `jms/MyQueue` resource that you created for <>. +* The `jms/MyQueue` resource that you created for <<_receiving_messages_synchronously>>. * `java:comp/DefaultJMSConnectionFactory`, the platform default connection factory preconfigured with GlassFish Server @@ -894,7 +894,7 @@ The example uses the following objects: . In a terminal window, go to the following directory: + ---- -tut-install/examples/jms/simple/producer/ +jakartaee-examples/tutorial/jms/simple/producer/ ---- . Run the `Producer` client, sending some messages to the queue: @@ -907,7 +907,7 @@ appclient -client target/producer.jar queue 3 . In another terminal window, go to the following directory: + ---- -tut-install/examples/jms/simple/clientackconsumer/ +jakartaee-examples/tutorial/jms/simple/clientackconsumer/ ---- . To run the client, use the following command: diff --git a/src/main/asciidoc/jms-examples/jms-examples004.adoc b/src/main/antora/modules/messaging/pages/jms-examples/jms-examples004.adoc similarity index 84% rename from src/main/asciidoc/jms-examples/jms-examples004.adoc rename to src/main/antora/modules/messaging/pages/jms-examples/jms-examples004.adoc index cb4b3eff..90da647a 100644 --- a/src/main/asciidoc/jms-examples/jms-examples004.adoc +++ b/src/main/antora/modules/messaging/pages/jms-examples/jms-examples004.adoc @@ -9,9 +9,9 @@ It demonstrates that a durable subscription continues to exist and accumulate me The example consists of two modules, a `durableconsumer` application that creates a durable subscription and consumes messages, and an `unsubscriber` application that enables you to unsubscribe from the durable subscription after you have finished running the `durableconsumer` application. -For information on durable subscriptions, see <>. +For information on durable subscriptions, see xref:jms-concepts/jms-concepts.adoc#_creating_durable_subscriptions[Creating Durable Subscriptions]. -The main client, `DurableConsumer.java`, is under the `_tut-install_/examples/jms/durablesubscriptionexample/durableconsumer` directory. +The main client, `DurableConsumer.java`, is under the `_jakartaee-examples_/tutorial/jms/durablesubscriptionexample/durableconsumer` directory. The example uses a connection factory, `jms/DurableConnectionFactory`, that has a client ID. @@ -46,13 +46,13 @@ try (JMSContext context = durableConnectionFactory.createContext();) { ==== To Create Resources for the Durable Subscription Example -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . In a command window, go to the `durableconsumer` example. + [source,shell] ---- -cd tut-install/jms/durablesubscriptionexample/durableconsumer +cd jakartaee-examples/tutorial/jms/durablesubscriptionexample/durableconsumer ---- . Create the resources using the `asadmin add-resources` command: @@ -87,7 +87,7 @@ Command list-jms-resources executed successfully. . In a terminal window, go to the following directory: + ---- -tut-install/examples/jms/durablesubscriptionexample/ +jakartaee-examples/tutorial/jms/durablesubscriptionexample/ ---- . Build the `durableconsumer` and `unsubscriber` examples: @@ -124,7 +124,7 @@ To end program, enter Q or q, then + [source,shell] ---- -cd tut-install/examples/jms/simple/producer +cd jakartaee-examples/tutorial/jms/simple/producer appclient -client target/producer.jar topic 3 ---- @@ -163,7 +163,7 @@ After you have finished running the `DurableConsumer` client, run the `unsubscri . In a terminal window, go to the following directory: + ---- -tut-install/examples/jms/durablesubscriptionexample/unsubscriber +jakartaee-examples/tutorial/jms/durablesubscriptionexample/unsubscriber ---- . To run the `Unsubscriber` client, enter the following command: @@ -178,16 +178,16 @@ The client reports that it is unsubscribing from the durable subscription. === Using Local Transactions The `transactedexample` example demonstrates the use of local transactions in a Messaging client application. -It also demonstrates the use of the request/reply messaging pattern described in <>, although it uses permanent rather than temporary destinations. -The example consists of three modules, `genericsupplier`, `retailer`, and `vendor`, which can be found under the `_tut-install_/examples/jms/transactedexample/` directory. -The source code can be found in the `src/main/java/ee.jakarta.tutorial` trees for each module. +It also demonstrates the use of the request/reply messaging pattern described in xref:jms-concepts/jms-concepts.adoc#_creating_temporary_destinations[Creating Temporary Destinations], although it uses permanent rather than temporary destinations. +The example consists of three modules, `genericsupplier`, `retailer`, and `vendor`, which can be found under the `_jakartaee-examples_/tutorial/jms/transactedexample/` directory. +The source code can be found in the `src/main/java/jakarta.tutorial` trees for each module. The `genericsupplier` and `retailer` modules each contain a single class, `genericsupplier/GenericSupplier.java` and `retailer/Retailer.java`, respectively. The `vendor` module is more complex, containing four classes: `vendor/Vendor.java`, `vendor/VendorMessageListener.java`, `vendor/Order.java`, and `vendor/SampleUtilities.java`. The example shows how to use a queue and a topic in a single transaction as well as how to pass a `JMSContext` to a message listener's constructor function. The example represents a highly simplified e-commerce application in which the following actions occur. -. A retailer (`retailer/src/main/java/ee/jakarta/tutorial/retailer/Retailer.java`) sends a `MapMessage` to a vendor order queue, ordering a quantity of computers, and waits for the vendor's reply: +. A retailer (`retailer/src/main/java/jakarta/tutorial/retailer/Retailer.java`) sends a `MapMessage` to a vendor order queue, ordering a quantity of computers, and waits for the vendor's reply: + [source,java] ---- @@ -200,7 +200,7 @@ System.out.println("Retailer: ordered " + quantity + " computer(s)"); orderConfirmReceiver = context.createConsumer(retailerConfirmQueue); ---- -. The vendor (`vendor/src/main/java/ee/jakarta/tutorial/retailer/Vendor.java`) receives the retailer's order message and sends an order message to the supplier order topic in one transaction. +. The vendor (`vendor/src/main/java/jakarta/tutorial/vendor/Vendor.java`) receives the retailer's order message and sends an order message to the supplier order topic in one transaction. This Jakarta Messaging transaction uses a single session, so you can combine a receive from a queue with a send to a topic. Here is the code that uses the same session to create a consumer for a queue: + @@ -225,7 +225,7 @@ context.commit(); + For simplicity, there are only two suppliers, one for CPUs and one for hard drives. -. Each supplier (`genericsupplier/src/main/java/ee/jakarta/tutorial/retailer/GenericSupplier.java`) receives the order from the order topic, checks its inventory, and then sends the items ordered to the queue named in the order message's `JMSReplyTo` field. +. Each supplier (`genericsupplier/src/main/java/jakarta/tutorial/genericsupplier/GenericSupplier.java`) receives the order from the order topic, checks its inventory, and then sends the items ordered to the queue named in the order message's `JMSReplyTo` field. If it does not have enough of the item in stock, the supplier sends what it has. The synchronous receive from the topic and the send to the queue take place in one Jakarta Messaging transaction: + @@ -279,11 +279,11 @@ inMessage = (MapMessage) orderConfirmReceiver.receive(); + The retailer then places a second order for twice as many computers as in the first order, so these steps are executed twice. -<> illustrates these steps. +<<_transactions_messaging_client_example>> illustrates these steps. -[[transactions-messaging-client-example]] +[[_transactions_messaging_client_example]] .Transactions: Messaging Client Example -image::jakartaeett_dt_034.svg["Diagram of steps in transaction example"] +image::common:jakartaeett_dt_034.svg["Diagram of steps in transaction example"] All the messages use the `MapMessage` message type. Synchronous receives are used for all message reception except when the vendor processes the replies of the suppliers. @@ -297,13 +297,13 @@ The example uses three queues named `jms/AQueue`, `jms/BQueue`, and `jms/CQueue` ==== To Create Resources for the transactedexample Example -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . In a command window, go to the `genericsupplier` example: + [source,shell] ---- -cd tut-install/jms/transactedexample/genericsupplier +cd jakartaee-examples/tutorial/jms/transactedexample/genericsupplier ---- . Create the resources using the `asadmin add-resources` command: @@ -343,7 +343,7 @@ Make sure that you start the clients in the correct order. . In a terminal window, go to the following directory: + ---- -tut-install/examples/jms/transactedexample/ +jakartaee-examples/tutorial/jms/transactedexample/ ---- . To build and package all the modules, enter the following command: @@ -378,7 +378,7 @@ Starting CPU supplier + [source,shell] ---- -cd tut-install/examples/jms/transactedexample/genericsupplier +cd jakartaee-examples/tutorial/jms/transactedexample/genericsupplier ---- . Use the following command to start the hard drive supplier client: @@ -399,7 +399,7 @@ Starting Hard Drive supplier + [source,shell] ---- -cd tut-install/examples/jms/transactedexample/vendor +cd jakartaee-examples/tutorial/jms/transactedexample/vendor ---- . Use the following command to start the `Vendor` client: @@ -420,10 +420,10 @@ Starting vendor + [source,shell] ---- -cd tut-install/examples/jms/transactedexample/retailer +cd jakartaee-examples/tutorial/jms/transactedexample/retailer ---- -. [[transactedexample-step-10, Step 10]] Use a command like the following to run the `Retailer` client. +. [[_transactedexample_step_10, Step 10]] Use a command like the following to run the `Retailer` client. The argument specifies the number of computers to order: + [source,shell] @@ -488,7 +488,7 @@ Hard Drive Supplier: Sent 1 Hard Drive(s) Hard Drive Supplier: Committed transaction ---- -. Repeat <> as many times as you wish. +. Repeat <<_transactedexample_step_10>> as many times as you wish. Occasionally, the vendor will report an exception that causes a rollback: + [source,shell] diff --git a/src/main/asciidoc/jms-examples/jms-examples005.adoc b/src/main/antora/modules/messaging/pages/jms-examples/jms-examples005.adoc similarity index 87% rename from src/main/asciidoc/jms-examples/jms-examples005.adoc rename to src/main/antora/modules/messaging/pages/jms-examples/jms-examples005.adoc index d89650f5..8802ef6f 100644 --- a/src/main/asciidoc/jms-examples/jms-examples005.adoc +++ b/src/main/antora/modules/messaging/pages/jms-examples/jms-examples005.adoc @@ -8,7 +8,7 @@ These examples use both nondurable and durable shared consumers. This section describes the receiving clients in an example that shows how to use a shared consumer to distribute messages sent to a topic among different consumers. This section then explains how to compile and run the clients using GlassFish Server. -You may wish to compare this example to the results of <> using an unshared consumer. +You may wish to compare this example to the results of xref:jms-examples/jms-examples.adoc#_running_multiple_consumers_on_the_same_destination[Running Multiple Consumers on the Same Destination] using an unshared consumer. In that example, messages are distributed among the consumers on a queue, but each consumer on the topic receives all the messages because each consumer on the topic is using a separate topic subscription. In this example, however, messages are distributed among multiple consumers on a topic, because all the consumers are sharing the same subscription. @@ -46,25 +46,25 @@ The end of the `try-with-resources` block automatically causes the `JMSContext` The `TextListener.java` class is identical to the one for the `asynchconsumer` example. -For this example, you will use the default connection factory and the topic you created in <>. +For this example, you will use the default connection factory and the topic you created in xref:jms-examples/jms-examples.adoc#_to_create_resources_for_the_simple_examples[To Create Resources for the Simple Examples]. ==== To Run the SharedConsumer and Producer Clients -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . Open three command windows. In the first, go to the `simple/producer/` directory: + [source,shell] ---- -cd tut-install/examples/jms/simple/producer/ +cd jakartaee-examples/tutorial/jms/simple/producer/ ---- . In the second and third command windows, go to the `shared/sharedconsumer/` directory: + [source,shell] ---- -cd tut-install/examples/jms/shared/sharedconsumer/ +cd jakartaee-examples/tutorial/jms/shared/sharedconsumer/ ---- . In one of the `sharedconsumer` windows, build the example: @@ -108,7 +108,7 @@ The `shareddurableconsumer` client shows how to use shared durable subscriptions It shows how shared durable subscriptions combine the advantages of durable subscriptions (the subscription remains active when the client is not) with those of shared consumers (the message load can be divided among multiple clients). The example is much more similar to the `sharedconsumer` example than to the `DurableConsumer.java` client. -It uses two classes, `SharedDurableConsumer.java` and `TextListener.java`, which can be found under the `_tut-install_/examples/jms/shared/shareddurableconsumer/` directory. +It uses two classes, `SharedDurableConsumer.java` and `TextListener.java`, which can be found under the `_jakartaee-examples_/tutorial/jms/shared/shareddurableconsumer/` directory. The client uses `java:comp/DefaultJMSConnectionFactory`, the connection factory that does not have a client identifier, as is recommended for shared durable subscriptions. It uses the `createSharedDurableConsumer` method with a subscription name to establish the subscription: @@ -125,7 +125,7 @@ You run the example in combination with the `Producer.java` client. . In a terminal window, go to the following directory: + ---- -tut-install/examples/jms/shared/shareddurableconsumer +jakartaee-examples/tutorial/jms/shared/shareddurableconsumer ---- . To compile and package the client, enter the following command: @@ -157,7 +157,7 @@ The subscription remains active, although the client is not running. + [source,shell] ---- -cd tut-install/examples/jms/simple/producer +cd jakartaee-examples/tutorial/jms/simple/producer ---- . Run the `producer` example, sending a number of messages to the topic: diff --git a/src/main/asciidoc/jms-examples/jms-examples006.adoc b/src/main/antora/modules/messaging/pages/jms-examples/jms-examples006.adoc similarity index 82% rename from src/main/asciidoc/jms-examples/jms-examples006.adoc rename to src/main/antora/modules/messaging/pages/jms-examples/jms-examples006.adoc index 26a74e18..dcb76bb7 100644 --- a/src/main/asciidoc/jms-examples/jms-examples006.adoc +++ b/src/main/antora/modules/messaging/pages/jms-examples/jms-examples006.adoc @@ -1,16 +1,16 @@ == Sending and Receiving Messages Using a Simple Web Application -Web applications can use Jakarta Messaging to send and receive messages, as noted in <>. This section describes the components of a very simple web application that uses Jakarta Messaging. +Web applications can use Jakarta Messaging to send and receive messages, as noted in xref:jms-concepts/jms-concepts.adoc#_using_jakarta_ee_components_to_produce_and_to_synchronously_receive_messages[Using Jakarta EE Components to Produce and to Synchronously Receive Messages]. This section describes the components of a very simple web application that uses Jakarta Messaging. -This section assumes that you are familiar with the basics of Jakarta Faces technology, described in xref:the-web-tier[xrefstyle=full]. +This section assumes that you are familiar with the basics of Jakarta Faces technology, described in the xref:web:faces-intro/faces-intro.adoc#_introduction_to_jakarta_faces_technology[Introduction to Jakarta Faces Technology] -The example, `websimplemessage`, is under the `_tut-install_/jms/examples/` directory. +The example, `websimplemessage`, is under the `_jakartaee-examples_/tutorial/jms/` directory. It uses sending and receiving Facelets pages as well as corresponding backing beans. When a user enters a message in the text field of the sending page and clicks a button, the backing bean for the page sends the message to a queue and displays it on the page. When the user goes to the receiving page and clicks another button, the backing bean for that page receives the message synchronously and displays it. .The websimplemessage Application -image::jakartaeett_dt_035.svg["Diagram showing a web application in which a managed bean sends a message to a queue, and another managed bean receives the message from the queue."] +image::common:jakartaeett_dt_035.svg["Diagram showing a web application in which a managed bean sends a message to a queue, and another managed bean receives the message from the queue."] === The websimplemessage Facelets Pages @@ -110,14 +110,14 @@ This example uses an annotation-defined queue and the preconfigured default conn ==== To Package and Deploy websimplemessage Using NetBeans IDE -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . From the *File* menu, choose *Open Project*. . In the *Open Project* dialog box, navigate to: + ---- -tut-install/examples/jms +jakartaee-examples/tutorial/jms ---- . Select the `websimplemessage` folder. @@ -130,12 +130,12 @@ This command builds and deploys the project. ==== To Package and Deploy websimplemessage Using Maven -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . In a terminal window, go to: + ---- -tut-install/examples/jms/websimplemessage/ +jakartaee-examples/tutorial/jms/websimplemessage/ ---- . To compile the source files and package and deploy the application, use the following command: diff --git a/src/main/asciidoc/jms-examples/jms-examples007.adoc b/src/main/antora/modules/messaging/pages/jms-examples/jms-examples007.adoc similarity index 75% rename from src/main/asciidoc/jms-examples/jms-examples007.adoc rename to src/main/antora/modules/messaging/pages/jms-examples/jms-examples007.adoc index 5c045a42..ca81f902 100644 --- a/src/main/asciidoc/jms-examples/jms-examples007.adoc +++ b/src/main/antora/modules/messaging/pages/jms-examples/jms-examples007.adoc @@ -10,7 +10,7 @@ Message-driven beans can implement any messaging type. Most commonly, however, they implement the Jakarta Messaging technology. This section describes a simple message-driven bean example. -Before proceeding, you should read the basic conceptual information in the section <> as well as <>. +Before proceeding, you should read the basic conceptual information in the section xref:entbeans:ejb-intro/ejb-intro.adoc#_what_is_a_message_driven_bean[What Is a Message-Driven Bean?] as well as xref:jms-concepts/jms-concepts.adoc#_using_message_driven_beans_to_receive_messages_asynchronously[Using Message-Driven Beans to Receive Messages Asynchronously]. === Overview of the simplemessage Example @@ -20,15 +20,15 @@ The `simplemessage` application has the following components: * `SimpleMessageBean`: A message-driven bean that asynchronously processes the messages that are sent to the queue -<> illustrates the structure of this application. +<<_the_simplemessage_application>> illustrates the structure of this application. The application client sends messages to the queue, which was created administratively using the Administration Console. The Messaging provider (in this case, GlassFish Server) delivers the messages to the instances of the message-driven bean, which then processes the messages. -[[the-simplemessage-application]] +[[_the_simplemessage_application]] .The simplemessage Application -image::jakartaeett_dt_036.svg["Diagram of application showing an application client sending a message to a queue, and the message being delivered to a message-driven bean"] +image::common:jakartaeett_dt_036.svg["Diagram of application showing an application client sending a message to a queue, and the message being delivered to a message-driven bean"] -The source code for this application is in the `_tut-install_/examples/jms/simplemessage/` directory. +The source code for this application is in the `_jakartaee-examples_/tutorial/jms/simplemessage/` directory. === The simplemessage Application Client @@ -67,7 +67,7 @@ for (int i = 0; i < NUM_MSGS; i++) { === The simplemessage Message-Driven Bean Class -The code for the `SimpleMessageBean` class illustrates the requirements of a message-driven bean class described in <>. +The code for the `SimpleMessageBean` class illustrates the requirements of a message-driven bean class described in xref:jms-concepts/jms-concepts.adoc#_using_message_driven_beans_to_receive_messages_asynchronously[Using Message-Driven Beans to Receive Messages Asynchronously]. The first few lines of the `SimpleMessageBean` class use the `@MessageDriven` annotation's `activationConfig` attribute to specify configuration properties: @@ -81,9 +81,9 @@ The first few lines of the `SimpleMessageBean` class use the `@MessageDriven` an }) ---- -See <> for a list of the available properties. +See xref:jms-concepts/jms-concepts.adoc#_activationconfigproperty_settings_for_message_driven_beans[null] for a list of the available properties. -See <> for examples of the `subscriptionDurability`, `clientId`, `subscriptionName`, and `messageSelector` properties. +See xref:jms-examples/jms-examples.adoc#_sending_messages_from_a_session_bean_to_an_mdb[Sending Messages from a Session Bean to an MDB] for examples of the `subscriptionDurability`, `clientId`, `subscriptionName`, and `messageSelector` properties. ==== The onMessage Method @@ -123,21 +123,21 @@ You can use either NetBeans IDE or Maven to build, deploy, and run the `simpleme This example uses the queue named `jms/MyQueue` and the preconfigured default connection factory `java:comp/DefaultJMSConnectionFactory`. -If you have run the simple Jakarta Messaging examples in <> and have not deleted the resources, you already have the queue. -Otherwise, follow the instructions in <> to create it. +If you have run the simple Jakarta Messaging examples in xref:jms-examples/jms-examples.adoc#_writing_simple_jakarta_messaging_applications[Writing Simple Jakarta Messaging Applications] and have not deleted the resources, you already have the queue. +Otherwise, follow the instructions in xref:jms-examples/jms-examples.adoc#_to_create_resources_for_the_simple_examples[To Create Resources for the Simple Examples] to create it. -For more information on creating Messaging resources, see <>. +For more information on creating Messaging resources, see xref:jms-examples/jms-examples.adoc#_creating_jakarta_messaging_administered_objects[Creating Jakarta Messaging Administered Objects]. ==== To Run the simplemessage Example Using NetBeans IDE -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . From the *File* menu, choose *Open Project*. . In the *Open Project* dialog box, navigate to: + ---- -tut-install/examples/jms/simplemessage +jakartaee-examples/tutorial/jms/simplemessage ---- . Select the `simplemessage` folder. @@ -174,12 +174,12 @@ The received messages may appear in a different order from the order in which th ==== To Run the simplemessage Example Using Maven -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . In a terminal window, go to: + ---- -tut-install/examples/jms/simplemessage/ +jakartaee-examples/tutorial/jms/simplemessage/ ---- . To compile the source files and package the application, use the following command: diff --git a/src/main/asciidoc/jms-examples/jms-examples008.adoc b/src/main/antora/modules/messaging/pages/jms-examples/jms-examples008.adoc similarity index 81% rename from src/main/asciidoc/jms-examples/jms-examples008.adoc rename to src/main/antora/modules/messaging/pages/jms-examples/jms-examples008.adoc index 7dd95b99..ac72d1f8 100644 --- a/src/main/asciidoc/jms-examples/jms-examples008.adoc +++ b/src/main/antora/modules/messaging/pages/jms-examples/jms-examples008.adoc @@ -9,18 +9,18 @@ The application contains the following components: * A message-driven bean that receives and processes the messages using a durable topic subscription and a message selector -You will find the source files for this section in the `_tut-install_/examples/jms/clientsessionmdb/` directory. +You will find the source files for this section in the `_jakartaee-examples_/tutorial/jms/clientsessionmdb/` directory. Path names in this section are relative to this directory. === Writing the Application Components for the clientsessionmdb Example -This application demonstrates how to send messages from an enterprise bean (in this case, a session bean) rather than from an application client, as in the example in <>. -<> illustrates the structure of this application. -Sending messages from an enterprise bean is very similar to sending messages from a managed bean, which was shown in <>. +This application demonstrates how to send messages from an enterprise bean (in this case, a session bean) rather than from an application client, as in the example in xref:jms-examples/jms-examples.adoc#_receiving_messages_asynchronously_using_a_message_driven_bean[Receiving Messages Asynchronously Using a Message-Driven Bean]. +<<_an_enterprise_bean_application_client_to_session_bean_to_message_driven_bean>> illustrates the structure of this application. +Sending messages from an enterprise bean is very similar to sending messages from a managed bean, which was shown in xref:jms-examples/jms-examples.adoc#_sending_and_receiving_messages_using_a_simple_web_application[Sending and Receiving Messages Using a Simple Web Application]. -[[an-enterprise-bean-application-client-to-session-bean-to-message-driven-bean]] +[[_an_enterprise_bean_application_client_to_session_bean_to_message_driven_bean]] .An Enterprise Bean Application: Client to Session Bean to Message-Driven Bean -image::jakartaeett_dt_037.svg["Diagram of application showing an application client calling a session bean, which sends messages that are processed by a message-driven bean"] +image::common:jakartaeett_dt_037.svg["Diagram of application showing an application client calling a session bean, which sends messages that are processed by a message-driven bean"] The Publisher enterprise bean in this example is the enterprise-application equivalent of a wire-service news feed that categorizes news events into six news categories. The message-driven bean could represent a newsroom, where the sports desk, for example, would set up a subscription for all news events pertaining to sports. @@ -32,7 +32,7 @@ The message-driven bean uses a message selector for the property to limit which ==== Coding the Application Client: MyAppClient.java -The application client, `MyAppClient.java`, found under `clientsessionmdb-app-client`, performs no Messaging operations and so is simpler than the client in <>. +The application client, `MyAppClient.java`, found under `clientsessionmdb-app-client`, performs no Messaging operations and so is simpler than the client in xref:jms-examples/jms-examples.adoc#_receiving_messages_asynchronously_using_a_message_driven_bean[Receiving Messages Asynchronously Using a Message-Driven Bean]. The client uses dependency injection to obtain the Publisher enterprise bean's business interface: [source,java] @@ -77,11 +77,11 @@ The business method `publishNews` creates a `JMSProducer` and publishes the mess ==== Coding the Message-Driven Bean: MessageBean.java -The message-driven bean class, `MessageBean.java`, found under `clientsessionmdb-ejb`, is almost identical to the one in <>. +The message-driven bean class, `MessageBean.java`, found under `clientsessionmdb-ejb`, is almost identical to the one in xref:jms-examples/jms-examples.adoc#_receiving_messages_asynchronously_using_a_message_driven_bean[Receiving Messages Asynchronously Using a Message-Driven Bean]. However, the `@MessageDriven` annotation is different, because instead of a queue, the bean is using a topic, a durable subscription, and a message selector. The bean defines a topic for the use of the application; the definition uses the `java:module` scope because both the session bean and the message-driven bean are in the same module. Because the destination is defined in the message-driven bean, the `@MessageDriven` annotation uses the `destinationLookup` activation config property. -(See <> for more information.) +(See xref:jms-concepts/jms-concepts.adoc#_creating_resources_for_jakarta_ee_applications[Creating Resources for Jakarta EE Applications] for more information.) The annotation also sets the activation config properties `messageSelector`, `subscriptionDurability`, `clientId`, and `subscriptionName`, as follows: [source,java] @@ -119,14 +119,14 @@ This example uses an annotation-defined topic and the preconfigured default conn ==== To Run clientsessionmdb Using NetBeans IDE -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . From the *File* menu, choose *Open Project*. . In the *Open Project* dialog box, navigate to: + ---- -tut-install/examples/jms/clientsessionmdb +jakartaee-examples/tutorial/jms/clientsessionmdb ---- . Select the `clientsessionmdb` folder. @@ -164,12 +164,12 @@ Because of the message selector, the message-driven bean receives only the messa ==== To Run clientsessionmdb Using Maven -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . Go to the following directory: + ---- -tut-install/examples/jms/clientsessionmdb/ +jakartaee-examples/tutorial/jms/clientsessionmdb/ ---- . To compile the source files and package, deploy, and run the application, enter the following command: diff --git a/src/main/asciidoc/jms-examples/jms-examples009.adoc b/src/main/antora/modules/messaging/pages/jms-examples/jms-examples009.adoc similarity index 88% rename from src/main/asciidoc/jms-examples/jms-examples009.adoc rename to src/main/antora/modules/messaging/pages/jms-examples/jms-examples009.adoc index a0d331cd..ffcba0ff 100644 --- a/src/main/asciidoc/jms-examples/jms-examples009.adoc +++ b/src/main/antora/modules/messaging/pages/jms-examples/jms-examples009.adoc @@ -9,7 +9,7 @@ The application uses the following components: * An entity class -You will find the source files for this section in the `_tut-install_/examples/jms/clientmdbentity/` directory. +You will find the source files for this section in the `_jakartaee-examples_/tutorial/jms/clientmdbentity/` directory. Path names in this section are relative to this directory. === Overview of the clientmdbentity Example Application @@ -22,7 +22,7 @@ It then uses the information in all these messages to assemble a message that it The common term for this design pattern (which is not specific to Jakarta Messaging) is joining messages. Such a task must be transactional, with all the receives and the send as a single transaction. If not all the messages are received successfully, the transaction can be rolled back. -For an application client example that illustrates this task, see <>. +For an application client example that illustrates this task, see xref:jms-examples/jms-examples.adoc#_using_local_transactions[Using Local Transactions]. A message-driven bean can process only one message at a time in a transaction. To provide the ability to join messages, an application can have the message-driven bean store the interim information in a Jakarta Persistence entity. @@ -34,7 +34,7 @@ The basic steps of the application are as follows. . The HR department's application client generates an employee ID for each new hire and then publishes a message (M1) containing the new hire's name, employee ID, and position. It publishes the message to a topic because the message needs to be consumed by two message-driven beans. The client then creates a temporary queue, `ReplyQueue`, with a message listener that waits for a reply to the message. -(See <> for more information.) +(See xref:jms-concepts/jms-concepts.adoc#_creating_temporary_destinations[Creating Temporary Destinations] for more information.) . Two message-driven beans process each message: One bean, `OfficeMDB`, assigns the new hire's office number, and the other bean, `EquipmentMDB`, assigns the new hire's equipment. The first bean to process the message creates and persists an entity named `SetupOffice`, then calls a business method of the entity to store the information it has generated. @@ -45,17 +45,17 @@ The message-driven bean then sends to the reply queue a message (M2) describing Then it removes the entity. The application client's message listener retrieves the information. -<> illustrates the structure of this application. +<<_an_enterprise_bean_application_client_to_message_driven_beans_to_entity>> illustrates the structure of this application. Of course, an actual HR application would have more components; other beans could set up payroll and benefits records, schedule orientation, and so on. -<> assumes that `OfficeMDB` is the first message-driven bean to consume the message from the client. +<<_an_enterprise_bean_application_client_to_message_driven_beans_to_entity>> assumes that `OfficeMDB` is the first message-driven bean to consume the message from the client. `OfficeMDB` then creates and persists the `SetupOffice` entity and stores the office information. `EquipmentMDB` then finds the entity, stores the equipment information, and learns that the entity has completed its work. `EquipmentMDB` then sends the message to the reply queue and removes the entity. -[[an-enterprise-bean-application-client-to-message-driven-beans-to-entity]] +[[_an_enterprise_bean_application_client_to_message_driven_beans_to_entity]] .An Enterprise Bean Application: Client to Message-Driven Beans to Entity -image::jakartaeett_dt_038.svg["Diagram of application showing an application client, two message-driven beans, and an entity, as well as the associated topic and queue"] +image::common:jakartaeett_dt_038.svg["Diagram of application showing an application client, two message-driven beans, and an entity, as well as the associated topic and queue"] === Writing the Application Components for the clientmdbentity Example @@ -165,14 +165,14 @@ Because the example defines its own application-private topic and uses the preco ==== To Run clientmdbentity Using NetBeans IDE -. Make sure that GlassFish Server has been started (see <>), as well as the database server (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]), as well as the database server (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_apache_derby[Starting and Stopping Apache Derby]). . From the *File* menu, choose *Open Project*. . In the *Open Project* dialog box, navigate to: + ---- -tut-install/examples/jms/clientmdbentity +jakartaee-examples/tutorial/jms/clientmdbentity ---- . Select the `clientmdbentity` folder. @@ -195,12 +195,12 @@ The command then deploys the EAR file, retrieves the client stubs, and runs the ==== To Run clientmdbentity Using Maven -. Make sure that GlassFish Server has been started (see <>), as well as the database server (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]), as well as the database server (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_apache_derby[Starting and Stopping Apache Derby]). . Go to the following directory: + ---- -tut-install/examples/jms/clientmdbentity/ +jakartaee-examples/tutorial/jms/clientmdbentity/ ---- . To compile the source files and package, deploy, and run the application, enter the following command: diff --git a/src/main/asciidoc/jms-examples/jms-examples010.adoc b/src/main/antora/modules/messaging/pages/jms-examples/jms-examples010.adoc similarity index 100% rename from src/main/asciidoc/jms-examples/jms-examples010.adoc rename to src/main/antora/modules/messaging/pages/jms-examples/jms-examples010.adoc diff --git a/src/main/antora/modules/messaging/pages/mail-api/mail-api.adoc b/src/main/antora/modules/messaging/pages/mail-api/mail-api.adoc new file mode 100644 index 00000000..9e33aaaf --- /dev/null +++ b/src/main/antora/modules/messaging/pages/mail-api/mail-api.adoc @@ -0,0 +1,3 @@ += Jakarta Mail + +https://jakarta.ee/specifications/mail/2.1/jakarta-mail-spec-2.1[Jakarta Mail Specification] \ No newline at end of file diff --git a/src/main/asciidoc/persistence-basicexamples/persistence-basicexamples.adoc b/src/main/antora/modules/persist/pages/persistence-basicexamples/persistence-basicexamples.adoc similarity index 89% rename from src/main/asciidoc/persistence-basicexamples/persistence-basicexamples.adoc rename to src/main/antora/modules/persist/pages/persistence-basicexamples/persistence-basicexamples.adoc index 8a1cd1d5..98bc1925 100644 --- a/src/main/asciidoc/persistence-basicexamples/persistence-basicexamples.adoc +++ b/src/main/antora/modules/persist/pages/persistence-basicexamples/persistence-basicexamples.adoc @@ -1,5 +1,7 @@ = Running the Persistence Examples +include::ROOT:partial$not_updated.adoc[] + This chapter explains how to use Jakarta Persistence. The material here focuses on the source code and settings of three examples. diff --git a/src/main/asciidoc/persistence-basicexamples/persistence-basicexamples001.adoc b/src/main/antora/modules/persist/pages/persistence-basicexamples/persistence-basicexamples001.adoc similarity index 75% rename from src/main/asciidoc/persistence-basicexamples/persistence-basicexamples001.adoc rename to src/main/antora/modules/persist/pages/persistence-basicexamples/persistence-basicexamples001.adoc index b395ab59..9e08ddcf 100644 --- a/src/main/asciidoc/persistence-basicexamples/persistence-basicexamples001.adoc +++ b/src/main/antora/modules/persist/pages/persistence-basicexamples/persistence-basicexamples001.adoc @@ -3,4 +3,4 @@ The first example, `order`, is an application that uses a stateful session bean to manage entities related to an ordering system. The second example, `roster`, is an application that manages a community sports system. The third example, `address-book`, is a web application that stores contact data. -This chapter assumes that you are familiar with the concepts detailed in <>. +This chapter assumes that you are familiar with the concepts detailed in xref:persistence-intro/persistence-intro.adoc#_introduction_to_jakarta_persistence[Introduction to Jakarta Persistence]. diff --git a/src/main/asciidoc/persistence-basicexamples/persistence-basicexamples002.adoc b/src/main/antora/modules/persist/pages/persistence-basicexamples/persistence-basicexamples002.adoc similarity index 94% rename from src/main/asciidoc/persistence-basicexamples/persistence-basicexamples002.adoc rename to src/main/antora/modules/persist/pages/persistence-basicexamples/persistence-basicexamples002.adoc index 28bfef6b..694c4937 100644 --- a/src/main/asciidoc/persistence-basicexamples/persistence-basicexamples002.adoc +++ b/src/main/antora/modules/persist/pages/persistence-basicexamples/persistence-basicexamples002.adoc @@ -11,11 +11,11 @@ What is the order number? What parts are included in the order? What parts make The `order` application consists of a single WAR module that includes the enterprise bean classes, the entities, the support classes, and the Facelets XHTML and class files. -The database schema in the Derby database for `order` is shown in <>. +The database schema in the Derby database for `order` is shown in <<_database_schema_for_the_order_application>>. -[[database-schema-for-the-order-application]] +[[_database_schema_for_the_order_application]] .Database Schema for the order Application -image::jakartaeett_dt_024.svg["Diagram showing the database schema for the order application"] +image::common:jakartaeett_dt_024.svg["Diagram showing the database schema for the order application"] [NOTE] In this diagram, for simplicity, the `PERSISTENCE_ORDER_` prefix is omitted from the table names. @@ -172,7 +172,7 @@ The primary key field `vendorPartNumber` is of type `Long`, as the generated pri ==== Compound Primary Keys -A compound primary key is made up of multiple fields and follows the requirements described in <>. +A compound primary key is made up of multiple fields and follows the requirements described in xref:persistence-intro/persistence-intro.adoc#_primary_keys_in_entities[Primary Keys in Entities]. To use a compound primary key, you must create a wrapper class. In `order`, two entities use compound primary keys: `Part` and `LineItem`. @@ -280,7 +280,7 @@ public CustomerOrder getCustomerOrder() { } ---- -For `customerOrder`, you also use the `@JoinColumn` annotation to specify the column name in the table and that this column is an overlapping foreign key pointing at the `PERSISTENCE_ORDER_CUSTOMERORDER` table's `ORDERID` column (see <>). +For `customerOrder`, you also use the `@JoinColumn` annotation to specify the column name in the table and that this column is an overlapping foreign key pointing at the `PERSISTENCE_ORDER_CUSTOMERORDER` table's `ORDERID` column (see <<_one_to_many_relationship_mapped_to_overlapping_primary_and_foreign_keys>>). That is, `customerOrder` will be set by the `CustomerOrder` entity. In ``LineItem``'s constructor, the line item number (`LineItem.itemId`) is set using the `CustomerOrder.getNextId` method: @@ -580,16 +580,16 @@ First, you will create the database tables in Apache Derby. ==== To Run the order Example Using NetBeans IDE -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). -. If the database server is not already running, start it by following the instructions in <>. +. If the database server is not already running, start it by following the instructions in xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_apache_derby[Starting and Stopping Apache Derby]. . From the *File* menu, choose *Open Project*. . In the *Open Project* dialog box, navigate to: + ---- -tut-install/examples/persistence +jakartaee-examples/tutorial/persistence ---- . Select the `order` folder. @@ -606,14 +606,14 @@ http://localhost:8080/order/ ==== To Run the order Example Using Maven -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). -. If the database server is not already running, start it by following the instructions in <>. +. If the database server is not already running, start it by following the instructions in xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_apache_derby[Starting and Stopping Apache Derby]. . In a terminal window, go to: + ---- -tut-install/examples/persistence/order/ +jakartaee-examples/tutorial/persistence/order/ ---- . Enter the following command: @@ -623,7 +623,7 @@ tut-install/examples/persistence/order/ mvn install ---- + -This compiles the source files and packages the application into a WAR file located at `_tut-install_/examples/persistence/order/target/order.war`. +This compiles the source files and packages the application into a WAR file located at `_jakartaee-examples_/tutorial/persistence/order/target/order.war`. Then the WAR file is deployed to your GlassFish Server instance. . To create and update the order data, open a web browser to the following URL: diff --git a/src/main/asciidoc/persistence-basicexamples/persistence-basicexamples003.adoc b/src/main/antora/modules/persist/pages/persistence-basicexamples/persistence-basicexamples003.adoc similarity index 92% rename from src/main/asciidoc/persistence-basicexamples/persistence-basicexamples003.adoc rename to src/main/antora/modules/persist/pages/persistence-basicexamples/persistence-basicexamples003.adoc index 3e9ba19b..c7561ba0 100644 --- a/src/main/asciidoc/persistence-basicexamples/persistence-basicexamples003.adoc +++ b/src/main/antora/modules/persist/pages/persistence-basicexamples/persistence-basicexamples003.adoc @@ -5,11 +5,11 @@ The application has four components: Jakarta Persistence entities (`Player`, `Te Functionally, `roster` is similar to the `order` application, with three new features that `order` does not have: many-to-many relationships, entity inheritance, and automatic table creation at deployment time. -The database schema in Apache Derby for the `roster` application is shown in <>. +The database schema in Apache Derby for the `roster` application is shown in <<_database_schema_for_the_roster_application>>. -[[database-schema-for-the-roster-application]] +[[_database_schema_for_the_roster_application]] .Database Schema for the roster Application -image::jakartaeett_dt_025.svg["Diagram showing the database schema for the roster application"] +image::common:jakartaeett_dt_025.svg["Diagram showing the database schema for the roster application"] [NOTE] In this diagram, for simplicity, the `PERSISTENCE_ROSTER_` prefix is omitted from the table names. @@ -72,7 +72,7 @@ public Collection getTeams() { === Entity Inheritance in the roster Application -The `roster` application shows how to use entity inheritance, as described in <>. +The `roster` application shows how to use entity inheritance, as described in xref:persistence-intro/persistence-intro.adoc#_entity_inheritance[Entity Inheritance]. The `League` entity in `roster` is an abstract entity with two concrete subclasses: `SummerLeague` and `WinterLeague`. Because `League` is an abstract class, it cannot be instantiated: @@ -256,16 +256,16 @@ You can use either NetBeans IDE or Maven to build, package, deploy, and run the ==== To Run the roster Example Using NetBeans IDE -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). -. If the database server is not already running, start it by following the instructions in <>. +. If the database server is not already running, start it by following the instructions in xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_apache_derby[Starting and Stopping Apache Derby]. . From the *File* menu, choose *Open Project*. . In the *Open Project* dialog box, navigate to: + ---- -tut-install/examples/persistence +jakartaee-examples/tutorial/persistence ---- . Select the `roster` folder. @@ -303,14 +303,14 @@ P25 Frank Fletcher defender 399.0 ==== To Run the roster Example Using Maven -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). -. If the database server is not already running, start it by following the instructions in <>. +. If the database server is not already running, start it by following the instructions in xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_apache_derby[Starting and Stopping Apache Derby]. . In a terminal window, go to: + ---- -tut-install/examples/persistence/roster/roster-ear/ +jakartaee-examples/tutorial/persistence/roster/roster-ear/ ---- . Enter the following command: @@ -320,7 +320,7 @@ tut-install/examples/persistence/roster/roster-ear/ mvn install ---- + -This compiles the source files and packages the application into an EAR file located at `_tut-install_/examples/persistence/roster/target/roster.ear`. +This compiles the source files and packages the application into an EAR file located at `_jakartaee-examples_/tutorial/persistence/roster/target/roster.ear`. The EAR file is then deployed to GlassFish Server. GlassFish Server will then drop and create the database tables during deployment, as specified in `persistence.xml`. + diff --git a/src/main/asciidoc/persistence-basicexamples/persistence-basicexamples004.adoc b/src/main/antora/modules/persist/pages/persistence-basicexamples/persistence-basicexamples004.adoc similarity index 87% rename from src/main/asciidoc/persistence-basicexamples/persistence-basicexamples004.adoc rename to src/main/antora/modules/persist/pages/persistence-basicexamples/persistence-basicexamples004.adoc index 0fef524b..b9859c8f 100644 --- a/src/main/asciidoc/persistence-basicexamples/persistence-basicexamples004.adoc +++ b/src/main/antora/modules/persist/pages/persistence-basicexamples/persistence-basicexamples004.adoc @@ -1,7 +1,7 @@ == The address-book Application The `address-book` example application is a simple web application that stores contact data. -It uses a single entity class, `Contact`, that uses Jakarta Bean Validation to validate the data stored in the persistent attributes of the entity, as described in <>. +It uses a single entity class, `Contact`, that uses Jakarta Bean Validation to validate the data stored in the persistent attributes of the entity, as described in xref:persistence-intro/persistence-intro.adoc#_validating_persistent_fields_and_properties[Validating Persistent Fields and Properties]. === Bean Validation Constraints in address-book @@ -75,7 +75,7 @@ The message can be specified directly: protected String homePhone; ---- -The constraints in `Contact`, however, are strings in the resource bundle `ValidationMessages.properties`, under `_tut-install_/examples/persistence/address-book/src/java/`. +The constraints in `Contact`, however, are strings in the resource bundle `ValidationMessages.properties`, under `_jakartaee-examples_/tutorial/persistence/address-book/src/main/java`. This allows the validation messages to be located in one single properties file and the messages to be easily localized. Overridden Bean Validation messages must be placed in a resource bundle properties file named `ValidationMessages.properties` in the default package, with localized resource bundles taking the form `ValidationMessages___locale-prefix__.properties`. For example, `ValidationMessages_es.properties` is the resource bundle used in Spanish-speaking locales. @@ -125,16 +125,16 @@ You can use either NetBeans IDE or Maven to build, package, deploy, and run the ==== To Run the address-book Example Using NetBeans IDE -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). -. If the database server is not already running, start it by following the instructions in <>. +. If the database server is not already running, start it by following the instructions in xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_apache_derby[Starting and Stopping Apache Derby]. . From the *File* menu, choose *Open Project*. . In the *Open Project* dialog box, navigate to: + ---- -tut-install/examples/persistence +jakartaee-examples/tutorial/persistence ---- . Select the `address-book` folder. @@ -156,14 +156,14 @@ If any of the values entered violate the constraints in `Contact`, an error mess ==== To Run the address-book Example Using Maven -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). -. If the database server is not already running, start it by following the instructions in <>. +. If the database server is not already running, start it by following the instructions in xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_apache_derby[Starting and Stopping Apache Derby]. . In a terminal window, go to: + ---- -tut-install/examples/persistence/address-book/ +jakartaee-examples/tutorial/persistence/address-book/ ---- . Enter the following command: diff --git a/src/main/asciidoc/persistence-cache/persistence-cache.adoc b/src/main/antora/modules/persist/pages/persistence-cache/persistence-cache.adoc similarity index 87% rename from src/main/asciidoc/persistence-cache/persistence-cache.adoc rename to src/main/antora/modules/persist/pages/persistence-cache/persistence-cache.adoc index c0237996..8305697f 100644 --- a/src/main/asciidoc/persistence-cache/persistence-cache.adoc +++ b/src/main/antora/modules/persist/pages/persistence-cache/persistence-cache.adoc @@ -1,5 +1,7 @@ = Using a Second-Level Cache with Jakarta Persistence Applications +include::ROOT:partial$not_updated.adoc[] + This chapter explains how to modify the second-level cache mode settings to improve the performance of applications that use the Jakarta Persistence. include::persistence-cache001.adoc[] diff --git a/src/main/asciidoc/persistence-cache/persistence-cache001.adoc b/src/main/antora/modules/persist/pages/persistence-cache/persistence-cache001.adoc similarity index 92% rename from src/main/asciidoc/persistence-cache/persistence-cache001.adoc rename to src/main/antora/modules/persist/pages/persistence-cache/persistence-cache001.adoc index 9853e920..8d66bad1 100644 --- a/src/main/asciidoc/persistence-cache/persistence-cache001.adoc +++ b/src/main/antora/modules/persist/pages/persistence-cache/persistence-cache001.adoc @@ -12,7 +12,7 @@ Portable applications should not rely on support by persistence providers for a The second-level cache for a persistence unit may be configured to one of several second-level cache modes. The following cache mode settings are defined by Jakarta Persistence. -[[cache-mode-settings-for-the-second-level-cache]] +[[_cache_mode_settings_for_the_second_level_cache]] .Cache Mode Settings for the Second-Level Cache [width="80%",cols="20%,60%"] |=== @@ -36,9 +36,9 @@ To avoid stale reads, use any of these strategies: * Change the second-level cache to one of the cache mode settings -* Control which entities may be cached (see <>) +* Control which entities may be cached (see <<_controlling_whether_entities_may_be_cached>>) -* Change the cache's retrieval or store modes (see <>) +* Change the cache's retrieval or store modes (see xref:persistence-cache/persistence-cache.adoc#_setting_the_cache_retrieval_and_store_modes[Setting the Cache Retrieval and Store Modes]) Which of these strategies works best to avoid stale reads depends upon the application. diff --git a/src/main/asciidoc/persistence-cache/persistence-cache002.adoc b/src/main/antora/modules/persist/pages/persistence-cache/persistence-cache002.adoc similarity index 100% rename from src/main/asciidoc/persistence-cache/persistence-cache002.adoc rename to src/main/antora/modules/persist/pages/persistence-cache/persistence-cache002.adoc diff --git a/src/main/asciidoc/persistence-criteria/persistence-criteria.adoc b/src/main/antora/modules/persist/pages/persistence-criteria/persistence-criteria.adoc similarity index 91% rename from src/main/asciidoc/persistence-criteria/persistence-criteria.adoc rename to src/main/antora/modules/persist/pages/persistence-criteria/persistence-criteria.adoc index 769b38b8..70f196b6 100644 --- a/src/main/asciidoc/persistence-criteria/persistence-criteria.adoc +++ b/src/main/antora/modules/persist/pages/persistence-criteria/persistence-criteria.adoc @@ -1,5 +1,7 @@ = Using the Criteria API to Create Queries +include::ROOT:partial$not_updated.adoc[] + The Criteria API is used to define queries for entities and their persistent state by creating query-defining objects. Criteria queries are written using Java programming language APIs, are typesafe, and are portable. Such queries work regardless of the underlying data store. diff --git a/src/main/asciidoc/persistence-criteria/persistence-criteria001.adoc b/src/main/antora/modules/persist/pages/persistence-criteria/persistence-criteria001.adoc similarity index 100% rename from src/main/asciidoc/persistence-criteria/persistence-criteria001.adoc rename to src/main/antora/modules/persist/pages/persistence-criteria/persistence-criteria001.adoc diff --git a/src/main/asciidoc/persistence-criteria/persistence-criteria002.adoc b/src/main/antora/modules/persist/pages/persistence-criteria/persistence-criteria002.adoc similarity index 100% rename from src/main/asciidoc/persistence-criteria/persistence-criteria002.adoc rename to src/main/antora/modules/persist/pages/persistence-criteria/persistence-criteria002.adoc diff --git a/src/main/asciidoc/persistence-criteria/persistence-criteria003.adoc b/src/main/antora/modules/persist/pages/persistence-criteria/persistence-criteria003.adoc similarity index 96% rename from src/main/asciidoc/persistence-criteria/persistence-criteria003.adoc rename to src/main/antora/modules/persist/pages/persistence-criteria/persistence-criteria003.adoc index c37a2c2d..ba5d3275 100644 --- a/src/main/asciidoc/persistence-criteria/persistence-criteria003.adoc +++ b/src/main/antora/modules/persist/pages/persistence-criteria/persistence-criteria003.adoc @@ -149,9 +149,9 @@ To create `Expression` instances, use methods defined in the `Expression` and `C ==== The Expression Interface Methods An `Expression` object is used in a query's `SELECT`, `WHERE`, or `HAVING` clause. -<> shows conditional methods you can use with `Expression` objects. +<<_conditional_methods_in_the_expression_interface>> shows conditional methods you can use with `Expression` objects. -[[conditional-methods-in-the-expression-interface]] +[[_conditional_methods_in_the_expression_interface]] .Conditional Methods in the Expression Interface [width="50%",cols="15%,35%"] |=== @@ -188,9 +188,9 @@ The `in` method can also check whether an attribute is a member of a collection. The `CriteriaBuilder` interface defines additional methods for creating expressions. These methods correspond to the arithmetic, string, date, time, and case operators and functions of JPQL. -<> shows conditional methods you can use with `CriteriaBuilder` objects. +<<_conditional_methods_in_the_criteriabuilder_interface>> shows conditional methods you can use with `CriteriaBuilder` objects. -[[conditional-methods-in-the-criteriabuilder-interface]] +[[_conditional_methods_in_the_criteriabuilder_interface]] .Conditional Methods in the CriteriaBuilder Interface [width="60%",cols="15%,45%"] |=== @@ -252,9 +252,9 @@ Root pet = cq.from(Pet.class); cq.where(cb.like(pet.get(Pet_.name), "*do")); ---- -To specify multiple conditional predicates, use the compound predicate methods of the `CriteriaBuilder` interface, as shown in <>. +To specify multiple conditional predicates, use the compound predicate methods of the `CriteriaBuilder` interface, as shown in <<_compound_predicate_methods_in_the_criteriabuildder_interface>>. -[[compound-predicate-methods-in-the-criteriabuildder-interface]] +[[_compound_predicate_methods_in_the_criteriabuildder_interface]] .Compound Predicate Methods in the CriteriaBuilder Interface [width="50%",cols="15%,35%"] |=== diff --git a/src/main/asciidoc/persistence-entitygraphs/persistence-entitygraphs.adoc b/src/main/antora/modules/persist/pages/persistence-entitygraphs/persistence-entitygraphs.adoc similarity index 89% rename from src/main/asciidoc/persistence-entitygraphs/persistence-entitygraphs.adoc rename to src/main/antora/modules/persist/pages/persistence-entitygraphs/persistence-entitygraphs.adoc index 06634cb1..17a93ae5 100644 --- a/src/main/asciidoc/persistence-entitygraphs/persistence-entitygraphs.adoc +++ b/src/main/antora/modules/persist/pages/persistence-entitygraphs/persistence-entitygraphs.adoc @@ -1,5 +1,7 @@ = Creating Fetch Plans with Entity Graphs +include::ROOT:partial$not_updated.adoc[] + This chapter explains how to use entity graphs to create fetch plans for Jakarta Persistence operations and queries. include::persistence-entitygraphs001.adoc[] diff --git a/src/main/asciidoc/persistence-entitygraphs/persistence-entitygraphs001.adoc b/src/main/antora/modules/persist/pages/persistence-entitygraphs/persistence-entitygraphs001.adoc similarity index 100% rename from src/main/asciidoc/persistence-entitygraphs/persistence-entitygraphs001.adoc rename to src/main/antora/modules/persist/pages/persistence-entitygraphs/persistence-entitygraphs001.adoc diff --git a/src/main/asciidoc/persistence-entitygraphs/persistence-entitygraphs002.adoc b/src/main/antora/modules/persist/pages/persistence-entitygraphs/persistence-entitygraphs002.adoc similarity index 100% rename from src/main/asciidoc/persistence-entitygraphs/persistence-entitygraphs002.adoc rename to src/main/antora/modules/persist/pages/persistence-entitygraphs/persistence-entitygraphs002.adoc diff --git a/src/main/asciidoc/persistence-entitygraphs/persistence-entitygraphs003.adoc b/src/main/antora/modules/persist/pages/persistence-entitygraphs/persistence-entitygraphs003.adoc similarity index 100% rename from src/main/asciidoc/persistence-entitygraphs/persistence-entitygraphs003.adoc rename to src/main/antora/modules/persist/pages/persistence-entitygraphs/persistence-entitygraphs003.adoc diff --git a/src/main/asciidoc/persistence-entitygraphs/persistence-entitygraphs004.adoc b/src/main/antora/modules/persist/pages/persistence-entitygraphs/persistence-entitygraphs004.adoc similarity index 100% rename from src/main/asciidoc/persistence-entitygraphs/persistence-entitygraphs004.adoc rename to src/main/antora/modules/persist/pages/persistence-entitygraphs/persistence-entitygraphs004.adoc diff --git a/src/main/asciidoc/persistence-intro/persistence-intro.adoc b/src/main/antora/modules/persist/pages/persistence-intro/persistence-intro.adoc similarity index 89% rename from src/main/asciidoc/persistence-intro/persistence-intro.adoc rename to src/main/antora/modules/persist/pages/persistence-intro/persistence-intro.adoc index 5cfbaa81..ed4b56fb 100644 --- a/src/main/asciidoc/persistence-intro/persistence-intro.adoc +++ b/src/main/antora/modules/persist/pages/persistence-intro/persistence-intro.adoc @@ -1,5 +1,7 @@ = Introduction to Jakarta Persistence +include::ROOT:partial$not_updated.adoc[] + This chapter provides a description of Jakarta Persistence. include::persistence-intro001.adoc[] diff --git a/src/main/asciidoc/persistence-intro/persistence-intro001.adoc b/src/main/antora/modules/persist/pages/persistence-intro/persistence-intro001.adoc similarity index 100% rename from src/main/asciidoc/persistence-intro/persistence-intro001.adoc rename to src/main/antora/modules/persist/pages/persistence-intro/persistence-intro001.adoc diff --git a/src/main/asciidoc/persistence-intro/persistence-intro002.adoc b/src/main/antora/modules/persist/pages/persistence-intro/persistence-intro002.adoc similarity index 97% rename from src/main/asciidoc/persistence-intro/persistence-intro002.adoc rename to src/main/antora/modules/persist/pages/persistence-intro/persistence-intro002.adoc index b0e68e2f..86d7f72b 100644 --- a/src/main/asciidoc/persistence-intro/persistence-intro002.adoc +++ b/src/main/antora/modules/persist/pages/persistence-intro/persistence-intro002.adoc @@ -197,9 +197,9 @@ When adding Bean Validation constraints, use the same access strategy as the per That is, if the persistent class uses field access, apply the Bean Validation constraint annotations on the class's fields. If the class uses property access, apply the constraints on the getter methods. -<> lists Bean Validation's built-in constraints, defined in the `jakarta.validation.constraints` package. +xref:beanvalidation:bean-validation/bean-validation.adoc#built_in_jakarta_bean_validation_constraints[Built In Jakarta Bean Validation Constraints] lists Bean Validation's built-in constraints, defined in the `jakarta.validation.constraints` package. -All the built-in constraints listed in <> have a corresponding annotation, `_ConstraintName_.List`, for grouping multiple constraints of the same type on the same field or property. +All the built-in constraints listed in xref:beanvalidation:bean-validation/bean-validation.adoc#built_in_jakarta_bean_validation_constraints[Built In Jakarta Bean Validation Constraints] have a corresponding annotation, `_ConstraintName_.List`, for grouping multiple constraints of the same type on the same field or property. For example, the following persistent field has two `@Pattern` constraints: [source,java] @@ -417,9 +417,9 @@ For example, a line item is part of an order; if the order is deleted, the line This is called a cascade delete relationship. The `jakarta.persistence.CascadeType` enumerated type defines the cascade operations that are applied in the `cascade` element of the relationship annotations. -<> lists the cascade operations for entities. +<<_cascade_operations_for_entities>> lists the cascade operations for entities. -[[cascade-operations-for-entities]] +[[_cascade_operations_for_entities]] .Cascade Operations for Entities [width="75%",cols="15%,60%"] |=== diff --git a/src/main/asciidoc/persistence-intro/persistence-intro003.adoc b/src/main/antora/modules/persist/pages/persistence-intro/persistence-intro003.adoc similarity index 94% rename from src/main/asciidoc/persistence-intro/persistence-intro003.adoc rename to src/main/antora/modules/persist/pages/persistence-intro/persistence-intro003.adoc index 000f3901..a674d2e3 100644 --- a/src/main/asciidoc/persistence-intro/persistence-intro003.adoc +++ b/src/main/antora/modules/persist/pages/persistence-intro/persistence-intro003.adoc @@ -4,7 +4,7 @@ Entities support class inheritance, polymorphic associations, and polymorphic qu Entity classes can extend non-entity classes, and non-entity classes can extend entity classes. Entity classes can be both abstract and concrete. -The `roster` example application demonstrates entity inheritance, as described in <>. +The `roster` example application demonstrates entity inheritance, as described in xref:persistence-basicexamples/persistence-basicexamples.adoc#_entity_inheritance_in_the_roster_application[Entity Inheritance in the roster Application]. === Abstract Entities @@ -106,9 +106,9 @@ The default strategy, `InheritanceType.SINGLE_TABLE`, is used if the `@Inheritan With this strategy, which corresponds to the default `InheritanceType.SINGLE_TABLE`, all classes in the hierarchy are mapped to a single table in the database. This table has a discriminator column containing a value that identifies the subclass to which the instance represented by the row belongs. -The discriminator column, whose elements are shown in <>, can be specified by using the `jakarta.persistence.DiscriminatorColumn` annotation on the root of the entity class hierarchy. +The discriminator column, whose elements are shown in <<_discriminator_column_elements>>, can be specified by using the `jakarta.persistence.DiscriminatorColumn` annotation on the root of the entity class hierarchy. -[[discriminator-column-elements]] +[[_discriminator_column_elements]] .@DiscriminatorColumn Elements [width="99%",cols="20%,20%,60%"] |=== @@ -177,4 +177,4 @@ Similarly, queries that cover the entire class hierarchy require join operations Some Jakarta Persistence providers, including the default provider in GlassFish Server, require a discriminator column that corresponds to the root entity when using the joined subclass strategy. If you are not using automatic table creation in your application, make sure that the database table is set up correctly for the discriminator column defaults, or use the `@DiscriminatorColumn` annotation to match your database schema. -For information on discriminator columns, see <>. +For information on discriminator columns, see <<_the_single_table_per_class_hierarchy_strategy>>. diff --git a/src/main/asciidoc/persistence-intro/persistence-intro004.adoc b/src/main/antora/modules/persist/pages/persistence-intro/persistence-intro004.adoc similarity index 100% rename from src/main/asciidoc/persistence-intro/persistence-intro004.adoc rename to src/main/antora/modules/persist/pages/persistence-intro/persistence-intro004.adoc diff --git a/src/main/asciidoc/persistence-intro/persistence-intro005.adoc b/src/main/antora/modules/persist/pages/persistence-intro/persistence-intro005.adoc similarity index 83% rename from src/main/asciidoc/persistence-intro/persistence-intro005.adoc rename to src/main/antora/modules/persist/pages/persistence-intro/persistence-intro005.adoc index ed25fb62..16acdd0d 100644 --- a/src/main/asciidoc/persistence-intro/persistence-intro005.adoc +++ b/src/main/antora/modules/persist/pages/persistence-intro/persistence-intro005.adoc @@ -3,10 +3,10 @@ Jakarta Persistence provides the following methods for querying entities. * The Jakarta Persistence query language (JPQL) is a simple, string-based language similar to SQL used to query entities and their relationships. -See xref:the-jakarta-persistence-query-language[xrefstyle=full] for more information. +See xref:persistence-querylanguage/persistence-querylanguage.adoc#_the_jakarta_persistence_query_language[The Jakarta Persistence Query Language] for more information. * The Criteria API is used to create typesafe queries using Java programming language APIs to query for entities and their relationships. -See xref:using-the-criteria-api-to-create-queries[xrefstyle=full] for more information. +See xref:persistence-criteria/persistence-criteria.adoc#_using_the_criteria_api_to_create_queries[Using the Criteria API to Create Queries] for more information. Both JPQL and the Criteria API have advantages and disadvantages. diff --git a/src/main/asciidoc/persistence-intro/persistence-intro006.adoc b/src/main/antora/modules/persist/pages/persistence-intro/persistence-intro006.adoc similarity index 98% rename from src/main/asciidoc/persistence-intro/persistence-intro006.adoc rename to src/main/antora/modules/persist/pages/persistence-intro/persistence-intro006.adoc index d96afe32..249f62c9 100644 --- a/src/main/asciidoc/persistence-intro/persistence-intro006.adoc +++ b/src/main/antora/modules/persist/pages/persistence-intro/persistence-intro006.adoc @@ -37,7 +37,7 @@ The following is an example of a `persistence.xml` deployment descriptor that sp The `jakarta.persistence.schema-generation.database.action` property is used to specify the action taken by the persistence provider when an application is deployed. If the property is not set, the persistence provider will not create or drop any database artifacts. -[[schema-creation-actions]] +[[_schema_creation_actions]] .Schema Creation Actions [width="75%",cols="15%,60%"] |=== @@ -65,7 +65,7 @@ By default, the object/relational metadata in the persistence unit is used to cr You may also supply scripts used by the provider to create and delete the database artifacts. The `jakarta.persistence.schema-generation.create-source` and `jakarta.persistence.schema-generation.drop-source` properties control how the provider will create or delete the database artifacts. -[[settings-for-create-and-delete-source-properties]] +[[_settings_for_create_and_delete_source_properties]] .Settings for Create and Delete Source Properties [width="75%",cols="15%,60%"] |=== diff --git a/src/main/asciidoc/persistence-intro/persistence-intro007.adoc b/src/main/antora/modules/persist/pages/persistence-intro/persistence-intro007.adoc similarity index 100% rename from src/main/asciidoc/persistence-intro/persistence-intro007.adoc rename to src/main/antora/modules/persist/pages/persistence-intro/persistence-intro007.adoc diff --git a/src/main/asciidoc/persistence-locking/persistence-locking.adoc b/src/main/antora/modules/persist/pages/persistence-locking/persistence-locking.adoc similarity index 87% rename from src/main/asciidoc/persistence-locking/persistence-locking.adoc rename to src/main/antora/modules/persist/pages/persistence-locking/persistence-locking.adoc index 0e0b89c9..c5143845 100644 --- a/src/main/asciidoc/persistence-locking/persistence-locking.adoc +++ b/src/main/antora/modules/persist/pages/persistence-locking/persistence-locking.adoc @@ -1,5 +1,7 @@ = Controlling Concurrent Access to Entity Data with Locking +include::ROOT:partial$not_updated.adoc[] + This chapter details how to handle concurrent access to entity data, and the locking strategies available to Jakarta Persistence application developers. include::persistence-locking001.adoc[] diff --git a/src/main/asciidoc/persistence-locking/persistence-locking001.adoc b/src/main/antora/modules/persist/pages/persistence-locking/persistence-locking001.adoc similarity index 100% rename from src/main/asciidoc/persistence-locking/persistence-locking001.adoc rename to src/main/antora/modules/persist/pages/persistence-locking/persistence-locking001.adoc diff --git a/src/main/asciidoc/persistence-locking/persistence-locking002.adoc b/src/main/antora/modules/persist/pages/persistence-locking/persistence-locking002.adoc similarity index 98% rename from src/main/asciidoc/persistence-locking/persistence-locking002.adoc rename to src/main/antora/modules/persist/pages/persistence-locking/persistence-locking002.adoc index 3e1fc3ba..772f6373 100644 --- a/src/main/asciidoc/persistence-locking/persistence-locking002.adoc +++ b/src/main/antora/modules/persist/pages/persistence-locking/persistence-locking002.adoc @@ -7,9 +7,9 @@ The use of optimistic lock modes causes the persistence provider to check the ve The use of pessimistic lock modes specifies that the persistence provider is to immediately acquire long-term read or write locks for the database data corresponding to entity state. -You can set the lock mode for an entity operation by specifying one of the lock modes defined in the `jakarta.persistence.LockModeType` enumerated type, listed in <>. +You can set the lock mode for an entity operation by specifying one of the lock modes defined in the `jakarta.persistence.LockModeType` enumerated type, listed in <<_lock_modes_for_concurrent_entity_access>>. -[[lock-modes-for-concurrent-entity-access]] +[[_lock_modes_for_concurrent_entity_access]] .Lock Modes for Concurrent Entity Access [width="75%",cols="25%,50%"] |=== diff --git a/src/main/asciidoc/persistence-querylanguage/persistence-querylanguage.adoc b/src/main/antora/modules/persist/pages/persistence-querylanguage/persistence-querylanguage.adoc similarity index 92% rename from src/main/asciidoc/persistence-querylanguage/persistence-querylanguage.adoc rename to src/main/antora/modules/persist/pages/persistence-querylanguage/persistence-querylanguage.adoc index befc0cfb..33bde5d8 100644 --- a/src/main/asciidoc/persistence-querylanguage/persistence-querylanguage.adoc +++ b/src/main/antora/modules/persist/pages/persistence-querylanguage/persistence-querylanguage.adoc @@ -1,5 +1,7 @@ = The Jakarta Persistence Query Language +include::ROOT:partial$not_updated.adoc[] + This chapter describes the Jakarta Persistence query language that defines queries for entities and their persistent state. The query language allows you to write portable queries that work regardless of the underlying data store. diff --git a/src/main/asciidoc/persistence-querylanguage/persistence-querylanguage001.adoc b/src/main/antora/modules/persist/pages/persistence-querylanguage/persistence-querylanguage001.adoc similarity index 64% rename from src/main/asciidoc/persistence-querylanguage/persistence-querylanguage001.adoc rename to src/main/antora/modules/persist/pages/persistence-querylanguage/persistence-querylanguage001.adoc index 9f844d24..b8c3b709 100644 --- a/src/main/asciidoc/persistence-querylanguage/persistence-querylanguage001.adoc +++ b/src/main/antora/modules/persist/pages/persistence-querylanguage/persistence-querylanguage001.adoc @@ -5,5 +5,5 @@ The scope of a query spans the abstract schemas of related entities that are pac The query language uses an SQL-like syntax to select objects or values based on entity abstract schema types and relationships among them. This chapter relies on the material presented in earlier chapters. -For conceptual information, see xref:introduction-to-jakarta-persistence[xrefstyle=full]. -For code examples, see xref:running-the-persistence-examples[xrefstyle=full]. +For conceptual information, see xref:persistence-intro/persistence-intro.adoc#_introduction_to_jakarta_persistence[Introduction to Jakarta Persistence]. +For code examples, see xref:persistence-basicexamples/persistence-basicexamples.adoc#_running_the_persistence_examples[Running the Persistence Examples]. diff --git a/src/main/asciidoc/persistence-querylanguage/persistence-querylanguage002.adoc b/src/main/antora/modules/persist/pages/persistence-querylanguage/persistence-querylanguage002.adoc similarity index 100% rename from src/main/asciidoc/persistence-querylanguage/persistence-querylanguage002.adoc rename to src/main/antora/modules/persist/pages/persistence-querylanguage/persistence-querylanguage002.adoc diff --git a/src/main/asciidoc/persistence-querylanguage/persistence-querylanguage003.adoc b/src/main/antora/modules/persist/pages/persistence-querylanguage/persistence-querylanguage003.adoc similarity index 100% rename from src/main/asciidoc/persistence-querylanguage/persistence-querylanguage003.adoc rename to src/main/antora/modules/persist/pages/persistence-querylanguage/persistence-querylanguage003.adoc diff --git a/src/main/asciidoc/persistence-querylanguage/persistence-querylanguage004.adoc b/src/main/antora/modules/persist/pages/persistence-querylanguage/persistence-querylanguage004.adoc similarity index 89% rename from src/main/asciidoc/persistence-querylanguage/persistence-querylanguage004.adoc rename to src/main/antora/modules/persist/pages/persistence-querylanguage/persistence-querylanguage004.adoc index 8018d8ba..6d1e4e6b 100644 --- a/src/main/asciidoc/persistence-querylanguage/persistence-querylanguage004.adoc +++ b/src/main/antora/modules/persist/pages/persistence-querylanguage/persistence-querylanguage004.adoc @@ -1,7 +1,7 @@ == Simplified Query Language Syntax -This section briefly describes the syntax of the query language so that you can quickly move on to <>. -When you are ready to learn about the syntax in more detail, see <>. +This section briefly describes the syntax of the query language so that you can quickly move on to xref:persistence-querylanguage/persistence-querylanguage.adoc#_example_queries[Example Queries]. +When you are ready to learn about the syntax in more detail, see xref:persistence-querylanguage/persistence-querylanguage.adoc#_full_query_language_syntax[Full Query Language Syntax]. === Select Statements diff --git a/src/main/asciidoc/persistence-querylanguage/persistence-querylanguage005.adoc b/src/main/antora/modules/persist/pages/persistence-querylanguage/persistence-querylanguage005.adoc similarity index 85% rename from src/main/asciidoc/persistence-querylanguage/persistence-querylanguage005.adoc rename to src/main/antora/modules/persist/pages/persistence-querylanguage/persistence-querylanguage005.adoc index 4c39274a..f560a3d5 100644 --- a/src/main/asciidoc/persistence-querylanguage/persistence-querylanguage005.adoc +++ b/src/main/antora/modules/persist/pages/persistence-querylanguage/persistence-querylanguage005.adoc @@ -1,6 +1,6 @@ == Example Queries -The following queries are from the `Player` entity of the `roster` application, which is documented in <>. +The following queries are from the `Player` entity of the `roster` application, which is documented in xref:persistence-basicexamples/persistence-basicexamples.adoc#_the_roster_application[The roster Application]. === Simple Queries @@ -26,7 +26,7 @@ FROM Player AS p + The `Player` element is the abstract schema name of the `Player` entity. -* See also: <>. +* See also: xref:persistence-querylanguage/persistence-querylanguage.adoc#_identification_variables[Identification Variables]. ==== Eliminating Duplicate Values @@ -44,7 +44,7 @@ WHERE p.position = ?1 The `WHERE` clause restricts the players retrieved by checking their `position`, a persistent field of the `Player` entity. The `?1` element denotes the input parameter of the query. -* See also: <> and <>. +* See also: xref:persistence-querylanguage/persistence-querylanguage.adoc#_input_parameters[Input Parameters] and xref:persistence-querylanguage/persistence-querylanguage.adoc#_the_distinct_keyword[The DISTINCT Keyword]. ==== Using Named Parameters @@ -136,7 +136,7 @@ Expressions cannot navigate beyond (or further qualify) relationship fields that In the syntax of an expression, a collection-valued field is a terminal symbol. Because the `teams` field is a collection, the `WHERE` clause cannot specify `p.teams.city` (an illegal expression). -* See also: <>. +* See also: xref:persistence-querylanguage/persistence-querylanguage.adoc#_path_expressions[Path Expressions]. ==== Traversing Multiple Relationships @@ -175,7 +175,7 @@ Because it is not a collection, the `league` relationship field can be followed Every `WHERE` clause must specify a conditional expression, of which there are several kinds. In the previous examples, the conditional expressions are comparison expressions that test for equality. The following examples demonstrate some of the other kinds of conditional expressions. -For descriptions of all conditional expressions, see <>. +For descriptions of all conditional expressions, see xref:persistence-querylanguage/persistence-querylanguage.adoc#_where_clause[WHERE Clause]. ==== The LIKE Expression @@ -191,7 +191,7 @@ WHERE p.name LIKE 'Mich%' * Description: The `LIKE` expression uses wildcard characters to search for strings that match the wildcard pattern. In this case, the query uses the `LIKE` expression and the `%` wildcard to find all players whose names begin with the string "Mich." For example, "Michael" and "Michelle" both match the wildcard pattern. -* See also: <>. +* See also: xref:persistence-querylanguage/persistence-querylanguage.adoc#_like_expressions[LIKE Expressions]. ==== The IS NULL Expression @@ -207,7 +207,7 @@ WHERE t.league IS NULL * Description: The `IS NULL` expression can be used to check whether a relationship has been set between two entities. In this case, the query checks whether the teams are associated with any leagues and returns the teams that do not have a league. -* See also: <> and <>. +* See also: xref:persistence-querylanguage/persistence-querylanguage.adoc#_null_comparison_expressions[NULL Comparison Expressions] and xref:persistence-querylanguage/persistence-querylanguage.adoc#_null_values[NULL Values]. ==== The IS EMPTY Expression @@ -223,7 +223,7 @@ WHERE p.teams IS EMPTY * Description: The `teams` relationship field of the `Player` entity is a collection. If a player does not belong to a team, the `teams` collection is empty, and the conditional expression is `TRUE`. -* See also: <>. +* See also: xref:persistence-querylanguage/persistence-querylanguage.adoc#_empty_collection_comparison_expressions[Empty Collection Comparison Expressions]. ==== The BETWEEN Expression @@ -244,7 +244,7 @@ The following expression is equivalent to the `BETWEEN` expression: p.salary >= :lowerSalary AND p.salary <= :higherSalary ---- -* See also: <>. +* See also: xref:persistence-querylanguage/persistence-querylanguage.adoc#_between_expressions[BETWEEN Expressions]. ==== Comparison Operators @@ -260,7 +260,7 @@ WHERE p1.salary > p2.salary AND p2.name = :name * Description: The `FROM` clause declares two identification variables (`p1` and `p2`) of the same type (`Player`). Two identification variables are needed because the `WHERE` clause compares the salary of one player (`p2`) with that of the other players (`p1`). -* See also: <>. +* See also: xref:persistence-querylanguage/persistence-querylanguage.adoc#_identification_variables[Identification Variables]. === Bulk Updates and Deletes diff --git a/src/main/asciidoc/persistence-querylanguage/persistence-querylanguage006.adoc b/src/main/antora/modules/persist/pages/persistence-querylanguage/persistence-querylanguage006.adoc similarity index 95% rename from src/main/asciidoc/persistence-querylanguage/persistence-querylanguage006.adoc rename to src/main/antora/modules/persist/pages/persistence-querylanguage/persistence-querylanguage006.adoc index d95946ff..8ea058b2 100644 --- a/src/main/asciidoc/persistence-querylanguage/persistence-querylanguage006.adoc +++ b/src/main/antora/modules/persist/pages/persistence-querylanguage/persistence-querylanguage006.adoc @@ -5,9 +5,9 @@ Much of the following material paraphrases or directly quotes the specification. === BNF Symbols -<> describes the BNF symbols used in this chapter. +<<_bnf_symbol_summary>> describes the BNF symbols used in this chapter. -[[bnf-symbol-summary]] +[[_bnf_symbol_summary]] .BNF Symbol Summary [width="75%",cols="25%,45%"] |=== @@ -327,7 +327,7 @@ All identification variables must be declared in the `FROM` clause. Because it is an identifier, an identification variable has the same naming conventions and restrictions as an identifier, with the exception that an identification variable is case-insensitive. For example, an identification variable cannot be the same as a query language keyword. -(See <> for more naming rules.) +(See <<_identifiers>> for more naming rules.) Also, within a given persistence unit, an identification variable name must not match the name of any entity or abstract schema. The `FROM` clause can contain multiple declarations, separated by commas. @@ -397,15 +397,15 @@ If the query compares multiple values of the same abstract schema type, the `FRO FROM Player p1, Player p2 ---- -For an example of such a query, see <>. +For an example of such a query, see xref:persistence-querylanguage/persistence-querylanguage.adoc#_comparison_operators[Comparison Operators]. ==== Collection Member Declarations In a one-to-many relationship, the multiple side consists of a collection of entities. An identification variable can represent a member of this collection. To access a collection member, the path expression in the variable's declaration navigates through the relationships in the abstract schema. -(For more information on path expressions, see <>.) Because a path expression can be based on another path expression, the navigation can traverse several relationships. -See <>. +(For more information on path expressions, see <<_path_expressions>>.) Because a path expression can be based on another path expression, the navigation can traverse several relationships. +See xref:persistence-querylanguage/persistence-querylanguage.adoc#_traversing_multiple_relationships[Traversing Multiple Relationships]. A collection member declaration must include the `IN` operator but can omit the optional `AS` operator. @@ -528,7 +528,7 @@ For example, the type of the expression `p.salary` is `double` because the termi In the expression `p.teams`, the terminating element is a collection-valued relationship field (`teams`). This expression's type is a collection of the abstract schema type named `Team`. Because `Team` is the abstract schema name for the `Team` entity, this type maps to the entity. -For more information on the type mapping of abstract schemas, see <>. +For more information on the type mapping of abstract schemas, see <<_return_types>>. ==== Navigation @@ -625,9 +625,9 @@ You can change the order of evaluation by using parentheses. ==== Operators and Their Precedence -<> lists the query language operators in order of decreasing precedence. +<> lists the query language operators in order of decreasing precedence. -[[query-language-order-precedence]] +[[query_language_order_precedence]] .Query Language Order Precedence [width="75%",cols="25%,45%"] |=== @@ -725,9 +725,9 @@ The pattern value is a string literal that can contain wildcard characters. The underscore (`_`) wildcard character represents any single character. The percent (`%`) wildcard character represents zero or more characters. The `ESCAPE` clause specifies an escape character for the wildcard characters in the pattern value. -<> shows some sample `LIKE` expressions. +<<_like_expression_examples>> shows some sample `LIKE` expressions. -[[like-expression-examples]] +[[_like_expression_examples]] .LIKE Expression Examples [width=75%",cols="35%,20%,20%"] |=== @@ -857,12 +857,12 @@ WHERE emp.salary > ALL ( ==== Functional Expressions The query language includes several string, arithmetic, and date/time functions that may be used in the `SELECT`, `WHERE`, or `HAVING` clause of a query. -The functions are listed in <>, <> and <>. +The functions are listed in <<_string_expressions>>, <<_arithmetic_expressions>> and <<_date_time_expressions>>. -In <>, the `start` and `length` arguments are of type `int` and designate positions in the `String` argument. +In <<_string_expressions>>, the `start` and `length` arguments are of type `int` and designate positions in the `String` argument. The first position in a string is designated by 1. -[[string-expressions]] +[[_string_expressions]] .String Expressions [width="75%",cols="45%,25%"] |=== @@ -906,9 +906,9 @@ The default is `BOTH`, which removes the leading and trailing characters from th The `LOWER` and `UPPER` functions convert a string to lowercase or uppercase, respectively. -In <>, the `number` argument can be an `int`, a `float`, or a `double`. +In <<_arithmetic_expressions>>, the `number` argument can be an `int`, a `float`, or a `double`. -[[arithmetic-expressions]] +[[_arithmetic_expressions]] .Arithmetic Expressions [width="60%",cols="30%,30%"] |=== @@ -931,9 +931,9 @@ The `SQRT` function returns the square root of a number. The `SIZE` function returns an integer of the number of elements in the given collection. -In <>, the date/time functions return the date, time, or timestamp on the database server. +In <<_date_time_expressions>>, the date/time functions return the date, time, or timestamp on the database server. -[[date-time-expressions]] +[[_date_time_expressions]] .Date/Time Expressions [width="60%",cols="30%,30%"] |=== @@ -998,10 +998,10 @@ Comparing two `NULL` values yields an unknown value. * The `IS NULL` test converts a `NULL` persistent field or a single-valued relationship field to `TRUE`. The `IS NOT NULL` test converts them to `FALSE`. -* Boolean operators and conditional tests use the three-valued logic defined by <> and <>. +* Boolean operators and conditional tests use the three-valued logic defined by <<_and_operator_logic>> and <<_or_operator_logic>>. (In these tables, T stands for `TRUE`, F for `FALSE`, and U for unknown.) -[[and-operator-logic]] +[[_and_operator_logic]] .AND Operator Logic [width="40%",cols="10%,10%,10%,10%"] |=== @@ -1014,7 +1014,7 @@ The `IS NOT NULL` test converts them to `FALSE`. |U |U |F |U |=== -[[or-operator-logic]] +[[_or_operator_logic]] .OR Operator Logic [width="40%",cols="10%,10%,10%,10%"] |=== @@ -1041,9 +1041,9 @@ Two strings are equal only if they contain the same sequence of characters. Trailing blanks are significant; for example, the strings `'abc'` and `'abc '` are not equal. Two entities of the same abstract schema type are equal only if their primary keys have the same value. -<> shows the operator logic of a negation, and <> shows the truth values of conditional tests. +<<_not_operator_logic>> shows the operator logic of a negation, and <<_conditional_test>> shows the truth values of conditional tests. -[[not-operator-logic]] +[[_not_operator_logic]] .NOT Operator Logic [width="30%",cols="15%,15%"] |=== @@ -1056,7 +1056,7 @@ Two entities of the same abstract schema type are equal only if their primary ke |U |U |=== -[[conditional-test]] +[[_conditional_test]] .Conditional Test [width="60%",cols="30%,10%,10%,10%"] |=== @@ -1099,9 +1099,9 @@ WHERE c.lastname = 'Coss' AND c.firstname = 'Roxane' This query returns a list of `Object[]` elements; the first array element is a string denoting the customer name, and the second array element is a string denoting the name of the customer's country. -The result of a query may be the result of an aggregate function, listed in <>. +The result of a query may be the result of an aggregate function, listed in <<_aggregate_functions_in_select_statements>>. -[[aggregate-functions-in-select-statements]] +[[_aggregate_functions_in_select_statements]] .Aggregate Functions in Select Statements [width="80%",cols="15%,50%,64%"] |=== diff --git a/src/main/asciidoc/persistence-string-queries/persistence-string-queries.adoc b/src/main/antora/modules/persist/pages/persistence-string-queries/persistence-string-queries.adoc similarity index 86% rename from src/main/asciidoc/persistence-string-queries/persistence-string-queries.adoc rename to src/main/antora/modules/persist/pages/persistence-string-queries/persistence-string-queries.adoc index 0b9670bc..44c39931 100644 --- a/src/main/asciidoc/persistence-string-queries/persistence-string-queries.adoc +++ b/src/main/antora/modules/persist/pages/persistence-string-queries/persistence-string-queries.adoc @@ -1,5 +1,7 @@ = Creating and Using String-Based Criteria Queries +include::ROOT:partial$not_updated.adoc[] + This chapter describes how to create weakly typed string-based Criteria API queries. include::persistence-string-queries001.adoc[] diff --git a/src/main/asciidoc/persistence-string-queries/persistence-string-queries001.adoc b/src/main/antora/modules/persist/pages/persistence-string-queries/persistence-string-queries001.adoc similarity index 84% rename from src/main/asciidoc/persistence-string-queries/persistence-string-queries001.adoc rename to src/main/antora/modules/persist/pages/persistence-string-queries/persistence-string-queries001.adoc index 96293269..82eb7527 100644 --- a/src/main/asciidoc/persistence-string-queries/persistence-string-queries001.adoc +++ b/src/main/antora/modules/persist/pages/persistence-string-queries/persistence-string-queries001.adoc @@ -9,4 +9,4 @@ The main advantage of string-based queries over metamodel queries is the ability The main disadvantage to string-based queries is their lack of type safety; this problem may lead to runtime errors due to type mismatches that would be caught at development time if you used strongly typed metamodel queries. -For information on constructing criteria queries, see xref:using-the-criteria-api-to-create-queries[xrefstyle=full]. +For information on constructing criteria queries, see xref:persistence-criteria/persistence-criteria.adoc#_using_the_criteria_api_to_create_queries[Using the Criteria API to Create Queries]. diff --git a/src/main/asciidoc/persistence-string-queries/persistence-string-queries002.adoc b/src/main/antora/modules/persist/pages/persistence-string-queries/persistence-string-queries002.adoc similarity index 100% rename from src/main/asciidoc/persistence-string-queries/persistence-string-queries002.adoc rename to src/main/antora/modules/persist/pages/persistence-string-queries/persistence-string-queries002.adoc diff --git a/src/main/asciidoc/persistence-string-queries/persistence-string-queries003.adoc b/src/main/antora/modules/persist/pages/persistence-string-queries/persistence-string-queries003.adoc similarity index 100% rename from src/main/asciidoc/persistence-string-queries/persistence-string-queries003.adoc rename to src/main/antora/modules/persist/pages/persistence-string-queries/persistence-string-queries003.adoc diff --git a/src/main/asciidoc/injection/injection.adoc b/src/main/antora/modules/platform/pages/injection/injection.adoc similarity index 94% rename from src/main/asciidoc/injection/injection.adoc rename to src/main/antora/modules/platform/pages/injection/injection.adoc index 64836f17..56f59edd 100644 --- a/src/main/asciidoc/injection/injection.adoc +++ b/src/main/antora/modules/platform/pages/injection/injection.adoc @@ -1,5 +1,7 @@ = Injection +include::ROOT:partial$not_updated.adoc[] + This chapter provides an overview of injection in Jakarta EE and describes the two injection mechanisms provided by the platform: resource injection and dependency injection. Jakarta EE provides injection mechanisms that enable your objects to obtain references to resources and other dependencies without having to instantiate them directly. diff --git a/src/main/asciidoc/injection/injection001.adoc b/src/main/antora/modules/platform/pages/injection/injection001.adoc similarity index 100% rename from src/main/asciidoc/injection/injection001.adoc rename to src/main/antora/modules/platform/pages/injection/injection001.adoc diff --git a/src/main/asciidoc/injection/injection002.adoc b/src/main/antora/modules/platform/pages/injection/injection002.adoc similarity index 88% rename from src/main/asciidoc/injection/injection002.adoc rename to src/main/antora/modules/platform/pages/injection/injection002.adoc index 988c61db..8ac77694 100644 --- a/src/main/asciidoc/injection/injection002.adoc +++ b/src/main/antora/modules/platform/pages/injection/injection002.adoc @@ -28,4 +28,4 @@ public class MyServlet extends HttpServlet { As opposed to resource injection, dependency injection is typesafe because it resolves by type. To decouple your code from the implementation of the managed bean, you can reference the injected instances using an interface type and have your managed bean implement that interface. -For more information about dependency injection, see xref:introduction-to-jakarta-contexts-and-dependency-injection[xrefstyle=full] and the Jakarta Contexts and Dependency Injection spec. \ No newline at end of file +For more information about dependency injection, see xref:cdi:cdi-basic/cdi-basic.adoc[Introduction to Jakarta Contexts and Dependency Injection] and the Jakarta Contexts and Dependency Injection spec. \ No newline at end of file diff --git a/src/main/asciidoc/injection/injection003.adoc b/src/main/antora/modules/platform/pages/injection/injection003.adoc similarity index 65% rename from src/main/asciidoc/injection/injection003.adoc rename to src/main/antora/modules/platform/pages/injection/injection003.adoc index 4e41bf06..23c5b83e 100644 --- a/src/main/asciidoc/injection/injection003.adoc +++ b/src/main/antora/modules/platform/pages/injection/injection003.adoc @@ -1,8 +1,8 @@ == The Main Differences between Resource Injection and Dependency Injection -<> lists the main differences between resource injection and dependency injection. +<<_differences_between_resource_injection_and_dependency_injection>> lists the main differences between resource injection and dependency injection. -[[differences-between-resource-injection-and-dependency-injection]] +[[_differences_between_resource_injection_and_dependency_injection]] .Differences between Resource Injection and Dependency Injection [options="header",width="99%",cols="25%,20%,20%,20%,15%"] |=== diff --git a/src/main/asciidoc/packaging/packaging.adoc b/src/main/antora/modules/platform/pages/packaging/packaging.adoc similarity index 91% rename from src/main/asciidoc/packaging/packaging.adoc rename to src/main/antora/modules/platform/pages/packaging/packaging.adoc index 9e232749..763c9cb3 100644 --- a/src/main/asciidoc/packaging/packaging.adoc +++ b/src/main/antora/modules/platform/pages/packaging/packaging.adoc @@ -1,5 +1,7 @@ = Packaging +include::ROOT:partial$not_updated.adoc[] + This chapter describes packaging. 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, and an optional deployment descriptor that describes its content. diff --git a/src/main/asciidoc/packaging/packaging001.adoc b/src/main/antora/modules/platform/pages/packaging/packaging001.adoc similarity index 87% rename from src/main/asciidoc/packaging/packaging001.adoc rename to src/main/antora/modules/platform/pages/packaging/packaging001.adoc index 5c95f94f..3009ff26 100644 --- a/src/main/asciidoc/packaging/packaging001.adoc +++ b/src/main/antora/modules/platform/pages/packaging/packaging001.adoc @@ -5,7 +5,7 @@ A WAR or EAR file is a standard JAR (`.jar`) file with a `.war` or `.ear` extens Using JAR, WAR, and EAR files and modules makes it possible to assemble a number of different Jakarta EE applications using some of the same components. No extra coding is needed; it is only a matter of assembling (or packaging) various Jakarta EE modules into Jakarta EE JAR, WAR, or EAR files. -An EAR file (see <>) contains Jakarta EE modules and, optionally, deployment descriptors. +An EAR file (see <<_ear_file_structure>>) contains Jakarta EE modules and, optionally, deployment descriptors. A deployment descriptor, an XML document with an `.xml` extension, describes the deployment settings of an application, a module, or a component. Because deployment descriptor information is declarative, it can be changed without the need to modify the source code. At runtime, the Jakarta EE server reads the deployment descriptor and acts upon the application, module, or component accordingly. @@ -13,9 +13,9 @@ At runtime, the Jakarta EE server reads the deployment descriptor and acts upon Deployment information is most commonly specified in the source code by annotations. Deployment descriptors, if present, override what is specified in the source code. -[[ear-file-structure]] +[[_ear_file_structure]] .EAR File Structure -image::jakartaeett_dt_010.svg["Diagram of EAR file structure. META-INF and web, application client, enterprise bean, and resource adapter modules are under the assembly root."] +image::common:jakartaeett_dt_010.svg["Diagram of EAR file structure. META-INF and web, application client, enterprise bean, and resource adapter modules are under the assembly root."] The two types of deployment descriptors are Jakarta EE and runtime. A Jakarta EE deployment descriptor is defined by a Jakarta EE specification and can be used to configure deployment settings on any Jakarta EE-compliant implementation. @@ -39,5 +39,5 @@ Web modules are packaged as JAR files with a `.war` (web archive) extension. Application client modules are packaged as JAR files with a `.jar` extension. * Resource adapter modules, which contain all Java interfaces, classes, native libraries, and, optionally, a resource adapter deployment descriptor. -Together, these implement the Connector architecture (see <>) for a particular EIS. +Together, these implement the Connector architecture (see xref:intro:overview/overview.adoc#_jakarta_connectors[Jakarta Connectors]) for a particular EIS. Resource adapter modules are packaged as JAR files with an `.rar` (resource adapter archive) extension. diff --git a/src/main/asciidoc/packaging/packaging002.adoc b/src/main/antora/modules/platform/pages/packaging/packaging002.adoc similarity index 89% rename from src/main/asciidoc/packaging/packaging002.adoc rename to src/main/antora/modules/platform/pages/packaging/packaging002.adoc index 856119f7..e74c936d 100644 --- a/src/main/asciidoc/packaging/packaging002.adoc +++ b/src/main/antora/modules/platform/pages/packaging/packaging002.adoc @@ -2,9 +2,9 @@ This section explains how enterprise beans can be packaged in enterprise bean JAR or WAR modules. It includes the following sections: -* <> +* <<_packaging_enterprise_beans_in_enterprise_bean_jar_modules>> -* <> +* <<_packaging_enterprise_beans_in_war_modules>> === Packaging Enterprise Beans in enterprise bean JAR Modules @@ -13,11 +13,11 @@ 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 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. -<> shows the contents of an enterprise bean JAR file. +<<_structure_of_an_enterprise_bean_jar>> shows the contents of an enterprise bean JAR file. -[[structure-of-an-enterprise-bean-jar]] +[[_structure_of_an_enterprise_bean_jar]] .Structure of an Enterprise Bean JAR -image::jakartaeett_dt_011.svg["Diagram showing the structure and contents of an enterprise bean JAR file."] +image::common:jakartaeett_dt_011.svg["Diagram showing the structure and contents of an enterprise bean JAR file."] === Packaging Enterprise Beans in WAR Modules diff --git a/src/main/asciidoc/packaging/packaging003.adoc b/src/main/antora/modules/platform/pages/packaging/packaging003.adoc similarity index 91% rename from src/main/asciidoc/packaging/packaging003.adoc rename to src/main/antora/modules/platform/pages/packaging/packaging003.adoc index 16263208..5516f773 100644 --- a/src/main/asciidoc/packaging/packaging003.adoc +++ b/src/main/antora/modules/platform/pages/packaging/packaging003.adoc @@ -33,8 +33,8 @@ The web module just described is portable; you can deploy it into any web contai You can provide a runtime deployment descriptor (DD) when you deploy a WAR on GlassFish Server, but it is not required under most circumstances. The runtime DD is an XML file that may contain such information as the context root of the web application, the mapping of the portable names of an application's resources to GlassFish Server resources, and the mapping of an application's security roles to users, groups, and principals defined in GlassFish Server. The GlassFish Server web application runtime DD, if used, is named `glassfish-web.xml` and is located in the `WEB-INF` directory. -The structure of a web module that can be deployed on GlassFish Server is shown in <>. +The structure of a web module that can be deployed on GlassFish Server is shown in <<_web_module_structure>>. -[[web-module-structure]] +[[_web_module_structure]] .Web Module Structure -image::jakartaeett_dt_012.svg["Diagram of web module structure. WEB-INF and web pages are under the root. Under WEB-INF are descriptors and the lib and classes directories."] +image::common:jakartaeett_dt_012.svg["Diagram of web module structure. WEB-INF and web pages are under the root. Under WEB-INF are descriptors and the lib and classes directories."] diff --git a/src/main/asciidoc/packaging/packaging004.adoc b/src/main/antora/modules/platform/pages/packaging/packaging004.adoc similarity index 100% rename from src/main/asciidoc/packaging/packaging004.adoc rename to src/main/antora/modules/platform/pages/packaging/packaging004.adoc diff --git a/src/main/asciidoc/resource-creation/resource-creation.adoc b/src/main/antora/modules/platform/pages/resource-creation/resource-creation.adoc similarity index 93% rename from src/main/asciidoc/resource-creation/resource-creation.adoc rename to src/main/antora/modules/platform/pages/resource-creation/resource-creation.adoc index e65050ea..ecbb8373 100644 --- a/src/main/asciidoc/resource-creation/resource-creation.adoc +++ b/src/main/antora/modules/platform/pages/resource-creation/resource-creation.adoc @@ -1,5 +1,7 @@ = Resource Creation +include::ROOT:partial$not_updated.adoc[] + A resource is a program object that provides connections to such systems as database servers and messaging systems. Jakarta EE components can access a wide variety of resources, including databases, mail sessions, Jakarta Messaging objects, and URLs. The Jakarta EE platform provides mechanisms that allow you to access all these resources in a similar manner. diff --git a/src/main/asciidoc/resource-creation/resource-creation001.adoc b/src/main/antora/modules/platform/pages/resource-creation/resource-creation001.adoc similarity index 100% rename from src/main/asciidoc/resource-creation/resource-creation001.adoc rename to src/main/antora/modules/platform/pages/resource-creation/resource-creation001.adoc diff --git a/src/main/asciidoc/resource-creation/resource-creation002.adoc b/src/main/antora/modules/platform/pages/resource-creation/resource-creation002.adoc similarity index 100% rename from src/main/asciidoc/resource-creation/resource-creation002.adoc rename to src/main/antora/modules/platform/pages/resource-creation/resource-creation002.adoc diff --git a/src/main/asciidoc/resource-creation/resource-creation003.adoc b/src/main/antora/modules/platform/pages/resource-creation/resource-creation003.adoc similarity index 100% rename from src/main/asciidoc/resource-creation/resource-creation003.adoc rename to src/main/antora/modules/platform/pages/resource-creation/resource-creation003.adoc diff --git a/src/main/antora/modules/security/images/authentication-mvc.drawio b/src/main/antora/modules/security/images/authentication-mvc.drawio new file mode 100644 index 00000000..1bc76a31 --- /dev/null +++ b/src/main/antora/modules/security/images/authentication-mvc.drawio @@ -0,0 +1,37 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/src/main/antora/modules/security/images/authentication-mvc.svg b/src/main/antora/modules/security/images/authentication-mvc.svg new file mode 100644 index 00000000..74a2a3ab --- /dev/null +++ b/src/main/antora/modules/security/images/authentication-mvc.svg @@ -0,0 +1,4 @@ + + + +
Authentication Mechanism
(Controller)
Authentication Mecha...
Login Form/Dialog
(View)
Login Form/Dialog...
Identity Store
(Model)
Identity Store...
HTTP
Cookies
Headers
URLs
HTTP...
Credentials
Caller name
Groups
Credentials...Text is not SVG - cannot display \ No newline at end of file diff --git a/src/main/antora/modules/security/images/authentication-mvc.vsdx b/src/main/antora/modules/security/images/authentication-mvc.vsdx new file mode 100644 index 00000000..c84406c7 Binary files /dev/null and b/src/main/antora/modules/security/images/authentication-mvc.vsdx differ diff --git a/src/main/antora/modules/security/nav.adoc b/src/main/antora/modules/security/nav.adoc new file mode 100644 index 00000000..24276def --- /dev/null +++ b/src/main/antora/modules/security/nav.adoc @@ -0,0 +1,10 @@ +.Security +* xref:security.adoc[] +// We can add these back as needed for any chapters that we intend to keep +// * xref:security-intro/security-intro.adoc[] +// * xref:security-webtier/security-webtier.adoc[] +// * xref:security-jakartaee/security-jakartaee.adoc[] +// * xref:security-api/security-api.adoc[] +// * xref:security-advanced/security-advanced.adoc[] + + diff --git a/src/main/asciidoc/security-advanced/security-advanced.adoc b/src/main/antora/modules/security/pages/security-advanced/security-advanced.adoc similarity index 90% rename from src/main/asciidoc/security-advanced/security-advanced.adoc rename to src/main/antora/modules/security/pages/security-advanced/security-advanced.adoc index d6ab99f5..714d4ff7 100644 --- a/src/main/asciidoc/security-advanced/security-advanced.adoc +++ b/src/main/antora/modules/security/pages/security-advanced/security-advanced.adoc @@ -1,5 +1,7 @@ = Jakarta EE Security: Advanced Topics +include::ROOT:partial$not_updated.adoc[] + This chapter provides advanced information on securing Jakarta EE applications. include::security-advanced001.adoc[] @@ -17,3 +19,4 @@ include::security-advanced006.adoc[] include::security-advanced007.adoc[] include::security-advanced008.adoc[] + diff --git a/src/main/asciidoc/security-advanced/security-advanced001.adoc b/src/main/antora/modules/security/pages/security-advanced/security-advanced001.adoc similarity index 90% rename from src/main/asciidoc/security-advanced/security-advanced001.adoc rename to src/main/antora/modules/security/pages/security-advanced/security-advanced001.adoc index 172dcd19..f00cb1ea 100644 --- a/src/main/asciidoc/security-advanced/security-advanced001.adoc +++ b/src/main/antora/modules/security/pages/security-advanced/security-advanced001.adoc @@ -29,13 +29,13 @@ If the two values match, the client can trust that the signature is authentic, b Digital certificates are used with HTTPS to authenticate web clients. The HTTPS service of most web servers will not run unless a digital certificate has been installed. -Use the procedure outlined in the next section, <>, to set up a digital certificate that can be used by your application or web server to enable SSL. +Use the procedure outlined in the next section, <<_creating_a_server_certificate>>, to set up a digital certificate that can be used by your application or web server to enable SSL. One tool that can be used to set up a digital certificate is `keytool`, a key and certificate management utility that ships with the JDK. This tool enables users to administer their own public/private key pairs and associated certificates for use in self-authentication, whereby the user authenticates himself or herself to other users or services, or data integrity and authentication services, using digital signatures. The tool also allows users to cache the public keys, in the form of certificates, of their communicating peers. -For a better understanding of `keytool` and public-key cryptography, see <> for a link to the `keytool` documentation. +For a better understanding of `keytool` and public-key cryptography, see xref:security-advanced/security-advanced.adoc#_further_information_about_advanced_security_topics[Further Information about Advanced Security Topics] for a link to the `keytool` documentation. === Creating a Server Certificate @@ -82,7 +82,7 @@ Enter the `keytool` command all on one line: + [source,shell] ---- -java-home/bin/keytool -genkey -alias server-alias -keyalg RSA +java-home/bin/keytool -genkey -alias server-alias -keyalg RSA -keypass changeit -storepass changeit -keystore keystore.jks ---- + @@ -96,7 +96,7 @@ Enter the `keytool` command all on one line: + [source,shell] ---- -java-home/bin/keytool -export -alias server-alias -storepass changeit +java-home/bin/keytool -export -alias server-alias -storepass changeit -file server.cer -keystore keystore.jks ---- @@ -108,9 +108,9 @@ Use the following parameters: + [source,shell] ---- -java-home/bin/keytool -import -v -trustcacerts -alias server-alias --file server.cer -keystore cacerts.jks -keypass changeit --storepass changeit +java-home/bin/keytool -import -v -trustcacerts -alias server-alias +-file server.cer -keystore cacerts.jks -keypass changeit +-storepass changeit ---- + Information on the certificate, such as that shown next, will appear: @@ -118,7 +118,7 @@ Information on the certificate, such as that shown next, will appear: ---- Owner: CN=localhost, OU=My Company, O=Software, L=Santa Clara, ST=CA, C=US Issuer: CN=localhost, OU=My Company, O=Software, L=Santa Clara, ST=CA, C=US -Serial number: 3e932169 +Serial number: 3e932169 Valid from: Mon Nov 26 18:15:47 EST 2012 until: Sun Feb 24 18:15:47 EST 2013 Certificate fingerprints: MD5: 52:9F:49:68:ED:78:6F:39:87:F3:98:B3:6A:6B:0F:90 @@ -142,11 +142,11 @@ Certificate was added to keystore === Adding Users to the Certificate Realm In the `certificate` realm, user identity is set up in the GlassFish Server security context and populated with user data obtained from cryptographically verified client certificates. -For step-by-step instructions for creating this type of certificate, see <>. +For step-by-step instructions for creating this type of certificate, see <<_working_with_digital_certificates>>. === Using a Different Server Certificate with GlassFish Server -Follow the steps in <> to create your own server certificate, have it signed by a CA, and import the certificate into `keystore.jks`. +Follow the steps in <<_creating_a_server_certificate>> to create your own server certificate, have it signed by a CA, and import the certificate into `keystore.jks`. Make sure that when you create the certificate, you follow these rules. @@ -162,7 +162,7 @@ To specify that GlassFish Server should use the new keystore for authentication To use a different keystore from the one provided for development purposes, follow these steps. . Start GlassFish Server if you haven't already done so. -Information on starting the GlassFish Server can be found in <>. +Information on starting the GlassFish Server can be found in xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]. . Open the GlassFish Server Administration Console in a web browser at http://localhost:4848[^]. @@ -181,7 +181,7 @@ The current settings are shown below: . If you've changed the keystore password from its default value, you need to add the password option as well: + ---- --Djavax.net.ssl.keyStorePassword=your-new-password +-Djavax.net.ssl.keyStorePassword=your-new-password ---- . Click Save, then restart GlassFish Server. diff --git a/src/main/asciidoc/security-advanced/security-advanced002.adoc b/src/main/antora/modules/security/pages/security-advanced/security-advanced002.adoc similarity index 89% rename from src/main/asciidoc/security-advanced/security-advanced002.adoc rename to src/main/antora/modules/security/pages/security-advanced/security-advanced002.adoc index 1fd7c843..1a43a19c 100644 --- a/src/main/asciidoc/security-advanced/security-advanced002.adoc +++ b/src/main/antora/modules/security/pages/security-advanced/security-advanced002.adoc @@ -12,7 +12,7 @@ You can think of a public key certificate as the digital equivalent of a passpor The certificate is issued by a trusted organization, a certificate authority (CA), and provides identification for the bearer. Before using client authentication, make sure that the client has a valid public key certificate. -For more information on creating and using public key certificates, read <>. +For more information on creating and using public key certificates, read xref:security-advanced/security-advanced.adoc#_working_with_digital_certificates[Working with Digital Certificates]. The following example shows how to declare client authentication in your deployment descriptor: @@ -25,16 +25,16 @@ The following example shows how to declare client authentication in your deploym Jakarta Security provides an alternative means to configure client authentication using the `HttpAuthenticationMechanism` interface. This interface defines an SPI for writing authentication mechanisms that can be provided with an application and deployed using CDI. -See <>. +See xref:security-api/security-api.adoc#_overview_of_the_http_authentication_mechanism_interface[Overview of the HTTP Authentication Mechanism Interface]. === Mutual Authentication With mutual authentication, the server and the client authenticate each other. Mutual authentication is of two types: -* Certificate-based (see <>) +* Certificate-based (see <<_certificate_based_mutual_authentication>>) -* User name/password-based (see <>) +* User name/password-based (see <<_username_password_based_mutual_authentication>>) When using certificate-based mutual authentication, the following actions occur. @@ -50,11 +50,11 @@ When using certificate-based mutual authentication, the following actions occur. . If successful, the server grants access to the protected resource requested by the client. -<> shows what occurs during certificate-based mutual authentication. +<<_certificate_based_mutual_authentication>> shows what occurs during certificate-based mutual authentication. -[[certificate-based-mutual-authentication]] +[[_certificate_based_mutual_authentication]] .Certificate-Based Mutual Authentication -image::jakartaeett_dt_048.svg["Diagram of six steps in mutual authentication with certificates"] +image::common:jakartaeett_dt_048.svg["Diagram of six steps in mutual authentication with certificates"] In user name/password-based mutual authentication, the following actions occur. @@ -70,11 +70,11 @@ In user name/password-based mutual authentication, the following actions occur. . If the verification is successful, the server grants access to the protected resource requested by the client. -<> shows what occurs during user name/password-based mutual authentication. +<<_username_password_based_mutual_authentication>> shows what occurs during user name/password-based mutual authentication. -[[username-password-based-mutual-authentication]] +[[_username_password_based_mutual_authentication]] .User Name/Password-Based Mutual Authentication -image::jakartaeett_dt_049.svg["Diagram of five steps in mutual authentication with user name and password"] +image::common:jakartaeett_dt_049.svg["Diagram of five steps in mutual authentication with user name and password"] ==== Enabling Mutual Authentication over SSL diff --git a/src/main/asciidoc/security-advanced/security-advanced003.adoc b/src/main/antora/modules/security/pages/security-advanced/security-advanced003.adoc similarity index 93% rename from src/main/asciidoc/security-advanced/security-advanced003.adoc rename to src/main/antora/modules/security/pages/security-advanced/security-advanced003.adoc index ec447765..7b95d303 100644 --- a/src/main/asciidoc/security-advanced/security-advanced003.adoc +++ b/src/main/antora/modules/security/pages/security-advanced/security-advanced003.adoc @@ -16,7 +16,7 @@ A realm can be thought of as a database of user names and passwords that identif Access to specific web application resources is granted to all users in a particular role, instead of enumerating a list of associated users. A user name can have any number of roles associated with it. -Two of the tutorial case studies, xref:dukes-tutoring-case-study-example[xrefstyle=full] and xref:dukes-forest-case-study-example[xrefstyle=full] use a JDBC realm for user authentication. +Two of the tutorial case studies, xref:casestudies:dukes-tutoring/dukes-tutoring.adoc#_dukes_tutoring_case_study_example[Duke's Tutoring Case Study Example] and xref:casestudies:dukes-forest/dukes-forest.adoc#_dukes_forest_case_study_example[Duke's Forest Case Study Example] use a JDBC realm for user authentication. === To Configure a JDBC Authentication Realm diff --git a/src/main/asciidoc/security-advanced/security-advanced004.adoc b/src/main/antora/modules/security/pages/security-advanced/security-advanced004.adoc similarity index 100% rename from src/main/asciidoc/security-advanced/security-advanced004.adoc rename to src/main/antora/modules/security/pages/security-advanced/security-advanced004.adoc diff --git a/src/main/asciidoc/security-advanced/security-advanced005.adoc b/src/main/antora/modules/security/pages/security-advanced/security-advanced005.adoc similarity index 82% rename from src/main/asciidoc/security-advanced/security-advanced005.adoc rename to src/main/antora/modules/security/pages/security-advanced/security-advanced005.adoc index 1ede10c2..14da7e9c 100644 --- a/src/main/asciidoc/security-advanced/security-advanced005.adoc +++ b/src/main/antora/modules/security/pages/security-advanced/security-advanced005.adoc @@ -4,11 +4,11 @@ The Jakarta EE authentication requirements for application clients are the same No authentication is necessary when accessing unprotected web resources. When accessing protected web resources, the usual varieties of authentication can be used: HTTP basic authentication, HTTP login-form authentication, or SSL client authentication. -<> describes how to specify HTTP basic authentication and HTTP login-form authentication. -<> describes how to specify SSL client authentication. +xref:security-webtier/security-webtier.adoc#_specifying_an_authentication_mechanism_in_the_deployment_descriptor[Specifying an Authentication Mechanism in the Deployment Descriptor] describes how to specify HTTP basic authentication and HTTP login-form authentication. +xref:security-advanced/security-advanced.adoc#_client_authentication[Client Authentication] describes how to specify SSL client authentication. Authentication is required when accessing protected enterprise beans. -The authentication mechanisms for enterprise beans are discussed in <>. +The authentication mechanisms for enterprise beans are discussed in xref:security-jakartaee/security-jakartaee.adoc#_securing_enterprise_beans[Securing Enterprise Beans]. An application client makes use of an authentication service provided by the application client container for authenticating its users. The container's service can be integrated with the native platform's authentication system so that a single sign-on capability is used. @@ -32,7 +32,7 @@ For example, the implementation of a callback handler for a GUI application migh The login module passes an array of appropriate callbacks to the callback handler's `handle` method, such as a `NameCallback` for the user name and a `PasswordCallback` for the password; the callback handler performs the requested user interaction and sets appropriate values in the callbacks. For example, to process a `NameCallback`, the `CallbackHandler` might prompt for a name, retrieve the value from the user, and call the `setName` method of the `NameCallback` to store the name. -For more information on using JAAS for authentication in login modules, refer to the documentation listed in <>. +For more information on using JAAS for authentication in login modules, refer to the documentation listed in xref:security-advanced/security-advanced.adoc#_further_information_about_advanced_security_topics[Further Information about Advanced Security Topics]. === Using Programmatic Login diff --git a/src/main/asciidoc/security-advanced/security-advanced006.adoc b/src/main/antora/modules/security/pages/security-advanced/security-advanced006.adoc similarity index 97% rename from src/main/asciidoc/security-advanced/security-advanced006.adoc rename to src/main/antora/modules/security/pages/security-advanced/security-advanced006.adoc index e650e2bb..9cb80bed 100644 --- a/src/main/asciidoc/security-advanced/security-advanced006.adoc +++ b/src/main/antora/modules/security/pages/security-advanced/security-advanced006.adoc @@ -13,7 +13,7 @@ The container determines the user name and password for establishing a connectio * Component-managed sign-on: The application component code manages EIS sign-on by including code that performs the sign-on process to an EIS. You can also configure security for resource adapters. -See <>. +See <<_configuring_resource_adapter_security>>. === Container-Managed Sign-On @@ -115,7 +115,7 @@ You can, however, manually update the `server.policy` file to add the relevant p + The security permissions listed in the deployment descriptor are different from those required by the default permission set as specified in the connector specification. + -For more information on the implementation of the security permission specification, see the security policy file documentation listed in <>. +For more information on the implementation of the security permission specification, see the security policy file documentation listed in xref:security-advanced/security-advanced.adoc#_further_information_about_advanced_security_topics[Further Information about Advanced Security Topics]. In addition to specifying resource adapter security in the `ra.xml` file, you can create a security map for a connector connection pool to map an application principal or a user group to a back-end EIS principal. The security map is usually used if one or more EIS back-end principals are used to execute operations (on the EIS) initiated by various principals or user groups in the application. diff --git a/src/main/asciidoc/security-advanced/security-advanced007.adoc b/src/main/antora/modules/security/pages/security-advanced/security-advanced007.adoc similarity index 97% rename from src/main/asciidoc/security-advanced/security-advanced007.adoc rename to src/main/antora/modules/security/pages/security-advanced/security-advanced007.adoc index 946fb2e1..7f8bd18f 100644 --- a/src/main/asciidoc/security-advanced/security-advanced007.adoc +++ b/src/main/antora/modules/security/pages/security-advanced/security-advanced007.adoc @@ -14,7 +14,7 @@ The elements of the deployment descriptor that add basic authentication to an ex * If authorized, display the servlet to the user. -The following sample code shows the security elements for a deployment descriptor that could be used in the example of basic authentication found in the `_tut-install_/examples/security/hello2_basicauth/` directory: +The following sample code shows the security elements for a deployment descriptor that could be used in the example of basic authentication found in the `_jakartaee-examples_/tutorial/security/hello2_basicauth/` directory: [source,xml] ---- diff --git a/src/main/asciidoc/security-advanced/security-advanced008.adoc b/src/main/antora/modules/security/pages/security-advanced/security-advanced008.adoc similarity index 100% rename from src/main/asciidoc/security-advanced/security-advanced008.adoc rename to src/main/antora/modules/security/pages/security-advanced/security-advanced008.adoc diff --git a/src/main/asciidoc/security-api/security-api.adoc b/src/main/antora/modules/security/pages/security-api/security-api.adoc similarity index 90% rename from src/main/asciidoc/security-api/security-api.adoc rename to src/main/antora/modules/security/pages/security-api/security-api.adoc index 6a979236..444bed5b 100644 --- a/src/main/asciidoc/security-api/security-api.adoc +++ b/src/main/antora/modules/security/pages/security-api/security-api.adoc @@ -1,5 +1,7 @@ = Using Jakarta Security +include::ROOT:partial$not_updated.adoc[] + This chapter describes the authentication and credential validation functionality provided by Jakarta Security. The API also defines a `SecurityContext` access point for programmatic security. diff --git a/src/main/asciidoc/security-api/security-api001.adoc b/src/main/antora/modules/security/pages/security-api/security-api001.adoc similarity index 90% rename from src/main/asciidoc/security-api/security-api001.adoc rename to src/main/antora/modules/security/pages/security-api/security-api001.adoc index e5be4a50..beb38ba0 100644 --- a/src/main/asciidoc/security-api/security-api001.adoc +++ b/src/main/antora/modules/security/pages/security-api/security-api001.adoc @@ -6,18 +6,18 @@ You can use the built-in implementations of these APIs, or define custom impleme Jakarta Security contains the following packages: * The `jakarta.security.enterprise` package is the main Jakarta Security package and contains classes and interfaces that span authentication, authorization, and identity concerns. -<> lists the main class and interfaces in this package. +<<_main_classes_and_interfaces_in_enterprise>> lists the main class and interfaces in this package. * The `jakarta.security.enterprise.authentication.mechanism.http` package contains classes and interfaces associated with HTTP-based authentication mechanisms that can interact with a caller or third-parties as part of an authentication protocol. -<> lists the main classes and interfaces in this package. +<<_main_classes_and_interfaces_in_authentication>> lists the main classes and interfaces in this package. * The `jakarta.security.enterprise.credential` package contains classes and interfaces for representing user credentials. -<> lists the main classes and interfaces in this package. +<<_main_classes_and_interfaces_in_credential>> lists the main classes and interfaces in this package. * The `jakarta.security.enterprise.identitystore` package contains classes and interfaces associated with identity stores that validate a caller's credentials and lookup caller groups. -<> lists the main classes and interfaces in this package. +<<_main_classes_and_interfaces_in_identitystore>> lists the main classes and interfaces in this package. -[[main-classes-and-interfaces-in-enterprise]] +[[_main_classes_and_interfaces_in_enterprise]] .Main Classes and Interfaces in `jakarta.security.enterprise` [width="99%",cols="25%,75%"] |=== @@ -32,7 +32,7 @@ Jakarta Security contains the following packages: |`AuthenticationException` |Indicates that a problem occurred during the authentication process. |=== -[[main-classes-and-interfaces-in-authentication]] +[[_main_classes_and_interfaces_in_authentication]] .Main Classes and Interfaces in `jakarta.security.enterprise.authentication.mechanism.http` [width="99%",cols="25%,75%"] |=== @@ -51,7 +51,7 @@ Developers can provide their own implementation of this interface, or use one of [NOTE] The `jakarta.security.enterprise.authentication.mechanism.http` package also includes a number of annotation classes that are used to configure/enable the built-in authentication mechanisms or to modify the behavior of an authentication mechanism. -[[main-classes-and-interfaces-in-credential]] +[[_main_classes_and_interfaces_in_credential]] .Main Classes and Interfaces in `jakarta.security.enterprise.credential` [width="99%",cols="25%,75%"] |=== @@ -73,7 +73,7 @@ All other classes in this package are implementations of the Credential interfac |`UsernamePasswordCredential` |Class that represents the credentials typically used by standard caller name/password authentication. |=== -[[main-classes-and-interfaces-in-identitystore]] +[[_main_classes_and_interfaces_in_identitystore]] .Main Classes and Interfaces in `jakarta.security.enterprise.identitystore` [width="99%",cols="25%,75%"] |=== diff --git a/src/main/asciidoc/security-api/security-api002.adoc b/src/main/antora/modules/security/pages/security-api/security-api002.adoc similarity index 100% rename from src/main/asciidoc/security-api/security-api002.adoc rename to src/main/antora/modules/security/pages/security-api/security-api002.adoc diff --git a/src/main/asciidoc/security-api/security-api003.adoc b/src/main/antora/modules/security/pages/security-api/security-api003.adoc similarity index 96% rename from src/main/asciidoc/security-api/security-api003.adoc rename to src/main/antora/modules/security/pages/security-api/security-api003.adoc index 3dd0da51..d8787eaa 100644 --- a/src/main/asciidoc/security-api/security-api003.adoc +++ b/src/main/antora/modules/security/pages/security-api/security-api003.adoc @@ -2,9 +2,9 @@ The Identity Store Interfaces are described in the following sections: -* <> +* <<_the_identitystore_interface>> -* <> +* <<_the_remembermeidentitystore_interface>> === The IdentityStore Interface @@ -20,14 +20,14 @@ They are configured with the parameters necessary to communicate with an externa * `DatabaseIdentityStoreDefinition` -- configures an identity store with the parameters necessary to connect to an external database, validate user credentials, and/or lookup user groups. You must supply a PasswordHash implementation when configuring a Database Identity Store. -See <>. +See <<_the_passwordhash_interface>>. An application can provide its own custom identity store, or use the built-in LDAP or database identity stores. For examples of both types, see: -* <> +* xref:security-api/security-api.adoc#_running_the_built_in_database_identity_store_example[Running the Built-In Database Identity Store Example] -* <> +* xref:security-api/security-api.adoc#_running_the_custom_identity_store_example[Running the Custom Identity Store Example] An implementation of `IdentityStore` must be a CDI bean to be recognized and deployed at runtime, and is assumed to be normal scoped. IdentityStores are primarily intended for use by implementations of `HttpAuthenticationMechanisms`, but this is not a requirement. diff --git a/src/main/asciidoc/security-api/security-api004.adoc b/src/main/antora/modules/security/pages/security-api/security-api004.adoc similarity index 87% rename from src/main/asciidoc/security-api/security-api004.adoc rename to src/main/antora/modules/security/pages/security-api/security-api004.adoc index c6c9b566..c11755f5 100644 --- a/src/main/asciidoc/security-api/security-api004.adoc +++ b/src/main/antora/modules/security/pages/security-api/security-api004.adoc @@ -4,9 +4,9 @@ The example described in this section demonstrates how to use the built-in datab Topics include: -* <> +* <<_overview_of_the_built_in_database_identity_store_example>> -* <> +* <<_running_the_built_in_db_identity_store_example>> === Overview of the Built-In Database Identity Store Example @@ -16,18 +16,18 @@ To support this mandatory requirement, `DatabaseIdentityStore` is bundled with G This example demonstrates how you can configure a `DatabaseIdentityStore` to point to a backend database and then use it as an IdentityStore. The authentication mechanism used is `BasicAuthenticationMechanism`. -The source code for this example is in the `_tut-install_/examples/security/security-api/built-in-db-identity-store` directory. +The source code for this example is in the `_jakartaee-examples_/tutorial/security/security-api/built-in-db-identity-store` directory. The following sections describe the high-level process for configuring the `DatabaseIdentityStore`. Note that the configuration described in these sections has already been completed in the application files, but is provided here to illustrate what you need to do to use the built-in database identity store. -* <> +* xref:security-api/security-api.adoc#_define_the_users_and_groups_in_the_identity_store[Define the Users and Groups in the Identity Store] -* <> +* <<_map_the_databaseidentitystore_to_the_default_data_source>> -* <> +* xref:security-api/security-api.adoc#_specify_the_authentication_mechanism[Specify the Authentication Mechanism] -* <> +* xref:security-api/security-api.adoc#_declare_roles_in_the_servlet_container[Declare Roles in the Servlet Container] When a request that includes credentials is sent to the application, it triggers the configured authentication mechanism and authentication is performed against the `DatabaseIdentityStore` as defined in the application. @@ -198,27 +198,27 @@ Therefore, you do not need to bundle web.xml with the application to provide map You can use either NetBeans IDE or Maven to build, package, deploy, and run the `built-in-db-identity-store` application as described in the following topics: -* <> +* <<_to_build_package_and_deploy_the_built_in_db_identity_store_example_using_netbeans_ide>> -* <> +* <<_to_build_package_and_deploy_the_built_in_db_identity_store_example_using_maven>> -* <> +* <<_to_run_the_built_in_db_identity_store_example>> ==== To Build, Package, and Deploy the built-in-db-identity-store Example Using NetBeans IDE . If you have not already done so, start the default database. This is necessary because we are using the DefaultDataSource bundled with GlassFish for `DatabaseIdentityStore`. -See <>. +See xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_apache_derby[Starting and Stopping Apache Derby]. . If you have not already done so, start the GlassFish server. -See <>. +See xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]. . From the File menu, choose Open Project. . In the Open Project dialog box, navigate to: + ---- -tut-install/examples/security/security-api +jakartaee-examples/tutorial/security/security-api ---- . Select the `built-in-db-identity-store` folder. @@ -233,15 +233,15 @@ This command builds and deploys the example application to your GlassFish Server . If you have not already done so, start the default database. This is necessary because we are using the DefaultDataSource bundled with GlassFish for `DatabaseIdentityStore`. -See <>. +See xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_apache_derby[Starting and Stopping Apache Derby]. . If you have not already done so, start the GlassFish server. See -<>. +xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]. . In a terminal window, go to: + ---- -tut-install/examples/security/security-api/built-in-db-identity-store +jakartaee-examples/tutorial/security/security-api/built-in-db-identity-store ---- . Enter the following command: diff --git a/src/main/asciidoc/security-api/security-api005.adoc b/src/main/antora/modules/security/pages/security-api/security-api005.adoc similarity index 86% rename from src/main/asciidoc/security-api/security-api005.adoc rename to src/main/antora/modules/security/pages/security-api/security-api005.adoc index 68557035..b16a457b 100644 --- a/src/main/asciidoc/security-api/security-api005.adoc +++ b/src/main/antora/modules/security/pages/security-api/security-api005.adoc @@ -4,9 +4,9 @@ The example described in this section demonstrates how to bundle and use a custo Topics include: -* <> +* <<_overview_of_the_custom_identity_store_example>> -* <> +* <<_running_the_custom_identity_store_example_2>> === Overview of the Custom Identity Store Example @@ -16,16 +16,16 @@ When bundled with the application, this custom identity store can then be used f This example demonstrates how to define a custom identity store, `TestIdentityStore`, and provide it as part of the application being deployed. The authentication mechanism used is `BasicAuthenticationMechanism`. -The source code for this example is in the `_tut-install_/examples/security/security-api/custom-identity-store` directory. +The source code for this example is in the `_jakartaee-examples_/tutorial/security/security-api/custom-identity-store` directory. The following sections describe the high-level process for defining the `TestIdentityStore`. Note that the configuration described in these sections has already been completed in the application files, but is provided here to illustrate what you need to do to use a custom identity store. -* <> +* <<_define_the_users_and_groups_in_the_identity_store>> -* <> +* <<_specify_the_authentication_mechanism>> -* <> +* <<_declare_roles_in_the_servlet_container>> When a request that includes credentials is sent to the application, the configured authentication mechanism comes into effect and authentication is performed against the `TestIdentityStore` as defined in the application. @@ -119,27 +119,28 @@ public class Servlet extends HttpServlet { In GlassFish 6.0, group to role mapping is enabled by default. Therefore, you do not need to bundle `web.xml` with the application to provide mapping between roles and groups. +[[_running_the_custom_identity_store_example_2]] === Running the custom-identity-store Example You can use either NetBeans IDE or Maven to build, package, deploy, and run the `custom-identity-store` application as described in the following topics: -* <> +* <<_to_build_package_and_deploy_the_custom_identity_store_example_using_netbeans_ide>> -* <> +* <<_to_build_package_and_deploy_the_custom_identity_store_example_using_maven>> -* <> +* <<_to_run_the_custom_identity_store_example>> ==== To Build, Package, and Deploy the custom-identity-store Example Using NetBeans IDE . If you have not already done so, start the GlassFish server. -See <>. +See xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]. . From the File menu, choose Open Project. . In the Open Project dialog box, navigate to: + ---- -tut-install/examples/security/security-api +jakartaee-examples/tutorial/security/security-api ---- . Select the `custom-identity-store` folder. @@ -153,12 +154,12 @@ This command builds and deploys the example application to your GlassFish Server ==== To Build, Package, and Deploy the custom-identity-store Example Using Maven . If you have not already done so, start the GlassFish server. -See <>. +See xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]. . In a terminal window, go to: + ---- -tut-install/examples/security/security-api/custom-identity-store +jakartaee-examples/tutorial/security/security-api/custom-identity-store ---- . Enter the following command: diff --git a/src/main/antora/modules/security/pages/security-authentication/security-authentication.adoc b/src/main/antora/modules/security/pages/security-authentication/security-authentication.adoc new file mode 100644 index 00000000..f73eb49b --- /dev/null +++ b/src/main/antora/modules/security/pages/security-authentication/security-authentication.adoc @@ -0,0 +1,3 @@ += Jakarta Authentication + +https://jakarta.ee/specifications/authentication/[Jakarta Authentication Specification] \ No newline at end of file diff --git a/src/main/antora/modules/security/pages/security-authorization/security-authorization.adoc b/src/main/antora/modules/security/pages/security-authorization/security-authorization.adoc new file mode 100644 index 00000000..e8292464 --- /dev/null +++ b/src/main/antora/modules/security/pages/security-authorization/security-authorization.adoc @@ -0,0 +1,3 @@ += Jakarta Authorization + +https://jakarta.ee/specifications/authorization/[Jakarta Authorization Specification] \ No newline at end of file diff --git a/src/main/asciidoc/security-intro/security-intro.adoc b/src/main/antora/modules/security/pages/security-intro/security-intro.adoc similarity index 93% rename from src/main/asciidoc/security-intro/security-intro.adoc rename to src/main/antora/modules/security/pages/security-intro/security-intro.adoc index 20c5ebd2..5d1babcd 100644 --- a/src/main/asciidoc/security-intro/security-intro.adoc +++ b/src/main/antora/modules/security/pages/security-intro/security-intro.adoc @@ -1,5 +1,7 @@ = Introduction to Security in the Jakarta EE Platform +include::ROOT:partial$not_updated.adoc[] + This chapter introduces basic security concepts and security mechanisms. More information on these concepts and mechanisms can be found in the chapter on security in the Jakarta EE 9 specification. diff --git a/src/main/asciidoc/security-intro/security-intro001.adoc b/src/main/antora/modules/security/pages/security-intro/security-intro001.adoc similarity index 78% rename from src/main/asciidoc/security-intro/security-intro001.adoc rename to src/main/antora/modules/security/pages/security-intro/security-intro001.adoc index ddec4c09..16874f5c 100644 --- a/src/main/asciidoc/security-intro/security-intro001.adoc +++ b/src/main/antora/modules/security/pages/security-intro/security-intro001.adoc @@ -10,7 +10,7 @@ A container provides two kinds of security: declarative and programmatic. * Declarative security expresses an application component's security requirements by using either deployment descriptors or annotations. + A deployment descriptor is an XML file that is external to the application and that expresses an application's security structure, including security roles, access control, and authentication requirements. -For more information about deployment descriptors, read <>. +For more information about deployment descriptors, read xref:security-intro/security-intro.adoc#_using_deployment_descriptors_for_declarative_security[Using Deployment Descriptors for Declarative Security]. + Annotations, also called metadata, are used to specify information about security within a class file. When the application is deployed, this information can be either used by or overridden by the application deployment descriptor. @@ -18,11 +18,11 @@ Annotations save you from having to write declarative information inside XML des Instead, you simply put annotations on the code, and the required information gets generated. For this tutorial, annotations are used for securing applications wherever possible. For more information about annotations, see -<>. +xref:security-intro/security-intro.adoc#_using_annotations_to_specify_security_information[Using Annotations to Specify Security Information]. * Programmatic security is embedded in an application and is used to make security decisions. Programmatic security is useful when declarative security alone is not sufficient to express the security model of an application. -For more information about programmatic security, read <>. +For more information about programmatic security, read xref:security-intro/security-intro.adoc#_using_programmatic_security[Using Programmatic Security]. Jakarta EE 9 includes a Security API specification that defines portable, plug-in interfaces for authentication and identity stores, and a new injectable-type `SecurityContext` interface that provides an access point for programmatic security. You can use the built-in implementations of these APIs, or define custom implementations. @@ -31,11 +31,11 @@ More information on these concepts and mechanisms can be found in the chapter on Other chapters in this Part discuss security requirements in web tier and enterprise tier applications, and the Jakarta Security. -* xref:getting-started-securing-web-applications[xrefstyle=full] explains how to add security to web components, such as servlets. +* xref:security-webtier/security-webtier.adoc#_getting_started_securing_web_applications[Getting Started Securing Web Applications] explains how to add security to web components, such as servlets. -* xref:getting-started-securing-enterprise-applications[xrefstyle=full] explains how to add security to Jakarta EE components, such as enterprise beans and application clients. +* xref:security-jakartaee/security-jakartaee.adoc#_getting_started_securing_enterprise_applications[Getting Started Securing Enterprise Applications] explains how to add security to Jakarta EE components, such as enterprise beans and application clients. -* xref:using-jakarta-security[xrefstyle=full] describes the authentication and credential validation funtionality provided by Jakarta Security, and provides examples. +* xref:security-api/security-api.adoc#_using_jakarta_security[Using Jakarta Security] describes the authentication and credential validation funtionality provided by Jakarta Security, and provides examples. === A Simple Application Security Walkthrough @@ -46,25 +46,25 @@ In the following example, which is taken from the Jakarta EE Specification, the ==== Step 1: Initial Request In the first step of this example, the web client requests the main application URL. -This action is shown in <>. +This action is shown in <<_initial_request>>. -[[initial-request]] +[[_initial_request]] .Initial Request -image::jakartaeett_dt_039.svg["Diagram of initial request from web client to web server for access to a protected resource"] +image::common:jakartaeett_dt_039.svg["Diagram of initial request from web client to web server for access to a protected resource"] Since the client has not yet authenticated itself to the application environment, the server responsible for delivering the web portion of the application, hereafter referred to as the web server, detects this and invokes the appropriate authentication mechanism for this resource. -For more information on these mechanisms, see <>. +For more information on these mechanisms, see xref:security-intro/security-intro.adoc#_security_mechanisms[Security Mechanisms]. ==== Step 2: Initial Authentication The web server returns a form that the web client uses to collect authentication data, such as user name and password, from the user. -The web client forwards the authentication data to the web server, where it is validated by the web server, as shown in <>. +The web client forwards the authentication data to the web server, where it is validated by the web server, as shown in <<_initial_authentication>>. The validation mechanism may be local to a server or may leverage the underlying security services. On the basis of the validation, the web server sets a credential for the user. -[[initial-authentication]] +[[_initial_authentication]] .Initial Authentication -image::jakartaeett_dt_040.svg["Diagram of initial authentication: server sends form to client, which sends authentication data to server for validation"] +image::common:jakartaeett_dt_040.svg["Diagram of initial authentication: server sends form to client, which sends authentication data to server for validation"] ==== Step 3: URL Authorization @@ -72,34 +72,34 @@ The credential is used for future determinations of whether the user is authoriz The web server consults the security policy associated with the web resource to determine the security roles that are permitted access to the resource. The security policy is derived from annotations or from the deployment descriptor. The web container then tests the user's credential against each role to determine whether it can map the user to the role. -<> shows this process. +<<_url_authorization>> shows this process. -[[url-authorization]] +[[_url_authorization]] .URL Authorization -image::jakartaeett_dt_041.svg["Diagram of URL authorization"] +image::common:jakartaeett_dt_041.svg["Diagram of URL authorization"] The web server's evaluation stops with an "is authorized" outcome when the web server is able to map the user to a role. A "not authorized" outcome is reached if the web server is unable to map the user to any of the permitted roles. ==== Step 4: Fulfilling the Original Request -If the user is authorized, the web server returns the result of the original URL request, as shown in <>. +If the user is authorized, the web server returns the result of the original URL request, as shown in <<_fulfilling_the_original_request>>. -[[fulfilling-the-original-request]] +[[_fulfilling_the_original_request]] .Fulfilling the Original Request -image::jakartaeett_dt_042.svg["Diagram of request fulfillment, showing server returning result to client"] +image::common:jakartaeett_dt_042.svg["Diagram of request fulfillment, showing server returning result to client"] In our example, the response URL of a web page is returned, enabling the user to post form data that needs to be handled by the business-logic component of the application. -See xref:getting-started-securing-web-applications[xrefstyle=full] for more information on protecting web applications. +See xref:security-webtier/security-webtier.adoc#_getting_started_securing_web_applications[Getting Started Securing Web Applications] for more information on protecting web applications. ==== Step 5: Invoking Enterprise Bean Business Methods -The web page performs the remote method call to the enterprise bean, using the user's credential to establish a secure association between the web page and the enterprise bean, as shown in <>. +The web page performs the remote method call to the enterprise bean, using the user's credential to establish a secure association between the web page and the enterprise bean, as shown in <<_invoking_an_enterprise_bean_business_method>>. The association is implemented as two related security contexts: one in the web server and one in the enterprise bean container. -[[invoking-an-enterprise-bean-business-method]] +[[_invoking_an_enterprise_bean_business_method]] .Invoking an Enterprise Bean Business Method -image::jakartaeett_dt_043.svg["Diagram of authorization process between web component and enterprise bean"] +image::common:jakartaeett_dt_043.svg["Diagram of authorization process between web component and enterprise bean"] The enterprise container is responsible for enforcing access control on the enterprise bean method. The container consults the security policy associated with the enterprise bean to determine the security roles that are permitted access to the method. diff --git a/src/main/asciidoc/security-intro/security-intro002.adoc b/src/main/antora/modules/security/pages/security-intro/security-intro002.adoc similarity index 95% rename from src/main/asciidoc/security-intro/security-intro002.adoc rename to src/main/antora/modules/security/pages/security-intro/security-intro002.adoc index 83146b10..3cb69415 100644 --- a/src/main/asciidoc/security-intro/security-intro002.adoc +++ b/src/main/antora/modules/security/pages/security-intro/security-intro002.adoc @@ -32,7 +32,7 @@ For more information on Java SE security, visit https://docs.oracle.com/javase/8 === Jakarta EE Security Mechanisms -Jakarta EE security services are provided by the component container and can be implemented by using declarative or programmatic techniques (see <>). +Jakarta EE security services are provided by the component container and can be implemented by using declarative or programmatic techniques (see xref:security-intro/security-intro.adoc#_securing_containers[Securing Containers]). Jakarta EE security services provide a robust and easily configured security mechanism for authenticating users and authorizing access to application functions and associated data at many different layers. Jakarta EE security services are separate from the security mechanisms of the operating system. @@ -59,7 +59,7 @@ The disadvantages of using application-layer security include the following. * Data is close to or contained within the point of vulnerability. -For more information on providing security at the application layer, see <>. +For more information on providing security at the application layer, see xref:security-intro/security-intro.adoc#_securing_containers[Securing Containers]. ==== Transport-Layer Security @@ -101,7 +101,7 @@ Protection is removed automatically by the endpoint when it receives the message * It is not an end-to-end solution, simply point-to-point. -For more information on transport-layer security, see <>. +For more information on transport-layer security, see xref:security-intro/security-intro.adoc#_establishing_a_secure_connection_using_ssl[Establishing a Secure Connection Using SSL]. ==== Message-Layer Security diff --git a/src/main/asciidoc/security-intro/security-intro003.adoc b/src/main/antora/modules/security/pages/security-intro/security-intro003.adoc similarity index 78% rename from src/main/asciidoc/security-intro/security-intro003.adoc rename to src/main/antora/modules/security/pages/security-intro/security-intro003.adoc index c6379ae6..89c53eb7 100644 --- a/src/main/asciidoc/security-intro/security-intro003.adoc +++ b/src/main/antora/modules/security/pages/security-intro/security-intro003.adoc @@ -11,11 +11,11 @@ GlassFish Server uses this information when the application is deployed. Not all security information can be specified by using annotations, however. Some information must be specified in the application deployment descriptors. -Specific annotations that can be used to specify security information within an enterprise bean class file are described in <>. -xref:getting-started-securing-web-applications[xrefstyle=full], describes how to use annotations to secure web applications where possible. +Specific annotations that can be used to specify security information within an enterprise bean class file are described in xref:security-jakartaee/security-jakartaee.adoc#_securing_an_enterprise_bean_using_declarative_security[Securing an Enterprise Bean Using Declarative Security]. +xref:security-webtier/security-webtier.adoc#_getting_started_securing_web_applications[Getting Started Securing Web Applications], describes how to use annotations to secure web applications where possible. Deployment descriptors are described only where necessary. -For more information on annotations, see <>. +For more information on annotations, see xref:security-intro/security-intro.adoc#_further_information_about_security[Further Information about Security]. === Using Deployment Descriptors for Declarative Security @@ -47,6 +47,6 @@ These methods allow components to make business-logic decisions based on the sec Programmatic security is discussed in more detail in the following sections: -* <> +* xref:security-webtier/security-webtier.adoc#_using_programmatic_security_with_web_applications[Using Programmatic Security with Web Applications] -* <> +* xref:security-jakartaee/security-jakartaee.adoc#_securing_an_enterprise_bean_programmatically[Securing an Enterprise Bean Programmatically] diff --git a/src/main/asciidoc/security-intro/security-intro003a.adoc b/src/main/antora/modules/security/pages/security-intro/security-intro003a.adoc similarity index 97% rename from src/main/asciidoc/security-intro/security-intro003a.adoc rename to src/main/antora/modules/security/pages/security-intro/security-intro003a.adoc index 8247aab9..9e446834 100644 --- a/src/main/asciidoc/security-intro/security-intro003a.adoc +++ b/src/main/antora/modules/security/pages/security-intro/security-intro003a.adoc @@ -3,9 +3,9 @@ Jakarta EE includes two specifications that define SPI interfaces for pluggable security providers, Jakarta Authentication and Jakarta Security. These specifications are described in more detail in the following sections: -* <> +* xref:intro:overview/overview.adoc#_jakarta_authentication[Jakarta Authentication] -* <> +* xref:intro:overview/overview.adoc#_jakarta_security[Jakarta Security] === Jakarta Authentication diff --git a/src/main/asciidoc/security-intro/security-intro004.adoc b/src/main/antora/modules/security/pages/security-intro/security-intro004.adoc similarity index 88% rename from src/main/asciidoc/security-intro/security-intro004.adoc rename to src/main/antora/modules/security/pages/security-intro/security-intro004.adoc index eae3422e..0b48211b 100644 --- a/src/main/asciidoc/security-intro/security-intro004.adoc +++ b/src/main/antora/modules/security/pages/security-intro/security-intro004.adoc @@ -5,7 +5,7 @@ GlassFish Server supports the Jakarta EE 9 security model. You can configure GlassFish Server for the following purposes. * Adding, deleting, or modifying authorized users. -For more information on this topic, see <>. +For more information on this topic, see xref:security-intro/security-intro.adoc#_working_with_realms_users_groups_and_roles[Working with Realms, Users, Groups, and Roles]. * Configuring secure HTTP and Internet Inter-Orb Protocol (IIOP) listeners. diff --git a/src/main/asciidoc/security-intro/security-intro005.adoc b/src/main/antora/modules/security/pages/security-intro/security-intro005.adoc similarity index 86% rename from src/main/asciidoc/security-intro/security-intro005.adoc rename to src/main/antora/modules/security/pages/security-intro/security-intro005.adoc index 2e66e285..1f5dbe34 100644 --- a/src/main/asciidoc/security-intro/security-intro005.adoc +++ b/src/main/antora/modules/security/pages/security-intro/security-intro005.adoc @@ -1,22 +1,22 @@ == Working with Realms, Users, Groups, and Roles You often need to protect resources to ensure that only authorized users have access. -See <> for an introduction to the concepts of authentication, identification, and authorization. +See xref:security-intro/security-intro.adoc#_characteristics_of_application_security[Characteristics of Application Security] for an introduction to the concepts of authentication, identification, and authorization. This section discusses setting up users so that they can be correctly identified and either given access to protected resources or denied access if they are not authorized to access the protected resources. To authenticate a user, you need to follow these basic steps. . The application developer writes code to prompt for a user name and password. -The various methods of authentication are discussed in <>. +The various methods of authentication are discussed in xref:security-webtier/security-webtier.adoc#_specifying_authentication_mechanisms[Specifying Authentication Mechanisms]. . The application developer communicates how to set up security for the deployed application by use of a metadata annotation or deployment descriptor. -This step is discussed in <>. +This step is discussed in <<_setting_up_security_roles>>. . The server administrator sets up authorized users and groups in GlassFish Server. -This is discussed in <>. +This is discussed in <<_managing_users_and_groups_in_glassfish_server>>. . The application deployer maps the application's security roles to users, groups, and principals defined in GlassFish Server. -This topic is discussed in <>. +This topic is discussed in <<_mapping_roles_to_users_and_groups>>. [NOTE] By default, group principal names are mapped to roles of the same name. @@ -25,20 +25,20 @@ By default, group principal names are mapped to roles of the same name. A realm is a security policy domain defined for a web or application server. A realm contains a collection of users, who may or may not be assigned to a group. -Managing users in GlassFish Server is discussed in <>. +Managing users in GlassFish Server is discussed in <<_managing_users_and_groups_in_glassfish_server>>. An application will often prompt for a user name and password before allowing access to a protected resource. After the user name and password have been entered, that information is passed to the server, which either authenticates the user and sends the protected resource or does not authenticate the user, in which case access to the protected resource is denied. -This type of user authentication is discussed in <>. +This type of user authentication is discussed in xref:security-webtier/security-webtier.adoc#_specifying_an_authentication_mechanism_in_the_deployment_descriptor[Specifying an Authentication Mechanism in the Deployment Descriptor]. In some applications, authorized users are assigned to roles. In this situation, the role assigned to the user in the application must be mapped to a principal or group defined on the application server. -<> shows this. -More information on mapping roles to users and groups can be found in <>. +<<_mapping_roles_to_users_and_groups>> shows this. +More information on mapping roles to users and groups can be found in <<_setting_up_security_roles>>. -[[mapping-roles-to-users-and-groups]] +[[_mapping_roles_to_users_and_groups]] .Mapping Roles to Users and Groups -image::jakartaeett_dt_044.svg["Diagram of role mapping, showing creation of users and groups, definition of roles, and mapping of roles to users and groups"] +image::common:jakartaeett_dt_044.svg["Diagram of role mapping, showing creation of users and groups, definition of roles, and mapping of roles to users and groups"] The following sections provide more information on realms, users, groups, and roles. @@ -58,12 +58,12 @@ This realm is used for the authentication of all clients except for web browser In the `certificate` realm, the server stores user credentials in a certificate database. When using the `certificate` realm, the server uses certificates with HTTPS to authenticate web clients. To verify the identity of a user in the `certificate` realm, the authentication service verifies an X.509 certificate. -For step-by-step instructions for creating this type of certificate, see <>. +For step-by-step instructions for creating this type of certificate, see xref:security-advanced/security-advanced.adoc#_working_with_digital_certificates[Working with Digital Certificates]. The common name field of the X.509 certificate is used as the principal name. The `admin-realm` is also a `file` realm and stores administrator user credentials locally in a file named `admin-keyfile`. You can use the Administration Console to manage users in this realm in the same way you manage users in the `file` realm. -For more information, see <>. +For more information, see <<_managing_users_and_groups_in_glassfish_server>>. ==== What Is a User? @@ -121,7 +121,7 @@ Follow these steps for managing users before you run the tutorial examples. . Start GlassFish Server, if you haven't already done so. + -Information on starting GlassFish Server is available in <>. +Information on starting GlassFish Server is available in xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]. . Start the Administration Console, if you haven't already done so. + @@ -144,7 +144,7 @@ For the example security applications, select the `file` realm. + You cannot add users to the `certificate` realm by using the Administration Console. In the `certificate` realm, you can add only certificates. -For information on adding (importing) certificates to the `certificate` realm, see <>. +For information on adding (importing) certificates to the `certificate` realm, see xref:security-advanced/security-advanced.adoc#_adding_users_to_the_certificate_realm[Adding Users to the Certificate Realm]. . On the Edit Realm page, click Manage Users. @@ -155,7 +155,7 @@ For information on adding (importing) certificates to the `certificate` realm, s For the Admin Realm, the Group List field is read-only, and the group name is `asadmin`. Restart GlassFish Server and the Administration Console after you add a user to the Admin Realm. + -For more information on these properties, see <>. +For more information on these properties, see <<_working_with_realms_users_groups_and_roles>>. + For the example security applications, specify a user with any name and password you like, but make sure that the user is assigned to the group `TutorialUser`. The user name and password are case-sensitive. @@ -169,7 +169,7 @@ When you design an enterprise bean or web component, you should always think abo For example, a web application for a human resources department might have a different request URL for someone who has been assigned the role of `DEPT_ADMIN` than for someone who has been assigned the role of `DIRECTOR`. The `DEPT_ADMIN` role may let you view employee data, but the `DIRECTOR` role enables you to modify employee data, including salary data. Each of these security roles is an abstract logical grouping of users that is defined by the person who assembles the application. -When an application is deployed, the deployer will map the roles to security identities in the operational environment, as shown in <>. +When an application is deployed, the deployer will map the roles to security identities in the operational environment, as shown in <<_mapping_roles_to_users_and_groups>>. For Jakarta EE components, you define security roles using the `@DeclareRoles` and `@RolesAllowed` metadata annotations. @@ -218,7 +218,7 @@ For example, a servlet might be annotated as follows: public class GreetingServlet extends HttpServlet { ... } ---- -These annotations are discussed in more detail in <> and <>. +These annotations are discussed in more detail in xref:security-webtier/security-webtier.adoc#_specifying_security_for_basic_authentication_using_annotations[Specifying Security for Basic Authentication Using Annotations] and xref:security-jakartaee/security-jakartaee.adoc#_securing_an_enterprise_bean_using_declarative_security[Securing an Enterprise Bean Using Declarative Security]. After users have provided their login information and the application has declared what roles are authorized to access protected parts of an application, the next step is to map the security role to the name of a user, or principal. diff --git a/src/main/asciidoc/security-intro/security-intro005a.adoc b/src/main/antora/modules/security/pages/security-intro/security-intro005a.adoc similarity index 92% rename from src/main/asciidoc/security-intro/security-intro005a.adoc rename to src/main/antora/modules/security/pages/security-intro/security-intro005a.adoc index 9223dc95..60ae2ff0 100644 --- a/src/main/asciidoc/security-intro/security-intro005a.adoc +++ b/src/main/antora/modules/security/pages/security-intro/security-intro005a.adoc @@ -12,4 +12,4 @@ The `IdentityStore` interface is intended primarily for use by the `HttpAuthenti Using the `HttpAuthenticationMechanism` and `IdentityStore` implementations, both built-in and custom, provides a significant advantage over the BASIC and FORM mechanisms defined by Servlet 5.0 (and previous versions) and configured declaratively using `` in `web.xml`, because it allows an application to control the identity stores it will authenticate against in a standard, portable way. An application can provide its own `IdentityStore`, or use the built in LDAP or Database identity store implementations of the interface. -For details about the `IdentityStore` interfaces and examples of their usage, see <>. +For details about the `IdentityStore` interfaces and examples of their usage, see xref:security-api/security-api.adoc#_overview_of_the_identity_store_interfaces[Overview of the Identity Store Interfaces]. diff --git a/src/main/asciidoc/security-intro/security-intro006.adoc b/src/main/antora/modules/security/pages/security-intro/security-intro006.adoc similarity index 96% rename from src/main/asciidoc/security-intro/security-intro006.adoc rename to src/main/antora/modules/security/pages/security-intro/security-intro006.adoc index cee5c28b..5fbac433 100644 --- a/src/main/asciidoc/security-intro/security-intro006.adoc +++ b/src/main/antora/modules/security/pages/security-intro/security-intro006.adoc @@ -1,6 +1,6 @@ == Establishing a Secure Connection Using SSL -Secure Sockets Layer (SSL) technology is security that is implemented at the transport layer (see <> for more information about transport-layer security). +Secure Sockets Layer (SSL) technology is security that is implemented at the transport layer (see xref:security-intro/security-intro.adoc#_transport_layer_security[Transport-Layer Security] for more information about transport-layer security). SSL allows web browsers and web servers to communicate over a secure connection. In this secure connection, the data is encrypted before being sent and then is decrypted upon receipt and before processing. Both the browser and the server encrypt all traffic before sending any data. diff --git a/src/main/asciidoc/security-intro/security-intro007.adoc b/src/main/antora/modules/security/pages/security-intro/security-intro007.adoc similarity index 100% rename from src/main/asciidoc/security-intro/security-intro007.adoc rename to src/main/antora/modules/security/pages/security-intro/security-intro007.adoc diff --git a/src/main/asciidoc/security-jakartaee/security-jakartaee.adoc b/src/main/antora/modules/security/pages/security-jakartaee/security-jakartaee.adoc similarity index 85% rename from src/main/asciidoc/security-jakartaee/security-jakartaee.adoc rename to src/main/antora/modules/security/pages/security-jakartaee/security-jakartaee.adoc index 003115e0..e0395e7b 100644 --- a/src/main/asciidoc/security-jakartaee/security-jakartaee.adoc +++ b/src/main/antora/modules/security/pages/security-jakartaee/security-jakartaee.adoc @@ -1,5 +1,7 @@ = Getting Started Securing Enterprise Applications +include::ROOT:partial$not_updated.adoc[] + This chapter describes how to administer security for enterprise applications. include::security-jakartaee001.adoc[] diff --git a/src/main/asciidoc/security-jakartaee/security-jakartaee001.adoc b/src/main/antora/modules/security/pages/security-jakartaee/security-jakartaee001.adoc similarity index 100% rename from src/main/asciidoc/security-jakartaee/security-jakartaee001.adoc rename to src/main/antora/modules/security/pages/security-jakartaee/security-jakartaee001.adoc diff --git a/src/main/asciidoc/security-jakartaee/security-jakartaee002.adoc b/src/main/antora/modules/security/pages/security-jakartaee/security-jakartaee002.adoc similarity index 93% rename from src/main/asciidoc/security-jakartaee/security-jakartaee002.adoc rename to src/main/antora/modules/security/pages/security-jakartaee/security-jakartaee002.adoc index 75cc43a4..96df689c 100644 --- a/src/main/asciidoc/security-jakartaee/security-jakartaee002.adoc +++ b/src/main/antora/modules/security/pages/security-jakartaee/security-jakartaee002.adoc @@ -21,14 +21,14 @@ A security role is a grouping of permissions that a given type of application us For example, in a payroll application, some users will want to view their own payroll information (employee), some will need to view others' payroll information (manager), and some will need to be able to change others' payroll information (payrollDept). The application developer would determine the potential users of the application and which methods would be accessible to which users. The application developer would then decorate classes or methods of the enterprise bean with annotations that specify the types of users authorized to access those methods. -Using annotations to specify authorized users is described in <>. +Using annotations to specify authorized users is described in <<_specifying_authorized_users_by_declaring_security_roles>>. + When one of the annotations is used to define method permissions, the deployment system will automatically require user name/password authentication. In this type of authentication, a user is prompted to enter a user name and password, which will be compared against a database of known users. If the user is found and the password matches, the roles that the user is assigned will be compared against the roles that are authorized to access the method. If the user is authenticated and found to have a role that is authorized to access that method, the data will be returned to the user. + -Using declarative security is discussed in <>. +Using declarative security is discussed in <<_securing_an_enterprise_bean_using_declarative_security>>. * Programmatic security: For an enterprise bean, code embedded in a business method that is used to access a caller's identity programmatically and that uses this information to make security decisions. Programmatic security is useful when declarative security alone is not sufficient to express the security model of an application. @@ -36,9 +36,9 @@ Programmatic security is useful when declarative security alone is not sufficien In general, security management should be enforced by the container in a manner that is transparent to the enterprise beans' business methods. The programmatic security APIs described in this chapter should be used only in the less frequent situations in which the enterprise bean business methods need to access the security-context information, such as when you want to grant access based on the time of day or other nontrivial condition checks for a particular role. + -Programmatic security is discussed in <>. +Programmatic security is discussed in <<_securing_an_enterprise_bean_programmatically>>. -Some of the material in this chapter assumes that you have already read xref:enterprise-beans-2[xrefstyle=full], xref:getting-started-with-enterprise-beans[xrefstyle=full], and xref:introduction-to-security-in-the-jakarta-ee-platform[xrefstyle=full]. +Some of the material in this chapter assumes that you have already read xref:entbeans:ejb-intro/ejb-intro.adoc#_enterprise_beans[Enterprise Beans], xref:entbeans:ejb-gettingstarted/ejb-gettingstarted.adoc#_getting_started_with_enterprise_beans[Getting Started with Enterprise Beans], and xref:security-intro/security-intro.adoc#_introduction_to_security_in_the_jakarta_ee_platform[Introduction to Security in the Jakarta EE Platform]. This section discusses securing a Jakarta EE application where one or more modules, such as enterprise bean JAR files, are packaged into an EAR file, the archive file that holds the application. Security annotations will be used in the Java programming class files to specify authorized users and basic, or user name/password, authentication. @@ -48,7 +48,7 @@ In these cases, packaging the enterprise bean within the web application's WAR m Enterprise beans may be packaged within a WAR module as Java class files or within a JAR file that is bundled within the WAR module. When a servlet or Jakarta Faces page handles the web front end and the application is packaged into a WAR module as a Java class file, security for the application can be handled in the application's `web.xml` file. The enterprise bean in the WAR file can have its own deployment descriptor, `ejb-jar.xml`, if required. -Securing web applications using `web.xml` is discussed in xref:getting-started-securing-web-applications[xrefsyle=full]. +Securing web applications using `web.xml` is discussed in xref:security-webtier/security-webtier.adoc#_getting_started_securing_web_applications[Getting Started Securing Web Applications]. The following sections describe declarative and programmatic security mechanisms that can be used to protect enterprise bean resources. The protected resources include enterprise bean methods that are called from application clients, web components, or other enterprise beans. @@ -75,7 +75,7 @@ It is important to keep in mind that security roles are used to define the logic They should not be confused with the user groups, users, principals, and other concepts that exist in GlassFish Server. Note that the Jakarta Security requires that group principal names be mapped to roles of the same name by default, but that implementations of the standard may allow configuration of a different default. In GlassFish Server, you do not need to perform any additional steps to map the roles defined in the application to users, groups, and principals that are the components of the user database in the `file` realm. -This mapping is set by default in the GlassFish Server Administration Console as described in <>. +This mapping is set by default in the GlassFish Server Administration Console as described in xref:security-intro/security-intro.adoc#_mapping_roles_to_users_and_groups[Mapping Roles to Users and Groups]>. The following sections show how an application developer uses declarative security to either secure an application or to create a security view to pass along to the deployer. @@ -218,7 +218,7 @@ public class SomeClass { ... } -@Stateless +@Stateless public class MyBean extends SomeClass implements A { @RolesAllowed("HR") @@ -277,12 +277,12 @@ The following code sample illustrates the use of the `getCallerPrincipal` method + [source,java] ---- -@Stateless +@Stateless public class EmployeeServiceBean implements EmployeeService { - @Resource + @Resource SessionContext ctx; - - @PersistenceContext + + @PersistenceContext EntityManager em; public void changePhoneNumber(...) { @@ -318,9 +318,9 @@ The following code sample illustrates the use of the `isCallerInRole` method: + [source,java] ---- -@Stateless +@Stateless public class PayrollBean implements Payroll { - @Resource + @Resource SessionContext ctx; public void updateEmployeeInfo(EmplInfo info) { @@ -340,16 +340,16 @@ public class PayrollBean implements Payroll { ---- You would use programmatic security in this way to dynamically control access to a method, for example, when you want to deny access except during a particular time of day. -An example application that uses the `getCallerPrincipal` and `isCallerInRole` methods is described in <>. +An example application that uses the `getCallerPrincipal` and `isCallerInRole` methods is described in xref:security-jakartaee/security-jakartaee.adoc#_the_converter_secure_example_securing_an_enterprise_bean_with_programmatic_security[The converter-secure Example: Securing an Enterprise Bean with Programmatic Security]. === Propagating a Security Identity (Run-As) You can specify whether a caller's security identity should be used for the execution of specified methods of an enterprise bean or whether a specific run-as identity should be used. -<> illustrates this concept. +<<_security_identity_propagation>> illustrates this concept. -[[security-identity-propagation]] +[[_security_identity_propagation]] .Security Identity Propagation -image::jakartaeett_dt_047.svg["Diagram of security identity propagation from client to intermediate container to target container"] +image::common:jakartaeett_dt_047.svg["Diagram of security identity propagation from client to intermediate container to target container"] In this illustration, an application client is making a call to an enterprise bean method in one enterprise bean container. This enterprise bean method, in turn, makes a call to an enterprise bean method in another container. @@ -362,7 +362,7 @@ This technique is used when the target container trusts the intermediate contain * A specific identity is propagated to the target enterprise bean. This technique is used when the target container expects access using a specific identity. -To propagate an identity to the target enterprise bean, configure a run-as identity for the bean, as described in <>. +To propagate an identity to the target enterprise bean, configure a run-as identity for the bean, as described in <<_configuring_a_components_propagated_security_identity>>. Establishing a run-as identity for an enterprise bean does not affect the identities of its callers, which are the identities tested for permission to access the methods of the enterprise bean. The run-as identity establishes the identity that the enterprise bean will use when it makes calls. diff --git a/src/main/asciidoc/security-jakartaee/security-jakartaee003.adoc b/src/main/antora/modules/security/pages/security-jakartaee/security-jakartaee003.adoc similarity index 78% rename from src/main/asciidoc/security-jakartaee/security-jakartaee003.adoc rename to src/main/antora/modules/security/pages/security-jakartaee/security-jakartaee003.adoc index b501cdca..55074968 100644 --- a/src/main/asciidoc/security-jakartaee/security-jakartaee003.adoc +++ b/src/main/antora/modules/security/pages/security-jakartaee/security-jakartaee003.adoc @@ -7,28 +7,28 @@ The following examples show how to secure enterprise beans using declarative and This section discusses how to configure an enterprise bean for basic user name/password authentication. When a bean that is constrained in this way is requested, the server requests a user name and password from the client and verifies that the user name and password are valid by comparing them against a database of authorized users in GlassFish Server. -If the topic of authentication is new to you, see <>. +If the topic of authentication is new to you, see xref:security-webtier/security-webtier.adoc#_specifying_authentication_mechanisms[Specifying Authentication Mechanisms]. -This example demonstrates security by starting with the unsecured enterprise bean application, `cart`, which is found in the `_tut-install_/examples/ejb/cart/` directory and is discussed in <>. +This example demonstrates security by starting with the unsecured enterprise bean application, `cart`, which is found in the `_jakartaee-examples_/tutorial/ejb/cart/` directory and is discussed in xref:entbeans:ejb-basicexamples/ejb-basicexamples.adoc#_the_cart_example[The cart Example]. In general, the following steps are necessary to add user name/password authentication to an existing application that contains an enterprise bean. In the example application included with this tutorial, these steps have been completed for you and are listed here simply to show what needs to be done should you wish to create a similar application. -. Create an application like the one in <>. +. Create an application like the one in xref:entbeans:ejb-basicexamples/ejb-basicexamples.adoc#_the_cart_example[The cart Example]. The example in this tutorial starts with this example and demonstrates adding basic authentication of the client to this application. -The example application discussed in this section can be found at `_tut-install_/examples/security/cart-secure/`. +The example application discussed in this section can be found at `_jakartaee-examples_/tutorial/security/cart-secure/`. -. If you have not already done so, complete the steps in <> to configure your system for running the tutorial applications. +. If you have not already done so, complete the steps in xref:security-webtier/security-webtier.adoc#_to_set_up_your_system_for_running_the_security_examples[To Set Up Your System for Running the Security Examples] to configure your system for running the tutorial applications. . Modify the source code for the enterprise bean, `CartBean.java`, to specify which roles are authorized to access which protected methods. -This step is discussed in <>. +This step is discussed in <<_annotating_the_bean>>. -. Build, package, and deploy the enterprise bean; then build and run the client application by following the steps in <> or <>. +. Build, package, and deploy the enterprise bean; then build and run the client application by following the steps in <<_to_run_the_cart_secure_example_using_netbeans_ide>> or <<_to_run_the_cart_secure_example_using_maven>>. ==== Annotating the Bean The source code for the original `cart` application was modified as shown in the following code snippet (modifications in bold). -The resulting file can be found in the file `_tut-install_/examples/security/cart-secure/cart-secure-ejb/src/main/java/ee/jakarta/tutorial/cart/ejb/CartBean.java`. +The resulting file can be found in the file `_jakartaee-examples_/tutorial/security/cart-secure/cart-secure-ejb/src/main/java/jakarta/tutorial/cart/ejb/CartBean.java`. The code snippet is as follows: @@ -123,14 +123,14 @@ If no authentication method is specified in the deployment descriptor, the type ==== To Run the cart-secure Example Using NetBeans IDE -. Follow the steps in <>. +. Follow the steps in xref:security-webtier/security-webtier.adoc#_to_set_up_your_system_for_running_the_security_examples[To Set Up Your System for Running the Security Examples]. . From the File menu, choose Open Project. . In the Open Project dialog box, navigate to: + ---- -tut-install/examples/security +jakartaee-examples/tutorial/security ---- . Select the `cart-secure` folder. @@ -162,12 +162,12 @@ If the user name and password are not authenticated, the dialog box reappears un ==== To Run the cart-secure Example Using Maven -. Follow the steps in <>. +. Follow the steps in xref:security-webtier/security-webtier.adoc#_to_set_up_your_system_for_running_the_security_examples[To Set Up Your System for Running the Security Examples]. . In a terminal window, go to: + ---- -tut-install/examples/security/cart-secure/ +jakartaee-examples/tutorial/security/cart-secure/ ---- . To build the application, package it into an EAR file in the `cart-secure-ear/target` subdirectory, deploy it, and run it, enter the following command at the terminal window or command prompt: @@ -199,9 +199,9 @@ If the user name and password are not authenticated, the dialog box reappears un This example demonstrates how to use the `getCallerPrincipal` and `isCallerInRole` methods with an enterprise bean. This example starts with a very simple enterprise bean application, `converter`, and modifies the methods of the `ConverterBean` so that currency conversion will occur only when the requester is in the role of `TutorialUser`. -This example can be found in the `_tut-install_/examples/security/converter-secure` directory. -This example is based on the unsecured enterprise bean application, `converter`, which is discussed in xref:getting-started-with-enterprise-beans[xrefstyle=full] and is found in the `_tut-install_/examples/ejb/converter/` directory. -This section builds on the example by adding the necessary elements to secure the application by using the `getCallerPrincipal` and `isCallerInRole` methods, which are discussed in more detail in <>. +This example can be found in the `_jakartaee-examples_/tutorial/security/converter-secure` directory. +This example is based on the unsecured enterprise bean application, `converter`, which is discussed in xref:entbeans:ejb-gettingstarted/ejb-gettingstarted.adoc#_getting_started_with_enterprise_beans[Getting Started with Enterprise Beans] and is found in the `_jakartaee-examples_/tutorial/ejb/converter/` directory. +This section builds on the example by adding the necessary elements to secure the application by using the `getCallerPrincipal` and `isCallerInRole` methods, which are discussed in more detail in xref:security-jakartaee/security-jakartaee.adoc#_securing_an_enterprise_bean_programmatically[Securing an Enterprise Bean Programmatically]. In general, the following steps are necessary when using the `getCallerPrincipal` and `isCallerInRole` methods with an enterprise bean. In the example application included with this tutorial, many of these steps have been completed for you and are listed here simply to show what needs to be done should you wish to create a similar application. @@ -209,11 +209,11 @@ In the example application included with this tutorial, many of these steps have . Create a simple enterprise bean application. . Set up a user on GlassFish Server in the `file` realm, in the group `TutorialUser`, and set up default principal to role mapping. -To do this, follow the steps in <>. +To do this, follow the steps in xref:security-webtier/security-webtier.adoc#_to_set_up_your_system_for_running_the_security_examples[To Set Up Your System for Running the Security Examples]. . Modify the bean to add the `getCallerPrincipal` and `isCallerInRole` methods. -. If the application contains a web client that is a servlet, specify security for the servlet, as described in <>. +. If the application contains a web client that is a servlet, specify security for the servlet, as described in xref:security-webtier/security-webtier.adoc#_specifying_security_for_basic_authentication_using_annotations[Specifying Security for Basic Authentication Using Annotations]. . Build, package, deploy, and run the application. @@ -222,7 +222,7 @@ To do this, follow the steps in <>. +. Follow the steps in xref:security-webtier/security-webtier.adoc#_to_set_up_your_system_for_running_the_security_examples[To Set Up Your System for Running the Security Examples]. . From the File menu, choose Open Project. . In the Open Project dialog box, navigate to: + ---- -tut-install/examples/security +jakartaee-examples/tutorial/security ---- . Select the `converter-secure` folder. @@ -307,12 +307,12 @@ This command builds and deploys the example application to your GlassFish Server ==== To Run the converter-secure Example Using Maven -. Follow the steps in <>. +. Follow the steps in xref:security-webtier/security-webtier.adoc#_to_set_up_your_system_for_running_the_security_examples[To Set Up Your System for Running the Security Examples]. . In a terminal window, go to: + ---- -tut-install/examples/security/converter-secure/ +jakartaee-examples/tutorial/security/converter-secure/ ---- . Enter the following command: diff --git a/src/main/asciidoc/security-webtier/security-webtier.adoc b/src/main/antora/modules/security/pages/security-webtier/security-webtier.adoc similarity index 57% rename from src/main/asciidoc/security-webtier/security-webtier.adoc rename to src/main/antora/modules/security/pages/security-webtier/security-webtier.adoc index 07ca9da8..f14053ba 100644 --- a/src/main/asciidoc/security-webtier/security-webtier.adoc +++ b/src/main/antora/modules/security/pages/security-webtier/security-webtier.adoc @@ -1,6 +1,8 @@ = Getting Started Securing Web Applications -This chapter describes in greater detail the ways to implement security for Jakarta EE web applications discussed in a general way in <>. The detail and examples in this chapter explore these security services as they relate to web components. +include::ROOT:partial$not_updated.adoc[] + +This chapter describes in greater detail the ways to implement security for Jakarta EE web applications discussed in a general way in xref:security-intro/security-intro.adoc#_securing_containers[Securing Containers]. The detail and examples in this chapter explore these security services as they relate to web components. include::security-webtier001.adoc[] diff --git a/src/main/asciidoc/security-webtier/security-webtier001.adoc b/src/main/antora/modules/security/pages/security-webtier/security-webtier001.adoc similarity index 64% rename from src/main/asciidoc/security-webtier/security-webtier001.adoc rename to src/main/antora/modules/security/pages/security-webtier/security-webtier001.adoc index 1759820e..259ed628 100644 --- a/src/main/asciidoc/security-webtier/security-webtier001.adoc +++ b/src/main/antora/modules/security/pages/security-webtier/security-webtier001.adoc @@ -1,13 +1,13 @@ == Overview of Web Application Security A web application is accessed using a web browser over a network, such as the Internet or a company's intranet. -As discussed in <>, the Jakarta EE platform uses a distributed multitiered application model, and web applications run in the web tier. +As discussed in xref:intro:overview/overview.adoc#_distributed_multitiered_applications[Distributed Multitiered Applications], the Jakarta EE platform uses a distributed multitiered application model, and web applications run in the web tier. Web applications contain resources that can be accessed by many users. These resources often traverse unprotected, open networks, such as the Internet. In such an environment, a substantial number of web applications will require some type of security. -Securing applications and their clients in the business tier and the EIS tier is discussed in xref:getting-started-securing-enterprise-applications[xrefstyle=full]. +Securing applications and their clients in the business tier and the EIS tier is discussed in xref:security-jakartaee/security-jakartaee.adoc#_getting_started_securing_enterprise_applications[Getting Started Securing Enterprise Applications]. In the Jakarta EE platform, web components provide the dynamic extension capabilities for a web server. Web components can be Jakarta servlets or Jakarta Faces pages. @@ -20,18 +20,18 @@ Any values explicitly specified in the deployment descriptor override any values Security for Jakarta EE web applications can be implemented in the following ways. * Declarative security can be implemented using either metadata annotations or an application's deployment descriptor. -See <> for more information. +See xref:security-intro/security-intro.adoc#_overview_of_jakarta_security[Overview of Jakarta Security] for more information. + -Declarative security for web applications is described in <>. +Declarative security for web applications is described in xref:security-webtier/security-webtier.adoc#_securing_web_applications[Securing Web Applications]. * Programmatic security is embedded in an application and can be used to make security decisions when declarative security alone is not sufficient to express the security model of an application. Declarative security alone may not be sufficient when conditional login in a particular work flow, instead of for all cases, is required in the middle of an application. -See <> for more information. +See xref:security-intro/security-intro.adoc#_overview_of_jakarta_security[Overview of Jakarta Security] for more information. + Servlet 5.0 provides the `authenticate`, `login`, and `logout` methods of the `HttpServletRequest` interface. With the addition of the `authenticate`, `login`, and `logout` methods to the Servlet specification, an application deployment descriptor is no longer required for web applications but may still be used to further specify security requirements beyond the basic default values. + -Programmatic security is discussed in <>. +Programmatic security is discussed in xref:security-webtier/security-webtier.adoc#_using_programmatic_security_with_web_applications[Using Programmatic Security with Web Applications]. * Message security works with web services and incorporates security features, such as digital signatures and encryption, into the header of a SOAP message, working in the application layer, ensuring end-to-end security. Message security is not a component of Jakarta EE and is mentioned here for informational purposes only. @@ -39,10 +39,10 @@ Message security is not a component of Jakarta EE and is mentioned here for info Some of the material in this chapter builds on material presented earlier in this tutorial. In particular, this chapter assumes that you are familiar with the information in the following chapters: -* xref:getting-started-with-web-applications[xrefstyle=full] +* xref:web:webapp/webapp.adoc#_getting_started_with_web_applications[Getting Started with Web Applications] -* xref:jakarta-faces-technology-2[xrefstyle=full] +* xref:web:faces-intro/faces-intro.adoc#_jakarta_faces_technology[Jakarta Faces Technology] -* xref:jakarta-servlet-technology-2[xrefstyle=full] +* xref:web:servlets/servlets.adoc#_jakarta_servlet_technology[Jakarta Servlet Technology] -* xref:introduction-to-security-in-the-jakarta-ee-platform[xrefstyle=full] +* xref:security-intro/security-intro.adoc#_introduction_to_security_in_the_jakarta_ee_platform[Introduction to Security in the Jakarta EE Platform] diff --git a/src/main/asciidoc/security-webtier/security-webtier002.adoc b/src/main/antora/modules/security/pages/security-webtier/security-webtier002.adoc similarity index 88% rename from src/main/asciidoc/security-webtier/security-webtier002.adoc rename to src/main/antora/modules/security/pages/security-webtier/security-webtier002.adoc index caba70ec..ab083e5a 100644 --- a/src/main/asciidoc/security-webtier/security-webtier002.adoc +++ b/src/main/antora/modules/security/pages/security-webtier/security-webtier002.adoc @@ -25,13 +25,13 @@ The authentication mechanism cannot be expressed using annotations, so if you us The following subelements can be part of a `security-constraint`. * Web resource collection (`web-resource-collection`): A list of URL patterns (the part of a URL after the host name and port you want to constrain) and HTTP operations (the methods within the files that match the URL pattern you want to constrain) that describe a set of resources to be protected. -Web resource collections are discussed in <>. +Web resource collections are discussed in <<_specifying_a_web_resource_collection>>. * Authorization constraint (`auth-constraint`): Specifies whether authentication is to be used and names the roles authorized to perform the constrained requests. -For more information about authorization constraints, see <>. +For more information about authorization constraints, see <<_specifying_an_authorization_constraint>>. * User data constraint (`user-data-constraint`): Specifies how data is protected when transported between a client and a server. -User data constraints are discussed in <>. +User data constraints are discussed in <<_specifying_a_secure_connection>>. ==== Specifying a Web Resource Collection @@ -75,8 +75,8 @@ Each role name specified here must either correspond to the role name of one of Role names are case sensitive. The roles defined for the application must be mapped to users and groups defined on the server, except when default principal-to-role mapping is used. -For more information about security roles, see <>. -For information on mapping security roles, see <>. +For more information about security roles, see <<_declaring_security_roles>>. +For information on mapping security roles, see xref:security-intro/security-intro.adoc#_mapping_roles_to_users_and_groups[Mapping Roles to Users and Groups]. For a servlet, the `@HttpConstraint` and `@HttpMethodConstraint` annotations accept a `rolesAllowed` element that specifies the authorized roles. @@ -101,7 +101,7 @@ In practice, Jakarta EE servers treat the `CONFIDENTIAL` and `INTEGRAL` transpor The user data constraint is handy to use in conjunction with basic and form-based user authentication. When the login authentication method is set to `BASIC` or `FORM`, passwords are not protected, meaning that passwords sent between a client and a server on an unprotected session can be viewed and intercepted by third parties. Using a user data constraint with the user authentication mechanism can alleviate this concern. -Configuring a user authentication mechanism is described in <>. +Configuring a user authentication mechanism is described in <<_specifying_an_authentication_mechanism_in_the_deployment_descriptor>>. To guarantee that data is transported over a secure connection, ensure that SSL support is configured for your server. SSL support is already configured for GlassFish Server. @@ -157,7 +157,7 @@ An example of a deployment descriptor that would demonstrate this functionality This section describes built-in authentication mechanisms defined by the Servlet specification. [NOTE] -An alternative way to perform user authentication, including BASIC and FORM authentication, is to use the `HttpAuthenticationMechanism`, specified by Jakarta Security, and documented in <>. +An alternative way to perform user authentication, including BASIC and FORM authentication, is to use the `HttpAuthenticationMechanism`, specified by Jakarta Security, and documented in xref:security-api/security-api.adoc#_using_jakarta_security[Using Jakarta Security]. A user authentication mechanism specifies: @@ -171,7 +171,7 @@ When an authentication mechanism is specified, the user must be authenticated be There can be multiple security constraints applying to multiple resources, but the same authentication method will apply to all constrained resources in an application. Before you can authenticate a user, you must have a database of user names, passwords, and roles configured on your web or application server. -For information on setting up the user database, see <>. +For information on setting up the user database, see xref:security-intro/security-intro.adoc#_managing_users_and_groups_in_glassfish_server[Managing Users and Groups in GlassFish Server]. The Jakarta EE platform supports the following authentication mechanisms: @@ -186,7 +186,7 @@ The Jakarta EE platform supports the following authentication mechanisms: * Mutual authentication Basic, form-based, and digest authentication are discussed in this section. -Client and mutual authentication are discussed in xref:jakarta-ee-security-advanced-topics[xrefstyle=full]. +Client and mutual authentication are discussed in xref:security-advanced/security-advanced.adoc#_jakarta_ee_security_advanced_topics[Jakarta EE Security: Advanced Topics]. HTTP basic authentication and form-based authentication are not very secure authentication mechanisms. Basic authentication sends user names and passwords over the Internet as Base64-encoded text. @@ -196,7 +196,7 @@ Therefore, these forms of authentication leave user data exposed and vulnerable. If someone can intercept the transmission, the user name and password information can easily be decoded. However, when a secure transport mechanism, such as SSL, or security at the network level, such as the Internet Protocol Security (IPsec) protocol or virtual private network (VPN) strategies, is used in conjunction with basic or form-based authentication, some of these concerns can be alleviated. -To specify a secure transport mechanism, use the elements described in <>. +To specify a secure transport mechanism, use the elements described in <<_specifying_a_secure_connection>>. ==== HTTP Basic Authentication @@ -214,11 +214,11 @@ When basic authentication is used, the following actions occur. . The server authenticates the user in the specified realm and, if successful, returns the requested resource. -<> shows what happens when you specify HTTP basic authentication. +<<_http_basic_authentication_2>> shows what happens when you specify HTTP basic authentication. -[[http-basic-authentication-2]] +[[_http_basic_authentication_2]] .HTTP Basic Authentication -image::jakartaeett_dt_045.svg["Diagram of four steps in HTTP basic authentication between client and server"] +image::common:jakartaeett_dt_045.svg["Diagram of four steps in HTTP basic authentication between client and server"] ==== Form-Based Authentication @@ -238,13 +238,13 @@ If the user is authorized, the server redirects the client to the resource by us * If authentication fails, the client is forwarded or redirected to an error page. -<> shows what happens when you specify form-based authentication. +<<_form_based_authentication_2>> shows what happens when you specify form-based authentication. -[[form-based-authentication-2]] +[[_form_based_authentication_2]] .Form-Based Authentication -image::jakartaeett_dt_046.svg["Diagram of four steps in form-based authentication between client and server"] +image::common:jakartaeett_dt_046.svg["Diagram of four steps in form-based authentication between client and server"] -The section <> is an example application that uses form-based authentication. +The section xref:security-webtier/security-webtier.adoc#_the_hello1_formauth_example_form_based_authentication_with_a_jakarta_faces_application[The hello1-formauth Example: Form-Based Authentication with a Jakarta Faces Application] is an example application that uses form-based authentication. When you create a form-based login, be sure to maintain sessions using cookies or SSL session information. @@ -279,7 +279,7 @@ The element content must be either `NONE`, `BASIC`, `DIGEST`, `FORM`, or `CLIENT * The `form-login-config` subelement specifies the login and error pages that should be used when form-based login is specified. [NOTE] -Another way to specify form-based authentication is to use the `authenticate`, `login`, and `logout` methods of `HttpServletRequest`, as discussed in <>. +Another way to specify form-based authentication is to use the `authenticate`, `login`, and `logout` methods of `HttpServletRequest`, as discussed in xref:security-webtier/security-webtier.adoc#_authenticating_users_programmatically[Authenticating Users Programmatically]. When you try to access a web resource that is constrained by a `security-constraint` element, the web container activates the authentication mechanism that has been configured for that resource. The authentication mechanism specifies how the user will be prompted to log in. @@ -301,7 +301,7 @@ The following example shows how to declare form-based authentication in your dep ---- The login and error page locations are specified relative to the location of the deployment descriptor. -Examples of login and error pages are shown in <>. +Examples of login and error pages are shown in xref:security-webtier/security-webtier.adoc#_creating_the_login_form_and_the_error_page[Creating the Login Form and the Error Page]. The following example shows how to declare digest authentication in your deployment descriptor: diff --git a/src/main/asciidoc/security-webtier/security-webtier003.adoc b/src/main/antora/modules/security/pages/security-webtier/security-webtier003.adoc similarity index 99% rename from src/main/asciidoc/security-webtier/security-webtier003.adoc rename to src/main/antora/modules/security/pages/security-webtier/security-webtier003.adoc index bedceaf6..2529fe3a 100644 --- a/src/main/asciidoc/security-webtier/security-webtier003.adoc +++ b/src/main/antora/modules/security/pages/security-webtier/security-webtier003.adoc @@ -145,7 +145,7 @@ If no user has been authenticated, this method returns `false`. This method expects a `String` user `role-name` parameter. + The `security-role-ref` element should be declared in the deployment descriptor with a `role-name` subelement containing the role name to be passed to the method. -Using security role references is discussed in <>. +Using security role references is discussed in <<_declaring_and_linking_role_references>>. * `getUserPrincipal` determines the principal name of the current user and returns a `java.security.Principal` object. If no user has been authenticated, this method returns `null`. diff --git a/src/main/asciidoc/security-webtier/security-webtier004.adoc b/src/main/antora/modules/security/pages/security-webtier/security-webtier004.adoc similarity index 82% rename from src/main/asciidoc/security-webtier/security-webtier004.adoc rename to src/main/antora/modules/security/pages/security-webtier/security-webtier004.adoc index 9ee42f06..a696afb3 100644 --- a/src/main/asciidoc/security-webtier/security-webtier004.adoc +++ b/src/main/antora/modules/security/pages/security-webtier/security-webtier004.adoc @@ -8,9 +8,9 @@ The examples use annotations, programmatic security, and/or declarative security Here are some other locations where you will find examples of securing various types of applications: -* <> +* xref:security-jakartaee/security-jakartaee.adoc#_the_cart_secure_example_securing_an_enterprise_bean_with_declarative_security[The cart-secure Example: Securing an Enterprise Bean with Declarative Security] -* <> +* xref:security-jakartaee/security-jakartaee.adoc#_the_converter_secure_example_securing_an_enterprise_bean_with_programmatic_security[The converter-secure Example: Securing an Enterprise Bean with Programmatic Security] * Eclipse GlassFish samples for Jakarta EE 9: https://github.com/eclipse-ee4j/glassfish-samples[^] @@ -19,10 +19,10 @@ Here are some other locations where you will find examples of securing various t To set up your system for running the security examples, you need to configure a user database that the application can use for authenticating users. Before continuing, follow these steps. -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . Add an authorized user to GlassFish Server. -For the examples in this chapter and in <>, add a user to the `file` realm of GlassFish Server, and assign the user to the group `TutorialUser`. +For the examples in this chapter and in xref:security-jakartaee/security-jakartaee.adoc#_getting_started_securing_enterprise_applications[Getting Started Securing Enterprise Applications], add a user to the `file` realm of GlassFish Server, and assign the user to the group `TutorialUser`. .. From the Administration Console, expand the Configurations node, then expand the server-config node. @@ -46,7 +46,7 @@ For the examples in this chapter and in <>. +This topic is discussed more in xref:security-intro/security-intro.adoc#_managing_users_and_groups_in_glassfish_server[Managing Users and Groups in GlassFish Server]. + [NOTE] Jakarta Security requires that group principal names are mapped to roles of the same name by default. @@ -58,19 +58,19 @@ This example explains how to use basic authentication with a servlet. With basic authentication of a servlet, the web browser presents a standard login dialog box that is not customizable. When a user submits his or her name and password, the server determines whether the user name and password are those of an authorized user and sends the requested web resource if the user is authorized to view it. -In general, the following steps are necessary for adding basic authentication to an unsecured servlet, such as the ones described in xref:getting-started-with-web-applications[xrefstyle=full]. +In general, the following steps are necessary for adding basic authentication to an unsecured servlet, such as the ones described in xref:web:webapp/webapp.adoc#_getting_started_with_web_applications[Getting Started with Web Applications]. In the example application included with this tutorial, many of these steps have been completed for you and are listed here simply to show what needs to be done should you wish to create a similar application. -This application can be found in the `_tut-install_/examples/security/hello2-basicauth/` directory. +This application can be found in the `_jakartaee-examples_/tutorial/security/hello2-basicauth/` directory. -. Follow the steps in <>. +. Follow the steps in <<_to_set_up_your_system_for_running_the_security_examples>>. -. Create a web module for the servlet example, `hello2`, as described in xref:getting-started-with-web-applications[xrefstyle=full]. +. Create a web module for the servlet example, `hello2`, as described in xref:web:webapp/webapp.adoc#_getting_started_with_web_applications[Getting Started with Web Applications]. -. Add the appropriate security annotations to the servlet. The security annotations are described in <>. +. Add the appropriate security annotations to the servlet. The security annotations are described in <<_specifying_security_for_basic_authentication_using_annotations>>. -. Build, package, and deploy the web application by following the steps in <> or <>. +. Build, package, and deploy the web application by following the steps in <<_to_build_package_and_deploy_the_hello2_basicauth_example_using_netbeans_ide>> or <<_to_build_package_and_deploy_the_hello2_basicauth_example_using_maven>>. -. Run the web application by following the steps described in <>. +. Run the web application by following the steps described in <<_to_run_the_hello2_basicauth_example>>. ==== Specifying Security for Basic Authentication Using Annotations @@ -111,14 +111,14 @@ Use the deployment descriptor to specify settings for nondefault authentication ==== To Build, Package, and Deploy the hello2-basicauth Example Using NetBeans IDE -. Follow the steps in <>. +. Follow the steps in <<_to_set_up_your_system_for_running_the_security_examples>>. . From the File menu, choose Open Project. . In the Open Project dialog box, navigate to: + ---- -tut-install/examples/security +jakartaee-examples/tutorial/security ---- . Select the `hello2-basicauth` folder. @@ -131,12 +131,12 @@ This command builds and deploys the example application to your GlassFish Server ==== To Build, Package, and Deploy the hello2-basicauth Example Using Maven -. Follow the steps in <>. +. Follow the steps in <<_to_set_up_your_system_for_running_the_security_examples>>. . In a terminal window, go to: + ---- -tut-install/examples/security/hello2-basicauth/ +jakartaee-examples/tutorial/security/hello2-basicauth/ ---- . Enter the following command: @@ -190,19 +190,19 @@ This example explains how to use form-based authentication with a Jakarta Faces With form-based authentication, you can customize the login screen and error pages that are presented to the web client for authentication of the user name and password. When a user submits his or her name and password, the server determines whether the user name and password are those of an authorized user and, if authorized, sends the requested web resource. -This example, `hello1-formauth`, adds security to the basic Jakarta Faces application shown in <>. +This example, `hello1-formauth`, adds security to the basic Jakarta Faces application shown in xref:web:webapp/webapp.adoc#_a_web_module_that_uses_jakarta_faces_technology_the_hello1_example[A Web Module That Uses Jakarta Faces Technology: The hello1 Example]. -In general, the steps necessary for adding form-based authentication to an unsecured Jakarta Faces application are similar to those described in <>. -The major difference is that you must use a deployment descriptor to specify the use of form-based authentication, as described in <>. -In addition, you must create a login form page and a login error page, as described in <>. +In general, the steps necessary for adding form-based authentication to an unsecured Jakarta Faces application are similar to those described in <<_the_hello2_basicauth_example_basic_authentication_with_a_servlet>>. +The major difference is that you must use a deployment descriptor to specify the use of form-based authentication, as described in <<_specifying_security_for_the_form_based_authentication_example>>. +In addition, you must create a login form page and a login error page, as described in <<_creating_the_login_form_and_the_error_page>>. -This application can be found in the `_tut-install_/examples/security/hello1-formauth/` directory. +This application can be found in the `_jakartaee-examples_/tutorial/security/hello1-formauth/` directory. ==== Creating the Login Form and the Error Page When using form-based login mechanisms, you must specify a page that contains the form you want to use to obtain the user name and password, as well as a page to display if login authentication fails. This section discusses the login form and the error page used in this example. -<> shows how you specify these pages in the deployment descriptor. +<<_specifying_security_for_the_form_based_authentication_example>> shows how you specify these pages in the deployment descriptor. The login page can be an HTML page or a servlet, and it must return an HTML page containing a form that conforms to specific naming conventions (see the Jakarta Servlet 5.0 specification for more information on these requirements). To do this, include the elements that accept user name and password information between `
` tags in your login page. @@ -216,7 +216,7 @@ The content of an HTML page or servlet for a login page should be coded as follo ---- -The full code for the login page used in this example can be found at `_tut-install_/examples/security/hello1-formauth/src/main/webapp/login.html`. +The full code for the login page used in this example can be found at `_jakartaee-examples_/tutorial/security/hello1-formauth/src/main/webapp/login.html`. Here is the code for this page: [source,html] @@ -250,7 +250,7 @@ Here is the code for this page: ---- The login error page is displayed if the user enters a user name and password combination that is not authorized to access the protected URI. -For this example, the login error page can be found at `_tut-install_/examples/security/hello1-formauth/src/main/webapp/error.html`. +For this example, the login error page can be found at `_jakartaee-examples_/tutorial/security/hello1-formauth/src/main/webapp/error.html`. For this example, the login error page explains the reason for receiving the error page and provides a link that will allow the user to try again. Here is the code for this page: @@ -277,7 +277,7 @@ Here is the code for this page: This example takes a very simple servlet-based web application and adds form-based security. To specify form-based instead of basic authentication for a Jakarta Faces example, you must use the deployment descriptor. -The following sample code shows the security elements added to the deployment descriptor for this example, which can be found in `_tut-install_/examples/security/hello1-formauth/src/main/webapp/WEB-INF/web.xml`: +The following sample code shows the security elements added to the deployment descriptor for this example, which can be found in `_jakartaee-examples_/tutorial/security/hello1-formauth/src/main/webapp/WEB-INF/web.xml`: [source,xml] ---- @@ -311,14 +311,14 @@ The following sample code shows the security elements added to the deployment de ==== To Build, Package, and Deploy the hello1-formauth Example Using NetBeans IDE -. Follow the steps in <>. +. Follow the steps in <<_to_set_up_your_system_for_running_the_security_examples>>. . From the File menu, choose Open Project. . In the Open Project dialog box, navigate to: + ---- -tut-install/examples/security +jakartaee-examples/tutorial/security ---- . Select the `hello1-formauth` folder. @@ -331,12 +331,12 @@ This command builds and deploys the example application to your GlassFish Server ==== To Build, Package, and Deploy the hello1-formauth Example Using Maven and the asadmin Command -. Follow the steps in <>. +. Follow the steps in <<_to_set_up_your_system_for_running_the_security_examples>>. . In a terminal window, go to: + ---- -tut-install/examples/security/hello1-formauth/ +jakartaee-examples/tutorial/security/hello1-formauth/ ---- . Enter the following command at the terminal window or command prompt: diff --git a/src/main/antora/modules/security/pages/security.adoc b/src/main/antora/modules/security/pages/security.adoc new file mode 100644 index 00000000..eaf92621 --- /dev/null +++ b/src/main/antora/modules/security/pages/security.adoc @@ -0,0 +1,1942 @@ += Jakarta Security + +Jakarta Security is the overarching security API in Jakarta EE. Overarching here means that it strives to address the security needs of all other APIs in Jakarta EE in a holistic way. + +Due to historical and political reasons, a number of security features are still distributed among several other APIs in Jakarta EE. Sometimes they overlap, and sometimes such features are only accessible from these other APIs. In this chapter, we'll focus primarily on explaining Jakarta Security, but we'll mention when other APIs are needed to accomplish a certain task. + +== Overview + +Before we look at some practical examples, let's quickly go through some basics. + +Some of the guiding principles in Jakarta Security are: + +. It should work directly out of the box, without requiring vendor-specific configuration. +. It leverages Jakarta CDI as much as possible. Most artifacts are CDI beans, and many features are done via CDI interceptors. +. The difference between framework-provided artifacts and custom (user provided) artifacts is minimal or non-existent. +. It fully integrates with security features from other Jakarta EE APIs and proprietary (vendor-specific) artifacts. + +Jakarta Security defines several distinct artifacts that play an important role in the security process: + +. https://jakarta.ee/specifications/security/3.0/jakarta-security-spec-3.0.html#authentication-mechanism[Authentication Mechanism,role=external,window=_blank] +. https://jakarta.ee/specifications/security/3.0/jakarta-security-spec-3.0.html#identity-store[Identity Store,role=external,window=_blank] +. Permission Store + +The first two of these are used in the authentication process: + +An _authentication mechanism_ is somewhat like a controller in the well-known https://en.wikipedia.org/wiki/Model–view–controller[MVC,role=external,window=_blank] pattern; it is the entity that interacts with the caller (typically a human), via some kind of view to collect credentials, and with the model (business logic) to validate `these` credentials. An authentication mechanism knows about the environment this caller uses to communicate with the server. An authentication mechanism for HTTP knows about URLs to redirect or forward to, or about response headers to send to the client. It also knows about the data coming back, such as cookies, request headers, and post data. Examples of authentication mechanisms are Form authentication and Basic authentication. + +An _identity store_ is more like the model in the MVC pattern. This entity strictly performs a business / data operation where credentials go in, and an identity comes out. The identity contains logic to validate said credentials, and embeds or contacts a database. This "database" contains usernames, along with their credentials and (typically) roles. An identity store therefore knows nothing about the environment that this caller uses to communicate with the server; for example, it doesn't know about HTTP or headers and more. +Some examples of identity stores are services that contact SQL or NoSQL databases, LDAP servers, files on the file-system, and more. + +<<_mechanism_store_in_mvc>> shows the _authentication mechanism_ and _identity store_ in an MVC-like structure. + +[[_mechanism_store_in_mvc]] +.Mechanism Store in MVC +image::authentication-mvc.svg["Diagram illustrating the role of the authentication mechanism and identity store in an MVC like structure"] + +The third one is used for the authorization process: + +A _permission store_ is another kind of model that stores permissions, typically either globally, or per role (role-based permissions). This entity then performs a business / data operation where a query and an identity go in, and a yes/no answer goes out. For instance, a query such as "can access /foo/bar?" along with the identity for user "John" with roles "bar" and "kaz" would return "yes" if that identity is authorized to access "/foo/bar", and "no" if not authorized. +Examples of permission stores are the Jakarta Authorization usage of the Policy class, or the internal data structure where a Servlet Container such as Tomcat or Jetty stores the security constraints an application defined. + +== Provided authentication mechanisms and identity stores + +Jakarta Security provides a number of built-in authentication mechanisms and identity stores. We'll enumerate them here first, and will look at them in more detail below. + +Authentication mechanisms: + +. https://jakarta.ee/specifications/security/3.0/jakarta-security-spec-3.0.html#basic-annotation[Basic,role=external,window=_blank] +. https://jakarta.ee/specifications/security/3.0/jakarta-security-spec-3.0.html#form-annotation[Form,role=external,window=_blank] +. https://jakarta.ee/specifications/security/3.0/jakarta-security-spec-3.0.html#custom-form-annotation[Custom Form,role=external,window=_blank] +. https://jakarta.ee/specifications/security/3.0/jakarta-security-spec-3.0.html#openid-connect-annotation[Open ID Connect (OIDC),role=external,window=_blank] + +Identity stores: + +. https://jakarta.ee/specifications/security/3.0/jakarta-security-spec-3.0.html#database-annotation[Database,role=external,window=_blank] +. https://jakarta.ee/specifications/security/3.0/jakarta-security-spec-3.0.html#ldap-annotation[LDAP,role=external,window=_blank] + +== Custom authentication mechanisms and identity stores + +When the provided authentication mechanisms and identity stores aren't sufficient, we can easily define custom ones. Both provided and custom ones use https://jakarta.ee/specifications/security/3.0/apidocs/jakarta.security/jakarta/security/enterprise/identitystore/identitystore[the same interfaces,role=external,window=_blank], and the system doesn't distinguish between them. + +== Authentication mechanisms and identity stores from other APIs + +The https://jakarta.ee/specifications/servlet/6.0/jakarta-servlet-spec-6.0.html[Servlet specification,role=external,window=_blank] defines the exact same https://jakarta.ee/specifications/servlet/6.0/jakarta-servlet-spec-6.0.html#form-based-authentication[Form,role=external,window=_blank] and https://jakarta.ee/specifications/servlet/6.0/jakarta-servlet-spec-6.0.html#http-basic-authentication[Basic,role=external,window=_blank] authentication mechanisms. Authenticating with them will have the same result as authenticating with a Jakarta Security authentication mechanism. (Role checks will work the same independent on which API was used to authenticate.) + +A Servlet authentication mechanism, however, will not necessarily consult a Jakarta Security identity store. This is server dependent. The identity store that is called is server dependent as well. Calling this server-dependent identity store is possible from Jakarta Security, but as an advanced feature. + +Likewise, programmatic role checks can be done from various APIs, including Jakarta Security, Jakarta REST, and Jakarta Servlet. These all return the same outcome, independent of whether authentication took place with a Jakarta Security Authentication Mechanism or a Servlet Authentication Mechanism. Within a Jakarta EE environment the usage of Jakarta Security for this is encouraged, and the usage of those other APIs is discouraged. + +NOTE: Programmatic role checks in Jakarta REST, Jakarta Servlet and various other APIs are not being deprecated for the time being, as those APIs are also used stand-alone (outside Jakarta EE). Future versions of those APIs may contain warnings about their usage within Jakarta EE. + +== Securing an endpoint with Basic authentication + +In the following example, we'll be securing a REST endpoint using Basic authentication. + +You'll learn how to: + +include::partial$list-item-learn-security-constraints.adoc[] +. Set a provided authentication mechanism +. Define (and implicitly set) a custom identity store +include::partial$list-item-learn-security-context.adoc[] + +=== Write the application + +include::partial$rest-resource-class.adoc[] + +==== Declare the security constraints + +include::partial$declare-security-constraints.adoc[] + +==== Declare the authentication mechanism + +[source,java] +---- +@ApplicationScoped +@BasicAuthenticationMechanismDefinition(realmName = "basicAuth") +@DeclareRoles({ "user", "caller" }) +@ApplicationPath("/rest") +public class ApplicationConfig extends Application { + +} +---- + +include::partial$declare-authentication-mechanism.adoc[] + +==== Define the identity store + +include::partial$simple-identity-store.adoc[] + +==== Test the application + +:app-name: restBasicAuthCustomStore +include::partial$test-github.adoc[] + +[source] +---- +john : true +[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 6.414 s - in jakartaee.examples.focused.security.restbasicauthcustomstore.RestBasicAuthCustomStoreIT +---- + +Let's take a quick look at the actual test: + +[source,java] +---- +@RunWith(Arquillian.class) +@RunAsClient +public class RestBasicAuthCustomStoreIT extends ITBase { + + /** + * Stores the base URL. + */ + @ArquillianResource + private URL baseUrl; + + /** + * Test the call to a protected REST service + * + * @throws Exception when a serious error occurs. + */ + @RunAsClient + @Test + public void testRestCall() throws Exception { + DefaultCredentialsProvider credentialsProvider = new DefaultCredentialsProvider(); + credentialsProvider.addCredentials("john", "secret1"); + + webClient.setCredentialsProvider(credentialsProvider); + + TextPage page = webClient.getPage(baseUrl + "/rest/resource"); + String content = page.getContent(); + + System.out.println(content); + } +} +---- + +include::partial$inspect-app.adoc[] + +The `DefaultCredentialsProvider` used here makes sure that the headers for Basic authentication are added to the request. The Basic authentication mechanism that we defined for our applications reads those headers, extracts the username and password from them, and consults our identity store with them. + + + + +== Securing an endpoint with Basic authentication and a database identity store + +In the following example, we'll secure a REST endpoint using Basic authentication and the database identity store that is provided by Jakarta Security. + +You'll learn how to: + +include::partial$list-item-learn-security-constraints.adoc[] +include::partial$list-item-learn-basic-authentication.adoc[] +. Use the provided https://jakarta.ee/specifications/security/3.0/apidocs/jakarta.security/jakarta/security/enterprise/identitystore/databaseidentitystoredefinition[DatabaseIdentityStoreDefinition,role=external,window=_blank] +. Populate and configure the identity store +include::partial$list-item-learn-security-context.adoc[] + +=== Write the application + +include::partial$rest-resource-class.adoc[] + +==== Declare the authentication mechanism and identity store + +[source,java] +---- +@ApplicationScoped +@BasicAuthenticationMechanismDefinition( + realmName = "basicAuth" +) +@DatabaseIdentityStoreDefinition( + callerQuery = "select password from basic_auth_user where username = ?", + groupsQuery = "select name from basic_auth_group where username = ?", + hashAlgorithmParameters = { + "Pbkdf2PasswordHash.Iterations=3072", + "Pbkdf2PasswordHash.Algorithm=PBKDF2WithHmacSHA512", + "Pbkdf2PasswordHash.SaltSizeBytes=64" + } +) +@DeclareRoles("user") +@ApplicationPath("/rest") +public class ApplicationConfig extends Application { + +---- + +include::partial$declare-authentication-mechanism.adoc[] + +Likewise, to declare the usage of a specific identity store, Jakarta EE provides `[XYZ]StoreDefinition` annotations. + +The annotations can be put on any bean, but in a REST application it fits particularly well on the `Application` subclass that also declares the path for REST resources. + +You can use the provided `DatabaseIdentityStoreDefinition` with any authentication mechanism that validates username/password credentials. It requires at least two SQL queries: + +. A query that returns a password for the username part of credentials. The returned password is compared with the password part of those credentials. If they match (of more typically, their hashes match) the credential is considered valid. +. A query that returns a number of roles given that same username part of the credentials + +Although not required, it's a good practice to provide some parameters for the hash algorithm. Passwords should never be stored in plain-text in a database. + +==== Populating the identity store + +In order to use the identity store, we need to put some data in a database. The following code shows one way how to do that: + +[source,java] +---- +@ApplicationScoped +@BasicAuthenticationMechanismDefinition( + realmName = "basicAuth" +) +@DatabaseIdentityStoreDefinition( + callerQuery = "select password from basic_auth_user where username = ?", + groupsQuery = "select name from basic_auth_group where username = ?", + hashAlgorithmParameters = { + "Pbkdf2PasswordHash.Iterations=3072", + "Pbkdf2PasswordHash.Algorithm=PBKDF2WithHmacSHA512", + "Pbkdf2PasswordHash.SaltSizeBytes=64" + } +) +@DeclareRoles("user") +@ApplicationPath("/rest") +public class ApplicationConfig extends Application { + + /** + * Id of the one and only user we populate in out DB. + */ + private static final BigInteger USER_ID = ONE; + + /** + * Id of the one and only group we populate in out DB. + */ + private static final BigInteger GROUP_ID = ONE; + + @PersistenceContext + private EntityManager entityManager; + + @Inject + private Pbkdf2PasswordHash passwordHash; + + @Transactional + public void onStart(@Observes @Initialized(ApplicationScoped.class) Object applicationContext) { + passwordHash.initialize(Map.of( + "Pbkdf2PasswordHash.Iterations", "3072", + "Pbkdf2PasswordHash.Algorithm", "PBKDF2WithHmacSHA512", + "Pbkdf2PasswordHash.SaltSizeBytes", "64")); + + if (entityManager.find(User.class, USER_ID) == null) { + var user = new User(); + user.id = USER_ID; + user.username = "john"; + user.password = passwordHash.generate("secret1".toCharArray()); + entityManager.persist(user); + } + + if (entityManager.find(Group.class, GROUP_ID) == null) { + var group = new Group(); + group.id = GROUP_ID; + group.name = "user"; + group.username = "john"; + entityManager.persist(group); + } + } + +} + +@Entity +@Table(name = "basic_auth_user") +class User { + @Id + BigInteger id; + + @Column(name = "password") + String password; + + @Column(name = "username", unique = true) + String username; +} + +@Entity +@Table(name = "basic_auth_group") +class Group { + @Column(name = "id") + @Id + BigInteger id; + + @Column(name = "name") + String name; + + @Column(name = "username") + String username; +} +---- + +The code above uses Jakarta Persistence, which generates SQL from Java types. Jakarta Persistence is discussed in detail in its own chapter. Since we haven't specified a datasource, the `@DatabaseIdentityStoreDefinition` annotation will use the default datasource defined in Jakarta EE, so you don't have to explicitly install and configure an external database such as Postgres or MySQL. However, if necessary, you can configure a different one using the `dataSourceLookup` attribute. + +==== Test the application + +:app-name: restBasicAuthDBStore +include::partial$test-github.adoc[] + +[source] +---- +john : true +[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 8.307 s - in jakartaee.examples.focused.security.restbasicauthdbstore.RestBasicAuthDBStoreIT +---- + +The test itself is basically the same as that for the <> example. + + + + + +== Securing an endpoint with Basic authentication and multiple identity stores + +In the following example, we'll be securing a REST endpoint using Basic authentication and two identity stores: the database identity store that is provided by Jakarta Security and a custom identity store. + +You'll learn how to: + +include::partial$list-item-learn-security-constraints.adoc[] +include::partial$list-item-learn-basic-authentication.adoc[] +. Use the provided https://jakarta.ee/specifications/security/3.0/apidocs/jakarta.security/jakarta/security/enterprise/identitystore/databaseidentitystoredefinition[DatabaseIdentityStoreDefinition,role=external,window=_blank] +. Create a custom https://jakarta.ee/specifications/security/3.0/apidocs/jakarta.security/jakarta/security/enterprise/identitystore/package-summary.html[identity store,role=external,window=_blank] +include::partial$list-item-learn-security-context.adoc[] + +=== Write the application + +include::partial$rest-resource-class.adoc[] + +==== Declare the authentication mechanism and identity store + +[source,java] +---- +@ApplicationScoped +@BasicAuthenticationMechanismDefinition( + realmName = "basicAuth" +) +@DatabaseIdentityStoreDefinition( + callerQuery = "select password from basic_auth_user where username = ?", + groupsQuery = "select name from basic_auth_group where username = ?", + hashAlgorithmParameters = { + "Pbkdf2PasswordHash.Iterations=3072", + "Pbkdf2PasswordHash.Algorithm=PBKDF2WithHmacSHA512", + "Pbkdf2PasswordHash.SaltSizeBytes=64" + } +) +@DeclareRoles("user") +@ApplicationPath("/rest") +public class ApplicationConfig extends Application { + +---- + +[source,java] +---- +@ApplicationScoped +public class CustomIdentityStore implements IdentityStore { + + public CredentialValidationResult validate(UsernamePasswordCredential usernamePasswordCredential) { + if (usernamePasswordCredential.compareTo("pete", "secret2")) { + return new CredentialValidationResult("pete", Set.of("user", "caller")); + } + + return INVALID_RESULT; + } + +} +---- + +In this example we have two enabled CDI beans implementing the `IdentityStore` interface. One of them will be implicitly enabled via the `@DatabaseIdentityStoreDefinition` annotation, while the other one is defined explicitly via the `CustomIdentityStore` class. As with a single identity store, it doesn't matter how or where the CDI beans are defined, only that multiple enabled ones exist. + +When multiple identity stores are present, the security system will try them in order of their priority. We didn't set a priority here, so the order will be undefined. If the default validation algorithm is used, a successful validation wins over a failed validation. For example, let's say we have multiple identity stores that know about the user "pete". If "pete" fails validation in one store, but passes validation in another store, the end result is still that validation passed. + +In the two stores above, however only one store knows about "pete" and that's the `CustomIdentityStore`. The store created from `@DatabaseIdentityStoreDefinition` doesn't know about "pete" at all, and will simply not validate it. + + +==== Populating the identity store + +In order to use the identity store, we need to put some data in a database. This is done in the same as in <>. + +==== Test the application + +:app-name: restBasicAuthDBStoreAndCustomStore +include::partial$test-github.adoc[] + +[source] +---- +john : true +pete : true +[INFO] Tests run: 2, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 9.239 s - in jakartaee.examples.focused.security.restbasicauthdbstoreandcustomstore.RestBasicAuthDBStoreAndCustomStoreIT +---- + +Let's take a quick look at the actual test again: + +[source,java] +---- +@RunWith(Arquillian.class) +@RunAsClient +public class RestBasicAuthDBStoreAndCustomStoreIT extends ITBase { + + @ArquillianResource + private URL baseUrl; + + /** + * Test the call to a protected REST service + * + *

+ * This will use the "john" credentials, which should be validated by the DB store + * + * @throws Exception when a serious error occurs. + */ + @RunAsClient + @Test + public void testRestCall1() throws Exception { + DefaultCredentialsProvider credentialsProvider = new DefaultCredentialsProvider(); + credentialsProvider.addCredentials("john", "secret1"); + + webClient.setCredentialsProvider(credentialsProvider); + + TextPage page = webClient.getPage(baseUrl + "/rest/resource"); + String content = page.getContent(); + + System.out.println(content); + } + + /** + * Test the call to a protected REST service + * + *

+ * This will use the "pete" credentials, which should be validated by the custom store + * + * @throws Exception when a serious error occurs. + */ + @RunAsClient + @Test + public void testRestCall2() throws Exception { + DefaultCredentialsProvider credentialsProvider = new DefaultCredentialsProvider(); + credentialsProvider.addCredentials("pete", "secret2"); + + webClient.setCredentialsProvider(credentialsProvider); + + TextPage page = webClient.getPage(baseUrl + "/rest/resource"); + String content = page.getContent(); + + System.out.println(content); + } +} +---- + +include::partial$inspect-app.adoc[] + +We have two tests here: in one test we try to authenticate as "john", in the other test as "pete". As we've seen, each identity store only validates one of them. The fact that both tests pass demonstrates that each store will validate the right user, and that not recognizing a username by any of them will not fail the overall validation. + + + + + +== Securing an endpoint with Form authentication + +In the following example, we'll secure a REST endpoint using Form authentication. + +You'll learn how to: + +include::partial$list-item-learn-security-constraints.adoc[] +. Use the https://jakarta.ee/specifications/security/3.0/apidocs/jakarta.security/jakarta/security/enterprise/authentication/mechanism/http/formauthenticationmechanismdefinition[Form authentication mechanism,role=external,window=_blank] +. How to define (and implicitly set) a custom https://jakarta.ee/specifications/security/3.0/apidocs/jakarta.security/jakarta/security/enterprise/identitystore/package-summary.html[identity store,role=external,window=_blank] +include::partial$list-item-learn-security-context.adoc[] + +=== Write the application + +include::partial$rest-resource-class.adoc[] + +==== Declare the security constraints + +include::partial$declare-security-constraints.adoc[] + +==== Declare the authentication mechanism + +[source,java] +---- +@ApplicationScoped +@FormAuthenticationMechanismDefinition( + loginToContinue = @LoginToContinue( + loginPage="/login.html", + errorPage="/login-error.html" + ) +) +@DeclareRoles({ "user", "caller" }) +@ApplicationPath("/rest") +public class ApplicationConfig extends Application { + +} +---- + +include::partial$declare-authentication-mechanism.adoc[] + +Contrary to the Basic HTTP authentication mechanism, the Form authentication mechanism allows us to customize the login dialog (the process between the caller and the authentication mechanism) and to keep track of the authenticated session on the server (using a cookie). This also allows us to logout, something that for unknown reasons has never been specified for Basic HTTP authentication. + +To use this authentication method, we need to designate two paths to resources that are relative to our application. One path is for the login page, which the user will be directed to when attempting to access a protected resource. The other path is for when login fails, such as when the user enters incorrect login credentials. If the paths are the same, a request parameter can be used to distinguish between them. Paths can point to anything our server can respond to; a static HTML file, a REST resource, or anything else. For simplicity, we'll use two static HTML files here: + +[source,html] +---- + + + Login to continue + +

Login to continue

+
+
+ +
+
+ +
+
+ +
+
+ + +---- + +[source,html] +---- + + + Login failed! + +

Login failed!

+
+ Try again +
+ + +---- + +==== Define the identity store + +Finally, let's define a basic identity store that the security system can use to validate provided credentials for Form authentication: + +[source,java] +----- +@ApplicationScoped +public class CustomIdentityStore implements IdentityStore { + + public CredentialValidationResult validate(UsernamePasswordCredential usernamePasswordCredential) { + if (usernamePasswordCredential.compareTo("john", "secret1")) { + return new CredentialValidationResult("john", Set.of("user", "caller")); + } + + return INVALID_RESULT; + } + +} +----- + +This identity store only validates the single identity (user) "john", with password "secret1" and roles "user" and "caller". Defining this kind of identity store is often the simplest way to get started. Note that Jakarta Security doesn't define a simple identity store out of the box, because there are questions about whether that would promote security best practices. + +include::partial$identity-store-installed.adoc[] + +==== Test the application + +:app-name: restBasicAuthCustomStore +include::partial$test-github.adoc[] + +[source] +---- +john : true +[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 5.24 s - in jakartaee.examples.focused.security.restformauthcustomstore.RestFormAuthCustomStoreIT +---- + +Let's take a quick look at the actual test: + +[source,java] +---- +@RunWith(Arquillian.class) +@RunAsClient +public class RestFormAuthCustomStoreIT extends ITBase { + + @ArquillianResource + private URL baseUrl; + + /** + * Test the call to a protected REST service + * + * @throws Exception when a serious error occurs. + */ + @RunAsClient + @Test + public void testRestCall() throws Exception { + HtmlPage loginPage = webClient.getPage(baseUrl + "/rest/resource"); + System.out.println(loginPage.asXml()); + + HtmlForm form = loginPage.getForms() + .get(0); + + form.getInputByName("j_username") + .setValueAttribute("john"); + + form.getInputByName("j_password") + .setValueAttribute("secret1"); + + TextPage page = form.getInputByValue("Submit") + .click(); + + System.out.println(page.getContent()); + } +} +---- + +include::partial$inspect-app.adoc[] + +The test first sends a request here to the protected resource, and the server responds with the HTML form we defined above. Using the `HtmlUnit` API, it's easy to navigate the HTML DOM, fill out the username and password in the form, and programmatically click the Submit button. The form posts back to a special "j_security_check" URL, where the authentication mechanism receives the request and retrieves the username and password from the POST data, much like the Basic authentication mechanism retrieves them from the HTTP headers. + + + + +== Securing an endpoint with Basic authentication and a custom algorithm for handling multiple identity stores + +In the following example, we'll be securing a REST endpoint using Basic authentication and two identity stores: the database identity store that is provided by Jakarta Security and a custom identity store. Instead of relying on the default algorithm provided by Jakarta Security to handle multiple identity stores we'll be using a custom algoritm. + +You'll learn how to: + +include::partial$list-item-learn-security-constraints.adoc[] +include::partial$list-item-learn-basic-authentication.adoc[] +. Use the provided https://jakarta.ee/specifications/security/3.0/apidocs/jakarta.security/jakarta/security/enterprise/identitystore/databaseidentitystoredefinition[DatabaseIdentityStoreDefinition,role=external,window=_blank] +. Create a custom https://jakarta.ee/specifications/security/3.0/apidocs/jakarta.security/jakarta/security/enterprise/identitystore/package-summary.html[identity store,role=external,window=_blank] +. Create a custom https://jakarta.ee/specifications/security/3.0/apidocs/jakarta.security/jakarta/security/enterprise/identitystore/identitystorehandler[identity store handler,role=external,window=_blank] +include::partial$list-item-learn-security-context.adoc[] + +=== Write the application + +We'll use a slightly modified resource and security constraints compared to the ones we used for the <> example. + +The REST resource is now as follows: + +[source,java] +---- +@Path("/resource") +@RequestScoped +public class Resource { + + @Inject + private SecurityContext securityContext; + + @GET + @Produces(TEXT_PLAIN) + public String getCallerAndRole() { + return + securityContext.getCallerPrincipal().getName() + " : " + + securityContext.isCallerInRole("user") + "," + + securityContext.isCallerInRole("caller1") + "," + + securityContext.isCallerInRole("caller2"); + } + +} +---- + +As can be seen, the difference is quite small; we're now printing out the results of two extra role checks. + + +`web.xml` on its turn looks as follows now: + +[source,xml] +---- + + + + + protected + /rest/* + + + user + caller2 + + + + caller1 + + + +---- + +Compared to the example in <> we have now added an extra role to the `` section. The semantics of that are that a caller needs to have both of these roles in order to be authorised to access the resource under `/rest/*`. + +Although it's customary to explicitly declare all roles in the application using ``, it's technically not needed. As long as the role name appears in some XML fragment or annotation attribute the Jakarta EE requirement to declare all roles upfront is satisfied. As we can see in the fragment above, the role names "user" and "caller2" already appear in the `` section, so they don't *have* to be repeated. + +NOTE: The reason it's deemed good practice to list all roles in the `` element in web.xml (or alternatively in an `@DeclareRoles` annotation) even when not really needed is to have a single place where all roles are listed, instead of them being scattered throughout the application. + + +==== Declare the authentication mechanism and identity store + +[source,java] +---- +@ApplicationScoped +@BasicAuthenticationMechanismDefinition( + realmName = "basicAuth" +) +@DatabaseIdentityStoreDefinition( + callerQuery = "select password from basic_auth_user where username = ?", + groupsQuery = "select name from basic_auth_group where username = ?", + hashAlgorithmParameters = { + "Pbkdf2PasswordHash.Iterations=3072", + "Pbkdf2PasswordHash.Algorithm=PBKDF2WithHmacSHA512", + "Pbkdf2PasswordHash.SaltSizeBytes=64" + } +) +@DeclareRoles("user") +@ApplicationPath("/rest") +public class ApplicationConfig extends Application { + +---- + +[source,java] +---- +@ApplicationScoped +public class CustomIdentityStore implements IdentityStore { + + public CredentialValidationResult validate(UsernamePasswordCredential usernamePasswordCredential) { + if (usernamePasswordCredential.compareTo("john", "secret1")) { + return new CredentialValidationResult("john", Set.of("caller1", "caller2")); + } + + return INVALID_RESULT; + } + +} +---- + +In this example we have two enabled CDI beans implementing the `IdentityStore` interface. One of them will be implicitly enabled via the `@DatabaseIdentityStoreDefinition` annotation, while the other one is defined explicitly via the `CustomIdentityStore` class. As with a single identity store, it doesn't matter how or where the CDI beans are defined, only that multiple enabled ones exist. + +When multiple identity stores are present, an identity store handler (of type `IdentityStoreHandler`) is consulted. Jakara Security provides a default one as explained in <>. This default handler can be overridden however to provide custom semantics. We'll use a custom handler to enforce a caller authenticates with both identity stores, and we'll combine the roles returned by both in the final result. + +==== Populating the identity store + +In order to use the identity store, we need to put some data in a database. This is done in the same as in <>. + +NOTE: In the custom identity store defined above and in the database identity store here we both use name "john' and password "secret1". + +==== Writing the identity store handler + +We'll now write the identity store handler: + +[source,java] +---- +@Alternative <1> +@Priority(APPLICATION) <2> +@ApplicationScoped +public class CustomIdentityStoreHandler implements IdentityStoreHandler { + + @Inject + Instance identityStores; <3> + + @Override + public CredentialValidationResult validate(Credential credential) { + CredentialValidationResult result = null; + Set groups = new HashSet<>(); + + for (IdentityStore identityStore : identityStores) { + result = identityStore.validate(credential); + if (result.getStatus() == NOT_VALIDATED) { + // Identity store probably doesn't handle our credential type + continue; + } + + if (result.getStatus() == INVALID) { + // Identity store handled our credential type and determined its + // invalid. End the loop. + return INVALID_RESULT; + } + + groups.addAll(result.getCallerGroups()); + } + + return new CredentialValidationResult( + result.getCallerPrincipal(), groups); + } +} +---- +<1> Since we're overriding an existing CDI bean (the default `IdentityStoreHandler` provided by Jakarta Security), we have to annotate our custom `IdentityStoreHandler` with `@Alternative`. +<2> To make `@Alternative` actually work, we additionally have to annotate with `@Priority(APPLICATION)` +<3> With `@Inject` `Instance identityStores` CDI will give us a collection of all identity stores in the application. In the case of this example that will be the store behind `@DatabaseIdentityStoreDefinition` and our `CustomIdentityStore`. We can the iterate over those stores in our code, and offer the credentials (the username and password in this example) to each of them. + +There are various result outcomes possible. + +`NOT_VALIDATED` means the store did not try to validate the credentials at all. In most situations that status is set when the store in question doesnt't handle a given credential. I.e. it only handles say `JWTCredentials` and not `UsernamePasswordCredential`. + +`INVALID` means the store tried to validate the credentials, and validation failed. For example the username and password were wrong. + +In our custom handler code here we return an `INVALID_RESULT` for the first store that fails, as we want all stores to validate successfully here. If validation does succeed (the outcome is `VALID` then) we grab the groups it returned and store in a set. + +NOTE: Identity stores also have a capability to query it for roles directly, without validating credentials. We haven't used that feature here. + +Eventually we return a result based on the `CallerPrincipal` from the last successful validation result, and all the collected groups. + +NOTE: In our example it doesn't matter from which validation result we grab the `CallerPrincipal` as it's all the one with name "pete" here. In general identity stores may transform the name from the input credential (for example "pete") to something else (for example "Pete Anderson"). + +==== Test the application + +:app-name: restBasicAuthCustomStoreHandler +include::partial$test-github.adoc[] + +[source] +---- +john : true,true,true +[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 7.634 s - in jakartaee.examples.focused.security.restbasicauthcustomstorehandler.RestBasicAuthCustomStoreHandlerIT +---- + +The resource that we defined above required only two roles to access it (`user` and `caller2`), but our custom identity store also returned `caller1`. The resource we created tests for this, and as it appears, we indeed had this role. + +NOTE: If we hadn't declared `caller1` in `web.xml` (or via an annotation), the test for `caller1` might have returned false. This is however server dependent. + + + +== Securing an endpoint with a custom authentication mechanism and a custom identity store + +In the following example, we'll be securing a REST endpoint using a custom authentication mechanism. A custom authentication mechanism is one we provide ourselves, instead of using one provided by Jakarta Security (such as the Basic HTTP authentication mechanism). + +You'll learn how to: + +include::partial$list-item-learn-security-constraints.adoc[] +. Define (and implicitly set) a custom authentication mechanism +. Define (and implicitly set) a custom identity store +include::partial$list-item-learn-security-context.adoc[] + +=== Write the application + +include::partial$rest-resource-class.adoc[] + +==== Define the authentication mechanism + +Let's now define a simple authentication mechanism that the security system can use to interact with the caller who tries to access a resource: + +[source,java] +---- +@ApplicationScoped +public class CustomAuthenticationMechanism implements HttpAuthenticationMechanism { + + @Inject + private IdentityStoreHandler identityStoreHandler; + + @Override + public AuthenticationStatus validateRequest( + HttpServletRequest request, + HttpServletResponse response, + HttpMessageContext httpMessageContext) throws AuthenticationException { + + var callerName = request.getHeader("callername"); <1> + var password = request.getHeader("callerpassword"); + + if (callerName == null || password == null) { <2> + return httpMessageContext.doNothing(); + } + + var result = identityStoreHandler.validate( <4> + new UsernamePasswordCredential(callerName, password)); <3> + + if (result.getStatus() != VALID) { + return httpMessageContext.responseUnauthorized(); + } + + return httpMessageContext.notifyContainerAboutLogin( <5> + result.getCallerPrincipal(), + result.getCallerGroups()); + } + +} +---- + +This custom authentication mechanism interacts with the caller by grabbing two headers from the request: `callername` and `callerpassword`. (1) In case any of them are `null`, we return a special status; the "do nothing" status. (2) This means there has been no request or attempt to do authentication. If the resource the caller is trying to access is not protected, the caller can access it anonymously. If it is proteced, the caller will not be able to access it. + +When the two required headers are provided by the caller, we create a `UsernamePasswordCredential` out of their values (3) and pass that into the injected `IdentityStoreHandler`. (4) We saw how this type of handler worked in the example <>. + +NOTE: An authentication mechanism in Jakarta Security is not strictly required to delegate the credential validation to the identity store handler. However not doing so is considered bad practice, as it would restrict developers from things like inserting extra identity stores into the chain that can do things like adding extra groups. + +If the credentials validated correctly, we use the `HttpMessageContext` to communicate the details of the authenticated caller to the container. (5) + +NOTE: In Jakarta Security the two basic items that make up an "authenticated identity" are just a caller principal (of type `Principal`) and a set of groups (of type `String`). Via a https://en.wikipedia.org/wiki/Service_provider_interface[Service Provider Interface,role=external,window=_blank] a specific Jakarta EE product (such as WildFly or GlassFish) is able to receive these two items and then stores it internally in some way. + +include::partial$authentication-mechanism-installed.adoc[] + +==== Define the identity store + +include::partial$simple-identity-store.adoc[] + +==== Test the application + +:app-name: restCustomAuthCustomStore +include::partial$test-github.adoc[] + +[source] +---- +john : true +[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 4.591 s - in jakartaee.examples.focused.security.restcustomauthcustomstore.RestCustomAuthCustomStoreIT +---- + +Let's take a quick look at the actual test: + +[source,java] +---- +@RunWith(Arquillian.class) +@RunAsClient +public class RestCustomAuthCustomStoreIT extends ITBase { + + @ArquillianResource + private URL baseUrl; + + /** + * Test the call to a protected REST service + * + * @throws Exception when a serious error occurs. + */ + @RunAsClient + @Test + public void testRestCall() throws Exception { + webClient.addRequestHeader("callername", "john"); + webClient.addRequestHeader("callerpassword", "secret1"); + + TextPage page = webClient.getPage(baseUrl + "rest/resource"); + String content = page.getContent(); + + System.out.println(content); + } +} +---- + +include::partial$inspect-app.adoc[] + +The `webClient.addRequestHeader()` calls used here make sure that the headers for our custom authentication mechanism are added to the request. The authentication mechanism that we defined for our applications reads those headers, extracts the username and password from them, and consults our identity store with them. + + + + +== Securing an endpoint with Form authentication and remember-me + +In the following example, we'll secure a REST endpoint using Form authentication and remember-me. + +Remember-me is a facility where an authenticated identity can be remembered beyond the scope of an HTTP session. This happens via +a separate cookie that has a longer life-time than the cookie used for the HTTP session (and the session itself on the server). + +You'll learn how to: + +include::partial$list-item-learn-security-constraints.adoc[] +. Use the https://jakarta.ee/specifications/security/3.0/apidocs/jakarta.security/jakarta/security/enterprise/authentication/mechanism/http/formauthenticationmechanismdefinition[Form authentication mechanism,role=external,window=_blank] +. Enable the https://jakarta.ee/specifications/security/3.0/apidocs/jakarta.security/jakarta/security/enterprise/authentication/mechanism/http/rememberme[remember-me,role=external,window=_blank] feature +. How to define (and implicitly set) a custom https://jakarta.ee/specifications/security/3.0/apidocs/jakarta.security/jakarta/security/enterprise/identitystore/remembermeidentitystore[remember-me identity store,role=external,window=_blank] +. How to define (and implicitly set) a custom https://jakarta.ee/specifications/security/3.0/apidocs/jakarta.security/jakarta/security/enterprise/identitystore/package-summary.html[identity store,role=external,window=_blank] +include::partial$list-item-learn-security-context.adoc[] + +=== Write the application + +include::partial$rest-resource-class.adoc[] + +==== Declare the security constraints + +include::partial$declare-security-constraints.adoc[] + +==== Declare the authentication mechanism + +We'll use the same authentication mechanism declaration as we used for <> + +==== Enable remember-me + +In Jakarta Security, there are several services available through CDI Interceptors footnote:[Technically Jakarta Interceptors is an API separate from CDI, but in modern applications they are used exclusively with CDI, hence we use the term "CDI Interceptors" here.], one of which is the remember-me service. Remember-me can be transparently applied to basically every authentication mechanism. In CDI, it's trivial to add Interceptors to beans that we define ourselves, but a little less trivial to add to provided beans. In this section we explain how to do this via a CDI extension. + + +For this example, we'll add the CDI extension interface (1) to our application config class: + +[source,java] +----- +@ApplicationScoped +@FormAuthenticationMechanismDefinition( + loginToContinue = @LoginToContinue( + loginPage="/login.html", + errorPage="/login-error.html" + ) +) +@ApplicationPath("/rest") +public class ApplicationConfig extends Application + implements BuildCompatibleExtension { <1> + + @Enhancement( + types = HttpAuthenticationMechanism.class, + withSubtypes = true) <2> + public void addRememberMe(ClassConfig httpAuthenticationMechanism) { + httpAuthenticationMechanism.addAnnotation( + RememberMe.Literal.INSTANCE); <3> + } +} +----- + +CDI allows us to enhance classes using a method annotated with the `@Enhancement` annotation and as attribute the class we're seeking to enhance. For our example that will be a sub-type of the `HttpAuthenticationMechanism` interface (we know the bean enabled by `FormAuthenticationMechanismDefinition` will implement the `HttpAuthenticationMechanism` interface), hence we set the `withSubtypes` attribute to `true`. (2) + +Within the method we can then programmatically add the `@RememberMe` annotation used to bind the remember-me interceptor to a class. In the example here we use the default instance (which has all attributes set to their defaults). There are attributes for setting various aspects of the cookie, such as its name, whether it should be secure and http only, and perhaps most importantly the max age of the cookie (default is one day). + +==== Define the remember-me identity store + +For remember-me to work a token has to be created that is used as a credential to authenticate right away instead of invoking the authentication mechanism that is being intercepted. Jakarta Security uses a special identity store for this; the `RememberMeIdentityStore`. This type of identity store is exclusively used by the remember-me feature, hence it's a different type from `IdentityStore`. + +Jakarta Security does not ship with any provided remember-me identity store, but for demonstration purposes we can easily create one ourselves. + +The following shows an example: + +[source,java] +----- +@ApplicationScoped +public class CustomRememberMeIdentityStore implements RememberMeIdentityStore { + + private final Map tokenToIdentityMap = + new ConcurrentHashMap<>(); + + @Override + public String generateLoginToken( + CallerPrincipal callerPrincipal, Set groups) { <1> + var token = UUID.randomUUID().toString(); + + tokenToIdentityMap.put( + token, + new CredentialValidationResult(callerPrincipal, groups)); + + return token; + } + + @Override + public CredentialValidationResult validate( + RememberMeCredential credential) { <2> + if (tokenToIdentityMap.containsKey(credential.getToken())) { + return tokenToIdentityMap.get(credential.getToken()); + } + + return INVALID_RESULT; + } + + @Override + public void removeLoginToken(String token) { <3> + tokenToIdentityMap.remove(token); + } + +} +----- + +The `RememberMeIdentityStore` needs to perform 3 tasks. + +It first needs to generate a token representing a caller principal and a set of groups. The caller principal and the set of groups are the ones set by the authentication mechanism right after the caller successfully authenticated. In our example (1) here we're generating a random UUID that's used as a key in an application scoped map. + +NOTE: Storing the authenticated identity (principal and groups) in an application scoped map is just an example. Other options could be storing it in a database or key-value store, encrypting the principal and groups, or generating some kind of JSON Web Token (JWT). + +NOTE: When storing the Principal, care must be taken that the Principal could be an elaborate custom Principal containing many more fields than just `name`. + +The next thing that must be done is essentially similar to what a normal identity store does: validating a `Credential`. For a `RememberMeIdentityStore` this will always be of type `RememberMeCredential` with `getToken()` returning a token of the kind that was generated in `generateLoginToken()`. In our example (2) we're just using the token as key in our map. + +Finally we can provide behaviour to remove the login token (and essentially invalidate it) via the `removeLoginToken` method. This method is called when a caller explicitly logs out. In our example (3) we just remove the token from our map. + +NOTE: When storing the principal and groups in a token that we send to the client we can't always easily invalidate it when the caller logs out; the caller can always keep the token and send it again. + + +==== Define the identity store + +include::partial$simple-identity-store.adoc[] + +==== Test the application + +:app-name: restFormAuthCustomStoreRememberMe +include::partial$test-github.adoc[] + +[source] +---- +john : true +john : true +[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 5.702 s - in jakartaee.examples.focused.security.restformauthcustomatorerememberme.RestFormAuthCustomStoreIT +---- + +Let's take a quick look at the actual test: + +[source,java] +---- +@RunWith(Arquillian.class) +@RunAsClient +public class RestFormAuthCustomStoreRememberMeIT extends ITBase { + + @ArquillianResource + private URL baseUrl; + + /** + * Test the call to a protected REST service + * + * @throws Exception when a serious error occurs. + */ + @RunAsClient + @Test + public void testRestCall() throws Exception { + // Initial request + HtmlPage loginPage = webClient.getPage(baseUrl + "/rest/resource"); + System.out.println(loginPage.asXml()); + + // Response is login form, so we can authenticate + HtmlForm form = loginPage.getForms() + .get(0); + + form.getInputByName("j_username") + .setValueAttribute("john"); + + form.getInputByName("j_password") + .setValueAttribute("secret1"); + + // After logging in, we should get the actual resource response + TextPage page = form.getInputByValue("Submit") + .click(); + + System.out.println(page.getContent()); + + // Remove all cookies (specially the JSESSONID), except for the + // JREMEMBERMEID cookie which carries the token to login again + for (Cookie cookie : webClient.getCookieManager().getCookies()) { + if (!"JREMEMBERMEID".equals(cookie.getName())) { + webClient.getCookieManager().removeCookie(cookie); + } + } + + // Should get the resource response, and not the login form + TextPage pageAgain = webClient.getPage(baseUrl + "/rest/resource"); + + System.out.println(pageAgain.getContent()); + } +} +---- + +include::partial$inspect-app.adoc[] + +The test first sends a request here to the protected resource, and the server responds with the HTML form we defined above. Using the `HtmlUnit` API, it's easy to navigate the HTML DOM, fill out the username and password in the form, and programmatically click the Submit button. The form posts back to a special "j_security_check" URL, where the authentication mechanism receives the request and retrieves the username and password from the POST data, much like the Basic authentication mechanism retrieves them from the HTTP headers. + +Then we delete all cookies, specifically the `JSESSIONID` cookie that keeps the session that the form authentication mechanism uses to remember the authenticated identity. The test then does another request, and this time the value from the `JREMEMBERMEID` cookie is used to login. + + + + +== Securing an endpoint with a custom authentication mechanism, a custom identity store and remember-me + +In the following example, we'll secure a REST endpoint using custom authentication and remember-me. + +Remember-me is a facility where an authenticated identity can be remembered beyond the scope of an HTTP session. This happens via +a separate cookie that has a longer life-time than the cookie used for the HTTP session (and the session itself on the server). + +You'll learn how to: + +include::partial$list-item-learn-security-constraints.adoc[] +. Define (and implicitly set) a custom authentication mechanism with remember-me +. How to define (and implicitly set) a custom remember-me identity store +. Define (and implicitly set) a custom identity store +include::partial$list-item-learn-security-context.adoc[] + +=== Write the application + +include::partial$rest-resource-class.adoc[] + +==== Define the authentication mechanism + +Let's now define a simple authentication mechanism that the security system can use to interact with the caller who tries to access a resource and specifically make sure the RememberMe feature is used: + +[source,java] +---- +@RememberMe <6> +@ApplicationScoped +public class CustomAuthenticationMechanism implements HttpAuthenticationMechanism { + + @Inject + private IdentityStoreHandler identityStoreHandler; + + @Override + public AuthenticationStatus validateRequest( + HttpServletRequest request, + HttpServletResponse response, + HttpMessageContext httpMessageContext) throws AuthenticationException { + + var callerName = request.getHeader("callername"); <1> + var password = request.getHeader("callerpassword"); + + if (callerName == null || password == null) { <2> + return httpMessageContext.doNothing(); + } + + var result = identityStoreHandler.validate( <4> + new UsernamePasswordCredential(callerName, password)); <3> + + if (result.getStatus() != VALID) { + return httpMessageContext.responseUnauthorized(); + } + + return httpMessageContext.notifyContainerAboutLogin( <5> + result.getCallerPrincipal(), + result.getCallerGroups()); + } + +} +---- + +NOTE: This is the same custom authentication mechanism that was used in <>, but with the `@RememberMe` annotation added. + +This custom authentication mechanism interacts with the caller by grabbing two headers from the request: `callername` and `callerpassword`. (1) In case any of them are `null`, we return a special status; the "do nothing" status. (2) This means there has been no request or attempt to do authentication. If the resource the caller is trying to access is not protected, the caller can access it anonymously. If it is proteced, the caller will not be able to access it. + +When the two required headers are provided by the caller, we create a `UsernamePasswordCredential` out of their values (3) and pass that into the injected `IdentityStoreHandler`. (4) We've seen how such handler worked in the example <>. + +NOTE: An authentication mechanism in Jakarta Security is not strictly required to delegate the credential validation to the identity store handler. However not doing so is considered bad practice, as it would restrict developers from things like inserting extra identity stores into the chain that can do things like adding extra groups. + +If the credentials validated correctly, we use the `HttpMessageContext` to communicate the details of the authenticated caller to the container. (5) + +NOTE: In Jakarta Security the two basic items that make up an "authenticated identity" are just a caller principal (of type `Principal`) and a set of groups (of type `String`). Via a https://en.wikipedia.org/wiki/Service_provider_interface[Service Provider Interface,role=external,window=_blank] a specific Jakarta EE product (such as WildFly or GlassFish) is able to receive these two items and then stores it internally in some way. + +We annotate our custom authentication mechanism with the `@RememberMe` annotation to enable the remember-me feature for use with this authentication mechanism. In the example here we don't set any attributes (all of them have default values). There are attributes for setting various aspects of the cookie used for remember-me, such as its name, whether it should be secure and http only, and perhaps most importantly the max age of the cookie (default is one day). + +NOTE: Instead of using the `@RememberMe` annotation here, we could also have used the same extension that was used in <> to enable the remember-me feature. The annotation however is a little bit easier to use. + +include::partial$authentication-mechanism-installed.adoc[] + +==== Define the identity store + +include::partial$simple-identity-store.adoc[] + +==== Define the remember-me identity store + +We'll use the same remember-me identity store as we used for the <> example. + +==== Test the application + +:app-name: restCustomAuthCustomStoreRememberMe +include::partial$test-github.adoc[] + +[source] +---- +john : true +john : true +[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 5.287 s - in jakartaee.examples.focused.security.restcustomauthcustomstorerememberme.RestCustomAuthCustomStoreRememberMeIT +---- + +Let's take a quick look at the actual test: + +[source,java] +---- +@RunWith(Arquillian.class) +@RunAsClient +public class RestFormAuthCustomStoreRememberMeIT extends ITBase { + + @ArquillianResource + private URL baseUrl; + + /** + * Test the call to a protected REST service + * + * @throws Exception when a serious error occurs. + */ + @RunAsClient + @Test + public void testRestCall() throws Exception { + // Initial request + HtmlPage loginPage = webClient.getPage(baseUrl + "/rest/resource"); + System.out.println(loginPage.asXml()); + + // Response is login form, so we can authenticate + HtmlForm form = loginPage.getForms() + .get(0); + + form.getInputByName("j_username") + .setValueAttribute("john"); + + form.getInputByName("j_password") + .setValueAttribute("secret1"); + + // After logging in, we should get the actual resource response + TextPage page = form.getInputByValue("Submit") + .click(); + + System.out.println(page.getContent()); + + // Remove all cookies (specially the JSESSONID), except for the + // JREMEMBERMEID cookie which carries the token to login again + for (Cookie cookie : webClient.getCookieManager().getCookies()) { + if (!"JREMEMBERMEID".equals(cookie.getName())) { + webClient.getCookieManager().removeCookie(cookie); + } + } + + // Should get the resource response, and not the login form + TextPage pageAgain = webClient.getPage(baseUrl + "/rest/resource"); + + System.out.println(pageAgain.getContent()); + } +} +---- + +include::partial$inspect-app.adoc[] + +The `webClient.addRequestHeader()` calls used here make sure that the headers for our custom authentication mechanism are added to the request. The authentication mechanism that we defined for our applications reads those headers, extracts the username and password from them, and consults our identity store with them. + +The test sends a request here to the protected resource along with the headers we mentioned above, and the server responds with the right content. + +Then we delete all cookies, except for the `JREMEMBERMEID` cookie, and we unset all headers that we used before. The test then does another request, and this time the value from the `JREMEMBERMEID` cookie is used to login. + + + + +== Securing an endpoint with OpenID Connect authentication + +In the following example, we'll be securing a REST endpoint using OpenID Connect authentication. + +With https://en.wikipedia.org/wiki/OpenID[OpenID Connect,role=external,window=_blank] authentication a caller is redirected to a third party server, typically a public one such as Google, Facebook, Linkedin, Apple, and more, but it can be a private one as well. The caller authenticates with that third party server, and is then redirected back along with a token. Our server than validates that token, and if it's valid the caller is considered authenticated. + +You'll learn how to: + +include::partial$list-item-learn-security-constraints.adoc[] +. Use the https://jakarta.ee/specifications/security/3.0/apidocs/jakarta.security/jakarta/security/enterprise/authentication/mechanism/http/openidauthenticationmechanismdefinition[OpenID Connect authentication mechanism,role=external,window=_blank] +. Define (and implicitly set) a custom identity store used for authorization only +include::partial$list-item-learn-security-context.adoc[] + +=== Write the application + +include::partial$rest-resource-class.adoc[] + +==== Declare the security constraints + +include::partial$declare-security-constraints.adoc[] + +==== Declare the authentication mechanism + +[source,java] +---- +@OpenIdAuthenticationMechanismDefinition( + providerURI = "https://localhost:8443/openid-connect-server-webapp", <1> + clientId = "client", <2> + clientSecret = "secret", <3> + redirectToOriginalResource = true <4> +) +@ApplicationScoped +@ApplicationPath("/rest") +public class ApplicationConfig extends Application { + +} +---- + +include::partial$declare-authentication-mechanism.adoc[] + +Contrary to the Basic HTTP authentication mechanism and the Form authentication mechanism, the OpenID Connect authentication mechanism requires a third party server that performs the actual authentication. Such third party server is called the OpenID Connect Provider (OIDC provider or OpenID Provider are also used). After authentication this provider handles user consent and and issues a token. The client requesting a user's authentication is called a Relying Party. In the case of Jakarta EE and Jakarta Security, the Jakarta EE server running the OpenID Connect authentication mechanism is a Relying Party. + +To use this authentication mechanism, Jakarta Security provides the `@OpenIdAuthenticationMechanismDefinition` annotation, for which we typically need 3 mandatory configuration items as shown in the example code above. + +The first is the `providerURI` (1), which points to the third party OpenID Connect Provider. In this example we use `https://localhost:8443/openid-connect-server-webapp`, which is the URL on which the example code has installed and started a local OpenID Connect provider called "Mitre". Whenever a caller accesses a protected resource, that caller is redirected to that OpenID Connect Provider. + +The OpenId authentication mechanism needs to identify itself to the OpenID Connect Provider via a username/password (called `clientId` (2) and `clientSecret` (3)). We use "client" respectively "secret" here for those, which are the credentials for a default client that is available in Mitre. + +After a caller successfully authenticates with the OpenID Connect Provider, that caller is redirected back to a URL on the Relying Party (our Jakarta EE server). This is called the "callback URL" and can be set via the `redirectURI` attribute. The default value is `$\{baseURL}/Callback`, where `$\{baseURL}` expands to the context-root of the application that uses Jakarta Security, for example `https://localhost:8080/openid-client` in our example. This exact URI must be known to Mitre. Mitre (and any OpenID Connect Provider in general) never redirects to unknown URIs. + +By default, after the caller is redirected back to the Relying Party (our Jakarta EE server), the resource behind `/Callback` is invoked. When the attribute `redirectToOriginalResource` (4) is set to `true` however, the caller is once again redirected to the URL originally requested and which triggered the authentication process. + +NOTE: When `redirectToOriginalResource` is set to to `true` it's not necessary to actually map anything to the callback URL (for example a Servlet or a REST resource). The authentication mechanism is invoked before the resource mapped to the callback URL is invoked, so if the authentication mechanism always redirects it never invokes this resource and the resource therefore doesn't need to actually exist. + +==== Define the identity store + +In many cases the OpenID Connect Provider has no knowledge of the application for which it authenticates the caller, and therefore does not normally provide any logical groups for the authenticated user. Those groups are application specific after all. We therefore define an additional identity store that does provide those groups for a caller. + +NOTE: Despite not being typical, Jakarta Security supports getting the groups via the https://jakarta.ee/specifications/security/3.0/apidocs/jakarta.security/jakarta/security/enterprise/authentication/mechanism/http/openidauthenticationmechanismdefinition#claimsDefinition()[claimsDefinition,role=external,window=_blank] attribute of the `@OpenIdAuthenticationMechanismDefinition` annotation. This can be used to set a claim name (default is "groups"). Jakarta Security then tries to find this name in the https://jakarta.ee/specifications/security/3.0/apidocs/jakarta.security/jakarta/security/enterprise/identitystore/openid/accesstoken[AccessToken,role=external,window=_blank], https://jakarta.ee/specifications/security/3.0/apidocs/jakarta.security/jakarta/security/enterprise/identitystore/openid/identitytoken[IdentityToken,role=external,window=_blank], or in the info returned by the `/userinfo` endpoint of the OpenId Connect Provider. Providers often need special configuration to return group claims. + +[source,java] +---- +@ApplicationScoped +public class AuthorizationIdentityStore implements IdentityStore { + + private Map> groupsPerCaller = + Map.of("user", Set.of("user")); <2> + + @Override + public Set validationTypes() { + return EnumSet.of(PROVIDE_GROUPS); <1> + } + + @Override + public Set getCallerGroups( + CredentialValidationResult validationResult) { <3> + return groupsPerCaller.get(validationResult.getCallerPrincipal().getName()); + } + +} +---- + +This identity store is set to `PROVIDE_GROUPS` (1) only, which means the default `IdentityStoreHandler` will consult this identity store for groups after another identity store has successfully validated the credentials. For our example here we create a `Map` (2) with as key the caller principal name, and as value the set of groups. When the `IdentityStoreHandler` comes asking for the groups (3) of caller "user", a set with just the group "user" is returned. + +NOTE: As validation of the `IdentityToken` that's returned by the OpenID Connect Provider is integral to the OpenID Connect flow and not application specific, developers don't have to provide or define an identity store explicitly for this. Such a store is provided by Jakarta Security as an implementation detail, and automatically activated when the OpenID Connect authentication mechanism is activated. + +include::partial$identity-store-installed.adoc[] + +==== Install and configure Mitre + +Installing and configuring the OpenID Connect provider Mitre is outside the scope of Jakarta Security itself, but for completeness sake we'll briefly discuss it by illustration of Maven pom fragments. + +[source,xml] +---- + + + + maven-dependency-plugin + + + + unpack + + + + + org.apache.tomcat + tomcat + 9.0.76 + zip + ${tomcat.root} + + + org.mitre + openid-connect-server-webapp + 1.3.4 + war + ${tomcat.dir}/webapps/openid-connect-server-webapp + + + + +---- + +Mitre is a Spring application that uses the `javax.*` namespace. We therefore need a Tomcat from the 9.x series, which is available as a zip file from the Maven coordinates `org.apache.tomcat:tomcat:9.0.76`. Likewise, Mitre is available from `org.mitre:openid-connect-server-webapp:1.3.4`. We simply need to unzip Tomcat, and unzip Mitre into its `webapps` folder. We also need to update Tomcat with the JAXB standalone libraries (see full example code). + + +[source,xml] +---- + + + maven-antrun-plugin + + + + run + + + + Replacing in ${tomcat.dir} + + + + + + + + + + + + + + + + + + + + + + + + + + +---- + +Out of the box Mitre runs on HTTP, but since we're using HTTPS instead we need to configure it to run on HTTPS using the `server-config.xml` file. We also need to tell it about the exact callback URL that we discussed above (`http://localhost:8080/openid-client/Callback`), which can be done in `clients.sql`. Tomcat has to be configured to run on HTTPS as well, which requires updating `server.xml` and providing it with a keystore. + +Tomcat, and with it Mitre, can be started by executing `[tomcat dir]/bin/startup.sh`. + +==== Test the application + +:app-name: restOpenIdConnectAuth +include::partial$test-github.adoc[] + +[source] +---- + +user : true +[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 22.324 s - in jakartaee.examples.focused.security.restopenidconnectauth.RestOpenIdConnectAuthIT +---- + +Let's take a quick look at the actual test: + +[source,java] +---- +@RunWith(Arquillian.class) +@RunAsClient +public class RestOpenIdConnectAuthIT extends ITBase { + + @ArquillianResource + private URL baseUrl; + + /** + * Test the call to a protected REST service + * + * @throws Exception when a serious error occurs. + */ + @RunAsClient + @Test + public void testRestCall() throws Exception { + HtmlPage page = webClient.getPage(baseUrl + "/rest/resource"); <1> + + // Authenticate with the OpenId Provider using the + // username and password for a default user + page.getElementById("j_username") + .setAttribute("value", "user"); + + page.getElementById("j_password") + .setAttribute("value", "password"); <2> + + // Submit + HtmlPage confirmationPage = + page.getElementByName("submit") + .click(); <3> + + // Confirm + TextPage originalResource = + confirmationPage.getElementByName("authorize") + .click(); <4> + + System.out.println(originalResource.getContent()); + } +} +---- + +include::partial$inspect-app.adoc[] + +After the test requests our protected resource at "/rest/resource" (1), the OpenID Connect authentication mechanism redirects to Mitre, which will respond with a login page. The test programmically sets the fields `j_username` and `j_password`, (2) and then clicks submits (3). After confirming (4), Mitre will redirect the test code back to the `/Callback` URL, which will redirect back to the original resource at "/rest/resource". + + + + + + + +== Securing an endpoint with Basic authentication and an LDAP identity store + +In the following example, we'll secure a REST endpoint using Basic authentication and the LDAP identity store that is provided by Jakarta Security. + +You'll learn how to: + +include::partial$list-item-learn-security-constraints.adoc[] +include::partial$list-item-learn-basic-authentication.adoc[] +. Use the provided https://jakarta.ee/specifications/security/3.0/apidocs/jakarta.security/jakarta/security/enterprise/identitystore/ldapidentitystoredefinition[LdapIdentityStoreDefinition,role=external,window=_blank] +. Populate and configure the identity store +include::partial$list-item-learn-security-context.adoc[] + + +=== Write the application + +include::partial$rest-resource-class.adoc[] + +==== Declare the authentication mechanism and identity store + +[source,java] +---- +@ApplicationScoped +@BasicAuthenticationMechanismDefinition( + realmName = "basicAuth" +) +@LdapIdentityStoreDefinition( + url = "ldap://localhost:40000", + callerBaseDn = "ou=caller,dc=jakartaee", + groupSearchBase = "ou=group,dc=jakartaee", + groupSearchFilter = "(&(member=%s)(objectclass=groupofnames))" +) +@ApplicationPath("/rest") +public class ApplicationConfig extends Application { + +---- + +include::partial$declare-authentication-mechanism.adoc[] + +Likewise, to declare the usage of a specific identity store, Jakarta EE provides `[XYZ]StoreDefinition` annotations. + +The annotations can be put on any bean, but in a REST application it fits particularly well on the `Application` subclass that also declares the path for REST resources. + +You can use the provided `@LdapIdentityStoreDefinition` with any authentication mechanism that validates username/password credentials. LDAP structures are very open-ended, and there's a lot of possible ways to model callers, their passwords, and their groups. We'll present one way here, where we'll define a `caller.jakartaee` object, that contains the caller name and password, and a `group.jakartaee` object that contains the group name and a list of all callers in that group. + +For this structure we need 3 attributes to be defined: + +. `callerBaseDn` - Used for credential validation using "direct binding", with the default caller name being "uid". +. `groupSearchBase` - The object root used to search for groups of the caller +. `groupSearchFilter` - The subtree to search for groups + + + +==== Populating the identity store + +In order to use the identity store, we need to put some data in an LDAP server. The following code shows one way how to do that: + +[source,java] +---- +@ApplicationScoped +@BasicAuthenticationMechanismDefinition( + realmName = "basicAuth" +) +@LdapIdentityStoreDefinition( + url = "ldap://localhost:40000", + callerBaseDn = "ou=caller,dc=jakartaee", + groupSearchBase = "ou=group,dc=jakartaee", + groupSearchFilter = "(&(member=%s)(objectclass=groupofnames))" +) +@DeclareRoles("user") +@ApplicationPath("/rest") +public class ApplicationConfig extends Application { + + private InMemoryDirectoryServer directoryServer; + + public void onStart(@Observes @Initialized(ApplicationScoped.class) Object applicationContext) { + try { + InMemoryDirectoryServerConfig config = new InMemoryDirectoryServerConfig("dc=jakartaee"); + config.setListenerConfigs( + new InMemoryListenerConfig("myListener", null, 40000, null, null, null)); + + directoryServer = new InMemoryDirectoryServer(config); + + directoryServer.importFromLDIF(true, + new LDIFReader(new ByteArrayInputStream(""" + + # Define caller.jakartaee and group.jakartaee structure + + dn: dc=jakartaee + objectclass: top + objectclass: dcObject + objectclass: organization + dc: jakartaee + o: jakartaee + + dn: ou=caller,dc=jakartaee + objectclass: top + objectclass: organizationalUnit + ou: caller + + dn: ou=group,dc=jakartaee + objectclass: top + objectclass: organizationalUnit + ou: group + + + # Add caller john:secret1 and group user with member john + + dn: uid=john,ou=caller,dc=jakartaee + objectclass: top + objectclass: uidObject + objectclass: person + uid: john + cn: John Smith + sn: John + userPassword: secret1 + + dn: cn=user,ou=group,dc=jakartaee + objectclass: top + objectclass: groupOfNames + cn: user + member: uid=john,ou=caller,dc=jakartaee + + """.getBytes()))); + + directoryServer.startListening(); + } catch (LDAPException e) { + throw new IllegalStateException(e); + } + } + +} +---- + +The code above uses an in-memory LDAP server called Unboundid that we start on port 40000. We populate it using embedded LDIF, which is a popular format to configure LDAP servers. + +In-depth explanation of LDAP itself is beyond the scope of this tutorial, but we'll briefly explain the process here. When a caller authenticates with username "john" and password "secret1", our LDAP identity store will construct the full name "uid=john,ou=caller,dc=jakartaee" using `callerNameAttribute` ("uid" as a default), and `callerBaseDn` ("ou=caller,dc=jakartaee" here). The store then uses the LDAP 'Bind' operation and directly attempts to "log in" as that user to the LDAP server. Unlike the Database identity store, the LDAP store doesn't look up and compare the passwords. If the aforementioned login succeeds, the credentials are assumed to be correct. + +The LDAP store will then search for groups using the `javax.naming.directory.DirContext.search()` method, with the `groupSearchBase` value ("ou=group,dc=jakartaee") and the formatted value from `groupSearchFilter` ("(&(member=uid=john,ou=caller,dc=jakartaee)(objectclass=groupofnames))") as parameters. The LDAP server will subsequently return "cn=user,ou=group,dc=jakartaee" for our example. From this the value of `groupNameAttribute` (defaults to "cn") is taken, which resolves to "user" here. + +==== Test the application + +:app-name: restBasicAuthLdapStore +include::partial$test-github.adoc[] + +[source] +---- +john : true +[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 8.247 s - in jakartaee.examples.focused.security.restBasicAuthLdapStore.RestBasicAuthLdapStoreIT +---- + +The test itself is basically the same as that for the <> example. + + + + +== Securing an endpoint with Custom Form authentication + +In the following example, we'll secure a REST endpoint using Custom Form authentication. + +You'll learn how to: + +include::partial$list-item-learn-security-constraints.adoc[] +. Use the https://jakarta.ee/specifications/security/3.0/apidocs/jakarta.security/jakarta/security/enterprise/authentication/mechanism/http/customformauthenticationmechanismdefinition[Custom Form authentication mechanism,role=external,window=_blank] +. Use Jakarta Faces and Jakarta Validation to customize the Form used for Form authentication +. How to define (and implicitly set) a custom https://jakarta.ee/specifications/security/3.0/apidocs/jakarta.security/jakarta/security/enterprise/identitystore/package-summary.html[identity store,role=external,window=_blank] +include::partial$list-item-learn-security-context.adoc[] + +=== Write the application + +include::partial$rest-resource-class.adoc[] + +==== Declare the security constraints + +include::partial$declare-security-constraints.adoc[] + +==== Declare the authentication mechanism + +[source,java] +---- +@ApplicationScoped +@CustomFormAuthenticationMechanismDefinition( + loginToContinue = @LoginToContinue( + loginPage="/login.xhtml", + errorPage="" + ) +) +@DeclareRoles({ "user", "caller" }) +@FacesConfig +@ApplicationPath("/rest") +public class ApplicationConfig extends Application { + +} +---- + +include::partial$declare-authentication-mechanism.adoc[] + +Contrary to the Basic HTTP authentication mechanism, the Form authentication mechanism allows us to customize the login dialog (the process between the caller and the authentication mechanism) and to keep track of the authenticated session on the server (using a cookie). This also allows us to logout, something that for unknown reasons has never been specified for Basic HTTP authentication. + +Contrary to the regular Form authentication mechanism, the Custom Form authentication mechanism lets us customize the login dialog even more by having the ability to execute custom code between the postback of a login form and the form authentication mechanism taking the provided credentials. + +To use this authentication method, we need to designate a path to a resource that is relative to our application. The authentication mechanism will redirect the caller to this resource when authentication is required. The resource can be anything, but a postback should eventually lead to some code being executed that continues the authentication dialog. For example a plain .html file or .jsp file combined with a Filter, or a Faces view with a backing bean. + + +==== Define the authentication mechanism's view and backing code + +For this example we'll use a Faces view with a backing bean: + +[source,xml] +---- + + + + Login to continue + + +

Login to continue

+ + + + +
+ + +
+
+ + +
+
+ +
+ + + +---- + +[source,java] +---- +@Named +@RequestScoped +public class LoginBacking { + + @Inject + private SecurityContext securityContext; + + @Inject + private FacesContext facesContext; + + @NotNull + @Size(min = 3, max = 15, message="Username must be between 3 and 15 characters") + private String username; + + @NotNull + @Size(min = 5, max = 50, message="Password must be between 5 and 50 characters") + private String password; + + public void login() { + switch ( + // Continue the authentication dialog manually by invoking the authenticate() + // method. The form authentication picks this up, just like a post to j_security does. + securityContext.authenticate( + getRequest(), + getResponse(), + withParams() + .credential(new UsernamePasswordCredential(username, new Password(password))))) { + + case SEND_CONTINUE: + + // Authentication mechanism has send a redirect, should not + // send anything to response from Faces now. + facesContext.responseComplete(); + return; + + case SEND_FAILURE: + + addError("Login failed"); + return; + + default: + } + } + + // getters/setters + utility methods omitted +} +---- + +The view itself is quite similar to the HTML page we used for the form in <>. The main difference is bindings of the form fields to a (CDI) backing bean. The bean side of the binding has Jakarta Validation constraints applied to it; this allows for fine-grained validation of some general requirements of the credentials without actually attempting authentication. + +If this initial validation passes, we arrive in the `login()` method. For our example the only thing we need to do here is signaling that we want to continue the authentication dialog (the process or interaction between the caller and the authentication mechanism), and when doing so provide the credentials that we earlier obtained in a custom way. + +We have two important outcomes to handle. `SEND_CONTINUE` effectively means the credentials were validated successfully, and the caller is therefore directed to the resource that was originally requested. `SEND_FAILURE` means the opposite; the credentials were not validated successfully. By just returning from our callback method in the last case the form will be redisplayed, albeit with the error message added. + +NOTE: `NOT_DONE` and `SUCCESS` are two other outcomes, but we don't have to handle them here. `NOT_DONE` only applies to pre-emptive authentication, but we're doing explicit (forced, mandatory) authentication here. `SUCCESS` means we can go ahead and render the page, which is exactly what happens if we don't do anything. + +See xref:web:webapp/webapp.adoc#_getting_started_with_web_applications[Getting Started with Web Applications] for more information on running `.xhtml` files and their backing beans. + + + +==== Define the identity store + +Finally, let's define a basic identity store that the security system can use to validate provided credentials for Form authentication: + +[source,java] +----- +@ApplicationScoped +public class CustomIdentityStore implements IdentityStore { + + public CredentialValidationResult validate(UsernamePasswordCredential usernamePasswordCredential) { + if (usernamePasswordCredential.compareTo("john", "secret1")) { + return new CredentialValidationResult("john", Set.of("user", "caller")); + } + + return INVALID_RESULT; + } + +} +----- + +This identity store only validates the single identity (user) "john", with password "secret1" and roles "user" and "caller". Defining this kind of identity store is often the simplest way to get started. Note that Jakarta Security doesn't define a simple identity store out of the box, because there are questions about whether that would promote security best practices. + +include::partial$identity-store-installed.adoc[] + +==== Test the application + +:app-name: restCustomFormAuthCustomStore +include::partial$test-github.adoc[] + +[source] +---- +john : true +[INFO] Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 9.272 s - in jakartaee.examples.focused.security.restCustomFormAuthCustomStore.RestCustomFormAuthCustomStoreIT +---- + +Let's take a quick look at the actual test: + +[source,java] +---- +@RunWith(Arquillian.class) +@RunAsClient +public class RestCustomFormAuthCustomStoreIT extends ITBase { + + @ArquillianResource + private URL baseUrl; + + /** + * Test the call to a protected REST service + * + * @throws Exception when a serious error occurs. + */ + @RunAsClient + @Test + public void testRestCall() throws Exception { + HtmlPage loginPage = webClient.getPage(baseUrl + "/rest/resource"); + System.out.println(loginPage.asXml()); + + HtmlForm form = loginPage.getForms() + .get(0); + + form.getInputByName("form:username") + .setValueAttribute("john"); + + form.getInputByName("form:password") + .setValueAttribute("secret1"); + + TextPage page = form.getInputByValue("Login") + .click(); + + System.out.println(page.getContent()); + } +} +---- + +include::partial$inspect-app.adoc[] + +The test first sends a request here to the protected resource, and the server responds with the rendered version of the Faces view form we defined above. Using the `HtmlUnit` API, it's easy to navigate the HTML DOM, fill out the username and password in the form, and programmatically click the `Login` button. The form posts back to the same URL it was requested from. Faces will detect this postback and will orchestrate the validation using Jakarta Validation and invoking the CDI based backing bean. + + diff --git a/src/main/antora/modules/security/partials/authentication-mechanism-installed.adoc b/src/main/antora/modules/security/partials/authentication-mechanism-installed.adoc new file mode 100644 index 00000000..251cad00 --- /dev/null +++ b/src/main/antora/modules/security/partials/authentication-mechanism-installed.adoc @@ -0,0 +1 @@ +The authentication mechanism is installed and used by the security system just by the virtue of being there; it picks up all enabled CDI beans that implement https://jakarta.ee/specifications/security/3.0/apidocs/jakarta.security/jakarta/security/enterprise/authentication/mechanism/http/httpauthenticationmechanism[HttpAuthenticationMechanism,role=external,window=_blank]. Such beans can be enabled by the security system itself (following some configuration annotation), or can be programmatically added using the appropriate CDI APIs. Where the bean comes from doesn't matter for Jakarta Security, only the fact that it's there. diff --git a/src/main/antora/modules/security/partials/declare-authentication-mechanism.adoc b/src/main/antora/modules/security/partials/declare-authentication-mechanism.adoc new file mode 100644 index 00000000..607f81b0 --- /dev/null +++ b/src/main/antora/modules/security/partials/declare-authentication-mechanism.adoc @@ -0,0 +1,3 @@ +To declare the usage of a specific authentication mechanism, Jakarta EE provides `[XYZ]MechanismDefinition` annotations. Such an annotation is picked up by the security system, and in response to it a CDI bean that implements the https://jakarta.ee/specifications/security/3.0/apidocs/jakarta.security/jakarta/security/enterprise/authentication/mechanism/http/httpauthenticationmechanism[HttpAuthenticationMechanism,role=external,window=_blank] is enabled for it. + +The annotation can be put on any bean, but in a REST application it fits particularly well on the `Application` subclass because it also declares the path for REST resources. \ No newline at end of file diff --git a/src/main/antora/modules/security/partials/declare-security-constraints.adoc b/src/main/antora/modules/security/partials/declare-security-constraints.adoc new file mode 100644 index 00000000..f3ad9e73 --- /dev/null +++ b/src/main/antora/modules/security/partials/declare-security-constraints.adoc @@ -0,0 +1,28 @@ +Next we'll define the security constraints in `web.xml`, which tell the security system that access to a given URL or URL pattern is protected, and hence authentication is required: + +[source,xml] +---- + + + + + + protected + /rest/* + + + user + + + + +---- + +This XML essentially says that to access any URL that starts with "/rest" requires the caller to have the role "user". Roles are opaque strings; merely identifiers. It's fully up to the application how broad or fine-grained they are. + +NOTE: In Jakarta EE, internally these XML constraints are transformed into `Permission` instances and made available via a specific type of permission store. Knowledge about this transformation is only needed for very advanced use cases. + +NOTE: The observant reader may wonder if XML is really the only option here, given the strong feelings that exist in parts of the community around XML. The answer is yes and no. Jakarta EE does define the https://jakarta.ee/specifications/annotations/2.1/annotations-spec-2.1.html#jakarta-annotation-security-rolesallowed[@RolesAllowed,role=external,window=_blank] annotation that could be used to replace the XML shown above, but only the legacy Enterprise Beans has specified a behaviour for this when put on an Enterprise Bean. Jakarta REST has done no such thing, although the https://microprofile.io/project/eclipse/microprofile-jwt-auth/spec/src/main/asciidoc/configuration.asciidoc[JWT API in MicroProfile,role=external,window=_blank] has defined this for REST resources. In Jakarta EE, however, this remains a vendor-specific extension. There are also a number of https://jakarta.ee/specifications/servlet/6.0/jakarta-servlet-spec-6.0.html#programmatic-security-policy-configuration[annotations and APIs,role=external,window=_blank] in Jakarta EE to set these kinds of constraints for individual Servlets, but those won't help us much either here. diff --git a/src/main/antora/modules/security/partials/identity-store-installed.adoc b/src/main/antora/modules/security/partials/identity-store-installed.adoc new file mode 100644 index 00000000..0da028df --- /dev/null +++ b/src/main/antora/modules/security/partials/identity-store-installed.adoc @@ -0,0 +1 @@ +The identity store is installed and used by the security system just by the virtue of being there; it picks up all enabled CDI beans that implement https://jakarta.ee/specifications/security/3.0/apidocs/jakarta.security/jakarta/security/enterprise/identitystore/identitystore[IdentityStore,role=external,window=_blank]. Such beans can be enabled by the security system itself (following some configuration annotation), or can be programmatically added using the appropriate CDI APIs. Where the bean comes from doesn't matter for Jakarta Security, only the fact that it's there. \ No newline at end of file diff --git a/src/main/antora/modules/security/partials/inspect-app.adoc b/src/main/antora/modules/security/partials/inspect-app.adoc new file mode 100644 index 00000000..92b68f6d --- /dev/null +++ b/src/main/antora/modules/security/partials/inspect-app.adoc @@ -0,0 +1,3 @@ +The test starts a server and deploys the output of the build process (a .war file) to it. The test runs in the integration test phase, rather than the unit test phase, to make sure this build output is available when it runs. The test then sends a request to the server using the provided HtmlUnit `webClient`. Note that the `webClient` can be used for any other HTTP requests your test requires. + +If you want to inspect the app yourself, you can manually deploy the WAR file (`security/{app-name}/target/{app-name}.war`) to the server of your choice (e.g. https://projects.eclipse.org/projects/ee4j.glassfish[GlassFish 7,role=external,window=_blank]), and request the URL via a browser or a commandline util such as `curl`. \ No newline at end of file diff --git a/src/main/antora/modules/security/partials/list-item-learn-basic-authentication.adoc b/src/main/antora/modules/security/partials/list-item-learn-basic-authentication.adoc new file mode 100644 index 00000000..c18ce357 --- /dev/null +++ b/src/main/antora/modules/security/partials/list-item-learn-basic-authentication.adoc @@ -0,0 +1 @@ +. Use the provided https://jakarta.ee/specifications/security/3.0/apidocs/jakarta.security/jakarta/security/enterprise/authentication/mechanism/http/basicauthenticationmechanismdefinition[BasicAuthenticationMechanismDefinition,role=external,window=_blank] \ No newline at end of file diff --git a/src/main/antora/modules/security/partials/list-item-learn-security-constraints.adoc b/src/main/antora/modules/security/partials/list-item-learn-security-constraints.adoc new file mode 100644 index 00000000..59b45630 --- /dev/null +++ b/src/main/antora/modules/security/partials/list-item-learn-security-constraints.adoc @@ -0,0 +1 @@ +. https://jakarta.ee/specifications/servlet/6.0/jakarta-servlet-spec-6.0.html#specifying-security-constraints[Define security constraints,role=external,window=_blank] \ No newline at end of file diff --git a/src/main/antora/modules/security/partials/list-item-learn-security-context.adoc b/src/main/antora/modules/security/partials/list-item-learn-security-context.adoc new file mode 100644 index 00000000..15517922 --- /dev/null +++ b/src/main/antora/modules/security/partials/list-item-learn-security-context.adoc @@ -0,0 +1 @@ +. Use the Jakarta Security https://jakarta.ee/specifications/security/3.0/apidocs/jakarta.security/jakarta/security/enterprise/securitycontext[SecurityContext,role=external,window=_blank] \ No newline at end of file diff --git a/src/main/antora/modules/security/partials/rest-resource-class.adoc b/src/main/antora/modules/security/partials/rest-resource-class.adoc new file mode 100644 index 00000000..e773afd5 --- /dev/null +++ b/src/main/antora/modules/security/partials/rest-resource-class.adoc @@ -0,0 +1,27 @@ +Let's start with defining a simple REST resource class for a `/rest/resource` endpoint: + +[source,java] +---- +@Path("/resource") +@RequestScoped +public class Resource { + + @Inject + private SecurityContext securityContext; + + @GET + @Produces(TEXT_PLAIN) + public String getCallerAndRole() { + return + securityContext.getCallerPrincipal().getName() + " : " + + securityContext.isCallerInRole("user"); + } + +} +---- + +This resource uses the injected Jakarta EE https://jakarta.ee/specifications/security/3.0/apidocs/jakarta.security/jakarta/security/enterprise/securitycontext[SecurityContext,role=external,window=_blank] to obtain access to the current authenticated caller, which is represented by a `Principal` instance. + +If this resource were available to unauthenticated callers, `getCallerPrincipal()` would return `null` for unauthenticated requests, so we'd have to check for `null`. Our example, however, requires authentication for this resource, so we can skip that check. + +NOTE: There is a Jakarta REST-specific type that is also named https://jakarta.ee/specifications/restful-ws/3.1/apidocs/jakarta.ws.rs/jakarta/ws/rs/core/securitycontext[SecurityContext,role=external,window=_blank] and has similar methods as the ones we used here. From the Jakarta EE perspective, that is a discouraged type and the Jakarta Security version is to be preferred. \ No newline at end of file diff --git a/src/main/antora/modules/security/partials/simple-identity-store.adoc b/src/main/antora/modules/security/partials/simple-identity-store.adoc new file mode 100644 index 00000000..676387d7 --- /dev/null +++ b/src/main/antora/modules/security/partials/simple-identity-store.adoc @@ -0,0 +1,23 @@ +Finally, let's define a simple identity store that the security system can use to validate provided credentials for Basic authentication: + +[source,java] +---- +@ApplicationScoped +public class TestIdentityStore implements IdentityStore { + + public CredentialValidationResult validate(UsernamePasswordCredential usernamePasswordCredential) { + if (usernamePasswordCredential.compareTo("john", "secret1")) { + return new CredentialValidationResult("john", Set.of("user", "caller")); + } + + return INVALID_RESULT; + } + +} +---- + +This identity store only validates the single identity (user) "john", with password "secret1" and roles "user" and "caller". Defining this kind of identity store is often the simplest way to get started. + +NOTE: Jakarta Security doesn't provide a simple identity store out of the box. The reason is that everything in Jakarta Security promotes best practices, and it's not clear if a simple identity store fits in with those best practices. + +include::partial$identity-store-installed.adoc[] \ No newline at end of file diff --git a/src/main/antora/modules/security/partials/test-github.adoc b/src/main/antora/modules/security/partials/test-github.adoc new file mode 100644 index 00000000..5b71ef8e --- /dev/null +++ b/src/main/antora/modules/security/partials/test-github.adoc @@ -0,0 +1,10 @@ +It's now time to test our application. A ready-to-test version is available from the Jakarta EE Examples project at https://github.com/eclipse-ee4j/jakartaee-examples. + +Download or clone this repo, then cd into the `focused` folder and execute: + +[source,subs="attributes+,+replacements"] +---- +mvn clean install -pl :{app-name} +---- + +This will run a test associated with the project, printing something like the following: \ No newline at end of file diff --git a/src/main/antora/modules/supporttechs/nav.adoc b/src/main/antora/modules/supporttechs/nav.adoc new file mode 100644 index 00000000..1dba5b7c --- /dev/null +++ b/src/main/antora/modules/supporttechs/nav.adoc @@ -0,0 +1,5 @@ +.Jakarta EE Supporting Technologies + +* xref:resources/resources.adoc[] + +* xref:connectorexample/connectorexample.adoc[] diff --git a/src/main/asciidoc/batch-processing/batch-processing.adoc b/src/main/antora/modules/supporttechs/pages/batch-processing/batch-processing.adoc similarity index 91% rename from src/main/asciidoc/batch-processing/batch-processing.adoc rename to src/main/antora/modules/supporttechs/pages/batch-processing/batch-processing.adoc index 5faf7b52..db574973 100644 --- a/src/main/asciidoc/batch-processing/batch-processing.adoc +++ b/src/main/antora/modules/supporttechs/pages/batch-processing/batch-processing.adoc @@ -1,4 +1,6 @@ -= Batch Processing += Jakarta Batch + +include::ROOT:partial$not_updated.adoc[] This chapter describes Jakarta Batch, which provides support for defining, implementing, and running batch jobs. Batch jobs are tasks that can be executed without user interaction. diff --git a/src/main/asciidoc/batch-processing/batch-processing001.adoc b/src/main/antora/modules/supporttechs/pages/batch-processing/batch-processing001.adoc similarity index 85% rename from src/main/asciidoc/batch-processing/batch-processing001.adoc rename to src/main/antora/modules/supporttechs/pages/batch-processing/batch-processing001.adoc index e7ff1066..e6ba47ab 100644 --- a/src/main/asciidoc/batch-processing/batch-processing001.adoc +++ b/src/main/antora/modules/supporttechs/pages/batch-processing/batch-processing001.adoc @@ -44,11 +44,11 @@ Batch frameworks enable chunk steps to bookmark their progress using checkpoints A chunk step that is interrupted can be restarted from the last checkpoint. The input retrieval and output writing parts of a chunk step save their current position after the processing of each chunk, and can recover it when the step is restarted. -<> shows the three parts of two steps in a batch job. +<<_chunk_steps_in_a_batch_job>> shows the three parts of two steps in a batch job. -[[chunk-steps-in-a-batch-job]] +[[_chunk_steps_in_a_batch_job]] .Chunk Steps in a Batch Job -image::jakartaeett_dt_058.svg["This figure shows a batch job that contains two chunk steps: step A and step B. Step A has the three parts of a chunk-oriented step: input retrieval A, business processing A, and output writing A. Step B also has the three parts of a chunk-oriented step: input retrieval B, business processing B, and output writing B."] +image::common:jakartaeett_dt_058.svg["This figure shows a batch job that contains two chunk steps: step A and step B. Step A has the three parts of a chunk-oriented step: input retrieval A, business processing A, and output writing A. Step B also has the three parts of a chunk-oriented step: input retrieval B, business processing B, and output writing B."] For example, the phone billing application consists of two chunk steps. @@ -86,11 +86,11 @@ Decision elements use the exit status of the previous step to determine the next Decision elements set the status of the batch job when terminating it. Like a step, a batch job can terminate successfully, be interrupted, or fail. -<> shows an example of a job that contains chunk steps, task steps and a decision element. +<<_steps_and_decision_elements_in_a_job>> shows an example of a job that contains chunk steps, task steps and a decision element. -[[steps-and-decision-elements-in-a-job]] +[[_steps_and_decision_elements_in_a_job]] .Steps and Decision Elements in a Job -image::jakartaeett_dt_059.svg["This figure shows a batch job that contains two chunk steps, a task step and a decision element. The job starts with chunk step A, continues with chunk step B, and then decision element D evaluates condition 1. The condition is based on the status of step B. If condition 1 is true, the job terminates; otherwise the job continues with step C and then the job ends."] +image::common:jakartaeett_dt_059.svg["This figure shows a batch job that contains two chunk steps, a task step and a decision element. The job starts with chunk step A, continues with chunk step B, and then decision element D evaluates condition 1. The condition is based on the status of step B. If condition 1 is true, the job terminates; otherwise the job continues with step C and then the job ends."] === Batch Framework Functionality diff --git a/src/main/asciidoc/batch-processing/batch-processing002.adoc b/src/main/antora/modules/supporttechs/pages/batch-processing/batch-processing002.adoc similarity index 80% rename from src/main/asciidoc/batch-processing/batch-processing002.adoc rename to src/main/antora/modules/supporttechs/pages/batch-processing/batch-processing002.adoc index 9e8fa39a..0962c4c5 100644 --- a/src/main/asciidoc/batch-processing/batch-processing002.adoc +++ b/src/main/antora/modules/supporttechs/pages/batch-processing/batch-processing002.adoc @@ -60,7 +60,7 @@ A batch job can contain one or more of the following elements: * Decision elements -Steps are described in <>, and can be chunk-oriented or task-oriented. +Steps are described in xref:batch-processing/batch-processing.adoc#_introduction_to_batch_processing[Introduction to Batch Processing], and can be chunk-oriented or task-oriented. Chunk-oriented steps can be partitioned steps. In a partitioned chunk step, the processing of one item does not depend on other items, so these steps can run in more than one thread. @@ -80,28 +80,28 @@ Jobs and steps can have a number of properties associated with them. You define properties in the job definition file, and batch artifacts access these properties using context objects from the batch runtime. Using properties in this manner enables you to decouple static parameters of the job from the business logic and to reuse batch artifacts in different job definition files. -Specifying properties is described in <>, and accessing properties in batch artifacts is described in <>. +Specifying properties is described in xref:batch-processing/batch-processing.adoc#_using_the_job_specification_language[Using the Job Specification Language], and accessing properties in batch artifacts is described in xref:batch-processing/batch-processing.adoc#_creating_batch_artifacts[Creating Batch Artifacts]. Jakarta EE applications can also pass parameters to a job when they submit it to the batch runtime. This enables you to specify dynamic parameters that are only known at runtime. Parameters are also necessary for partitioned steps, since each partition needs to know, for example, what range of items to process. -Specifying parameters when submitting jobs is described in <>. -Specifying parameters for partitioned steps and accessing them in batch artifacts is demonstrated in <>. +Specifying parameters when submitting jobs is described in xref:batch-processing/batch-processing.adoc#_submitting_jobs_to_the_batch_runtime[Submitting Jobs to the Batch Runtime]. +Specifying parameters for partitioned steps and accessing them in batch artifacts is demonstrated in xref:batch-processing/batch-processing.adoc#_the_phonebilling_example_application[The phonebilling Example Application]. === Job Instances and Job Executions A job definition can have multiple instances, each with different parameters. A job execution is an attempt to run a job instance. -The batch runtime maintains information about job instances and job executions, as described in <>. +The batch runtime maintains information about job instances and job executions, as described in xref:batch-processing/batch-processing.adoc#_checking_the_status_of_a_job[Checking the Status of a Job]. === Batch and Exit Status The state of jobs, steps, splits, and flows is represented in the batch runtime as a batch status value. -Batch status values are listed <>. +Batch status values are listed <<_batch_status_values>>. They are represented as strings. -[[batch-status-values]] +[[_batch_status_values]] .Batch Status Values [width="50%",cols="15%,35%"] |=== @@ -122,9 +122,9 @@ They are represented as strings. |`ABANDONED` |The job was marked abandoned. |=== -Jakarta EE applications can submit jobs and access the batch status of a job using the `JobOperator` interface, as described in <>. -Job definition files can refer to batch status values using the Job Specification Language (JSL), as described in <>. -Batch artifacts can access batch status values using context objects, as described in <>. +Jakarta EE applications can submit jobs and access the batch status of a job using the `JobOperator` interface, as described in xref:batch-processing/batch-processing.adoc#_submitting_jobs_to_the_batch_runtime[Submitting Jobs to the Batch Runtime]. +Job definition files can refer to batch status values using the Job Specification Language (JSL), as described in xref:batch-processing/batch-processing.adoc#_using_the_job_specification_language[Using the Job Specification Language]. +Batch artifacts can access batch status values using context objects, as described in xref:batch-processing/batch-processing.adoc#_using_the_context_objects_from_the_batch_runtime[Using the Context Objects from the Batch Runtime]. For flows, the batch status is that of its last step. For splits, the batch status is the following: diff --git a/src/main/asciidoc/batch-processing/batch-processing003.adoc b/src/main/antora/modules/supporttechs/pages/batch-processing/batch-processing003.adoc similarity index 100% rename from src/main/asciidoc/batch-processing/batch-processing003.adoc rename to src/main/antora/modules/supporttechs/pages/batch-processing/batch-processing003.adoc diff --git a/src/main/asciidoc/batch-processing/batch-processing004.adoc b/src/main/antora/modules/supporttechs/pages/batch-processing/batch-processing004.adoc similarity index 95% rename from src/main/asciidoc/batch-processing/batch-processing004.adoc rename to src/main/antora/modules/supporttechs/pages/batch-processing/batch-processing004.adoc index 47a2ce42..8a626729 100644 --- a/src/main/asciidoc/batch-processing/batch-processing004.adoc +++ b/src/main/antora/modules/supporttechs/pages/batch-processing/batch-processing004.adoc @@ -69,7 +69,7 @@ For example: The `listener` element specifies a batch artifact whose methods are invoked before and after the execution of the job. The batch artifact is an implementation of the `jakarta.batch.api.listener.JobListener` interface. -See <> for an example of a job listener implementation. +See xref:batch-processing/batch-processing.adoc#_the_listener_batch_artifacts[The Listener Batch Artifacts] for an example of a job listener implementation. The first `step`, `flow`, or `split` element inside the `job` element executes first. @@ -91,7 +91,7 @@ For chunk steps, the batch artifacts for these listeners can be implementations + For task steps, the batch artifact for these listeners must be an implementation of the `StepListener` interface. + -See <> for an example of an item processor listener implementation. +See xref:batch-processing/batch-processing.adoc#_the_listener_batch_artifacts[The Listener Batch Artifacts] for an example of an item processor listener implementation. * One `partition` element (optional). + @@ -145,9 +145,9 @@ The following is an example of a task step: ==== The chunk Element The `chunk` element is a child of the `step` element for chunk-oriented steps. -The attributes of this element are listed in <>. +The attributes of this element are listed in <<_attributes_of_the_chunk_element>>. -[[attributes-of-the-chunk-element]] +[[_attributes_of_the_chunk_element]] .Attributes of the chunk Element [width="99%",cols="15%,75%,10%"] |=== @@ -284,7 +284,7 @@ The batch runtime invokes this artifact and then uses the information it provide The rest of this section describes the `partition` element in detail and shows two examples of job definition files: one that uses partition properties to specify a range of items for each partition, and one that relies on a `PartitionMapper` implementation to determine partition-specific information. -See <> in <> for a complete example of a partitioned chunk step. +See xref:batch-processing/batch-processing.adoc#_the_phone_billing_chunk_step[The Phone Billing Chunk Step] in xref:batch-processing/batch-processing.adoc#_the_phonebilling_example_application[The phonebilling Example Application] for a complete example of a partitioned chunk step. The `partition` element can contain the following elements. @@ -366,7 +366,7 @@ The `PartitionMapper` implementation dynamically provides the same information a ---- -Refer to <> for an example implementation of the `PartitionMapper` interface. +Refer to xref:batch-processing/batch-processing.adoc#_the_phonebilling_example_application[The phonebilling Example Application] for an example implementation of the `PartitionMapper` interface. === The flow Element diff --git a/src/main/asciidoc/batch-processing/batch-processing005.adoc b/src/main/antora/modules/supporttechs/pages/batch-processing/batch-processing005.adoc similarity index 89% rename from src/main/asciidoc/batch-processing/batch-processing005.adoc rename to src/main/antora/modules/supporttechs/pages/batch-processing/batch-processing005.adoc index 7b10645e..605c4d83 100644 --- a/src/main/asciidoc/batch-processing/batch-processing005.adoc +++ b/src/main/antora/modules/supporttechs/pages/batch-processing/batch-processing005.adoc @@ -7,15 +7,15 @@ This section lists the main batch artifact interfaces, demonstrates how to acces === Batch Artifact Interfaces The following tables list the interfaces that you implement to create batch artifacts. -The interface implementations are referenced from the elements described in <>. +The interface implementations are referenced from the elements described in xref:batch-processing/batch-processing.adoc#_using_the_job_specification_language[Using the Job Specification Language]. -<> lists the interfaces to implement batch artifacts for chunk steps, task steps, and decision elements. +<<_main_batch_artifact_interfaces>> lists the interfaces to implement batch artifacts for chunk steps, task steps, and decision elements. -<> lists the interfaces to implement batch artifacts for partitioned steps. +<<_partition_batch_artifact_interfaces>> lists the interfaces to implement batch artifacts for partitioned steps. -<> lists the interfaces to implement batch artifacts for job and step listeners. +<<_listener_batch_artifact_interfaces>> lists the interfaces to implement batch artifacts for job and step listeners. -[[main-batch-artifact-interfaces]] +[[_main_batch_artifact_interfaces]] .Main Batch Artifact Interfaces [width="99%",cols="15%,15%,70%"] |=== @@ -40,7 +40,7 @@ It is referenced from the `processor` element inside the `chunk` element. It is referenced from the `writer` element inside the `chunk` element. |=== -[[partition-batch-artifact-interfaces]] +[[_partition_batch_artifact_interfaces]] .Partition Batch Artifact Interfaces [width="99%",cols="15%,15%,70%"] |=== @@ -62,7 +62,7 @@ It is referenced from the `collector` element inside the `partition` element. It is referenced from the `analyzer` element inside the `partition` element. |=== -[[listener-batch-artifact-interfaces]] +[[_listener_batch_artifact_interfaces]] .Listener Batch Artifact Interfaces [width="99%",cols="15%,15%,70%"] |=== @@ -156,7 +156,7 @@ For example, the following batch artifact is annotated with `@Dependent`: public class MyItemReaderImpl implements ItemReader { ... } ---- + -For more information on bean archives, see <> in xref:jakarta-contexts-and-dependency-injection-advanced-topics[xrefstyle=full]. +For more information on bean archives, see xref:cdi:cdi-adv/cdi-adv.adoc#_packaging_cdi_applications[Packaging CDI Applications] in xref:cdi:cdi-adv/cdi-adv.adoc#_jakarta_contexts_and_dependency_injection_advanced_topics[Jakarta Contexts and Dependency Injection: Advanced Topics]. [NOTE] Jakarta Contexts and Dependency Injection (CDI) is required in order to access context objects from the batch runtime in batch artifacts. @@ -203,7 +203,7 @@ public class MyItemReaderImpl implements ItemReader { } ---- -See <> for instructions on how to define your batch artifacts to use dependency injection. +See <<_dependency_injection_in_batch_artifacts>> for instructions on how to define your batch artifacts to use dependency injection. [NOTE] ==== diff --git a/src/main/asciidoc/batch-processing/batch-processing006.adoc b/src/main/antora/modules/supporttechs/pages/batch-processing/batch-processing006.adoc similarity index 85% rename from src/main/asciidoc/batch-processing/batch-processing006.adoc rename to src/main/antora/modules/supporttechs/pages/batch-processing/batch-processing006.adoc index 1294b5ce..b20461cc 100644 --- a/src/main/asciidoc/batch-processing/batch-processing006.adoc +++ b/src/main/antora/modules/supporttechs/pages/batch-processing/batch-processing006.adoc @@ -54,4 +54,4 @@ String status = jobExec.getBatchStatus().toString(); The component from which you invoke the batch runtime depends on the architecture of your particular application. For example, you can invoke the batch runtime from an enterprise bean, a servlet, a managed bean, and so on. -See <> and <> for details on how to invoke the batch runtime from a managed bean driven by a Jakarta Faces user interface. +See xref:batch-processing/batch-processing.adoc#_the_webserverlog_example_application[The webserverlog Example Application] and xref:batch-processing/batch-processing.adoc#_the_phonebilling_example_application[The phonebilling Example Application] for details on how to invoke the batch runtime from a managed bean driven by a Jakarta Faces user interface. diff --git a/src/main/asciidoc/batch-processing/batch-processing007.adoc b/src/main/antora/modules/supporttechs/pages/batch-processing/batch-processing007.adoc similarity index 100% rename from src/main/asciidoc/batch-processing/batch-processing007.adoc rename to src/main/antora/modules/supporttechs/pages/batch-processing/batch-processing007.adoc diff --git a/src/main/asciidoc/batch-processing/batch-processing008.adoc b/src/main/antora/modules/supporttechs/pages/batch-processing/batch-processing008.adoc similarity index 94% rename from src/main/asciidoc/batch-processing/batch-processing008.adoc rename to src/main/antora/modules/supporttechs/pages/batch-processing/batch-processing008.adoc index add6c215..399db509 100644 --- a/src/main/asciidoc/batch-processing/batch-processing008.adoc +++ b/src/main/antora/modules/supporttechs/pages/batch-processing/batch-processing008.adoc @@ -1,6 +1,6 @@ == The webserverlog Example Application -The `webserverlog` example application, located in the `_tut-install_/examples/batch/webserverlog/` directory, demonstrates how to use the batch framework in Jakarta EE to analyze the log file from a web server. +The `webserverlog` example application, located in the `_jakartaee-examples_/tutorial/batch/webserverlog/` directory, demonstrates how to use the batch framework in Jakarta EE to analyze the log file from a web server. This example application reads a log file and finds what percentage of page views from tablet devices are product sales. === Architecture of the webserverlog Example Application @@ -335,14 +335,14 @@ You can use either NetBeans IDE or Maven to build, package, deploy, and run the ==== To Run the webserverlog Example Application Using NetBeans IDE -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . From the File menu, choose Open Project. . In the Open Project dialog box, navigate to: + ---- -tut-install/examples/batch +jakartaee-examples/tutorial/batch ---- . Select the `webserverlog` folder. @@ -359,12 +359,12 @@ http://localhost:8080/webserverlog/ ==== To Run the webserverlog Example Application Using Maven -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . In a terminal window, go to: + ---- -tut-install/examples/batch/webserverlog/ +jakartaee-examples/tutorial/batch/webserverlog/ ---- . Enter the following command to deploy the application: diff --git a/src/main/asciidoc/batch-processing/batch-processing009.adoc b/src/main/antora/modules/supporttechs/pages/batch-processing/batch-processing009.adoc similarity index 94% rename from src/main/asciidoc/batch-processing/batch-processing009.adoc rename to src/main/antora/modules/supporttechs/pages/batch-processing/batch-processing009.adoc index 1fe7b0a2..cbf06c43 100644 --- a/src/main/asciidoc/batch-processing/batch-processing009.adoc +++ b/src/main/antora/modules/supporttechs/pages/batch-processing/batch-processing009.adoc @@ -1,6 +1,6 @@ == The phonebilling Example Application -The `phonebilling` example application, located in the `_tut-install_/examples/batch/phonebilling/` directory, demonstrates how to use the batch framework in Jakarta EE to implement a phone billing system. +The `phonebilling` example application, located in the `_jakartaee-examples_/tutorial/batch/phonebilling/` directory, demonstrates how to use the batch framework in Jakarta EE to implement a phone billing system. This example application processes a log file of phone calls and creates a bill for each customer. === Architecture of the phonebilling Example Application @@ -170,8 +170,8 @@ The `OrderBy` annotation defines an order for retrieving the elements of the cal The batch artifacts use instances of these two entities as items to read, process, and write. -For more information on Jakarta Persistence, see <>. -For more information on Jakarta JSON Processing, see <>. +For more information on Jakarta Persistence, see xref:persist:persistence-intro/persistence-intro.adoc#_introduction_to_jakarta_persistence[Introduction to Jakarta Persistence]. +For more information on Jakarta JSON Processing, see xref:web:jsonp/jsonp.adoc#_json_processing[JSON Processing]. ==== The Call Records Chunk Step @@ -427,14 +427,14 @@ You can use either NetBeans IDE or Maven to build, package, deploy, and run the ==== To Run the phonebilling Example Application Using NetBeans IDE . Make sure that GlassFish Server has been started (see -<>). +xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . From the File menu, choose Open Project. . In the Open Project dialog box, navigate to: + ---- -tut-install/examples/batch +jakartaee-examples/tutorial/batch ---- . Select the `phonebilling` folder. @@ -451,12 +451,12 @@ http://localhost:8080/phonebilling/ ==== To Run the phonebilling Example Application Using Maven -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . In a terminal window, go to: + ---- -tut-install/examples/batch/phonebilling/ +jakartaee-examples/tutorial/batch/phonebilling/ ---- . Enter the following command to deploy the application: diff --git a/src/main/asciidoc/batch-processing/batch-processing010.adoc b/src/main/antora/modules/supporttechs/pages/batch-processing/batch-processing010.adoc similarity index 100% rename from src/main/asciidoc/batch-processing/batch-processing010.adoc rename to src/main/antora/modules/supporttechs/pages/batch-processing/batch-processing010.adoc diff --git a/src/main/asciidoc/concurrency-utilities/concurrency-utilities.adoc b/src/main/antora/modules/supporttechs/pages/concurrency-utilities/concurrency-utilities.adoc similarity index 89% rename from src/main/asciidoc/concurrency-utilities/concurrency-utilities.adoc rename to src/main/antora/modules/supporttechs/pages/concurrency-utilities/concurrency-utilities.adoc index 98961226..d7d80f7b 100644 --- a/src/main/asciidoc/concurrency-utilities/concurrency-utilities.adoc +++ b/src/main/antora/modules/supporttechs/pages/concurrency-utilities/concurrency-utilities.adoc @@ -1,5 +1,7 @@ = Jakarta Concurrency +include::ROOT:partial$not_updated.adoc[] + This chapter describes Jakarta Concurrency spec. include::concurrency-utilities001.adoc[] diff --git a/src/main/asciidoc/concurrency-utilities/concurrency-utilities001.adoc b/src/main/antora/modules/supporttechs/pages/concurrency-utilities/concurrency-utilities001.adoc similarity index 100% rename from src/main/asciidoc/concurrency-utilities/concurrency-utilities001.adoc rename to src/main/antora/modules/supporttechs/pages/concurrency-utilities/concurrency-utilities001.adoc diff --git a/src/main/asciidoc/concurrency-utilities/concurrency-utilities002.adoc b/src/main/antora/modules/supporttechs/pages/concurrency-utilities/concurrency-utilities002.adoc similarity index 100% rename from src/main/asciidoc/concurrency-utilities/concurrency-utilities002.adoc rename to src/main/antora/modules/supporttechs/pages/concurrency-utilities/concurrency-utilities002.adoc diff --git a/src/main/asciidoc/concurrency-utilities/concurrency-utilities003.adoc b/src/main/antora/modules/supporttechs/pages/concurrency-utilities/concurrency-utilities003.adoc similarity index 100% rename from src/main/asciidoc/concurrency-utilities/concurrency-utilities003.adoc rename to src/main/antora/modules/supporttechs/pages/concurrency-utilities/concurrency-utilities003.adoc diff --git a/src/main/asciidoc/concurrency-utilities/concurrency-utilities004.adoc b/src/main/antora/modules/supporttechs/pages/concurrency-utilities/concurrency-utilities004.adoc similarity index 100% rename from src/main/asciidoc/concurrency-utilities/concurrency-utilities004.adoc rename to src/main/antora/modules/supporttechs/pages/concurrency-utilities/concurrency-utilities004.adoc diff --git a/src/main/asciidoc/concurrency-utilities/concurrency-utilities005.adoc b/src/main/antora/modules/supporttechs/pages/concurrency-utilities/concurrency-utilities005.adoc similarity index 93% rename from src/main/asciidoc/concurrency-utilities/concurrency-utilities005.adoc rename to src/main/antora/modules/supporttechs/pages/concurrency-utilities/concurrency-utilities005.adoc index 69e07bec..b8baad3a 100644 --- a/src/main/asciidoc/concurrency-utilities/concurrency-utilities005.adoc +++ b/src/main/antora/modules/supporttechs/pages/concurrency-utilities/concurrency-utilities005.adoc @@ -70,14 +70,14 @@ Use the following settings (keep the default values for other settings): ==== To Build, Package, and Deploy the jobs Example Using NetBeans IDE -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . From the File menu, choose Open Project. . In the Open Project dialog box, navigate to: + ---- -tut-install/examples/concurrency +jakartaee-examples/tutorial/concurrency ---- . Select the `jobs` folder. @@ -90,12 +90,12 @@ This command builds and deploys the application. ==== To Build, Package, and Deploy the jobs Example Using Maven -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . In a terminal window, go to: + ---- -tut-install/examples/concurrency/jobs +jakartaee-examples/tutorial/concurrency/jobs ---- . Enter the following command to build and deploy the application: diff --git a/src/main/asciidoc/concurrency-utilities/concurrency-utilities006.adoc b/src/main/antora/modules/supporttechs/pages/concurrency-utilities/concurrency-utilities006.adoc similarity index 80% rename from src/main/asciidoc/concurrency-utilities/concurrency-utilities006.adoc rename to src/main/antora/modules/supporttechs/pages/concurrency-utilities/concurrency-utilities006.adoc index 394d196a..9fd6a3b5 100644 --- a/src/main/asciidoc/concurrency-utilities/concurrency-utilities006.adoc +++ b/src/main/antora/modules/supporttechs/pages/concurrency-utilities/concurrency-utilities006.adoc @@ -3,7 +3,7 @@ The `taskcreator` example demonstrates how to use Jakarta Concurrency to run tasks immediately, periodically, or after a fixed delay. This example provides a Jakarta Faces interface that enables users to submit tasks to be executed and displays information messages for each task. The example uses the Managed Executor Service to run tasks immediately and the Managed Scheduled Executor Service to run tasks periodically or after a fixed delay. -(See <> for information about these services.) +(See xref:concurrency-utilities/concurrency-utilities.adoc#_main_components_of_the_concurrency_utilities[Main Components of the Concurrency Utilities] for information about these services.) The `taskcreator` example consists of the following components. @@ -23,11 +23,11 @@ The tasks send information messages to this endpoint. * A task class (`Task`) that implements the `Runnable` interface. The `run` method in this class sends information messages to the web service endpoint in `TaskEJB` and sleeps for 1.5 seconds. -<> shows the architecture of the `taskcreator` example. +<<_architecture_of_the_taskcreator_example>> shows the architecture of the `taskcreator` example. -[[architecture-of-the-taskcreator-example]] +[[_architecture_of_the_taskcreator_example]] .Architecture of the taskcreator Example -image::jakartaeett_dt_060.svg["The figure shows the architecture of the taskcreator example. The Jakarta Faces page invokes methods on a CDI-managed bean, which submits task initiation requests to an enterprise bean. The enterprise bean uses a WebSocket endpoint to indicate to clients that an updated task execution log is available."] +image::common:jakartaeett_dt_060.svg["The figure shows the architecture of the taskcreator example. The Jakarta Faces page invokes methods on a CDI-managed bean, which submits task initiation requests to an enterprise bean. The enterprise bean uses a WebSocket endpoint to indicate to clients that an updated task execution log is available."] The `TaskEJB` class obtains the default executor service objects from the application server as follows: @@ -71,14 +71,14 @@ This section describes how to build, package, deploy, and run the `taskcreator` ==== To Build, Package, and Deploy the taskcreator Example Using NetBeans IDE -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . From the File menu, choose Open Project. . In the Open Project dialog box, navigate to: + ---- -tut-install/examples/concurrency +jakartaee-examples/tutorial/concurrency ---- . Select the `taskcreator` folder. @@ -91,12 +91,12 @@ This command builds and deploys the application. ==== To Build, Package, and Deploy the taskcreator Example Using Maven -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . In a terminal window, go to: + ---- -tut-install/examples/concurrency/taskcreator +jakartaee-examples/tutorial/concurrency/taskcreator ---- . Enter the following command to build and deploy the application: diff --git a/src/main/asciidoc/concurrency-utilities/concurrency-utilities007.adoc b/src/main/antora/modules/supporttechs/pages/concurrency-utilities/concurrency-utilities007.adoc similarity index 100% rename from src/main/asciidoc/concurrency-utilities/concurrency-utilities007.adoc rename to src/main/antora/modules/supporttechs/pages/concurrency-utilities/concurrency-utilities007.adoc diff --git a/src/main/asciidoc/connectorexample/connectorexample.adoc b/src/main/antora/modules/supporttechs/pages/connectorexample/connectorexample.adoc similarity index 87% rename from src/main/asciidoc/connectorexample/connectorexample.adoc rename to src/main/antora/modules/supporttechs/pages/connectorexample/connectorexample.adoc index c218cd33..906dadd6 100644 --- a/src/main/asciidoc/connectorexample/connectorexample.adoc +++ b/src/main/antora/modules/supporttechs/pages/connectorexample/connectorexample.adoc @@ -1,5 +1,7 @@ = The Resource Adapter Examples +include::ROOT:partial$not_updated.adoc[] + This chapter describes two examples that demonstrate how to use resource adapters in Jakarta EE applications and how to implement simple resource adapters. include::connectorexample001.adoc[] diff --git a/src/main/asciidoc/connectorexample/connectorexample001.adoc b/src/main/antora/modules/supporttechs/pages/connectorexample/connectorexample001.adoc similarity index 100% rename from src/main/asciidoc/connectorexample/connectorexample001.adoc rename to src/main/antora/modules/supporttechs/pages/connectorexample/connectorexample001.adoc diff --git a/src/main/asciidoc/connectorexample/connectorexample002.adoc b/src/main/antora/modules/supporttechs/pages/connectorexample/connectorexample002.adoc similarity index 87% rename from src/main/asciidoc/connectorexample/connectorexample002.adoc rename to src/main/antora/modules/supporttechs/pages/connectorexample/connectorexample002.adoc index 673eda7a..b7a0fa8b 100644 --- a/src/main/asciidoc/connectorexample/connectorexample002.adoc +++ b/src/main/antora/modules/supporttechs/pages/connectorexample/connectorexample002.adoc @@ -1,7 +1,7 @@ == The trading Example The `trading` example demonstrates how to implement and use a simple outbound resource adapter that submits requests to a legacy EIS using a TCP socket. -The example demonstrates the scenario in <> and consists of the following modules: +The example demonstrates the scenario in <<_the_trading_example_2>> and consists of the following modules: * `trading-eis`: A Java SE program that simulates a legacy EIS @@ -11,9 +11,9 @@ The example demonstrates the scenario in <> and consists * `trading-ear`: An enterprise archive that contains the resource adapter and the web application -[[the-trading-example-2]] +[[_the_trading_example_2]] .The trading Example -image::jakartaeett_dt_054.svg["This figure shows the trading example components: a deployed WAR and RAR that communicate with the EIS over a TCP socket."] +image::common:jakartaeett_dt_054.svg["This figure shows the trading example components: a deployed WAR and RAR that communicate with the EIS over a TCP socket."] The `trading-eis` module is an auxiliary project that resembles a legacy stock trading execution platform. It contains a Java SE program that listens for trading requests in plain text on a TCP socket. @@ -48,9 +48,9 @@ Outbound resource adapters provide Jakarta EE applications with the following el Jakarta EE applications obtain an instance of the connection factory via resource injection and then use the factory object to obtain connection handles to the EIS. The connection handles enable the application to make requests and obtain information from the EIS. -The `trading-rar` module provides a custom client interface that consists of the classes listed in <>. +The `trading-rar` module provides a custom client interface that consists of the classes listed in <<_classes_and_interfaces_in_the_trading_rar_module>>. -[[classes-and-interfaces-in-the-trading-rar-module]] +[[_classes_and_interfaces_in_the_trading_rar_module]] .Classes and Interfaces in the trading-rar module [width="80%",cols="20%,60%"] |=== @@ -140,15 +140,15 @@ try { === Implementing the Outbound Resource Adapter The `trading-rar` module implements the outbound contract and a custom client interface for the simple legacy stock trading platform EIS used in this example. -The architecture of the outbound resource adapter is shown in <>. +The architecture of the outbound resource adapter is shown in <<_architecture_of_the_trading_example>>. -[[architecture-of-the-trading-example]] +[[_architecture_of_the_trading_example]] .Architecture of the trading Example -image::jakartaeett_dt_055.svg["This figure shows the classes in each of the modules of the trading example."] +image::common:jakartaeett_dt_055.svg["This figure shows the classes in each of the modules of the trading example."] -The `trading-rar` module implements the interfaces listed in <>. +The `trading-rar` module implements the interfaces listed in <<_interfaces_implemented_in_the_trading_rar_module>>. -[[interfaces-implemented-in-the-trading-rar-module]] +[[_interfaces_implemented_in_the_trading_rar_module]] .Interfaces Implemented in the trading-rar Module [width="99%",cols="20%,20%,60%"] |=== @@ -165,7 +165,7 @@ The `trading-rar` module implements the interfaces listed in <>, the application server creates `TradeConnectionFactory` objects that applications can obtain using resource injection. +When the `trading-ear` archive is deployed and a connection pool resource is configured as described in <<_using_the_outbound_resource_adapter>>, the application server creates `TradeConnectionFactory` objects that applications can obtain using resource injection. The `TradeConnectionFactory` implementation delegates creating connections to the connection manager provided by the application server. The connection manager uses the `ManagedConnectionFactory` implementation to obtain physical connections to the EIS and maintains a pool of active physical connections. @@ -180,14 +180,14 @@ You can use either NetBeans IDE or Maven to build, package, deploy, and run the ==== To Run the trading Example Using NetBeans IDE -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . From the File menu, choose Open Project. . In the Open Project dialog box, navigate to: + ---- -tut-install/examples/connectors +jakartaee-examples/tutorial/connectors ---- . Select the `trading` folder. @@ -223,12 +223,12 @@ The server log shows the requests from the web application and the call sequence ==== To Run the trading Example Using Maven -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . In a terminal window, go to: + ---- -tut-install/examples/connectors/trading/ +jakartaee-examples/tutorial/connectors/trading/ ---- . Enter the following command: diff --git a/src/main/asciidoc/connectorexample/connectorexample003.adoc b/src/main/antora/modules/supporttechs/pages/connectorexample/connectorexample003.adoc similarity index 86% rename from src/main/asciidoc/connectorexample/connectorexample003.adoc rename to src/main/antora/modules/supporttechs/pages/connectorexample/connectorexample003.adoc index 189febb5..36849cd1 100644 --- a/src/main/asciidoc/connectorexample/connectorexample003.adoc +++ b/src/main/antora/modules/supporttechs/pages/connectorexample/connectorexample003.adoc @@ -2,10 +2,10 @@ The `traffic` example demonstrates how to implement and use a simple inbound resource adapter that receives data from a legacy EIS using a TCP socket. -The example is in the `_tut-install_/examples/connectors/traffic` directory. -See xref:using-the-tutorial-examples[xrefstyle=full] for basic information on building and running sample applications. +The example is in the `_jakartaee-examples_/tutorial/connectors/traffic` directory. +See xref:intro:usingexamples/usingexamples.adoc#_using_the_tutorial_examples[Using the Tutorial Examples] for basic information on building and running sample applications. -The example demonstrates the scenario in <> and consists of the following modules: +The example demonstrates the scenario in <<_the_traffic_example_2>> and consists of the following modules: * `traffic-eis`: A Java SE program that simulates an EIS @@ -17,9 +17,9 @@ The example demonstrates the scenario in <> and consists * `traffic-ear`: An enterprise archive that contains the resource adapter, the message-driven bean, and the web application -[[the-traffic-example-2]] +[[_the_traffic_example_2]] .The traffic Example -image::jakartaeett_dt_056.svg["This figure shows the components of the traffic example: a WAR communicating with an enterprise bean using a JMS topic, and a RAR communicating with an EIS over a TCP socket."] +image::common:jakartaeett_dt_056.svg["This figure shows the components of the traffic example: a WAR communicating with an enterprise bean using a JMS topic, and a RAR communicating with an EIS over a TCP socket."] The `traffic-eis` module is an auxiliary project that resembles a legacy traffic information system. It contains a Java SE program that sends traffic status updates for several cities to any subscribed client. @@ -94,15 +94,15 @@ This approach enables you to adapt the MDB to support new features in the EIS wi === Implementing the Inbound Resource Adapter The `traffic-rar` module implements the Jakarta Connectors inbound resource adapter contract for the simple traffic information system (EIS) used in this example. -The architecture of the inbound resource adapter is shown in <>. +The architecture of the inbound resource adapter is shown in <<_architecture_of_the_traffic_example>>. -[[architecture-of-the-traffic-example]] +[[_architecture_of_the_traffic_example]] .Architecture of the traffic Example -image::jakartaeett_dt_057.svg["This figure shows the classes in each of the components of the traffic example."] +image::common:jakartaeett_dt_057.svg["This figure shows the classes in each of the components of the traffic example."] -The `traffic-rar` module implements the interfaces listed in <>. +The `traffic-rar` module implements the interfaces listed in <<_interfaces_implemented_in_the_traffic_rar_module>>. -[[interfaces-implemented-in-the-traffic-rar-module]] +[[_interfaces_implemented_in_the_traffic_rar_module]] .Interfaces Implemented in the traffic-rar Module [width="99%",cols="20%,20%,60%"] |=== @@ -185,14 +185,14 @@ You can use either NetBeans IDE or Maven to build, package, deploy, and run the ==== To Run the traffic Example Using NetBeans IDE -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . From the File menu, choose Open Project. . In the Open Project dialog box, navigate to: + ---- -tut-install/examples/connectors +jakartaee-examples/tutorial/connectors ---- . Select the `traffic` folder. @@ -228,12 +228,12 @@ The web interface shows filtered traffic updates for City1 every few seconds. ==== To Run the traffic Example Using Maven -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . In a terminal window, go to: + ---- -tut-install/examples/connectors/traffic/traffic-eis/ +jakartaee-examples/tutorial/connectors/traffic/traffic-eis/ ---- . Enter the following command in the terminal window: @@ -263,7 +263,7 @@ Leave this terminal window open. . Open a new terminal window and go to: + ---- -tut-install/examples/connectors/traffic/ +jakartaee-examples/tutorial/connectors/traffic/ ---- . Enter the following command: diff --git a/src/main/antora/modules/supporttechs/pages/connectors/connectors.adoc b/src/main/antora/modules/supporttechs/pages/connectors/connectors.adoc new file mode 100644 index 00000000..ca27f691 --- /dev/null +++ b/src/main/antora/modules/supporttechs/pages/connectors/connectors.adoc @@ -0,0 +1,5 @@ += Jakarta Connectors + +Jakarta Connectors mediate communications between Jakarta EE servers and EIS systems + +https://jakarta.ee/specifications/connectors/[Jakarta Connectors Specification] diff --git a/src/main/asciidoc/interceptors/interceptors.adoc b/src/main/antora/modules/supporttechs/pages/interceptors/interceptors.adoc similarity index 86% rename from src/main/asciidoc/interceptors/interceptors.adoc rename to src/main/antora/modules/supporttechs/pages/interceptors/interceptors.adoc index 4190c0da..afe9e52a 100644 --- a/src/main/asciidoc/interceptors/interceptors.adoc +++ b/src/main/antora/modules/supporttechs/pages/interceptors/interceptors.adoc @@ -1,5 +1,7 @@ = Using Jakarta EE Interceptors +include::ROOT:partial$not_updated.adoc[] + This chapter discusses how to create interceptor classes and methods that interpose on method invocations or lifecycle events on a target class. include::interceptors001.adoc[] diff --git a/src/main/asciidoc/interceptors/interceptors001.adoc b/src/main/antora/modules/supporttechs/pages/interceptors/interceptors001.adoc similarity index 94% rename from src/main/asciidoc/interceptors/interceptors001.adoc rename to src/main/antora/modules/supporttechs/pages/interceptors/interceptors001.adoc index 45ce4843..08e14faa 100644 --- a/src/main/asciidoc/interceptors/interceptors001.adoc +++ b/src/main/antora/modules/supporttechs/pages/interceptors/interceptors001.adoc @@ -14,9 +14,9 @@ Interceptor classes and methods are defined using metadata annotations, or in th [NOTE] Applications that use the deployment descriptor to define interceptors are not portable across Jakarta EE servers. -Interceptor methods within the target class or in an interceptor class are annotated with one of the metadata annotations defined in <>. +Interceptor methods within the target class or in an interceptor class are annotated with one of the metadata annotations defined in <<_interceptor_metadata_annotations>>. -[[interceptor-metadata-annotations]] +[[_interceptor_metadata_annotations]] .Interceptor Metadata Annotations [width="80%",cols="20%,60%"] |=== @@ -55,4 +55,4 @@ The target class instance and all interceptor class instances are fully instanti === Interceptors and CDI Jakarta Contexts and Dependency Injection (CDI) builds on the basic functionality of Jakarta EE interceptors. -For information on CDI interceptors, including a discussion of interceptor binding types, see <>. +For information on CDI interceptors, including a discussion of interceptor binding types, see xref:cdi:cdi-adv/cdi-adv.adoc#_using_interceptors_in_cdi_applications[Using Interceptors in CDI Applications]. diff --git a/src/main/asciidoc/interceptors/interceptors002.adoc b/src/main/antora/modules/supporttechs/pages/interceptors/interceptors002.adoc similarity index 98% rename from src/main/asciidoc/interceptors/interceptors002.adoc rename to src/main/antora/modules/supporttechs/pages/interceptors/interceptors002.adoc index 84d6cbae..a8f69caa 100644 --- a/src/main/asciidoc/interceptors/interceptors002.adoc +++ b/src/main/antora/modules/supporttechs/pages/interceptors/interceptors002.adoc @@ -1,6 +1,6 @@ == Using Interceptors -To define an interceptor, use one of the interceptor metadata annotations listed in <> within the target class, or in a separate interceptor class. +To define an interceptor, use one of the interceptor metadata annotations listed in xref:interceptors/interceptors.adoc#_interceptor_metadata_annotations[Interceptor Metadata Annotations] within the target class, or in a separate interceptor class. The following code declares an `@AroundTimeout` interceptor method within a target class: [source,java] @@ -335,9 +335,9 @@ The lower the number, the higher the priority of the associated interceptor. [NOTE] The invocation order of interceptors with the same priority value is implementation-specific. -The `jakarta.interceptor.Interceptor.Priority` class defines the priority constants listed in <>. +The `jakarta.interceptor.Interceptor.Priority` class defines the priority constants listed in <<_interceptor_priority_constants>>. -[[interceptor-priority-constants]] +[[_interceptor_priority_constants]] .Interceptor Priority Constants [width="99%",cols="15%,15%,70%"] |=== diff --git a/src/main/asciidoc/interceptors/interceptors003.adoc b/src/main/antora/modules/supporttechs/pages/interceptors/interceptors003.adoc similarity index 88% rename from src/main/asciidoc/interceptors/interceptors003.adoc rename to src/main/antora/modules/supporttechs/pages/interceptors/interceptors003.adoc index d4b361ba..9e08106b 100644 --- a/src/main/asciidoc/interceptors/interceptors003.adoc +++ b/src/main/antora/modules/supporttechs/pages/interceptors/interceptors003.adoc @@ -46,14 +46,14 @@ You can use either NetBeans IDE or Maven to build, package, deploy, and run the ==== To Run the interceptor Example Using NetBeans IDE -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . From the File menu, choose Open Project. . In the Open Project dialog box, navigate to: + ---- -tut-install/examples/ejb +jakartaee-examples/tutorial/ejb ---- . Select the `interceptor` folder and click Open Project. @@ -72,12 +72,12 @@ The name will be converted to lowercase by the method interceptor defined in the ==== To Run the interceptor Example Using Maven -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . Go to the following directory: + ---- -tut-install/examples/ejb/interceptor/ +jakartaee-examples/tutorial/ejb/interceptor/ ---- . To compile the source files and package the application, use the following command: diff --git a/src/main/asciidoc/resources/resources.adoc b/src/main/antora/modules/supporttechs/pages/resources/resources.adoc similarity index 88% rename from src/main/asciidoc/resources/resources.adoc rename to src/main/antora/modules/supporttechs/pages/resources/resources.adoc index 0c2e3009..e6fb6647 100644 --- a/src/main/asciidoc/resources/resources.adoc +++ b/src/main/antora/modules/supporttechs/pages/resources/resources.adoc @@ -1,5 +1,7 @@ = Resource Adapters and Contracts +include::ROOT:partial$not_updated.adoc[] + This chapter examines resource adapters and explains how communications between Jakarta EE servers and EIS systems are mediated by them. include::resources001.adoc[] diff --git a/src/main/asciidoc/resources/resources001.adoc b/src/main/antora/modules/supporttechs/pages/resources/resources001.adoc similarity index 96% rename from src/main/asciidoc/resources/resources001.adoc rename to src/main/antora/modules/supporttechs/pages/resources/resources001.adoc index 145b01bb..e4bf5d88 100644 --- a/src/main/asciidoc/resources/resources001.adoc +++ b/src/main/antora/modules/supporttechs/pages/resources/resources001.adoc @@ -3,11 +3,11 @@ A resource adapter is a Jakarta EE component that implements the Jakarta Connectors API for a specific EIS. Examples of EISs include enterprise resource planning, mainframe transaction processing, and database systems. In a Jakarta EE server, Jakarta Messaging and Jakarta Mail also act as EISs that you access using resource adapters. -As illustrated in <>, the resource adapter facilitates communication between a Jakarta EE application and an EIS. +As illustrated in <<_resource_adapters>>, the resource adapter facilitates communication between a Jakarta EE application and an EIS. -[[resource-adapters]] +[[_resource_adapters]] .Resource Adapters -image::jakartaeett_dt_053.svg["Resource Adapter Contracts"] +image::common:jakartaeett_dt_053.svg["Resource Adapter Contracts"] Stored in a Resource Adapter Archive (RAR) file, a resource adapter can be deployed on any Jakarta EE server, much like a Jakarta EE application. A RAR file may be contained in an Enterprise Archive (EAR) file, or it may exist as a separate file. diff --git a/src/main/asciidoc/resources/resources002.adoc b/src/main/antora/modules/supporttechs/pages/resources/resources002.adoc similarity index 100% rename from src/main/asciidoc/resources/resources002.adoc rename to src/main/antora/modules/supporttechs/pages/resources/resources002.adoc diff --git a/src/main/asciidoc/resources/resources003.adoc b/src/main/antora/modules/supporttechs/pages/resources/resources003.adoc similarity index 100% rename from src/main/asciidoc/resources/resources003.adoc rename to src/main/antora/modules/supporttechs/pages/resources/resources003.adoc diff --git a/src/main/asciidoc/resources/resources004.adoc b/src/main/antora/modules/supporttechs/pages/resources/resources004.adoc similarity index 79% rename from src/main/asciidoc/resources/resources004.adoc rename to src/main/antora/modules/supporttechs/pages/resources/resources004.adoc index 2c90692b..cfe03238 100644 --- a/src/main/asciidoc/resources/resources004.adoc +++ b/src/main/antora/modules/supporttechs/pages/resources/resources004.adoc @@ -1,6 +1,6 @@ == Using Resource Adapters with Jakarta Contexts and Dependency Injection (CDI) -For details about CDI, see xref:introduction-to-jakarta-contexts-and-dependency-injection[xrefstyle=full] and xref:jakarta-contexts-and-dependency-injection-advanced-topics[xrefstyle=full]. +For details about CDI, see xref:cdi:cdi-basic/cdi-basic.adoc#_introduction_to_jakarta_contexts_and_dependency_injection[Introduction to Jakarta Contexts and Dependency Injection] and xref:cdi:cdi-adv/cdi-adv.adoc#_jakarta_contexts_and_dependency_injection_advanced_topics[Jakarta Contexts and Dependency Injection: Advanced Topics]. Do not specify the following classes in the resource adapter as CDI managed beans (that is, do not inject them), because the behavior of these classes as CDI managed beans has not been portably defined. diff --git a/src/main/asciidoc/resources/resources005.adoc b/src/main/antora/modules/supporttechs/pages/resources/resources005.adoc similarity index 100% rename from src/main/asciidoc/resources/resources005.adoc rename to src/main/antora/modules/supporttechs/pages/resources/resources005.adoc diff --git a/src/main/asciidoc/transactions/transactions.adoc b/src/main/antora/modules/supporttechs/pages/transactions/transactions.adoc similarity index 85% rename from src/main/asciidoc/transactions/transactions.adoc rename to src/main/antora/modules/supporttechs/pages/transactions/transactions.adoc index ef76209a..3f711bd1 100644 --- a/src/main/asciidoc/transactions/transactions.adoc +++ b/src/main/antora/modules/supporttechs/pages/transactions/transactions.adoc @@ -1,4 +1,6 @@ -= Transactions += Jakarta Transactions + +include::ROOT:partial$not_updated.adoc[] This chapter describes types of transactions and how they are managed in different applications. diff --git a/src/main/asciidoc/transactions/transactions001.adoc b/src/main/antora/modules/supporttechs/pages/transactions/transactions001.adoc similarity index 100% rename from src/main/asciidoc/transactions/transactions001.adoc rename to src/main/antora/modules/supporttechs/pages/transactions/transactions001.adoc diff --git a/src/main/asciidoc/transactions/transactions002.adoc b/src/main/antora/modules/supporttechs/pages/transactions/transactions002.adoc similarity index 100% rename from src/main/asciidoc/transactions/transactions002.adoc rename to src/main/antora/modules/supporttechs/pages/transactions/transactions002.adoc diff --git a/src/main/asciidoc/transactions/transactions003.adoc b/src/main/antora/modules/supporttechs/pages/transactions/transactions003.adoc similarity index 100% rename from src/main/asciidoc/transactions/transactions003.adoc rename to src/main/antora/modules/supporttechs/pages/transactions/transactions003.adoc diff --git a/src/main/asciidoc/transactions/transactions004.adoc b/src/main/antora/modules/supporttechs/pages/transactions/transactions004.adoc similarity index 93% rename from src/main/asciidoc/transactions/transactions004.adoc rename to src/main/antora/modules/supporttechs/pages/transactions/transactions004.adoc index b4a23a7a..e35e615c 100644 --- a/src/main/asciidoc/transactions/transactions004.adoc +++ b/src/main/antora/modules/supporttechs/pages/transactions/transactions004.adoc @@ -22,13 +22,13 @@ Enterprise beans that use container-managed transaction demarcation also must no === Transaction Attributes A transaction attribute controls the scope of a transaction. -<> illustrates why controlling the scope is important. +<<_transaction_scope>> illustrates why controlling the scope is important. In the diagram, `method-A` begins a transaction and then invokes `method-B` of `Bean-2`. When `method-B` executes, does it run within the scope of the transaction started by `method-A`, or does it execute with a new transaction? The answer depends on the transaction attribute of `method-B`. -[[transaction-scope]] +[[_transaction_scope]] .Transaction Scope -image::jakartaeett_dt_050.svg["A diagram showing a transaction between two beans."] +image::common:jakartaeett_dt_050.svg["A diagram showing a transaction between two beans."] A transaction attribute can have one of the following values: @@ -100,16 +100,16 @@ If the client is not associated with a transaction, the container does not start ==== Summary of Transaction Attributes -<> summarizes the effects of the transaction attributes. +<<_transaction_attributes_and_scope>> summarizes the effects of the transaction attributes. Both the `T1` and the `T2` transactions are controlled by the container. A `T1` transaction is associated with the client that calls a method in the enterprise bean. In most cases, the client is another enterprise bean. A `T2` transaction is started by the container just before the method executes. -In the last column of <>, the word "None" means that the business method does not execute within a transaction controlled by the container. +In the last column of <<_transaction_attributes_and_scope>>, the word "None" means that the business method does not execute within a transaction controlled by the container. However, the database calls in such a business method might be controlled by the transaction manager of the database management system. -[[transaction-attributes-and-scope]] +[[_transaction_attributes_and_scope]] .Transaction Attributes and Scope [width="60%",cols="20%,20%,20%"] |=== @@ -148,9 +148,9 @@ If you decorate the enterprise bean class with `@TransactionAttribute`, the spec Decorating a business method with `@TransactionAttribute` applies the `TransactionAttributeType` only to that method. If a `@TransactionAttribute` annotation decorates both the class and the method, the method `TransactionAttributeType` overrides the class `TransactionAttributeType`. -The `TransactionAttributeType` constants shown in <> encapsulate the transaction attributes described earlier in this section. +The `TransactionAttributeType` constants shown in <<_transactionattributetype_constants>> encapsulate the transaction attributes described earlier in this section. -[[transactionattributetype-constants]] +[[_transactionattributetype_constants]] .TransactionAttributeType Constants [width="34%",cols="20%,80%"] |=== diff --git a/src/main/asciidoc/transactions/transactions005.adoc b/src/main/antora/modules/supporttechs/pages/transactions/transactions005.adoc similarity index 100% rename from src/main/asciidoc/transactions/transactions005.adoc rename to src/main/antora/modules/supporttechs/pages/transactions/transactions005.adoc diff --git a/src/main/asciidoc/transactions/transactions006.adoc b/src/main/antora/modules/supporttechs/pages/transactions/transactions006.adoc similarity index 86% rename from src/main/asciidoc/transactions/transactions006.adoc rename to src/main/antora/modules/supporttechs/pages/transactions/transactions006.adoc index a054902f..b1bb1563 100644 --- a/src/main/asciidoc/transactions/transactions006.adoc +++ b/src/main/antora/modules/supporttechs/pages/transactions/transactions006.adoc @@ -1,7 +1,7 @@ == Transaction Timeouts For container-managed transactions, you can use the Administration Console to configure the transaction timeout interval. -See <>. +See xref:intro:usingexamples/usingexamples.adoc#_starting_the_administration_console[Starting the Administration Console]. For enterprise beans with bean-managed Jakarta transactions, you invoke the `setTransactionTimeout` method of the `UserTransaction` interface. diff --git a/src/main/asciidoc/transactions/transactions007.adoc b/src/main/antora/modules/supporttechs/pages/transactions/transactions007.adoc similarity index 52% rename from src/main/asciidoc/transactions/transactions007.adoc rename to src/main/antora/modules/supporttechs/pages/transactions/transactions007.adoc index 924d2889..9618a78a 100644 --- a/src/main/asciidoc/transactions/transactions007.adoc +++ b/src/main/antora/modules/supporttechs/pages/transactions/transactions007.adoc @@ -2,22 +2,22 @@ The Jakarta EE transaction manager controls all enterprise bean transactions except for bean-managed JDBC transactions. The Jakarta EE transaction manager allows an enterprise bean to update multiple databases within a transaction. -<> and <> show two scenarios for updating multiple databases in a single transaction. +<<_updating_multiple_databases_2>> and <<_updating_multiple_databases_across_jakarta_ee_servers>> show two scenarios for updating multiple databases in a single transaction. -In <>, the client invokes a business method in `Bean-A`. +In <<_updating_multiple_databases_2>>, the client invokes a business method in `Bean-A`. The business method begins a transaction, updates Database X, updates Database Y, and invokes a business method in `Bean-B`. The second business method updates Database Z and returns control to the business method in `Bean-A`, which commits the transaction. All three database updates occur in the same transaction. -In <>, the client calls a business method in `Bean-A`, which begins a transaction and updates Database X. +In <<_updating_multiple_databases_across_jakarta_ee_servers>>, the client calls a business method in `Bean-A`, which begins a transaction and updates Database X. Then `Bean-A` invokes a method in `Bean-B`, which resides in a remote Jakarta EE server. The method in `Bean-B` updates Database Y. The transaction managers of the Jakarta EE servers ensure that both databases are updated in the same transaction. -[[updating-multiple-databases-2]] +[[_updating_multiple_databases_2]] .Updating Multiple Databases -image::jakartaeett_dt_051.svg["A diagram showing Bean-A updating databases X and Y, and Bean-B updating database Z."] +image::common:jakartaeett_dt_051.svg["A diagram showing Bean-A updating databases X and Y, and Bean-B updating database Z."] -[[updating-multiple-databases-across-jakarta-ee-servers]] +[[_updating_multiple_databases_across_jakarta_ee_servers]] .Updating Multiple Databases Across Jakarta EE Servers -image::jakartaeett_dt_052.svg["A diagram showing Bean-A on one Jakarta EE server updating database X, and Bean-B on another Jakarta EE server updating database Y."] +image::common:jakartaeett_dt_052.svg["A diagram showing Bean-A on one Jakarta EE server updating database X, and Bean-B on another Jakarta EE server updating database Y."] diff --git a/src/main/asciidoc/transactions/transactions008.adoc b/src/main/antora/modules/supporttechs/pages/transactions/transactions008.adoc similarity index 78% rename from src/main/asciidoc/transactions/transactions008.adoc rename to src/main/antora/modules/supporttechs/pages/transactions/transactions008.adoc index 2a2ec376..263fb7e1 100644 --- a/src/main/asciidoc/transactions/transactions008.adoc +++ b/src/main/antora/modules/supporttechs/pages/transactions/transactions008.adoc @@ -2,4 +2,4 @@ You can demarcate a transaction in a web component by using either the `java.sql.Connection` or the `jakarta.transaction.UserTransaction` interface. These are the same interfaces that a session bean with bean-managed transactions can use. -Transactions demarcated with the `UserTransaction` interface are discussed in <>. +Transactions demarcated with the `UserTransaction` interface are discussed in xref:transactions/transactions.adoc#_jakarta_transactions[Jakarta Transactions]. diff --git a/src/main/asciidoc/transactions/transactions009.adoc b/src/main/antora/modules/supporttechs/pages/transactions/transactions009.adoc similarity index 100% rename from src/main/asciidoc/transactions/transactions009.adoc rename to src/main/antora/modules/supporttechs/pages/transactions/transactions009.adoc diff --git a/src/main/asciidoc/faces-advanced-cc/faces-advanced-cc.adoc b/src/main/antora/modules/web/pages/faces-advanced-cc/faces-advanced-cc.adoc similarity index 87% rename from src/main/asciidoc/faces-advanced-cc/faces-advanced-cc.adoc rename to src/main/antora/modules/web/pages/faces-advanced-cc/faces-advanced-cc.adoc index f7148aae..d2ce8307 100644 --- a/src/main/asciidoc/faces-advanced-cc/faces-advanced-cc.adoc +++ b/src/main/antora/modules/web/pages/faces-advanced-cc/faces-advanced-cc.adoc @@ -1,5 +1,7 @@ = Composite Components: Advanced Topics and an Example +include::ROOT:partial$not_updated.adoc[] + This chapter describes the advanced features of composite components in Jakarta Faces technology. include::faces-advanced-cc001.adoc[] diff --git a/src/main/asciidoc/faces-advanced-cc/faces-advanced-cc001.adoc b/src/main/antora/modules/web/pages/faces-advanced-cc/faces-advanced-cc001.adoc similarity index 87% rename from src/main/asciidoc/faces-advanced-cc/faces-advanced-cc001.adoc rename to src/main/antora/modules/web/pages/faces-advanced-cc/faces-advanced-cc001.adoc index c3376c93..bc2aa4b5 100644 --- a/src/main/asciidoc/faces-advanced-cc/faces-advanced-cc001.adoc +++ b/src/main/antora/modules/web/pages/faces-advanced-cc/faces-advanced-cc001.adoc @@ -1,12 +1,12 @@ == Attributes of a Composite Component A composite component is a special type of Jakarta Faces template that acts as a component. -If you are new to composite components, see <> before you proceed with this chapter. +If you are new to composite components, see xref:faces-facelets/faces-facelets.adoc#_composite_components[Composite Components] before you proceed with this chapter. You define an attribute of a composite component by using the `composite:attribute` tag. -<> lists the commonly used attributes of this tag. +<<_commonly_used_attributes_of_the_compositeattribute_tag>> lists the commonly used attributes of this tag. -[[commonly-used-attributes-of-the-compositeattribute-tag]] +[[_commonly_used_attributes_of_the_compositeattribute_tag]] .Commonly Used Attributes of the composite:attribute Tag [width="70%",cols="15%,55%"] |=== diff --git a/src/main/antora/modules/web/pages/faces-advanced-cc/faces-advanced-cc002.adoc b/src/main/antora/modules/web/pages/faces-advanced-cc/faces-advanced-cc002.adoc new file mode 100644 index 00000000..2e12c6a4 --- /dev/null +++ b/src/main/antora/modules/web/pages/faces-advanced-cc/faces-advanced-cc002.adoc @@ -0,0 +1,11 @@ +== Invoking a Managed Bean + +To enable a composite component to handle server-side data + +. Invoke a managed bean in one of the following ways: + +* Pass the reference of the managed bean to the composite component. + +* Directly use the properties of the managed bean. ++ +The example application described in xref:faces-advanced-cc/faces-advanced-cc.adoc#_the_compositecomponentexample_example_application[The compositecomponentexample Example Application] shows how to use a managed bean with a composite component by passing the reference of the managed bean to the component. diff --git a/src/main/asciidoc/faces-advanced-cc/faces-advanced-cc003.adoc b/src/main/antora/modules/web/pages/faces-advanced-cc/faces-advanced-cc003.adoc similarity index 77% rename from src/main/asciidoc/faces-advanced-cc/faces-advanced-cc003.adoc rename to src/main/antora/modules/web/pages/faces-advanced-cc/faces-advanced-cc003.adoc index 9d29c75a..67d1b7ec 100644 --- a/src/main/asciidoc/faces-advanced-cc/faces-advanced-cc003.adoc +++ b/src/main/antora/modules/web/pages/faces-advanced-cc/faces-advanced-cc003.adoc @@ -3,10 +3,10 @@ Jakarta Faces provides the following tags for validating values of input components. These tags can be used with the `composite:valueHolder` or the `composite:editableValueHolder` tag. -<> lists commonly used validator tags. -See <> for details and a complete list. +<<_validator_tags>> lists commonly used validator tags. +See xref:faces-page-core/faces-page-core.adoc#_using_the_standard_validators[Using the Standard Validators] for details and a complete list. -[[validator-tags]] +[[_validator_tags]] .Validator Tags [width="70%",cols="15%,55%"] |=== diff --git a/src/main/asciidoc/faces-advanced-cc/faces-advanced-cc004.adoc b/src/main/antora/modules/web/pages/faces-advanced-cc/faces-advanced-cc004.adoc similarity index 87% rename from src/main/asciidoc/faces-advanced-cc/faces-advanced-cc004.adoc rename to src/main/antora/modules/web/pages/faces-advanced-cc/faces-advanced-cc004.adoc index 035b7576..4897ec2a 100644 --- a/src/main/asciidoc/faces-advanced-cc/faces-advanced-cc004.adoc +++ b/src/main/antora/modules/web/pages/faces-advanced-cc/faces-advanced-cc004.adoc @@ -6,7 +6,7 @@ The component displays the sum of the letter values and reports whether it is or The `compositecomponentexample` application has a composite component file, a using page, and a managed bean. -The source code for this application is in the `_tut-install_/examples/web/faces/compositecomponentexample/` directory. +The source code for this application is in the `_jakartaee-examples_/tutorial/web/faces/compositecomponentexample/` directory. === The Composite Component File @@ -99,12 +99,12 @@ It calculates the sum of the letters in the string, with `'a'` equal to 1 and `' An uppercase letter in the input string has the same value as its lowercase equivalent. The bean specifies the minimum and maximum size of the `name` string, which is enforced by the Bean Validation `@Size` constraint. -The bean uses the `@Model` annotation, a shortcut for `@Named` and `@RequestScoped`, as described in <> of <>. +The bean uses the `@Model` annotation, a shortcut for `@Named` and `@RequestScoped`, as described in xref:webapp/webapp.adoc#_hello1_nb_step_7[Step 7] of xref:webapp/webapp.adoc#_to_view_the_hello1_web_module_using_netbeans_ide[To View the hello1 Web Module Using NetBeans IDE]. [source,java] ---- @Model -public class PrimeBean implements Serializable { +public class PrimeBean { ... @Size(min=1, max=45) private String name; @@ -122,14 +122,14 @@ You can use either NetBeans IDE or Maven to build, package, deploy, and run the ==== To Build, Package, and Deploy the compositecomponentexample Example Using NetBeans IDE -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . From the *File* menu, choose *Open Project*. . In the Open Project dialog box, navigate to: + ---- -tut-install/examples/web/faces +jakartaee-examples/tutorial/web/faces ---- . Select the `compositecomponentexample` folder. @@ -142,12 +142,12 @@ This command builds and deploys the application. ==== To Build, Package, and Deploy the compositecomponentexample Example Using Maven -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . In a terminal window, go to: + ---- -tut-install/examples/web/faces/compositecomponentexample/ +jakartaee-examples/tutorial/web/faces/compositecomponentexample/ ---- . Enter the following command to build and deploy the application: diff --git a/src/main/asciidoc/faces-ajax/faces-ajax.adoc b/src/main/antora/modules/web/pages/faces-ajax/faces-ajax.adoc similarity index 95% rename from src/main/asciidoc/faces-ajax/faces-ajax.adoc rename to src/main/antora/modules/web/pages/faces-ajax/faces-ajax.adoc index 16cd15f6..3da89ffe 100644 --- a/src/main/asciidoc/faces-ajax/faces-ajax.adoc +++ b/src/main/antora/modules/web/pages/faces-ajax/faces-ajax.adoc @@ -1,5 +1,7 @@ = Using Ajax with Jakarta Faces Technology +include::ROOT:partial$not_updated.adoc[] + This chapter describes using Ajax functionality in Jakarta Faces web applications. Ajax is an acronym for Asynchronous JavaScript and XML, a group of web technologies that enable creation of dynamic and highly responsive web applications. Using Ajax, web applications can retrieve content from the server without interfering with the display on the client. diff --git a/src/main/asciidoc/faces-ajax/faces-ajax001.adoc b/src/main/antora/modules/web/pages/faces-ajax/faces-ajax001.adoc similarity index 94% rename from src/main/asciidoc/faces-ajax/faces-ajax001.adoc rename to src/main/antora/modules/web/pages/faces-ajax/faces-ajax001.adoc index df570795..79597b00 100644 --- a/src/main/asciidoc/faces-ajax/faces-ajax001.adoc +++ b/src/main/antora/modules/web/pages/faces-ajax/faces-ajax001.adoc @@ -18,7 +18,7 @@ When a JavaScript function sends an asynchronous request from the client to the This response is often in the format of an XML document. The term Ajax refers to this interaction between the client and server. -The server response need not be in XML only; it can also be in other formats, such as JSON (see <> and https://www.json.org/[^]). +The server response need not be in XML only; it can also be in other formats, such as JSON (see xref:jsonp/jsonp.adoc#_introduction_to_json[Introduction to JSON] and https://www.json.org/[^]). This tutorial does not focus on the response formats. Ajax enables asynchronous and partial updating of web applications. diff --git a/src/main/asciidoc/faces-ajax/faces-ajax002.adoc b/src/main/antora/modules/web/pages/faces-ajax/faces-ajax002.adoc similarity index 89% rename from src/main/asciidoc/faces-ajax/faces-ajax002.adoc rename to src/main/antora/modules/web/pages/faces-ajax/faces-ajax002.adoc index e3166ef0..01c4fde1 100644 --- a/src/main/asciidoc/faces-ajax/faces-ajax002.adoc +++ b/src/main/antora/modules/web/pages/faces-ajax/faces-ajax002.adoc @@ -16,6 +16,6 @@ The next sections of the tutorial describe the use of the built-in Ajax resource In addition, because the Jakarta Faces technology component model can be extended, custom components can be created with Ajax functionality. The tutorial examples include an Ajax version of the `guessnumber` application, `ajaxguessnumber`. -See <> for more information. +See xref:faces-ajax/faces-ajax.adoc#_the_ajaxguessnumber_example_application[The ajaxguessnumber Example Application] for more information. The Ajax specific `f:ajax` tag and its attributes are explained in the next sections. diff --git a/src/main/asciidoc/faces-ajax/faces-ajax003.adoc b/src/main/antora/modules/web/pages/faces-ajax/faces-ajax003.adoc similarity index 91% rename from src/main/asciidoc/faces-ajax/faces-ajax003.adoc rename to src/main/antora/modules/web/pages/faces-ajax/faces-ajax003.adoc index 3d001f1e..08201915 100644 --- a/src/main/asciidoc/faces-ajax/faces-ajax003.adoc +++ b/src/main/antora/modules/web/pages/faces-ajax/faces-ajax003.adoc @@ -27,9 +27,9 @@ In the following example, Ajax behavior is added to an input component by includ In this example, although Ajax is enabled, the other attributes of the `f:ajax` tag are not defined. If an event is not defined, the default action for the component is performed. For the `inputText` component, when no `event` attribute is specified, the default event is `valueChange`. -<> lists the attributes of the `f:ajax` tag and their default actions. +<<_attributes_of_the_fajax_tag>> lists the attributes of the `f:ajax` tag and their default actions. -[[attributes-of-the-fajax-tag]] +[[_attributes_of_the_fajax_tag]] .Attributes of the f:ajax Tag [width="99%",cols="15%,25%,60%"] |=== @@ -66,9 +66,9 @@ If a `ValueExpression` is specified, it must refer to a property that returns a If not specified, the default value is `@none`. |=== -The keywords listed in <> can be used with the `execute` and `render` attributes of the `f:ajax` tag. +The keywords listed in <<_execute_and_render_keywords>> can be used with the `execute` and `render` attributes of the `f:ajax` tag. -[[execute-and-render-keywords]] +[[_execute_and_render_keywords]] .Execute and Render Keywords [width="60%",cols="15%,45%"] |=== @@ -84,4 +84,4 @@ The keywords listed in <> can be used with the `exe |=== Note that when you use the `f:ajax` tag in a Facelets page, the JavaScript resource library is loaded implicitly. -This resource library can also be loaded explicitly as described in <>. +This resource library can also be loaded explicitly as described in xref:faces-ajax/faces-ajax.adoc#_loading_javascript_as_a_resource[Loading JavaScript as a Resource]. diff --git a/src/main/asciidoc/faces-ajax/faces-ajax004.adoc b/src/main/antora/modules/web/pages/faces-ajax/faces-ajax004.adoc similarity index 92% rename from src/main/asciidoc/faces-ajax/faces-ajax004.adoc rename to src/main/antora/modules/web/pages/faces-ajax/faces-ajax004.adoc index 997b0859..f21d48f9 100644 --- a/src/main/asciidoc/faces-ajax/faces-ajax004.adoc +++ b/src/main/antora/modules/web/pages/faces-ajax/faces-ajax004.adoc @@ -3,7 +3,7 @@ To activate Ajax functionality, the web application must create an Ajax request and send it to the server. The server then processes the request. -The application uses the attributes of the `f:ajax` tag listed in <> to create the Ajax request. +The application uses the attributes of the `f:ajax` tag listed in xref:faces-ajax/faces-ajax.adoc#_attributes_of_the_fajax_tag[attributes of the f:ajax tag] to create the Ajax request. The following sections explain the process of creating and sending an Ajax request using some of these attributes. [NOTE] @@ -70,7 +70,7 @@ If not defined, the default value of this attribute is `false`. The `listener` attribute refers to a method expression that is executed on the server side in response to an Ajax action on the client. The listener's `jakarta.faces.event.AjaxBehaviorListener.processAjaxBehavior` method is called once during the Invoke Application phase of the lifecycle. -In the following code from the `reservation` example application (see <>), a `listener` attribute is defined by an `f:ajax` tag, which refers to a method from the bean: +In the following code from the `reservation` example application (see xref:faces-facelets/faces-facelets.adoc#_the_reservation_example_application[The reservation Example Application]), a `listener` attribute is defined by an `f:ajax` tag, which refers to a method from the bean: [source,xml] ---- diff --git a/src/main/asciidoc/faces-ajax/faces-ajax005.adoc b/src/main/antora/modules/web/pages/faces-ajax/faces-ajax005.adoc similarity index 90% rename from src/main/asciidoc/faces-ajax/faces-ajax005.adoc rename to src/main/antora/modules/web/pages/faces-ajax/faces-ajax005.adoc index bf4a8f9a..9007a491 100644 --- a/src/main/asciidoc/faces-ajax/faces-ajax005.adoc +++ b/src/main/antora/modules/web/pages/faces-ajax/faces-ajax005.adoc @@ -5,9 +5,9 @@ The value of this attribute is the name of a JavaScript function. Jakarta Faces calls the `onevent` function at each stage of the processing of an Ajax request: begin, complete, and success. When calling the JavaScript function assigned to the `onevent` property, Jakarta Faces passes a data object to it. -The data object contains the properties listed in <>. +The data object contains the properties listed in <<_properties_of_the_onevent_data_object>>. -[[properties-of-the-onevent-data-object]] +[[_properties_of_the_onevent_data_object]] .Properties of the onevent Data Object [width="60%",cols="15%,45%"] |=== diff --git a/src/main/asciidoc/faces-ajax/faces-ajax006.adoc b/src/main/antora/modules/web/pages/faces-ajax/faces-ajax006.adoc similarity index 89% rename from src/main/asciidoc/faces-ajax/faces-ajax006.adoc rename to src/main/antora/modules/web/pages/faces-ajax/faces-ajax006.adoc index 329e3dce..757ccad0 100644 --- a/src/main/asciidoc/faces-ajax/faces-ajax006.adoc +++ b/src/main/antora/modules/web/pages/faces-ajax/faces-ajax006.adoc @@ -13,9 +13,9 @@ The data object contains all the properties available for the `onevent` attribut * `errorMessage` The `type` is `error`. -The `status` property of the data object contains one of the valid error values listed in <>. +The `status` property of the data object contains one of the valid error values listed in <<_valid_error_values_for_the_data_object_status_property>>. -[[valid-error-values-for-the-data-object-status-property]] +[[_valid_error_values_for_the_data_object_status_property]] .Valid Error Values for the Data Object status Property [width="60%",cols="15%,45%"] |=== diff --git a/src/main/asciidoc/faces-ajax/faces-ajax007.adoc b/src/main/antora/modules/web/pages/faces-ajax/faces-ajax007.adoc similarity index 100% rename from src/main/asciidoc/faces-ajax/faces-ajax007.adoc rename to src/main/antora/modules/web/pages/faces-ajax/faces-ajax007.adoc diff --git a/src/main/asciidoc/faces-ajax/faces-ajax008.adoc b/src/main/antora/modules/web/pages/faces-ajax/faces-ajax008.adoc similarity index 82% rename from src/main/asciidoc/faces-ajax/faces-ajax008.adoc rename to src/main/antora/modules/web/pages/faces-ajax/faces-ajax008.adoc index 4cdaf006..35eedbc6 100644 --- a/src/main/asciidoc/faces-ajax/faces-ajax008.adoc +++ b/src/main/antora/modules/web/pages/faces-ajax/faces-ajax008.adoc @@ -2,7 +2,7 @@ An Ajax request varies from other typical Jakarta Faces requests, and its processing is also handled differently by the Jakarta Faces lifecycle. -As described in <>, when an Ajax request is received, the state associated with that request is captured by the `jakarta.faces.context.PartialViewContext`. +As described in xref:faces-intro/faces-intro.adoc#_partial_processing_and_partial_rendering[Partial Processing and Partial Rendering], when an Ajax request is received, the state associated with that request is captured by the `jakarta.faces.context.PartialViewContext`. This object provides access to information such as which components are targeted for processing/rendering. The `processPartial` method of `PartialViewContext` uses this information to perform partial component tree processing and rendering. diff --git a/src/main/asciidoc/faces-ajax/faces-ajax009.adoc b/src/main/antora/modules/web/pages/faces-ajax/faces-ajax009.adoc similarity index 100% rename from src/main/asciidoc/faces-ajax/faces-ajax009.adoc rename to src/main/antora/modules/web/pages/faces-ajax/faces-ajax009.adoc diff --git a/src/main/asciidoc/faces-ajax/faces-ajax010.adoc b/src/main/antora/modules/web/pages/faces-ajax/faces-ajax010.adoc similarity index 81% rename from src/main/asciidoc/faces-ajax/faces-ajax010.adoc rename to src/main/antora/modules/web/pages/faces-ajax/faces-ajax010.adoc index 5bde4d33..84da0c27 100644 --- a/src/main/asciidoc/faces-ajax/faces-ajax010.adoc +++ b/src/main/antora/modules/web/pages/faces-ajax/faces-ajax010.adoc @@ -9,9 +9,9 @@ You may want to use the `h:outputScript` tag to specify other JavaScript librari To use a JavaScript resource directly with a `UIComponent`, you must explicitly load the resource as described in either of the following topics: -* <> – Uses the `h:outputScript` tag directly in a Facelets page +* <<_using_javascript_api_in_a_facelets_application>> – Uses the `h:outputScript` tag directly in a Facelets page -* <> – Uses the `jakarta.faces.application.ResourceDependency` annotation on a `UIComponent` Java class +* <<_using_the_resourcedependency_annotation_in_a_bean_class>> – Uses the `jakarta.faces.application.ResourceDependency` annotation on a `UIComponent` Java class === Using JavaScript API in a Facelets Application @@ -51,17 +51,17 @@ For example, consider the following: The `faces.ajax.request` method takes up to three parameters that specify source, event, and options. The source parameter identifies the DOM element that triggered the Ajax request, typically `this`. The optional event parameter identifies the DOM event that triggered this request. -The optional options parameter contains a set of name/value pairs from <>. +The optional options parameter contains a set of name/value pairs from <<_possible_values_for_the_options_parameter>>. + -[[possible-values-for-the-options-parameter]] +[[_possible_values_for_the_options_parameter]] .Possible Values for the Options Parameter [width="70%",cols="15%,55%"] |=== |Name |Value -|`execute` |A space-delimited list of client identifiers or one of the keywords listed in <>. The identifiers reference the components that will be processed during the Execute phase of the lifecycle. +|`execute` |A space-delimited list of client identifiers or one of the keywords listed in xref:faces-ajax/faces-ajax.adoc#_execute_and_render_keywords[Execute And Render Keywords]. The identifiers reference the components that will be processed during the Execute phase of the lifecycle. -|`render` |A space-delimited list of client identifiers or one of the keywords listed in <>. The identifiers reference the components that will be processed during the render phase of the lifecycle. +|`render` |A space-delimited list of client identifiers or one of the keywords listed in xref:faces-ajax/faces-ajax.adoc#_execute_and_render_keywords[Execute And Render Keywords]. The identifiers reference the components that will be processed during the render phase of the lifecycle. |`onevent` |A `String` that is the name of the JavaScript function to call when an event occurs. diff --git a/src/main/asciidoc/faces-ajax/faces-ajax011.adoc b/src/main/antora/modules/web/pages/faces-ajax/faces-ajax011.adoc similarity index 85% rename from src/main/asciidoc/faces-ajax/faces-ajax011.adoc rename to src/main/antora/modules/web/pages/faces-ajax/faces-ajax011.adoc index 70f58918..04efbf16 100644 --- a/src/main/asciidoc/faces-ajax/faces-ajax011.adoc +++ b/src/main/antora/modules/web/pages/faces-ajax/faces-ajax011.adoc @@ -1,10 +1,10 @@ == The ajaxguessnumber Example Application -To demonstrate the advantages of using Ajax, revisit the `guessnumber` example from xref:introduction-to-facelets[xrefstyle=full]. +To demonstrate the advantages of using Ajax, revisit the `guessnumber` example from xref:faces-facelets/faces-facelets.adoc#_introduction_to_facelets[Introduction to Facelets]. If you modify this example to use Ajax, the response need not be displayed on the `response.xhtml` page. Instead, an asynchronous call is made to the bean on the server side, and the response is displayed on the originating page by executing just the input component rather than by form submission. -The source code for this application is in the `_tut-install_/examples/web/faces/ajaxguessnumber/` directory. +The source code for this application is in the `_jakartaee-examples_/tutorial/web/faces/ajaxguessnumber/` directory. === The ajaxguessnumber Source Files @@ -99,7 +99,7 @@ It is injected into `UserNumberBean` with the CDI `@Inject` annotation so that t DukesNumberBean dukesNumberBean; ---- -You will learn more about CDI in xref:introduction-to-jakarta-contexts-and-dependency-injection[xrefstyle=full]. +You will learn more about CDI in xref:cdi:cdi-basic/cdi-basic.adoc#_introduction_to_jakarta_contexts_and_dependency_injection[Introduction to Jakarta Contexts and Dependency Injection]. === Running the ajaxguessnumber Example @@ -107,14 +107,14 @@ You can use either NetBeans IDE or Maven to build, package, deploy, and run the ==== To Build, Package, and Deploy the ajaxguessnumber Example Using NetBeans IDE -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . From the *File* menu, choose *Open Project*. . In the Open Project dialog box, navigate to: + ---- -tut-install/examples/web/faces +jakartaee-examples/tutorial/web/faces ---- . Select the `ajaxguessnumber` folder. @@ -127,12 +127,12 @@ This command builds and deploys the project. ==== To Build, Package, and Deploy the ajaxguessnumber Example Using Maven -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . In a terminal window, go to: + ---- -tut-install/examples/web/faces/ajaxguessnumber/ +jakartaee-examples/tutorial/web/faces/ajaxguessnumber/ ---- . Enter the following command: diff --git a/src/main/asciidoc/faces-ajax/faces-ajax012.adoc b/src/main/antora/modules/web/pages/faces-ajax/faces-ajax012.adoc similarity index 100% rename from src/main/asciidoc/faces-ajax/faces-ajax012.adoc rename to src/main/antora/modules/web/pages/faces-ajax/faces-ajax012.adoc diff --git a/src/main/asciidoc/faces-configure/faces-configure.adoc b/src/main/antora/modules/web/pages/faces-configure/faces-configure.adoc similarity index 88% rename from src/main/asciidoc/faces-configure/faces-configure.adoc rename to src/main/antora/modules/web/pages/faces-configure/faces-configure.adoc index a1426873..09de0a8d 100644 --- a/src/main/asciidoc/faces-configure/faces-configure.adoc +++ b/src/main/antora/modules/web/pages/faces-configure/faces-configure.adoc @@ -1,5 +1,7 @@ = Configuring Jakarta Faces Applications +include::ROOT:partial$not_updated.adoc[] + This chapter describes additional configuration tasks required when you create large and complex applications. include::faces-configure001.adoc[] @@ -10,6 +12,8 @@ include::faces-configure003.adoc[] include::faces-configure004.adoc[] +include::faces-configure005.adoc[] + include::faces-configure006.adoc[] include::faces-configure007.adoc[] diff --git a/src/main/asciidoc/faces-configure/faces-configure001.adoc b/src/main/antora/modules/web/pages/faces-configure/faces-configure001.adoc similarity index 56% rename from src/main/asciidoc/faces-configure/faces-configure001.adoc rename to src/main/antora/modules/web/pages/faces-configure/faces-configure001.adoc index a33f9699..ab1ecb3d 100644 --- a/src/main/asciidoc/faces-configure/faces-configure001.adoc +++ b/src/main/antora/modules/web/pages/faces-configure/faces-configure001.adoc @@ -1,6 +1,6 @@ == Introduction to Configuring Jakarta Faces Applications -The process of building and deploying simple Jakarta Faces applications is described in earlier chapters of this tutorial, including xref:getting-started-with-web-applications[xrefstyle=full], xref:introduction-to-facelets[xrefstyle=full], xref:using-ajax-with-jakarta-faces-technology[xrefstyle=full] and xref:composite-components-advanced-topics-and-an-example[xrefstyle=full] When you create large and complex applications, however, various additional configuration tasks are required. +The process of building and deploying simple Jakarta Faces applications is described in earlier chapters of this tutorial, including xref:webapp/webapp.adoc#_getting_started_with_web_applications[Getting Started with Web Applications], xref:faces-facelets/faces-facelets.adoc#_introduction_to_facelets[Introduction to Facelets], xref:faces-ajax/faces-ajax.adoc#_using_ajax_with_jakarta_faces_technology[Using Ajax with Jakarta Faces Technology] and xref:faces-advanced-cc/faces-advanced-cc.adoc#_composite_components_advanced_topics_and_an_example[Composite Components: Advanced Topics and an Example] When you create large and complex applications, however, various additional configuration tasks are required. These tasks include the following: * Registering managed beans with the application so that all parts of the application have access to them diff --git a/src/main/asciidoc/faces-configure/faces-configure002.adoc b/src/main/antora/modules/web/pages/faces-configure/faces-configure002.adoc similarity index 75% rename from src/main/asciidoc/faces-configure/faces-configure002.adoc rename to src/main/antora/modules/web/pages/faces-configure/faces-configure002.adoc index 706c06d8..95177d98 100644 --- a/src/main/asciidoc/faces-configure/faces-configure002.adoc +++ b/src/main/antora/modules/web/pages/faces-configure/faces-configure002.adoc @@ -3,7 +3,7 @@ [NOTE] In Jakarta Faces 2.3, managed bean annotations are deprecated; CDI is now the preferred approach. -Jakarta Faces support for bean annotations is introduced in xref:jakarta-faces-technology-2[xrefstyle=full]. +Jakarta Faces support for bean annotations is introduced in xref:faces-intro/faces-intro.adoc#_jakarta_faces_technology[Jakarta Faces Technology]. Bean annotations can be used for configuring Jakarta Faces applications. The `@Named` (`jakarta.inject.Named`) annotation in a class, along with a scope annotation, automatically registers that class as a resource with the Jakarta Faces implementation. @@ -20,12 +20,12 @@ public class ShoppingCart ... { ... } The above code snippet shows a bean that is managed by the Jakarta Faces implementation and is available for the length of the session. -You can annotate beans with any of the scopes listed in the next section, <>. +You can annotate beans with any of the scopes listed in the next section, <<_using_managed_bean_scopes>>. All classes will be scanned for annotations at startup unless the `faces-config` element in the `faces-config.xml` file has the `metadata-complete` attribute set to `true`. Annotations are also available for other artifacts, such as components, converters, validators, and renderers, to be used in place of application configuration resource file entries. -These are discussed, along with registration of custom listeners, custom validators, and custom converters, in xref:creating-custom-ui-components-and-other-custom-objects[xrefstyle=full]. +These are discussed, along with registration of custom listeners, custom validators, and custom converters, in xref:faces-custom/faces-custom.adoc#_creating_custom_ui_components_and_other_custom_objects[Creating Custom UI Components and Other Custom Objects]. === Using Managed Bean Scopes @@ -34,14 +34,16 @@ You can specify one of the following scopes for a bean class. * Application (`jakarta.enterprise.context.ApplicationScoped`): Application scope persists across all users' interactions with a web application. -* Session (`jakarta.enterprise.context.SessionScoped`): Session scope persists across multiple HTTP requests in a web application. +* Session (`jakarta.enterprise.context.SessionScoped`): Session scope persists across multiple HTTP requests during a single HTTP session in a web application. -* Flow (`jakarta.faces.flows.FlowScoped`): Flow scope persists during a user's interaction with a specific flow of a web application. -See <> for more information. +* Flow (`jakarta.faces.flow.FlowScoped`): Flow scope persists during a user's interaction with a specific flow during a single HTTP session in a web application. +See xref:faces-configure/faces-configure.adoc#_using_faces_flows[Using Faces Flows] for more information. + +* View (`jakarta.faces.view.ViewScoped`): View scope persists across multiple HTTP postbacks on a single view during a single HTTP session in a web application. * Request (`jakarta.enterprise.context.RequestScoped`): Request scope persists during a single HTTP request in a web application. -* Dependent (`jakarta.enterprise.context.Dependent`): Indicates that the bean depends on some other bean. +* Dependent (`jakarta.enterprise.context.Dependent`): Indicates that the bean scope depends on the other bean where it's injected. You may want to use `@Dependent` when a managed bean references another managed bean. The second bean should not be in a scope (`@Dependent`) if it is supposed to be created only when it is referenced. diff --git a/src/main/asciidoc/faces-configure/faces-configure003.adoc b/src/main/antora/modules/web/pages/faces-configure/faces-configure003.adoc similarity index 100% rename from src/main/asciidoc/faces-configure/faces-configure003.adoc rename to src/main/antora/modules/web/pages/faces-configure/faces-configure003.adoc diff --git a/src/main/asciidoc/faces-configure/faces-configure004.adoc b/src/main/antora/modules/web/pages/faces-configure/faces-configure004.adoc similarity index 91% rename from src/main/asciidoc/faces-configure/faces-configure004.adoc rename to src/main/antora/modules/web/pages/faces-configure/faces-configure004.adoc index ec581190..7cad6847 100644 --- a/src/main/asciidoc/faces-configure/faces-configure004.adoc +++ b/src/main/antora/modules/web/pages/faces-configure/faces-configure004.adoc @@ -27,11 +27,11 @@ You can configure a flow programmatically, by creating a class annotated `@FlowD The configuration file can be limited to one flow, or you can use the `faces-config.xml` file to put all the flows in one place, if you have many flows in an application. The programmatic configuration places the code closer to the rest of the flow code and enables you to modularize the flows. -<> shows two flows and illustrates how they interact. +<<_two_faces_flows_and_their_interactions>> shows two flows and illustrates how they interact. -[[two-faces-flows-and-their-interactions]] +[[_two_faces_flows_and_their_interactions]] .Two Faces Flows and Their Interactions -image::jakartaeett_dt_017.svg["This figure shows two Faces flows, Flow A and Flow B. Each has a start node and two additional pages. Each has an associated managed bean. Each defines a return node, and each defines two parameters to be passed to the other flow."] +image::common:jakartaeett_dt_017.svg["This figure shows two Faces flows, Flow A and Flow B. Each has a start node and two additional pages. Each has an associated managed bean. Each defines a return node, and each defines two parameters to be passed to the other flow."] In this figure, Flow A has a start node named `flow-a` and two additional pages, `next_a1` and `next_a2`. From `next_a2`, a user can either exit the flow using the defined return node, `taskFlowReturn1`, or call Flow B, passing two parameters. @@ -44,7 +44,7 @@ Each flow also has an associated managed bean; the beans are `Flow_a_Bean` and ` Typically, you package flows in a web application using a directory structure that modularizes the flows. In the `src/main/webapp` directory of a Maven project, for example, you would place the Facelets files that are outside the flow at the top level as usual. Then the `webapp` files for each flow would be in a separate directory, and the Java files would be under `src/main/java`. -For example, the files for the application shown in <> might look like this: +For example, the files for the application shown in <<_two_faces_flows_and_their_interactions>> might look like this: ---- src/main/webapp/ @@ -61,7 +61,7 @@ src/main/webapp/ flow-b-flow.xml next_b1.xhtml next_b2.xhtml -src/main/java/ee/jakarta/tutorial/flowexample +src/main/java/jakarta/tutorial/flowexample FlowA.java Flow_a_Bean.java Flow_b_Bean.java @@ -77,7 +77,7 @@ You may want to start with a simple example like this one and build upon it. This example provides an implicit flow definition by including an empty configuration file. A configuration file that has content, or a class annotated `@FlowDefinition`, provides an explicit flow definition. -The source code for this application is in the `_tut-install_/examples/web/faces/simple-flow/` directory. +The source code for this application is in the `_jakartaee-examples_/tutorial/web/faces/simple-flow/` directory. The file layout of the `simple-flow` example looks like this: @@ -149,14 +149,14 @@ The Facelets pages use only flow-scoped data, so the example does not need a man ==== To Build, Package, and Deploy the simple-flow Example Using NetBeans IDE -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . From the *File* menu, choose *Open Project*. . In the Open Project dialog box, navigate to: + ---- -tut-install/examples/web/faces +jakartaee-examples/tutorial/web/faces ---- . Select the `simple-flow` folder. @@ -170,12 +170,12 @@ It then deploys the application to the server. ==== To Build, Package, and Deploy the simple-flow Example Using Maven -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . In a terminal window, go to: + ---- -tut-install/examples/web/faces/simple-flow/ +jakartaee-examples/tutorial/web/faces/simple-flow/ ---- . Enter the following command: @@ -211,12 +211,12 @@ Click Back to Start to return to the `index.xhtml` page. The `checkout-module` example application is considerably more complex than `simple-flow`. It shows how you might use the Faces Flows feature to implement a checkout module for an online store. -Like the hypothetical example in <>, the example application contains two flows, each of which can call the other. +Like the hypothetical example in <<_two_faces_flows_and_their_interactions>>, the example application contains two flows, each of which can call the other. Both flows have explicit flow definitions. One flow, `checkoutFlow`, is specified programmatically. The other flow, `joinFlow`, is specified in a configuration file. -The source code for this application is in the `_tut-install_/examples/web/faces/checkout-module/` directory. +The source code for this application is in the `_jakartaee-examples_/tutorial/web/faces/checkout-module/` directory. For the `checkout-module` application, the directory structure is as follows (there is also a `src/main/webapp/resources` directory with a stylesheet and an image): @@ -236,7 +236,7 @@ src/main/webapp/ joinFlow-flow.xml joinFlow.xhtml joinFlow2.xhtml -src/main/java/ee/jakarta/tutorial/checkoutmodule +src/main/java/jakarta/tutorial/checkoutmodule CheckoutBean.java CheckoutFlow.java CheckoutFlowBean.java @@ -461,14 +461,14 @@ For the `JoinFlowBean`, the return node is the `exithome.xhtml` page. ==== To Build, Package, and Deploy the checkout-module Example Using NetBeans IDE -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . From the *File* menu, choose *Open Project*. . In the Open Project dialog box, navigate to: + ---- -tut-install/examples/web/faces +jakartaee-examples/tutorial/web/faces ---- . Select the `checkout-module` folder. @@ -482,12 +482,12 @@ It then deploys the application to the server. ==== To Build, Package, and Deploy the checkout-module Example Using Maven -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . In a terminal window, go to: + ---- -tut-install/examples/web/faces/checkout-module/ +jakartaee-examples/tutorial/web/faces/checkout-module/ ---- . Enter the following command: diff --git a/src/main/antora/modules/web/pages/faces-configure/faces-configure005.adoc b/src/main/antora/modules/web/pages/faces-configure/faces-configure005.adoc new file mode 100644 index 00000000..080d7193 --- /dev/null +++ b/src/main/antora/modules/web/pages/faces-configure/faces-configure005.adoc @@ -0,0 +1,366 @@ +== Configuring Managed Beans + +When a page references a managed bean for the first time, the Jakarta Faces implementation initializes it either based on a `@Named` annotation and scope annotation in the bean class or according to its configuration in the application configuration resource file. +For information on using annotations to initialize beans, see xref:faces-configure/faces-configure.adoc#_using_annotations_to_configure_managed_beans[Using Annotations to Configure Managed Beans]. + +You can use either annotations or the application configuration resource file to instantiate managed beans that are used in a Jakarta Faces application and to store them in scope. +The managed bean creation facility is configured in the application configuration resource file using `managed-bean` XML elements to define each bean. This file is processed at application startup time. +For information on using this facility, see <<_using_the_managed_bean_element>>. + +Managed beans created in the application configuration resource file are Jakarta Faces managed beans, not CDI managed beans. + +With the managed bean creation facility, you can + +* Create beans in one centralized file that is available to the entire application, rather than conditionally instantiate beans throughout the application + +* Customize a bean's properties without any additional code + +* Customize a bean's property values directly from within the configuration file so that it is initialized with these values when it is created + +* Using `value` elements, set a property of one managed bean to be the result of evaluating another value expression + +This section shows you how to initialize beans using the managed bean creation facility. +See xref:faces-develop/faces-develop.adoc#_writing_bean_properties[Writing Bean Properties] and xref:faces-develop/faces-develop.adoc#_writing_managed_bean_methods[Writing Managed Bean Methods] for information on programming managed beans. + +=== Using the managed-bean Element + +A managed bean is initiated in the application configuration resource file using a `managed-bean` element, which represents an instance of a bean class that must exist in the application. +At runtime, the Jakarta Faces implementation processes the `managed-bean` element. +If a page references the bean and no bean instance exists, the Jakarta Faces implementation instantiates the bean as specified by the element configuration. + +Here is an example managed bean configuration from the Duke's Bookstore case study: + +[source,xml] +---- + + Book201 + dukesbookstore.model.ImageArea + application + + shape + rect + + + alt + Duke + + + coords + 67,23,212,268 + + +---- + +The `managed-bean-name` element defines the key under which the bean will be stored in a scope. +For a component's value to map to this bean, the component tag's `value` attribute must match the `managed-bean-name` up to the first period. + +The `managed-bean-class` element defines the fully qualified name of the JavaBeans component class used to instantiate the bean. + +The `managed-bean` element can contain zero or more `managed-property` elements, each corresponding to a property defined in the bean class. +These elements are used to initialize the values of the bean properties. +If you don't want a particular property initialized with a value when the bean is instantiated, do not include a `managed-property` definition for it in your application configuration resource file. + +If a `managed-bean` element does not contain other `managed-bean` elements, it can contain one `map-entries` element or `list-entries` element. +The `map-entries` element configures a set of beans that are instances of `Map`. +The `list-entries` element configures a set of beans that are instances of `List`. + +In the following example, the `newsletters` managed bean, representing a `UISelectItems` component, is configured as an `ArrayList` that represents a set of `SelectItem` objects. +Each `SelectItem` object is in turn configured as a managed bean with properties: + +[source,xml] +---- + + newsletters + java.util.ArrayList + application + + jakarta.faces.model.SelectItem + #{newsletter0} + #{newsletter1} + #{newsletter2} + #{newsletter3} + + + + newsletter0 + jakarta.faces.model.SelectItem + none + + label + Duke's Quarterly + + + value + 200 + + +... +---- + +This approach may be useful for quick-and-dirty creation of selection item lists before a development team has had time to create such lists from the database. +Note that each of the individual newsletter beans has a `managed-bean-scope` setting of `none` so that they will not themselves be placed into any scope. + +See <<_initializing_array_and_list_properties>> for more information on configuring collections as beans. + +To map to a property defined by a `managed-property` element, you must ensure that the part of a component tag's `value` expression after the period matches the `managed-property` element's `property-name` element. +The next section, <<_initializing_properties_using_the_managed_property_element>>, explains in more detail how to use the `managed-property` element. +See <<_initializing_managed_bean_properties>> for an example of initializing a managed bean property. + +=== Initializing Properties Using the managed-property Element + +A `managed-property` element must contain a `property-name` element, which must match the name of the corresponding property in the bean. +A `managed-property` element must also contain one of a set of elements that defines the value of the property. +This value must be of the same type as that defined for the property in the corresponding bean. +Which element you use to define the value depends on the type of the property defined in the bean. +<<_subelements_of_managed_property_elements_that_define_property_values>> lists all the elements that are used to initialize a value. + +[[_subelements_of_managed_property_elements_that_define_property_values]] +.Subelements of managed-property Elements That Define Property Values +[width="75%",cols="25%,50%"] +|=== +|Element |Value It Defines + +|`list-entries` |Defines the values in a list + +|`map-entries` |Defines the values of a map + +|`null-value` |Explicitly sets the property to `null` + +|`value` |Defines a single value, such as a `String`, `int`, or Jakarta Faces EL expression +|=== + +<<_using_the_managed_bean_element>> includes an example of initializing an `int` property (a primitive type) using the `value` subelement. +You also use the `value` subelement to initialize `String` and other reference types. +The rest of this section describes how to use the `value` subelement and other subelements to initialize properties of Java `Enum` types, `Map`, `array`, and `Collection`, as well as initialization parameters. + +==== Referencing a Java Enum Type + +A managed bean property can also be a Java `Enum` type (see https://docs.oracle.com/javase/8/docs/api/java/lang/Enum.html[^]). +In this case, the `value` element of the `managed-property` element must be a `String` that matches one of the `String` constants of the `Enum`. +In other words, the `String` must be one of the valid values that can be returned if you were to call `valueOf(Class, String)` on `enum`, where `Class` is the `Enum` class and `String` is the contents of the `value` subelement. +For example, suppose the managed bean property is the following: + +[source,java] +---- +public enum Suit { Hearts, Spades, Diamonds, Clubs } + ... +public Suit getSuit() { ... return Suit.Hearts; } +---- + +Assuming you want to configure this property in the application configuration resource file, the corresponding `managed-property` element looks like this: + +[source,xml] +---- + + Suit + Hearts + +---- + +When the system encounters this property, it iterates over each of the members of the `enum` and calls `toString()` on each member until it finds one that is exactly equal to the value from the `value` element. + +==== Referencing a Context Initialization Parameter + +Another powerful feature of the managed bean creation facility is the ability to reference implicit objects from a managed bean property. + +Suppose you have a page that accepts data from a customer, including the customer's address. +Suppose also that most of your customers live in a particular area code. +You can make the area code component render this area code by saving it in an implicit object and referencing it when the page is rendered. + +You can save the area code as an initial default value in the context `initParam` implicit object by adding a context parameter to your web application and setting its value in the deployment descriptor. +For example, to set a context parameter called `defaultAreaCode` to `650`, add a `context-param` element to the deployment descriptor and give the parameter the name `defaultAreaCode` and the value `650`. + +Next, write a `managed-bean` declaration that configures a property that references the parameter: + +[source,xml] +---- + + customer + CustomerBean + request + + areaCode + #{initParam.defaultAreaCode} + + ... + +---- + +To access the area code at the time the page is rendered, refer to the property from the `area` component tag's `value` attribute: + +[source,xml] +---- + +---- + +Values are retrieved from other implicit objects in a similar way. + +==== Initializing Map Properties + +The `map-entries` element is used to initialize the values of a bean property with a type of `Map` if the `map-entries` element is used within a `managed-property` element. +A `map-entries` element contains an optional `key-class` element, an optional `value-class` element, and zero or more `map-entry` elements. + +Each of the `map-entry` elements must contain a `key` element and either a `null-value` or `value` element. +Here is an example that uses the `map-entries` element: + +[source,xml] +---- + + ... + + prices + + + My Early Years: Growing Up on *7 + 30.75 + + + Web Servers for Fun and Profit + 40.75 + + + + +---- + +The map created from this `map-entries` tag contains two entries. +By default, all the keys and values are converted to `String`. +If you want to specify a different type for the keys in the map, embed the `key-class` element just inside the `map-entries` element: + +[source,xml] +---- + + java.math.BigDecimal + ... + +---- + +This declaration will convert all the keys into `java.math.BigDecimal`. +Of course, you must make sure that the keys can be converted to the type you specify. +The key from the example in this section cannot be converted to a `BigDecimal`, because it is a `String`. + +If you want to specify a different type for all the values in the map, include the `value-class` element after the `key-class` element: + +[source,xml] +---- + + int + java.math.BigDecimal + ... + +---- + +Note that this tag sets only the type of all the `value` subelements. + +Each `map-entry` in the preceding example includes a `value` subelement. +The `value` subelement defines a single value, which will be converted to the type specified in the bean. + +Instead of using a `map-entries` element, it is also possible to assign the entire map using a `value` element that specifies a map-typed expression. + +==== Initializing Array and List Properties + +The `list-entries` element is used to initialize the values of an array or `List` property. +Each individual value of the array or `List` is initialized using a `value` or `null-value` element. +Here is an example: + +[source,xml] +---- + + ... + + books + + java.lang.String + Web Servers for Fun and Profit + #{myBooks.bookId[3]} + + + + +---- + +This example initializes an array or a `List`. +The type of the corresponding property in the bean determines which data structure is created. +The `list-entries` element defines the list of values in the array or `List`. +The `value` element specifies a single value in the array or `List` and can reference a property in another bean. +The `null-value` element will cause the `setBooks` method to be called with an argument of `null`. +A `null` property cannot be specified for a property whose data type is a Java primitive, such as `int` or `boolean`. + +==== Initializing Managed Bean Properties + +Sometimes you might want to create a bean that also references other managed beans so that you can construct a graph or a tree of beans. +For example, suppose you want to create a bean representing a customer's information, including the mailing address and street address, each of which is also a bean. +The following `managed-bean` declarations create a `CustomerBean` instance that has two `AddressBean` properties: one representing the mailing address and the other representing the street address. +This declaration results in a tree of beans with `CustomerBean` as its root and the two `AddressBean` objects as children. + +[source,xml] +---- + + customer + + com.example.mybeans.CustomerBean + + request + + mailingAddress + #{addressBean} + + + streetAddress + #{addressBean} + + + customerType + New + + + + addressBean + + com.example.mybeans.AddressBean + + none + + street + + + ... + +---- + +The first `CustomerBean` declaration (with the `managed-bean-name` of `customer`) creates a `CustomerBean` in request scope. +This bean has two properties, `mailingAddress` and `streetAddress`. +These properties use the `value` element to reference a bean named `addressBean`. + +The second managed bean declaration defines an `AddressBean` but does not create it, because its `managed-bean-scope` element defines a scope of `none`. +Recall that a scope of `none` means that the bean is created only when something else references it. +Because both the `mailingAddress` and the `streetAddress` properties reference `addressBean` using the `value` element, two instances of `AddressBean` are created when `CustomerBean` is created. + +When you create an object that points to other objects, do not try to point to an object with a shorter life span, because it might be impossible to recover that scope's resources when it goes away. +A session-scoped object, for example, cannot point to a request-scoped object. +And objects with `none` scope have no effective life span managed by the framework, so they can point only to other `none`-scoped objects. +<<_allowable_connections_between_scoped_objects>> outlines all of the allowed connections. + +[[_allowable_connections_between_scoped_objects]] +.Allowable Connections between Scoped Objects +[width="60%",cols="20%,40%"] +|=== +|An Object of This Scope |May Point to an Object of This Scope + +|`none` |`none` + +|`application` |`none`, `application` + +|`session` |`none`, `application`, `session` + +|`request` |`none`, `application`, `session`, `request`, `view` + +|`view` |`none`, `application`, `session`, `view` +|=== + +Be sure not to allow cyclical references between objects. +For example, neither of the `AddressBean` objects in the preceding example should point back to the `CustomerBean` object, because `CustomerBean` already points to the `AddressBean` objects. + +=== Initializing Maps and Lists + +In addition to configuring `Map` and `List` properties, you can also configure a `Map` and a `List` directly so that you can reference them from a tag rather than referencing a property that wraps a `Map` or a `List`. diff --git a/src/main/asciidoc/faces-configure/faces-configure006.adoc b/src/main/antora/modules/web/pages/faces-configure/faces-configure006.adoc similarity index 95% rename from src/main/asciidoc/faces-configure/faces-configure006.adoc rename to src/main/antora/modules/web/pages/faces-configure/faces-configure006.adoc index 5062b103..f3daa0e0 100644 --- a/src/main/asciidoc/faces-configure/faces-configure006.adoc +++ b/src/main/antora/modules/web/pages/faces-configure/faces-configure006.adoc @@ -3,7 +3,7 @@ Application messages can include any strings displayed to the user as well as custom error messages (which are displayed by the `message` and `messages` tags) for your custom converters or validators. To make messages available at application startup time, do one of the following: -* Queue an individual message onto the `jakarta.faces.context.FacesContext` instance programmatically, as described in <> +* Queue an individual message onto the `jakarta.faces.context.FacesContext` instance programmatically, as described in <<_using_facesmessage_to_create_a_message>> * Register all the messages with your application using the application configuration resource file @@ -92,7 +92,7 @@ public static String loadErrorMessage(FacesContext context, === Referencing Error Messages -A Jakarta Faces page uses the `message` or `messages` tags to access error messages, as explained in <>. +A Jakarta Faces page uses the `message` or `messages` tags to access error messages, as explained in xref:faces-page/faces-page.adoc#_displaying_error_messages_with_the_hmessage_and_hmessages_tags[Displaying Error Messages with the h:message and h:messages Tags]. The error messages these tags access include diff --git a/src/main/asciidoc/faces-configure/faces-configure007.adoc b/src/main/antora/modules/web/pages/faces-configure/faces-configure007.adoc similarity index 100% rename from src/main/asciidoc/faces-configure/faces-configure007.adoc rename to src/main/antora/modules/web/pages/faces-configure/faces-configure007.adoc diff --git a/src/main/asciidoc/faces-configure/faces-configure008.adoc b/src/main/antora/modules/web/pages/faces-configure/faces-configure008.adoc similarity index 71% rename from src/main/asciidoc/faces-configure/faces-configure008.adoc rename to src/main/antora/modules/web/pages/faces-configure/faces-configure008.adoc index b5c2912e..ff386e6b 100644 --- a/src/main/asciidoc/faces-configure/faces-configure008.adoc +++ b/src/main/antora/modules/web/pages/faces-configure/faces-configure008.adoc @@ -1,6 +1,6 @@ == Registering a Custom Validator -If the application developer provides an implementation of the `jakarta.faces.validator.Validator` interface to perform validation, you must register this custom validator either by using the `@FacesValidator` annotation, as described in <>, or by using the `validator` XML element in the application configuration resource file: +If the application developer provides an implementation of the `jakarta.faces.validator.Validator` interface to perform validation, you must register this custom validator either by using the `@FacesValidator` annotation, as described in xref:faces-custom/faces-custom.adoc#_implementing_the_validator_interface[Implementing the Validator Interface], or by using the `validator` XML element in the application configuration resource file: [source,xml] ---- @@ -31,6 +31,6 @@ It has required `attribute-name` and `attribute-class` subelements. The `attribute-name` element refers to the name of the attribute as it appears in the `validator` tag. The `attribute-class` element identifies the Java type of the value associated with the attribute. -<> explains how to implement the `Validator` interface. +xref:faces-custom/faces-custom.adoc#_creating_and_using_a_custom_validator[Creating and Using a Custom Validator] explains how to implement the `Validator` interface. -<> explains how to reference the validator from the page. +xref:faces-custom/faces-custom.adoc#_using_a_custom_validator[Using a Custom Validator] explains how to reference the validator from the page. diff --git a/src/main/asciidoc/faces-configure/faces-configure009.adoc b/src/main/antora/modules/web/pages/faces-configure/faces-configure009.adoc similarity index 69% rename from src/main/asciidoc/faces-configure/faces-configure009.adoc rename to src/main/antora/modules/web/pages/faces-configure/faces-configure009.adoc index 8904345c..ec6a35ea 100644 --- a/src/main/asciidoc/faces-configure/faces-configure009.adoc +++ b/src/main/antora/modules/web/pages/faces-configure/faces-configure009.adoc @@ -1,6 +1,6 @@ == Registering a Custom Converter -As is the case with a custom validator, if the application developer creates a custom converter, you must register it with the application either by using the `@FacesConverter` annotation, as described in <>, or by using the `converter` XML element in the application configuration resource file. +As is the case with a custom validator, if the application developer creates a custom converter, you must register it with the application either by using the `@FacesConverter` annotation, as described in xref:faces-custom/faces-custom.adoc#_creating_a_custom_converter[Creating a Custom Converter], or by using the `converter` XML element in the application configuration resource file. Here is a hypothetical `converter` configuration for `CreditCardConverter` from the Duke's Bookstore case study: [source,xml] @@ -22,8 +22,8 @@ Attributes specified in a `converter` tag override any settings in the `@FacesCo The `converter` element represents a `jakarta.faces.convert.Converter` implementation and contains required `converter-id` and `converter-class` elements. The `converter-id` element identifies an ID that is used by the `converter` attribute of a UI component tag to apply the converter to the component's data. -<> includes an example of referencing the custom converter from a component tag. +xref:faces-custom/faces-custom.adoc#_using_a_custom_converter[Using a Custom Converter] includes an example of referencing the custom converter from a component tag. The `converter-class` element identifies the `Converter` implementation. -<> explains how to create a custom converter. +xref:faces-custom/faces-custom.adoc#_creating_and_using_a_custom_converter[Creating and Using a Custom Converter] explains how to create a custom converter. diff --git a/src/main/asciidoc/faces-configure/faces-configure010.adoc b/src/main/antora/modules/web/pages/faces-configure/faces-configure010.adoc similarity index 94% rename from src/main/asciidoc/faces-configure/faces-configure010.adoc rename to src/main/antora/modules/web/pages/faces-configure/faces-configure010.adoc index 600153d4..47b28417 100644 --- a/src/main/asciidoc/faces-configure/faces-configure010.adoc +++ b/src/main/antora/modules/web/pages/faces-configure/faces-configure010.adoc @@ -2,7 +2,7 @@ Navigation between different pages of a Jakarta Faces application, such as choosing the next page to be displayed after a button or link component is clicked, is defined by a set of rules. Navigation rules can be implicit, or they can be explicitly defined in the application configuration resource file. -For more information on implicit navigation rules, see <>. +For more information on implicit navigation rules, see xref:faces-intro/faces-intro.adoc#_navigation_model[Navigation Model]. Each navigation rule specifies how to navigate from one page to another page or set of pages. The Jakarta Faces implementation chooses the proper navigation rule according to which page is currently displayed. @@ -13,9 +13,9 @@ After the proper navigation rule is selected, the choice of which page to access * The logical outcome referenced by the component's tag or returned from the action method -The outcome can be anything the developer chooses, but <> lists some outcomes commonly used in web applications. +The outcome can be anything the developer chooses, but <<_common_outcome_strings>> lists some outcomes commonly used in web applications. -[[common-outcome-strings]] +[[_common_outcome_strings]] .Common Outcome Strings [width="60%",cols="15%,45%"] |=== diff --git a/src/main/asciidoc/faces-configure/faces-configure011.adoc b/src/main/antora/modules/web/pages/faces-configure/faces-configure011.adoc similarity index 92% rename from src/main/asciidoc/faces-configure/faces-configure011.adoc rename to src/main/antora/modules/web/pages/faces-configure/faces-configure011.adoc index 9c768fb9..ddc878fe 100644 --- a/src/main/asciidoc/faces-configure/faces-configure011.adoc +++ b/src/main/antora/modules/web/pages/faces-configure/faces-configure011.adoc @@ -1,9 +1,9 @@ == Registering a Custom Renderer with a Render Kit -When the application developer creates a custom renderer, as described in <>, you must register it using the appropriate render kit. +When the application developer creates a custom renderer, as described in xref:faces-custom/faces-custom.adoc#_delegating_rendering_to_a_renderer[Delegating Rendering to a Renderer], you must register it using the appropriate render kit. Because the image map application implements an HTML image map, the `AreaRenderer` and `MapRenderer` classes in the Duke's Bookstore case study should be registered using the HTML render kit. -You register the renderer either by using the `@FacesRenderer` annotation, as described in <>, or by using the `render-kit` element of the application configuration resource file. +You register the renderer either by using the `@FacesRenderer` annotation, as described in xref:faces-custom/faces-custom.adoc#_creating_the_renderer_class[Creating the Renderer Class], or by using the `render-kit` element of the application configuration resource file. Here is a hypothetical configuration of `AreaRenderer`: [source,xml] diff --git a/src/main/asciidoc/faces-configure/faces-configure012.adoc b/src/main/antora/modules/web/pages/faces-configure/faces-configure012.adoc similarity index 80% rename from src/main/asciidoc/faces-configure/faces-configure012.adoc rename to src/main/antora/modules/web/pages/faces-configure/faces-configure012.adoc index 3e4747da..010ef550 100644 --- a/src/main/asciidoc/faces-configure/faces-configure012.adoc +++ b/src/main/antora/modules/web/pages/faces-configure/faces-configure012.adoc @@ -1,7 +1,7 @@ == Registering a Custom Component In addition to registering custom renderers (as explained in the preceding section), you also must register the custom components that are usually associated with the custom renderers. -You use either a `@FacesComponent` annotation, as described in <>, or the `component` element of the application configuration resource file. +You use either a `@FacesComponent` annotation, as described in xref:faces-custom/faces-custom.adoc#_creating_custom_component_classes[Creating Custom Component Classes], or the `component` element of the application configuration resource file. Here is a hypothetical `component` element from the application configuration resource file that registers `AreaComponent`: @@ -37,4 +37,4 @@ The `component-class` element indicates the fully qualified class name of the co The `property` elements specify the component properties and their types. If the custom component can include facets, you can configure the facets in the component configuration using `facet` elements, which are allowed after the `component-class` elements. -See <> for further details on configuring facets. +See xref:faces-configure/faces-configure.adoc#_registering_a_custom_renderer_with_a_render_kit[Registering a Custom Renderer with a Render Kit] for further details on configuring facets. diff --git a/src/main/asciidoc/faces-configure/faces-configure013.adoc b/src/main/antora/modules/web/pages/faces-configure/faces-configure013.adoc similarity index 93% rename from src/main/asciidoc/faces-configure/faces-configure013.adoc rename to src/main/antora/modules/web/pages/faces-configure/faces-configure013.adoc index 6e00c4e4..f8c14bc7 100644 --- a/src/main/asciidoc/faces-configure/faces-configure013.adoc +++ b/src/main/antora/modules/web/pages/faces-configure/faces-configure013.adoc @@ -73,7 +73,7 @@ A requirement of a Jakarta Faces application is that all requests to the applica A `FacesServlet` instance manages the request-processing lifecycle for web applications and initializes the resources required by Jakarta Faces technology. Before a Jakarta Faces application can launch its first web page, the web container must invoke the `FacesServlet` instance in order for the application lifecycle process to start. -See <> for more information. +See xref:faces-intro/faces-intro.adoc#_the_lifecycle_of_a_jakarta_faces_application[The Lifecycle of a Jakarta Faces Application] for more information. The following example shows the default configuration of the `FacesServlet`: @@ -133,7 +133,7 @@ If you created your application without an IDE, you can create a web deployment ==== To Specify a Path to an Application Configuration Resource File -As explained in <>, an application can have multiple application configuration resource files. +As explained in xref:faces-configure/faces-configure.adoc#_application_configuration_resource_file[Application Configuration Resource File], an application can have multiple application configuration resource files. If these files are not located in the directories that the implementation searches by default or the files are not named `faces-config.xml`, you need to specify paths to these files. To specify these paths using NetBeans IDE, do the following. @@ -165,7 +165,7 @@ To specify these paths using NetBeans IDE, do the following. For all the components in a web application, you can specify in your deployment descriptor where you want the state to be saved, on either client or server. You do this by setting a context parameter in your deployment descriptor. By default, state is saved on the server, so you need to specify this context parameter only if you want to save state on the client. -See <> for information on the advantages and disadvantages of each location. +See xref:faces-custom/faces-custom.adoc#_saving_and_restoring_state[Saving and Restoring State] for information on the advantages and disadvantages of each location. To specify where state is saved using NetBeans IDE, do the following. @@ -236,7 +236,7 @@ When packaging web applications using the included build scripts, you'll notice * All application JAR files are packaged in the `WEB-INF/lib/` directory. * All resource files are either under the root of the web application `/resources` directory or in the web application's classpath, the `META-INF/resources/_resourceIdentifier_` directory. -For more information on resources, see <>. +For more information on resources, see xref:faces-facelets/faces-facelets.adoc#_web_resources[Web Resources]. When packaging your own applications, you can use NetBeans IDE or you can use XML files such as those created for Maven. You can modify the XML files to fit your situation. diff --git a/src/main/asciidoc/faces-custom/faces-custom.adoc b/src/main/antora/modules/web/pages/faces-custom/faces-custom.adoc similarity index 94% rename from src/main/asciidoc/faces-custom/faces-custom.adoc rename to src/main/antora/modules/web/pages/faces-custom/faces-custom.adoc index dfba3d3f..f2234558 100644 --- a/src/main/asciidoc/faces-custom/faces-custom.adoc +++ b/src/main/antora/modules/web/pages/faces-custom/faces-custom.adoc @@ -1,5 +1,7 @@ = Creating Custom UI Components and Other Custom Objects +include::ROOT:partial$not_updated.adoc[] + This chapter describes creating custom components for applications that have additional functionality not provided by standard Jakarta Faces components. include::faces-custom001.adoc[] diff --git a/src/main/asciidoc/faces-custom/faces-custom001.adoc b/src/main/antora/modules/web/pages/faces-custom/faces-custom001.adoc similarity index 91% rename from src/main/asciidoc/faces-custom/faces-custom001.adoc rename to src/main/antora/modules/web/pages/faces-custom/faces-custom001.adoc index 687fa4ba..4ee96d77 100644 --- a/src/main/asciidoc/faces-custom/faces-custom001.adoc +++ b/src/main/antora/modules/web/pages/faces-custom/faces-custom001.adoc @@ -28,10 +28,10 @@ Most Jakarta Faces component libraries provide their own render kits. A `jakarta.faces.view.facelets.Tag` object is a helper to the `UIComponent` and `Renderer` that allows the page author to include an instance of a `UIComponent` in a Jakarta Faces view. A tag represents a specific combination of `component-type` and `renderer-type`. -See <> for information on how components, renderers, and tags interact. +See xref:faces-custom/faces-custom.adoc#_component_renderer_and_tag_combinations[Component, Renderer, and Tag Combinations] for information on how components, renderers, and tags interact. This chapter uses the image map component from the Duke's Bookstore case study example to explain how you can create simple custom components, custom renderers, and associated custom tags, and take care of all the other details associated with using the components and renderers in an application. -See xref:dukes-bookstore-case-study-example[xrefstyle=full] for more information about this example. +See xref:casestudies:dukes-bookstore/dukes-bookstore.adoc#_dukes_bookstore_case_study_example[Duke's Bookstore Case Study Example] for more information about this example. The chapter also describes how to create other custom objects: custom converters, custom listeners, and custom validators. It also describes how to bind component values and instances to data objects and how to bind custom objects to managed bean properties. diff --git a/src/main/asciidoc/faces-custom/faces-custom002.adoc b/src/main/antora/modules/web/pages/faces-custom/faces-custom002.adoc similarity index 84% rename from src/main/asciidoc/faces-custom/faces-custom002.adoc rename to src/main/antora/modules/web/pages/faces-custom/faces-custom002.adoc index 14efd7db..e02152f1 100644 --- a/src/main/asciidoc/faces-custom/faces-custom002.adoc +++ b/src/main/antora/modules/web/pages/faces-custom/faces-custom002.adoc @@ -28,22 +28,22 @@ You do not need to create a custom component in the following cases. * You need to aggregate components to create a new component that has its own unique behavior. In this situation, you can use a composite component to combine existing standard components. -For more information on composite components, see <> and xref:composite-components-advanced-topics-and-an-example[xrefstyle=full]. +For more information on composite components, see xref:faces-facelets/faces-facelets.adoc#_composite_components[Composite Components] and xref:faces-advanced-cc/faces-advanced-cc.adoc#_composite_components_advanced_topics_and_an_example[Composite Components: Advanced Topics and an Example]. * You simply need to manipulate data on the component or add application-specific functionality to it. In this situation, you should create a managed bean for this purpose and bind it to the standard component rather than create a custom component. -See <> for more information on managed beans. +See xref:faces-develop/faces-develop.adoc#_managed_beans_in_jakarta_faces_technology[Managed Beans in Jakarta Faces Technology] for more information on managed beans. * You need to convert a component's data to a type not supported by its renderer. -See <> for more information about converting a component's data. +See xref:faces-page-core/faces-page-core.adoc#_using_the_standard_converters[Using the Standard Converters] for more information about converting a component's data. * You need to perform validation on the component data. Standard validators and custom validators can be added to a component by using the validator tags from the page. -See <> and <> for more information about validating a component's data. +See xref:faces-page-core/faces-page-core.adoc#_using_the_standard_validators[Using the Standard Validators] and xref:faces-custom/faces-custom.adoc#_creating_and_using_a_custom_validator[Creating and Using a Custom Validator] for more information about validating a component's data. * You need to register event listeners on components. You can either register event listeners on components using the `f:valueChangeListener` and `f:actionListener` tags, or you can point at an event-processing method on a managed bean using the component's `actionListener` or `valueChangeListener` attributes. -See <> and <> for more information. +See xref:faces-custom/faces-custom.adoc#_implementing_an_event_listener[Implementing an Event Listener] and xref:faces-develop/faces-develop.adoc#_writing_managed_bean_methods[Writing Managed Bean Methods] for more information. === When to Use a Custom Renderer @@ -93,9 +93,9 @@ For example, suppose that you need to create a custom validator that requires ex In this case, the custom tag corresponds to a custom validator and not to a custom component or custom renderer. In any case, you still need to associate the custom tag with a server-side object. -<> summarizes what you must or can associate with a custom component, custom renderer, or custom tag. +<<_requirements_for_custom_components_custom_renderers_and_custom_tags>> summarizes what you must or can associate with a custom component, custom renderer, or custom tag. -[[requirements-for-custom-components-custom-renderers-and-custom-tags]] +[[_requirements_for_custom_components_custom_renderers_and_custom_tags]] .Requirements for Custom Components, Custom Renderers and Custom Tags [width="90%",cols="34%,30%,36%"] |=== diff --git a/src/main/asciidoc/faces-custom/faces-custom003.adoc b/src/main/antora/modules/web/pages/faces-custom/faces-custom003.adoc similarity index 92% rename from src/main/asciidoc/faces-custom/faces-custom003.adoc rename to src/main/antora/modules/web/pages/faces-custom/faces-custom003.adoc index e0e2df5c..5a1ed4d1 100644 --- a/src/main/asciidoc/faces-custom/faces-custom003.adoc +++ b/src/main/antora/modules/web/pages/faces-custom/faces-custom003.adoc @@ -97,10 +97,10 @@ The `alt` attribute of the `h:graphicImage` tag maps to the localized string `"C The `f:actionListener` tag within the `bookstore:map` tag points to a listener class for an action event. The `processAction` method of the listener places the book ID for the selected map area into the session map. -The way this event is handled is explained more in <>. +The way this event is handled is explained more in xref:faces-custom/faces-custom.adoc#_handling_events_for_custom_components[Handling Events for Custom Components]. The `action` attribute of the `bookstore:map` tag specifies a logical outcome `String`, `"bookstore"`, which by implicit navigation rules sends the application to the page `bookstore.xhtml`. -For more information on navigation, see <>. +For more information on navigation, see xref:faces-configure/faces-configure.adoc#_configuring_navigation_rules[Configuring Navigation Rules]. The `immediate` attribute of the `bookstore:map` tag is set to `true`, which indicates that the default `jakarta.faces.event.ActionListener` implementation should execute during the Apply Request Values phase of the request-processing lifecycle, instead of waiting for the Invoke Application phase. Because the request resulting from clicking the map does not require any validation, data conversion, or server-side object updates, it makes sense to skip directly to the Invoke Application phase. @@ -110,7 +110,7 @@ The `current` attribute of the `bookstore:map` tag is set to the default area, w Notice that the `bookstore:area` tags do not contain any of the JavaScript, coordinate, or shape data that is displayed on the HTML page. The JavaScript is generated by the `dukesbookstore.renderers.AreaRenderer` class. The `onmouseover` and `onmouseout` attribute values indicate the image to be loaded when these events occur. -How the JavaScript is generated is explained more in <>. +How the JavaScript is generated is explained more in xref:faces-custom/faces-custom.adoc#_performing_encoding[Performing Encoding]. The coordinate, shape, and alternate text data are obtained through the `value` attribute, whose value refers to an attribute in application scope. The value of this attribute is a bean, which stores the `coords`, `shape`, and `alt` data. @@ -118,9 +118,9 @@ How these beans are stored in the application scope is explained more in the nex === Summary of the Image Map Application Classes -<> summarizes all the classes needed to implement the image map component. +<<_image_map_classes>> summarizes all the classes needed to implement the image map component. -[[image-map-classes]] +[[_image_map_classes]] .Image Map Classes [width="60%",cols="15%,45%"] |=== @@ -139,7 +139,7 @@ How these beans are stored in the application scope is explained more in the nex |`MapBookChangeListener` a|The action listener for the `MapComponent`. |=== -The Duke's Bookstore source directory, called bookstore-dir, is `_tut-install_/examples/case-studies/dukes-bookstore/src/java/dukesbookstore/`. +The Duke's Bookstore source directory, called bookstore-dir, is `_jakartaee-examples_/tutorial/case-studies/dukes-bookstore/src/main/java/jakarta/tutorial/dukesbookstore/`. The event and listener classes are located in `_bookstore-dir_/listeners/`. The component classes are located in `_bookstore-dir_/components/`. The renderer classes are located in `_bookstore-dir_/renderers/`. diff --git a/src/main/asciidoc/faces-custom/faces-custom004.adoc b/src/main/antora/modules/web/pages/faces-custom/faces-custom004.adoc similarity index 55% rename from src/main/asciidoc/faces-custom/faces-custom004.adoc rename to src/main/antora/modules/web/pages/faces-custom/faces-custom004.adoc index 6a9b07b3..6a705d2d 100644 --- a/src/main/asciidoc/faces-custom/faces-custom004.adoc +++ b/src/main/antora/modules/web/pages/faces-custom/faces-custom004.adoc @@ -6,7 +6,7 @@ You can apply the following steps while developing your own custom component. .. Overrides the `getFamily` method to return the component family, which is used to look up renderers that can render the component -.. Includes the rendering code or delegates it to a renderer (explained in <>) +.. Includes the rendering code or delegates it to a renderer (explained in <<_create_custom_component_step_2>>) .. Enables component attributes to accept expressions @@ -14,7 +14,7 @@ You can apply the following steps while developing your own custom component. .. Saves and restores the component state -. [[create-custom-component-step-2, Step 2]] Delegate rendering to a renderer if your component does not handle the rendering. +. [[_create_custom_component_step_2, Step 2]] Delegate rendering to a renderer if your component does not handle the rendering. To do this: .. Create a custom renderer class by extending `jakarta.faces.render.Renderer`. @@ -27,5 +27,5 @@ To do this: . Create a tag library descriptor (TLD) that defines the custom tag. -See <> and <> for information on registering the custom component and the renderer. -The section <> discusses how to use the custom component in a Jakarta Faces page. +See xref:faces-configure/faces-configure.adoc#_registering_a_custom_component[Registering a Custom Component] and xref:faces-configure/faces-configure.adoc#_registering_a_custom_renderer_with_a_render_kit[Registering a Custom Renderer with a Render Kit] for information on registering the custom component and the renderer. +The section xref:faces-custom/faces-custom.adoc#_using_a_custom_component[Using a Custom Component] discusses how to use the custom component in a Jakarta Faces page. diff --git a/src/main/asciidoc/faces-custom/faces-custom005.adoc b/src/main/antora/modules/web/pages/faces-custom/faces-custom005.adoc similarity index 94% rename from src/main/asciidoc/faces-custom/faces-custom005.adoc rename to src/main/antora/modules/web/pages/faces-custom/faces-custom005.adoc index 0aafbd54..3069a0f5 100644 --- a/src/main/asciidoc/faces-custom/faces-custom005.adoc +++ b/src/main/antora/modules/web/pages/faces-custom/faces-custom005.adoc @@ -1,6 +1,6 @@ == Creating Custom Component Classes -As explained in <>, a component class defines the state and behavior of a UI component. +As explained in xref:faces-custom/faces-custom.adoc#_when_to_use_a_custom_component[When to Use a Custom Component], a component class defines the state and behavior of a UI component. The state information includes the component's type, identifier, and local value. The behavior defined by the component class includes the following: @@ -109,7 +109,7 @@ Its behavior consists of the following actions: `MapComponent` delegates the rendering of the HTML `map` and `input` tags to the `MapRenderer` class. `AreaComponent` is bound to a bean that stores the shape and coordinates of the region of the image map. -You will see how all this data is accessed through the value expression in <>. +You will see how all this data is accessed through the value expression in xref:faces-custom/faces-custom.adoc#_creating_the_renderer_class[Creating the Renderer Class]. The behavior of `AreaComponent` consists of the following: * Retrieving the shape and coordinate data from the bean @@ -119,10 +119,10 @@ The behavior of `AreaComponent` consists of the following: * Rendering the `area` tag, including the JavaScript for the `onmouseover`, `onmouseout`, and `onclick` functions Although these tasks are actually performed by `AreaRenderer`, `AreaComponent` must delegate the tasks to `AreaRenderer`. -See <> for more information. +See xref:faces-custom/faces-custom.adoc#_delegating_rendering_to_a_renderer[Delegating Rendering to a Renderer] for more information. The rest of this section describes the tasks that `MapComponent` performs as well as the encoding and decoding that it delegates to `MapRenderer`. -<> details how `MapComponent` handles events. +xref:faces-custom/faces-custom.adoc#_handling_events_for_custom_components[Handling Events for Custom Components] details how `MapComponent` handles events. === Specifying the Component Family @@ -137,8 +137,8 @@ public String getFamily() { ---- The component family identifier, `Map`, must match that defined by the `component-family` elements included in the component and renderer configurations in the application configuration resource file. -<> explains how to define the component family in the renderer configuration. -<> explains how to define the component family in the component configuration. +xref:faces-configure/faces-configure.adoc#_registering_a_custom_renderer_with_a_render_kit[Registering a Custom Renderer with a Render Kit] explains how to define the component family in the renderer configuration. +xref:faces-configure/faces-configure.adoc#_registering_a_custom_component[Registering a Custom Component] explains how to define the component family in the component configuration. === Performing Encoding @@ -316,7 +316,7 @@ public void setAction(MethodExpression action) { === Saving and Restoring State -As described in <>, use of the `StateHelper` interface facilities allows you to save the component's state at the same time you set and retrieve property values. +As described in <<_enabling_component_properties_to_accept_expressions>>, use of the `StateHelper` interface facilities allows you to save the component's state at the same time you set and retrieve property values. The `StateHelper` implementation allows partial state saving; it saves only the changes in the state since the initial request, not the entire state, because the full state can be restored during the Restore View phase. Component classes that implement `StateHolder` may prefer to implement the `saveState(FacesContext)` and `restoreState(FacesContext, Object)` methods to help the Jakarta Faces implementation save and restore the state of components across multiple requests. diff --git a/src/main/asciidoc/faces-custom/faces-custom006.adoc b/src/main/antora/modules/web/pages/faces-custom/faces-custom006.adoc similarity index 92% rename from src/main/asciidoc/faces-custom/faces-custom006.adoc rename to src/main/antora/modules/web/pages/faces-custom/faces-custom006.adoc index 6818fb9c..2505bf79 100644 --- a/src/main/asciidoc/faces-custom/faces-custom006.adoc +++ b/src/main/antora/modules/web/pages/faces-custom/faces-custom006.adoc @@ -1,14 +1,14 @@ == Delegating Rendering to a Renderer Both `MapComponent` and `AreaComponent` delegate all of their rendering to a separate renderer. -The section <> explains how `MapRenderer` performs the encoding for `MapComponent`. +The section xref:faces-custom/faces-custom.adoc#_performing_encoding[Performing Encoding] explains how `MapRenderer` performs the encoding for `MapComponent`. This section explains in detail the process of delegating rendering to a renderer using `AreaRenderer`, which performs the rendering for `AreaComponent`. To delegate rendering, you perform the tasks described in the following topics: -* <> +* <<_creating_the_renderer_class>> -* <> +* <<_identifying_the_renderer_type>> === Creating the Renderer Class @@ -37,7 +37,7 @@ ImageArea ia = (ImageArea)area.getValue(); ---- The attribute value is the `ImageArea` bean instance, which contains the `shape`, `coords`, and `alt` values associated with the `book203` `AreaComponent` instance. -<> describes how the application stores these values. + After retrieving the `ImageArea` object, the method renders the values for `shape`, `coords`, and `alt` by simply calling the associated accessor methods and passing the returned values to the `ResponseWriter` instance, as shown by these lines of code, which write out the shape and coordinates: @@ -101,7 +101,7 @@ The annotation identifies the component family as well as the renderer type. === Identifying the Renderer Type -Register the renderer with a render kit by using the `@FacesRenderer` annotation (or by using the application configuration resource file, as explained in <>). +Register the renderer with a render kit by using the `@FacesRenderer` annotation (or by using the application configuration resource file, as explained in xref:faces-configure/faces-configure.adoc#_registering_a_custom_renderer_with_a_render_kit[Registering a Custom Renderer with a Render Kit]). During the Render Response phase, the Jakarta Faces implementation calls the `getRendererType` method of the component's tag handler to determine which renderer to invoke, if there is one. You identify the type associated with the renderer in the `rendererType` element of the `@FacesRenderer` annotation for `AreaRenderer` as well as in the `renderer-type` element of the tag library descriptor. diff --git a/src/main/asciidoc/faces-custom/faces-custom007.adoc b/src/main/antora/modules/web/pages/faces-custom/faces-custom007.adoc similarity index 82% rename from src/main/asciidoc/faces-custom/faces-custom007.adoc rename to src/main/antora/modules/web/pages/faces-custom/faces-custom007.adoc index 2a9fd6d0..03b3b473 100644 --- a/src/main/asciidoc/faces-custom/faces-custom007.adoc +++ b/src/main/antora/modules/web/pages/faces-custom/faces-custom007.adoc @@ -15,11 +15,11 @@ Similarly, listeners that handle the value-change events must implement the inte This section explains how to implement the two listener classes. To handle events generated by custom components, you must implement an event listener and an event handler and manually queue the event on the component. -See <> for more information. +See xref:faces-custom/faces-custom.adoc#_handling_events_for_custom_components[Handling Events for Custom Components] for more information. [NOTE] You do not need to create an `ActionListener` implementation to handle an event that results solely in navigating to a page and does not perform any other application-specific processing. -See <> for information on how to manage page navigation. +See xref:faces-develop/faces-develop.adoc#_writing_a_method_to_handle_navigation[Writing a Method to Handle Navigation] for information on how to manage page navigation. === Implementing Value-Change Listeners @@ -68,7 +68,7 @@ public class NameChanged extends Object implements ValueChangeListener { When the user enters the name in the field, a value-change event is generated, and the `processValueChange(ValueChangeEvent)` method of the `NameChanged` listener implementation is invoked. This method first gets the ID of the component that fired the event from the `ValueChangeEvent` object, and it puts the value, along with an attribute name, into the session map of the `FacesContext` instance. -<> explains how to +xref:faces-page-core/faces-page-core.adoc#_registering_a_value_change_listener_on_a_component[Registering a Value-Change Listener on a Component] explains how to register this listener onto a component. === Implementing Action Listeners @@ -78,6 +78,6 @@ The `processAction(ActionEvent)` method processes the specified action event. The Jakarta Faces implementation invokes the `processAction(ActionEvent)` method when the `ActionEvent` occurs. The Duke's Bookstore case study uses two `ActionListener` implementations, `LinkBookChangeListener` and `MapBookChangeListener`. -See <> for details on `MapBookChangeListener`. +See xref:faces-custom/faces-custom.adoc#_handling_events_for_custom_components[Handling Events for Custom Components] for details on `MapBookChangeListener`. -<> explains how to register this listener onto a component. +xref:faces-page-core/faces-page-core.adoc#_registering_an_action_listener_on_a_component[Registering an Action Listener on a Component] explains how to register this listener onto a component. diff --git a/src/main/asciidoc/faces-custom/faces-custom008.adoc b/src/main/antora/modules/web/pages/faces-custom/faces-custom008.adoc similarity index 68% rename from src/main/asciidoc/faces-custom/faces-custom008.adoc rename to src/main/antora/modules/web/pages/faces-custom/faces-custom008.adoc index 9f55223d..17fb0eda 100644 --- a/src/main/asciidoc/faces-custom/faces-custom008.adoc +++ b/src/main/antora/modules/web/pages/faces-custom/faces-custom008.adoc @@ -1,12 +1,12 @@ == Handling Events for Custom Components -As explained in <>, events are automatically queued on standard components that fire events. +As explained in xref:faces-custom/faces-custom.adoc#_implementing_an_event_listener[Implementing an Event Listener], events are automatically queued on standard components that fire events. A custom component, on the other hand, must manually queue events from its `decode` method if it fires events. -<> explains how to queue an event on `MapComponent` using its `decode` method. +xref:faces-custom/faces-custom.adoc#_performing_decoding[Performing Decoding] explains how to queue an event on `MapComponent` using its `decode` method. This section explains how to write the class that represents the event of clicking on the map and how to write the method that processes this event. -As explained in <>, the `actionListener` attribute of the `bookstore:map` tag points to the `MapBookChangeListener` class. +As explained in xref:faces-custom/faces-custom.adoc#_understanding_the_facelets_page[Understanding the Facelets Page], the `actionListener` attribute of the `bookstore:map` tag points to the `MapBookChangeListener` class. The listener class's `processAction` method processes the event of clicking the image map. Here is the `processAction` method: @@ -25,7 +25,7 @@ public void processAction(ActionEvent actionEvent) ---- When the Jakarta Faces implementation calls this method, it passes in an `ActionEvent` object that represents the event generated by clicking on the image map. -Next, it casts it to an `AreaSelectedEvent` object (see `_tut-install_/examples/case-studies/dukes-bookstore/src/java/dukesbookstore/listeners/AreaSelectedEvent.java`). +Next, it casts it to an `AreaSelectedEvent` object (see `_jakartaee-examples_/tutorial/case-studies/dukes-bookstore/src/main/java/jakarta/tutorial/dukesbookstore/listeners/AreaSelectedEvent.java`). Then this method gets the `MapComponent` associated with the event. Next, it gets the value of the `MapComponent` object's `current` attribute, which indicates the currently selected area. The method then uses the value of the `current` attribute to get the book's ID value from a `HashMap` object, which is constructed elsewhere in the `MapBookChangeListener` class. @@ -47,5 +47,5 @@ public class AreaSelectedEvent extends ActionEvent { } ---- -As explained in the section <>, in order for `MapComponent` to fire events in the first place, it must implement `ActionSource`. +As explained in the section xref:faces-custom/faces-custom.adoc#_creating_custom_component_classes[Creating Custom Component Classes], in order for `MapComponent` to fire events in the first place, it must implement `ActionSource`. Because `MapComponent` extends `UICommand`, it also implements `ActionSource`. diff --git a/src/main/asciidoc/faces-custom/faces-custom009.adoc b/src/main/antora/modules/web/pages/faces-custom/faces-custom009.adoc similarity index 93% rename from src/main/asciidoc/faces-custom/faces-custom009.adoc rename to src/main/antora/modules/web/pages/faces-custom/faces-custom009.adoc index 9bb68213..6be371ee 100644 --- a/src/main/asciidoc/faces-custom/faces-custom009.adoc +++ b/src/main/antora/modules/web/pages/faces-custom/faces-custom009.adoc @@ -37,7 +37,7 @@ Here are the tag definitions for the `area` and `map` components: The `component-type` element specifies the name defined in the `@FacesComponent` annotation, and the `renderer-type` element specifies the `rendererType` defined in the `@FacesRenderer` annotation. The `facelet-taglib` element must also include a `namespace` element, which defines the namespace to be specified in pages that use the custom component. -See <> for information on specifying the namespace in pages. +See xref:faces-custom/faces-custom.adoc#_using_a_custom_component[Using a Custom Component] for information on specifying the namespace in pages. The TLD file is located in the `WEB-INF` directory. In addition, an entry is included in the web deployment descriptor (`web.xml`) to identify the custom tag library descriptor file, as follows: diff --git a/src/main/asciidoc/faces-custom/faces-custom010.adoc b/src/main/antora/modules/web/pages/faces-custom/faces-custom010.adoc similarity index 92% rename from src/main/asciidoc/faces-custom/faces-custom010.adoc rename to src/main/antora/modules/web/pages/faces-custom/faces-custom010.adoc index 388be0cf..a62dcf13 100644 --- a/src/main/asciidoc/faces-custom/faces-custom010.adoc +++ b/src/main/antora/modules/web/pages/faces-custom/faces-custom010.adoc @@ -2,7 +2,7 @@ To use a custom component in a page, you add the custom tag associated with the component to the page. -As explained in <>, you must ensure that the TLD that defines any custom tags is packaged in the application if you intend to use the tags in your pages. +As explained in xref:faces-custom/faces-custom.adoc#_defining_the_custom_component_tag_in_a_tag_library_descriptor[Defining the Custom Component Tag in a Tag Library Descriptor], you must ensure that the TLD that defines any custom tags is packaged in the application if you intend to use the tags in your pages. TLD files are stored in the `WEB-INF/` directory or subdirectory of the WAR file or in the `META-INF/` directory or subdirectory of a tag library packaged in a JAR file. You also need to include a namespace declaration in the page so that the page has access to the tags. diff --git a/src/main/asciidoc/faces-custom/faces-custom011.adoc b/src/main/antora/modules/web/pages/faces-custom/faces-custom011.adoc similarity index 87% rename from src/main/asciidoc/faces-custom/faces-custom011.adoc rename to src/main/antora/modules/web/pages/faces-custom/faces-custom011.adoc index 8367c24d..e12bb67f 100644 --- a/src/main/asciidoc/faces-custom/faces-custom011.adoc +++ b/src/main/antora/modules/web/pages/faces-custom/faces-custom011.adoc @@ -2,15 +2,15 @@ A Jakarta Faces converter class converts strings to objects and objects to strings as required. Several standard converters are provided by Jakarta Faces for this purpose. -See <> for more information on these included converters. +See xref:faces-page-core/faces-page-core.adoc#_using_the_standard_converters[Using the Standard Converters] for more information on these included converters. -As explained in <>, if the standard converters included with Jakarta Faces cannot perform the data conversion that you need, you can create a custom converter to perform this specialized conversion. -This implementation, at a minimum, must define how to convert data both ways between the two views of the data described in <>. +As explained in xref:faces-intro/faces-intro.adoc#_conversion_model[Conversion Model], if the standard converters included with Jakarta Faces cannot perform the data conversion that you need, you can create a custom converter to perform this specialized conversion. +This implementation, at a minimum, must define how to convert data both ways between the two views of the data described in xref:faces-intro/faces-intro.adoc#_conversion_model[Conversion Model]. All custom converters must implement the `jakarta.faces.convert.Converter` interface. This section explains how to implement this interface to perform a custom data conversion. -The Duke's Bookstore case study uses a custom `Converter` implementation, located in `_tut-install_/examples/case-studies/dukes-bookstore/src/java/dukesbookstore/converters/CreditCardConverter.java`, to convert the data entered in the Credit Card Number field on the `bookcashier.xhtml` page. +The Duke's Bookstore case study uses a custom `Converter` implementation, located in `_jakarta-examples_/tutorial/case-studies/dukes-bookstore/src/main/java/jakarta/tutorial/dukesbookstore/converters/CreditCardConverter.java`, to convert the data entered in the Credit Card Number field on the `bookcashier.xhtml` page. It strips blanks and hyphens from the text string and formats it so that a blank space separates every four characters. Another common use case for a custom converter is in a list for a nonstandard object type. @@ -29,7 +29,7 @@ public class CreditCardConverter implements Converter { ---- The `@FacesConverter` annotation registers the custom converter class as a converter with the name of `ccno` with the Jakarta Faces implementation. -Alternatively, you can register the converter with entries in the application configuration resource file, as shown in <>. +Alternatively, you can register the converter with entries in the application configuration resource file, as shown in xref:faces-configure/faces-configure.adoc#_registering_a_custom_converter[Registering a Custom Converter]. To define how the data is converted from the presentation view to the model view, the `Converter` implementation must implement the `getAsObject(FacesContext, UIComponent, String)` method from the `Converter` interface. Here is the implementation of this method from `CreditCardConverter`: @@ -114,7 +114,7 @@ When the Jakarta Faces implementation calls this method, it passes in the curren Because this converter does a `String`-to-`String` conversion, this method can cast the bean value to a `String`. If the value cannot be converted to a `String`, the method throws an exception, passing an error message from the resource bundle that is registered with the application. -<> explains how to register custom error messages with the application. +xref:faces-configure/faces-configure.adoc#_registering_application_messages[Registering Application Messages] explains how to register custom error messages with the application. If the value can be converted to a `String`, the method reads the `String` to a character array and loops through the array, adding a space after every four characters. @@ -141,7 +141,7 @@ To apply the data conversion performed by a custom converter to a particular com * Nest an `f:converter` tag inside the component's tag and reference the custom converter from one of the `f:converter` tag's attributes. If you are using the component tag's `converter` attribute, this attribute must reference the `Converter` implementation's identifier or the fully-qualified class name of the converter. -<> explains how to implement a custom converter. +<<_creating_and_using_a_custom_converter>> explains how to implement a custom converter. The identifier for the credit card converter class is `ccno`, the value specified in the `@FacesConverter` annotation: @@ -188,7 +188,7 @@ This method is shown in `bookcashier.xhtml`: ---- -* Bind the `Converter` implementation to a managed bean property using the `f:converter` tag's `binding` attribute, as described in <>. +* Bind the `Converter` implementation to a managed bean property using the `f:converter` tag's `binding` attribute, as described in xref:faces-custom/faces-custom.adoc#_binding_converters_listeners_and_validators_to_managed_bean_properties[Binding Converters, Listeners, and Validators to Managed Bean Properties]. The Jakarta Faces implementation calls the converter's `getAsObject` method to strip spaces and hyphens from the input value. The `getAsString` method is called when the `bookcashier.xhtml` page is redisplayed; this happens if the user orders more than $100 worth of books. diff --git a/src/main/asciidoc/faces-custom/faces-custom012.adoc b/src/main/antora/modules/web/pages/faces-custom/faces-custom012.adoc similarity index 88% rename from src/main/asciidoc/faces-custom/faces-custom012.adoc rename to src/main/antora/modules/web/pages/faces-custom/faces-custom012.adoc index d7cf6cea..6aa8ec3b 100644 --- a/src/main/asciidoc/faces-custom/faces-custom012.adoc +++ b/src/main/antora/modules/web/pages/faces-custom/faces-custom012.adoc @@ -1,27 +1,27 @@ == Creating and Using a Custom Validator If the standard validators or Bean Validation don't perform the validation checking you need, you can create a custom validator to validate user input. -As explained in <>, there are two ways to implement validation code. +As explained in xref:faces-intro/faces-intro.adoc#_validation_model[Validation Model], there are two ways to implement validation code. * Implement a managed bean method that performs the validation. * Provide an implementation of the `jakarta.faces.validator.Validator` interface to perform the validation. -<> explains how to implement a managed bean method to perform validation. +xref:faces-develop/faces-develop.adoc#_writing_a_method_to_perform_validation[Writing a Method to Perform Validation] explains how to implement a managed bean method to perform validation. The rest of this section explains how to implement the `Validator` interface. If you choose to implement the `Validator` interface and you want to allow the page author to configure the validator's attributes from the page, you also must specify a custom tag for registering the validator on a component. -If you prefer to configure the attributes in the `Validator` implementation, you can forgo specifying a custom tag and instead let the page author register the validator on a component using the `f:validator` tag, as described in <>. +If you prefer to configure the attributes in the `Validator` implementation, you can forgo specifying a custom tag and instead let the page author register the validator on a component using the `f:validator` tag, as described in <<_using_a_custom_validator>>. -You can also create a managed bean property that accepts and returns the `Validator` implementation you create, as described in <>. +You can also create a managed bean property that accepts and returns the `Validator` implementation you create, as described in xref:faces-develop/faces-develop.adoc#_writing_properties_bound_to_converters_listeners_or_validators[Writing Properties Bound to Converters, Listeners, or Validators]. You can use the `f:validator` tag's binding attribute to bind the `Validator` implementation to the managed bean property. Usually, you will want to display an error message when data fails validation. You need to store these error messages in a resource bundle. After creating the resource bundle, you have two ways to make the messages available to the application. -You can queue the error messages onto the `FacesContext` programmatically, or you can register the error messages in the application configuration resource file, as explained in <>. +You can queue the error messages onto the `FacesContext` programmatically, or you can register the error messages in the application configuration resource file, as explained in xref:faces-configure/faces-configure.adoc#_registering_application_messages[Registering Application Messages]. For example, an e-commerce application might use a general-purpose custom validator called `FormatValidator.java` to validate input data against a format pattern that is specified in the custom validator tag. This validator would be used with a Credit Card Number field on a Facelets page. @@ -127,7 +127,7 @@ public static final String FORMAT_INVALID_MESSAGE_ID = Finally, the method passes the message to the constructor of `jakarta.faces.validator.ValidatorException`. -When the error message is displayed, the format pattern will be substituted for the `{0}` in the error message, which, in English, is as follows: +When the error message is displayed, the format pattern will be substituted for the `\{0}` in the error message, which, in English, is as follows: [source,java] ---- @@ -137,7 +137,7 @@ Input must match one of the following patterns: {0} You may wish to save and restore state for your validator, although state saving is not usually necessary. To do so, you will need to implement the `StateHolder` interface as well as the `Validator` interface. To implement `StateHolder`, you would need to implement its four methods: `saveState(FacesContext)`, `restoreState(FacesContext, Object)`, `isTransient`, and `setTransient(boolean)`. -See <> for more information. +See xref:faces-custom/faces-custom.adoc#_saving_and_restoring_state[Saving and Restoring State] for more information. === Specifying a Custom Tag @@ -145,7 +145,7 @@ If you implemented a `Validator` interface rather than implementing a managed be * Allow the page author to specify the `Validator` implementation to use with the `f:validator` tag. In this case, the `Validator` implementation must define its own properties. -<> explains how to use the `f:validator` tag. +<<_using_a_custom_validator>> explains how to use the `f:validator` tag. * Specify a custom tag that provides attributes for configuring the properties of the validator from the page. @@ -168,7 +168,7 @@ The `tag-name` element defines the name of the tag as it must be used in a Facel The `validator-id` element identifies the custom validator. The `validator-class` element wires the custom tag to its implementation class. -<> explains how to use the custom validator tag on the page. +<<_using_a_custom_validator>> explains how to use the custom validator tag on the page. === Using a Custom Validator @@ -202,7 +202,7 @@ Then the page author needs to do one of the following. * Set the `f:validator` tag's `validatorId` attribute to the ID of the validator that is defined in the application configuration resource file. -* Bind the custom `Validator` implementation to a managed bean property using the `f:validator` tag's `binding` attribute, as described in <>. +* Bind the custom `Validator` implementation to a managed bean property using the `f:validator` tag's `binding` attribute, as described in xref:faces-custom/faces-custom.adoc#_binding_converters_listeners_and_validators_to_managed_bean_properties[Binding Converters, Listeners, and Validators to Managed Bean Properties]. The following tag registers a hypothetical validator on a component using an `f:validator` tag and references the ID of the validator: diff --git a/src/main/asciidoc/faces-custom/faces-custom013.adoc b/src/main/antora/modules/web/pages/faces-custom/faces-custom013.adoc similarity index 94% rename from src/main/asciidoc/faces-custom/faces-custom013.adoc rename to src/main/antora/modules/web/pages/faces-custom/faces-custom013.adoc index 99ba92e9..1b258343 100644 --- a/src/main/asciidoc/faces-custom/faces-custom013.adoc +++ b/src/main/antora/modules/web/pages/faces-custom/faces-custom013.adoc @@ -50,9 +50,9 @@ The `value` attribute that references this property must have this value-binding ---- In addition to binding a component's value to a bean property, the `value` attribute can specify a literal value or can map the component's data to any primitive (such as `int`), structure (such as an array), or collection (such as a list), independent of a JavaBeans component. -<> lists some example value-binding expressions that you can use with the `value` attribute. +<<_examples_of_value_binding_expressions>> lists some example value-binding expressions that you can use with the `value` attribute. -[[examples-of-value-binding-expressions]] +[[_examples_of_value_binding_expressions]] .Examples of Value-Binding Expressions [width="60%",cols="30%,30%"] |=== @@ -117,10 +117,10 @@ Thank you, Gwen Canigetit, for purchasing your books from us. ---- Retrieving values from other implicit objects is done in a similar way to the example shown in this section. -<> lists the implicit objects to which a value attribute can refer. +<<_implicit_objects>> lists the implicit objects to which a value attribute can refer. All of the implicit objects, except for the scope objects, are read-only and therefore should not be used as values for a `UIInput` component. -[[implicit-objects]] +[[_implicit_objects]] .Implicit Objects [width="75%",cols="15%,60%"] |=== @@ -183,4 +183,4 @@ These tags use component bindings rather than value bindings because the managed If the tags were to use value bindings instead of component bindings, the managed bean would not have direct access to the components and would therefore require additional code to access the components from the `FacesContext` instance to change the components' `rendered` properties. -<> explains how to write the bean properties bound to the example components. +xref:faces-develop/faces-develop.adoc#_writing_properties_bound_to_component_instances[Writing Properties Bound to Component Instances] explains how to write the bean properties bound to the example components. diff --git a/src/main/asciidoc/faces-custom/faces-custom014.adoc b/src/main/antora/modules/web/pages/faces-custom/faces-custom014.adoc similarity index 71% rename from src/main/asciidoc/faces-custom/faces-custom014.adoc rename to src/main/antora/modules/web/pages/faces-custom/faces-custom014.adoc index 18428f9e..66b01f60 100644 --- a/src/main/asciidoc/faces-custom/faces-custom014.adoc +++ b/src/main/antora/modules/web/pages/faces-custom/faces-custom014.adoc @@ -1,8 +1,8 @@ == Binding Converters, Listeners, and Validators to Managed Bean Properties -As described in <>, a page author can bind converter, listener, and validator implementations to managed bean properties using the `binding` attributes of the tags that are used to register the implementations on components. +As described in xref:faces-page/faces-page.adoc#_adding_components_to_a_page_using_html_tag_library_tags[Adding Components to a Page Using HTML Tag Library Tags], a page author can bind converter, listener, and validator implementations to managed bean properties using the `binding` attributes of the tags that are used to register the implementations on components. -This technique has similar advantages to binding component instances to managed bean properties, as described in <>. +This technique has similar advantages to binding component instances to managed bean properties, as described in xref:faces-custom/faces-custom.adoc#_binding_component_values_and_instances_to_managed_bean_properties[Binding Component Values and Instances to Managed Bean Properties]. In particular, binding a converter, listener, or validator implementation to a managed bean property yields the following benefits. * The managed bean can instantiate the implementation instead of @@ -45,4 +45,4 @@ public void setConvertDate(DateTimeConverter convertDate) { } ---- -See <> for more information on writing managed bean properties for converter, listener, and validator implementations. +See xref:faces-develop/faces-develop.adoc#_writing_properties_bound_to_converters_listeners_or_validators[Writing Properties Bound to Converters, Listeners, or Validators] for more information on writing managed bean properties for converter, listener, and validator implementations. diff --git a/src/main/asciidoc/faces-develop/faces-develop.adoc b/src/main/antora/modules/web/pages/faces-develop/faces-develop.adoc similarity index 89% rename from src/main/asciidoc/faces-develop/faces-develop.adoc rename to src/main/antora/modules/web/pages/faces-develop/faces-develop.adoc index d53d9729..dd71dc9d 100644 --- a/src/main/asciidoc/faces-develop/faces-develop.adoc +++ b/src/main/antora/modules/web/pages/faces-develop/faces-develop.adoc @@ -1,5 +1,7 @@ = Developing with Jakarta Faces Technology +include::ROOT:partial$not_updated.adoc[] + This chapter provides an overview of managed beans and explains how to write methods and properties of managed beans that are used by a Jakarta Faces application. This chapter also introduces the Bean Validation feature. diff --git a/src/main/asciidoc/faces-develop/faces-develop001.adoc b/src/main/antora/modules/web/pages/faces-develop/faces-develop001.adoc similarity index 83% rename from src/main/asciidoc/faces-develop/faces-develop001.adoc rename to src/main/antora/modules/web/pages/faces-develop/faces-develop001.adoc index cbaf4dd3..ff366be0 100644 --- a/src/main/asciidoc/faces-develop/faces-develop001.adoc +++ b/src/main/antora/modules/web/pages/faces-develop/faces-develop001.adoc @@ -4,7 +4,7 @@ A typical Jakarta Faces application includes one or more managed beans, each of This section introduces the basic concepts of creating, configuring, and using managed beans in an application. [NOTE] -xref:using-jakarta-faces-technology-in-web-pages[xrefstyle=full] and xref:using-converters-listeners-and-validators[xrefstyle=full] show how to add components to a page and connect them to server-side objects by using component tags and core tags. +xref:faces-page/faces-page.adoc#_using_jakarta_faces_technology_in_web_pages[Using Jakarta Faces Technology in Web Pages] and xref:faces-page-core/faces-page-core.adoc#_using_converters_listeners_and_validators[Using Converters, Listeners, and Validators] show how to add components to a page and connect them to server-side objects by using component tags and core tags. These chapters also show how to provide additional functionality to the components through converters, listeners, and validators. Developing a Jakarta Faces application also involves the task of programming the server-side objects: managed beans, converters, event handlers, and validators. @@ -47,18 +47,18 @@ public Integer getUserNumber() { When bound to a component's value, a bean property can be any of the basic primitive and numeric types or any Java object type for which the application has access to an appropriate converter. For example, a property can be of type `java.util.Date` if the application has access to a converter that can convert the `Date` type to a `String` and back again. -See <> for information on which types are accepted by which component tags. +See xref:faces-develop/faces-develop.adoc#_writing_bean_properties[Writing Bean Properties] for information on which types are accepted by which component tags. When a bean property is bound to a component instance, the property's type must be the same as the component object. For example, if a `jakarta.faces.component.UISelectBoolean` component is bound to the property, the property must accept and return a `UISelectBoolean` object. Likewise, if the property is bound to a converter, validator, or listener instance, the property must be of the appropriate converter, validator, or listener type. -For more information on writing beans and their properties, see <>. +For more information on writing beans and their properties, see xref:faces-develop/faces-develop.adoc#_writing_bean_properties[Writing Bean Properties]. === Using the EL to Reference Managed Beans To bind component values and objects to managed bean properties or to reference managed bean methods from component tags, page authors use the Expression Language syntax. -As explained in <>, the following are some of the features that the EL offers: +As explained in xref:faces-el/faces-el.adoc#_overview_of_the_el[Overview of the EL], the following are some of the features that the EL offers: * Deferred evaluation of expressions @@ -68,7 +68,7 @@ As explained in <>, the following are some of the features t Deferred evaluation of expressions is important because the Jakarta Faces lifecycle is split into several phases in which component event handling, data conversion and validation, and data propagation to external objects are all performed in an orderly fashion. The implementation must be able to delay the evaluation of expressions until the proper phase of the lifecycle has been reached. -Therefore, the implementation's tag attributes always use deferred-evaluation syntax, which is distinguished by the `#{}` delimiter. +Therefore, the implementation's tag attributes always use deferred-evaluation syntax, which is distinguished by the `#{}` delimiter. To store data in external objects, almost all Jakarta Faces tag attributes use lvalue expressions, which are expressions that allow both getting and setting data on external objects. @@ -108,6 +108,6 @@ A page author does this by referencing the property from the `binding` attribute In addition to using expressions with the standard component tags, you can configure your custom component properties to accept expressions by creating `jakarta.el.ValueExpression` or `jakarta.el.MethodExpression` instances for them. -For information on the EL, see xref:expression-language[xrefstyle=full]. +For information on the EL, see xref:faces-el/faces-el.adoc#_expression_language[Expression Language]. -For information on referencing managed bean methods from component tags, see <>. +For information on referencing managed bean methods from component tags, see xref:faces-page-core/faces-page-core.adoc#_referencing_a_managed_bean_method[Referencing a Managed Bean Method]. diff --git a/src/main/asciidoc/faces-develop/faces-develop002.adoc b/src/main/antora/modules/web/pages/faces-develop/faces-develop002.adoc similarity index 82% rename from src/main/asciidoc/faces-develop/faces-develop002.adoc rename to src/main/antora/modules/web/pages/faces-develop/faces-develop002.adoc index 91f6797c..1ef2c712 100644 --- a/src/main/asciidoc/faces-develop/faces-develop002.adoc +++ b/src/main/antora/modules/web/pages/faces-develop/faces-develop002.adoc @@ -1,6 +1,6 @@ == Writing Bean Properties -As explained in <>, a managed bean property can be bound to one of the following items: +As explained in xref:faces-develop/faces-develop.adoc#_managed_beans_in_jakarta_faces_technology[Managed Beans in Jakarta Faces Technology], a managed bean property can be bound to one of the following items: * A component value @@ -17,7 +17,7 @@ For more information on JavaBeans components, see the JavaBeans Tutorial at http The component's tag binds the component's value to a managed bean property by using its `value` attribute and binds the component's instance to a managed bean property by using its `binding` attribute. Likewise, all the converter, listener, and validator tags use their `binding` attributes to bind their associated implementations to managed bean properties. -See <> and <> for more information. +See xref:faces-custom/faces-custom.adoc#_binding_component_values_and_instances_to_managed_bean_properties[Binding Component Values and Instances to Managed Bean Properties] and xref:faces-custom/faces-custom.adoc#_binding_converters_listeners_and_validators_to_managed_bean_properties[Binding Converters, Listeners, and Validators to Managed Bean Properties] for more information. To bind a component's value to a managed bean property, the type of the property must match the type of the component's value to which it is bound. For example, if a managed bean property is bound to a `UISelectBoolean` component's value, the property should accept and return a `boolean` value or a `Boolean` wrapper `Object` instance. @@ -28,15 +28,15 @@ For example, if a managed bean property is bound to a `UISelectBoolean` instance Similarly, to bind a converter, listener, or validator implementation to a managed bean property, the property must accept and return the same type of converter, listener, or validator object. For example, if you are using the `convertDateTime` tag to bind a `jakarta.faces.convert.DateTimeConverter` to a property, that property must accept and return a `DateTimeConverter` instance. -The rest of this section explains how to write properties that can be bound to component values, to component instances for the component objects described in <>, and to converter, listener, and validator implementations. +The rest of this section explains how to write properties that can be bound to component values, to component instances for the component objects described in xref:faces-page/faces-page.adoc#_adding_components_to_a_page_using_html_tag_library_tags[Adding Components to a Page Using HTML Tag Library Tags], and to converter, listener, and validator implementations. === Writing Properties Bound to Component Values To write a managed bean property that is bound to a component's value, you must match the property type to the component's value. -<> lists the `jakarta.faces.component` classes and the acceptable types of their values. +<<_acceptable_types_of_component_values>> lists the `jakarta.faces.component` classes and the acceptable types of their values. -[[acceptable-types-of-component-values]] +[[_acceptable_types_of_component_values]] .Acceptable Types of Component Values [width="99%",cols="25%,75%"] |=== @@ -84,8 +84,8 @@ public String getName() { } ---- -As described in <>, to convert the value of an input or output component you can either apply a converter or create the bean property bound to the component with the matching type. -Here is the example tag, from <>, that displays the date on which items will be shipped. +As described in xref:faces-page-core/faces-page-core.adoc#_using_the_standard_converters[Using the Standard Converters], to convert the value of an input or output component you can either apply a converter or create the bean property bound to the component with the matching type. +Here is the example tag, from xref:faces-page-core/faces-page-core.adoc#_using_datetimeconverter[Using DateTimeConverter], that displays the date on which items will be shipped. [source,xml] ---- @@ -113,8 +113,8 @@ public void setShipDate(Date shipDate) { The `UIData` component class is represented by the `h:dataTable` component tag. -`UIData` components must be bound to one of the managed bean property types listed in <>. -Data components are discussed in <>. +`UIData` components must be bound to one of the managed bean property types listed in <<_acceptable_types_of_component_values>>. +Data components are discussed in xref:faces-page/faces-page.adoc#_using_data_bound_table_components[Using Data-Bound Table Components]. Here is part of the start tag of `dataTable` from that section: [source,xml] @@ -151,7 +151,7 @@ For example, here is the `h:outputText` tag that displays the book title in the ---- The title is actually a link to the `bookdetails.xhtml` page. -The `h:outputText` tag uses the value expression `#{item.item.title}` to bind its `UIOutput` component to the `title` property of the `Book` entity. +The `h:outputText` tag uses the value expression `#{item.item.title}` to bind its `UIOutput` component to the `title` property of the `Book` entity. The first item in the expression is the `ShoppingCartItem` instance that the `h:dataTable` tag is referencing while rendering the current row. The second item in expression refers to the `item` property of `ShoppingCartItem`, which returns an `Object` (in this case, a `Book`). The `title` part of the expression refers to the `title` property of `Book`. @@ -199,7 +199,7 @@ For UIData and UIRepeat, the supported types are: The `UISelectBoolean` component class is represented by the component tag `h:selectBooleanCheckbox`. Managed bean properties that hold a `UISelectBoolean` component's data must be of `boolean` or `Boolean` type. -The example `selectBooleanCheckbox` tag from the section <> binds a component to a property. +The example `selectBooleanCheckbox` tag from the section xref:faces-page/faces-page.adoc#_displaying_components_for_selecting_one_value[Displaying Components for Selecting One Value] binds a component to a property. The following example shows a tag that binds a component value to a `boolean` property: [source,xml] @@ -231,7 +231,7 @@ The `UISelectMany` component class is represented by the component tags that beg Because a `UISelectMany` component allows a user to select one or more items from a list of items, this component must map to a bean property of type `List` or `array`. This bean property represents the set of currently selected items from the list of available items. -The following example of the `selectManyCheckbox` tag comes from <>: +The following example of the `selectManyCheckbox` tag comes from xref:faces-page/faces-page.adoc#_displaying_components_for_selecting_multiple_values[Displaying Components for Selecting Multiple Values]: [source,xml] ---- @@ -257,7 +257,7 @@ public String[] getNewsletters() { ---- The `UISelectItem` and `UISelectItems` components are used to represent all the values in a `UISelectMany` component. -See <> for information on writing the bean properties for the `UISelectItem` and `UISelectItems` components. +See <<_uiselectitems_properties>> for information on writing the bean properties for the `UISelectItem` and `UISelectItems` components. ==== UISelectOne Properties @@ -266,7 +266,7 @@ The `UISelectOne` component class is represented by the component tags that begi `UISelectOne` properties accept the same types as `UIInput` and `UIOutput` properties, because a `UISelectOne` component represents the single selected item from a set of items. This item can be any of the primitive types and anything else for which you can apply a converter. -Here is an example of the `h:selectOneMenu` tag from <>: +Here is an example of the `h:selectOneMenu` tag from xref:faces-page/faces-page.adoc#_displaying_a_menu_using_the_hselectonemenu_tag[Displaying a Menu Using the h:selectOneMenu Tag]: [source,xml] ---- @@ -299,9 +299,9 @@ public String getShippingOption() { Note that `shippingOption` represents the currently selected item from the list of items in the `UISelectOne` component. The `UISelectItem` and `UISelectItems` components are used to represent all the values in a `UISelectOne` component. -This is explained in <>. +This is explained in xref:faces-page/faces-page.adoc#_displaying_a_menu_using_the_hselectonemenu_tag[Displaying a Menu Using the h:selectOneMenu Tag]. -For information on how to write the managed bean properties for the `UISelectItem` and `UISelectItems` components, see <>. +For information on how to write the managed bean properties for the `UISelectItem` and `UISelectItems` components, see <<_uiselectitems_properties>>. ==== UISelectItem Properties @@ -309,7 +309,7 @@ A `UISelectItem` component represents a single value in a set of values in a `UI A `UISelectItem` component must be bound to a managed bean property of type `jakarta.faces.model.SelectItem`. A `SelectItem` object is composed of an `Object` representing the value along with two `Strings` representing the label and the description of the `UISelectItem` object. -The example `selectOneMenu` tag from <> contains `selectItem` tags that set the values of the list of items in the page. +The example `selectOneMenu` tag from <<_uiselectone_properties>> contains `selectItem` tags that set the values of the list of items in the page. Here is an example of a bean property that can set the values for this list in the bean: [source,java] @@ -401,11 +401,11 @@ public void setSpecialOffer(UISelectBoolean specialOffer) { } ---- -For more general information on component binding, see <>. +For more general information on component binding, see xref:faces-develop/faces-develop.adoc#_managed_beans_in_jakarta_faces_technology[Managed Beans in Jakarta Faces Technology]. -For information on how to reference a managed bean method that performs navigation when a button is clicked, see <>. +For information on how to reference a managed bean method that performs navigation when a button is clicked, see xref:faces-page-core/faces-page-core.adoc#_referencing_a_method_that_performs_navigation[Referencing a Method That Performs Navigation]. -For more information on writing managed bean methods that handle navigation, see <>. +For more information on writing managed bean methods that handle navigation, see xref:faces-develop/faces-develop.adoc#_writing_a_method_to_handle_navigation[Writing a Method to Handle Navigation]. === Writing Properties Bound to Converters, Listeners, or Validators diff --git a/src/main/asciidoc/faces-develop/faces-develop003.adoc b/src/main/antora/modules/web/pages/faces-develop/faces-develop003.adoc similarity index 86% rename from src/main/asciidoc/faces-develop/faces-develop003.adoc rename to src/main/antora/modules/web/pages/faces-develop/faces-develop003.adoc index 1aba1b3e..1af50cbd 100644 --- a/src/main/asciidoc/faces-develop/faces-develop003.adoc +++ b/src/main/antora/modules/web/pages/faces-develop/faces-develop003.adoc @@ -79,8 +79,8 @@ public Object submit(){ } ---- -The section <> explains how a component tag references this method. -The section <> explains how to write the bean properties to which the components are bound. +The section xref:faces-page-core/faces-page-core.adoc#_referencing_a_method_that_performs_navigation[Referencing a Method That Performs Navigation] explains how a component tag references this method. +The section xref:faces-develop/faces-develop.adoc#_writing_properties_bound_to_component_instances[Writing Properties Bound to Component Instances] explains how to write the bean properties to which the components are bound. === Writing a Method to Handle an Action Event @@ -104,7 +104,7 @@ This method gets the component that generated the event from the event object; t The method matches the code against a `HashMap` object that contains the book codes and corresponding book ID values. Finally, the method sets the book ID by using the selected value from the `HashMap` object. -<> explains how a component tag references this method. +xref:faces-page-core/faces-page-core.adoc#_referencing_a_method_that_handles_an_action_event[Referencing a Method That Handles an Action Event] explains how a component tag references this method. === Writing a Method to Perform Validation @@ -113,7 +113,7 @@ A managed bean method that performs validation must accept a `jakarta.faces.cont A component refers to the managed bean method by using its `validator` attribute. Only values of `UIInput` components or values of components that extend `UIInput` can be validated. -Here is an example of a managed bean method that validates user input, from <>: +Here is an example of a managed bean method that validates user input, from xref:cdi:cdi-basicexamples/cdi-basicexamples.adoc#_the_guessnumber_cdi_cdi_example[The guessnumber-cdi CDI Example]: [source,java] ---- @@ -145,7 +145,7 @@ Then it queues a message onto the `FacesContext` instance, associating the messa * If the user has some remaining guesses, the method then retrieves the local value of the component. If the input value is outside the allowable range, the method again sets the `valid` property of the `UIInput` component to `false`, queues a different message on the `FacesContext` instance, and returns. -See <> for information on how a component tag references this method. +See xref:faces-page-core/faces-page-core.adoc#_referencing_a_method_that_performs_validation[Referencing a Method That Performs Validation] for information on how a component tag references this method. === Writing a Method to Handle a Value-Change Event @@ -153,7 +153,7 @@ A managed bean that handles a value-change event must use a public method that a This method is referenced using the component's `valueChangeListener` attribute. This section explains how to write a managed bean method to replace the `jakarta.faces.event.ValueChangeListener` implementation. -The following example tag comes from <>, where the `h:inputText` tag with the `id` of `name` has a `ValueChangeListener` instance registered on it. +The following example tag comes from xref:faces-page-core/faces-page-core.adoc#_registering_a_value_change_listener_on_a_component[Registering a Value-Change Listener on a Component], where the `h:inputText` tag with the `id` of `name` has a `ValueChangeListener` instance registered on it. This `ValueChangeListener` instance handles the event of entering a value in the field corresponding to the component. When the user enters a value, a value-change event is generated, and the `processValueChange(ValueChangeEvent)` method of the `ValueChangeListener` class is invoked: @@ -186,4 +186,4 @@ public void processValueChange(ValueChangeEvent event) ---- To make this method handle the `ValueChangeEvent` generated by an input component, reference this method from the component tag's `valueChangeListener` attribute. -See <> for more information. +See xref:faces-page-core/faces-page-core.adoc#_referencing_a_method_that_handles_a_value_change_event[Referencing a Method That Handles a Value-Change Event] for more information. diff --git a/src/main/asciidoc/faces-el/faces-el.adoc b/src/main/antora/modules/web/pages/faces-el/faces-el.adoc similarity index 91% rename from src/main/asciidoc/faces-el/faces-el.adoc rename to src/main/antora/modules/web/pages/faces-el/faces-el.adoc index 20afd682..5984b0ba 100644 --- a/src/main/asciidoc/faces-el/faces-el.adoc +++ b/src/main/antora/modules/web/pages/faces-el/faces-el.adoc @@ -1,4 +1,6 @@ -= Expression Language += Jakarta Expression Language + +include::ROOT:partial$not_updated.adoc[] This chapter introduces the Expression Language (also referred to as the EL), which provides an important mechanism for enabling the presentation layer (web pages) to communicate with the application logic (managed beans). The EL is used by several Jakarta EE technologies, such as Jakarta Faces technology, Jakarta Server Pages technology, and Dependency Injection for Jakarta EE (CDI). diff --git a/src/main/asciidoc/faces-el/faces-el001.adoc b/src/main/antora/modules/web/pages/faces-el/faces-el001.adoc similarity index 85% rename from src/main/asciidoc/faces-el/faces-el001.adoc rename to src/main/antora/modules/web/pages/faces-el/faces-el001.adoc index 3f104acc..c3c9b376 100644 --- a/src/main/asciidoc/faces-el/faces-el001.adoc +++ b/src/main/antora/modules/web/pages/faces-el/faces-el001.adoc @@ -10,7 +10,7 @@ For example, the `test` attribute of the following conditional tag is supplied w ---- -See <> for more information on how to use the EL in Jakarta Faces applications. +See xref:faces-develop/faces-develop.adoc#_using_the_el_to_reference_managed_beans[Using the EL to Reference Managed Beans] for more information on how to use the EL in Jakarta Faces applications. To summarize, the EL provides a way to use simple expressions to perform the following tasks: diff --git a/src/main/asciidoc/faces-el/faces-el002.adoc b/src/main/antora/modules/web/pages/faces-el/faces-el002.adoc similarity index 88% rename from src/main/asciidoc/faces-el/faces-el002.adoc rename to src/main/antora/modules/web/pages/faces-el/faces-el002.adoc index f86a23db..c72a081e 100644 --- a/src/main/asciidoc/faces-el/faces-el002.adoc +++ b/src/main/antora/modules/web/pages/faces-el/faces-el002.adoc @@ -4,7 +4,7 @@ The EL supports both immediate and deferred evaluation of expressions. Immediate evaluation means that the expression is evaluated and the result returned as soon as the page is first rendered. Deferred evaluation means that the technology using the expression language can use its own machinery to evaluate the expression sometime later during the page's lifecycle, whenever it is appropriate to do so. -Those expressions that are evaluated immediately use the `${}` syntax. Expressions whose evaluation is deferred use the `#{}` syntax. +Those expressions that are evaluated immediately use the `${}` syntax. Expressions whose evaluation is deferred use the `#{}` syntax. Because of its multiphase lifecycle, Jakarta Faces technology uses mostly deferred evaluation expressions. During the lifecycle, component events are handled, data is validated, and other tasks are performed in a particular order. @@ -28,7 +28,7 @@ The Jakarta Faces implementation evaluates the expression `${catalog.bookQuantit === Deferred Evaluation -Deferred evaluation expressions take the form `#{expr}` and can be evaluated at other phases of a page lifecycle as defined by whatever technology is using the expression. +Deferred evaluation expressions take the form `#\{expr}` and can be evaluated at other phases of a page lifecycle as defined by whatever technology is using the expression. In the case of Jakarta Faces technology, its controller can evaluate the expression at different phases of the lifecycle, depending on how the expression is being used in the page. The following example shows a Jakarta Faces `h:inputText` tag, which represents a field component into which a user enters a value. @@ -39,7 +39,7 @@ The `h:inputText` tag's `value` attribute references a deferred evaluation expre ---- -For an initial request of the page containing this tag, the Jakarta Faces implementation evaluates the `#{customer.name}` expression during the render-response phase of the lifecycle. +For an initial request of the page containing this tag, the Jakarta Faces implementation evaluates the `#{customer.name}` expression during the render-response phase of the lifecycle. During this phase, the expression merely accesses the value of `name` from the `customer` bean, as is done in immediate evaluation. For a postback request, the Jakarta Faces implementation evaluates the expression at different phases of the lifecycle, during which the value is retrieved from the request, validated, and propagated to the `customer` bean. diff --git a/src/main/asciidoc/faces-el/faces-el003.adoc b/src/main/antora/modules/web/pages/faces-el/faces-el003.adoc similarity index 96% rename from src/main/asciidoc/faces-el/faces-el003.adoc rename to src/main/antora/modules/web/pages/faces-el/faces-el003.adoc index 14d822ad..b524c619 100644 --- a/src/main/asciidoc/faces-el/faces-el003.adoc +++ b/src/main/antora/modules/web/pages/faces-el/faces-el003.adoc @@ -10,7 +10,7 @@ An _lvalue_ expression can specify a target, such as an object, a bean property, An _rvalue_ expression cannot specify such a target. All expressions that are evaluated immediately use the `${}` delimiters, and although the expression can be an _lvalue_ expression, no assignments will ever happen. -Expressions whose evaluation can be deferred use the `#{}` delimiters and can act as both _rvalue_ and _lvalue_ expressions; if the expression is an _lvalue_ expression, it can be assigned a new value. +Expressions whose evaluation can be deferred use the `#{}` delimiters and can act as both _rvalue_ and _lvalue_ expressions; if the expression is an _lvalue_ expression, it can be assigned a new value. Consider the following two value expressions: [source,java] @@ -50,7 +50,7 @@ ${customer} ---- You can use a custom EL resolver to alter the way variables are resolved. -For instance, you can provide an EL resolver that intercepts objects with the name `customer`, so that `${customer}` returns a value in the EL resolver instead. +For instance, you can provide an EL resolver that intercepts objects with the name `customer`, so that `$\{customer}` returns a value in the EL resolver instead. (Jakarta Faces technology uses an EL resolver to handle managed beans.) An `enum` constant is a special case of a static field, and you can reference such a constant directly. @@ -134,9 +134,9 @@ Here are some examples: * `${"literal"}` -* `${true}` +* `$\{true}` -* `${57}` +* `$\{57}` ==== Parameterized Method Calls @@ -283,7 +283,7 @@ The `h:inputText` tag displays as a field. The `validator` attribute of this `h: Because a method can be invoked during different phases of the lifecycle, method expressions must always use the deferred evaluation syntax. Like lvalue expressions, method expressions can use the `.` and the `[]` operators. -For example, `#{object.method}` is equivalent to #`{object["method"]}`. +For example, `#{object.method}` is equivalent to #`{object["method"]}`. The literal inside the `[]` is converted to `String` and is used to find the name of the method that matches it. Method expressions can be used only in tag attributes and only in the following ways: diff --git a/src/main/asciidoc/faces-el/faces-el004.adoc b/src/main/antora/modules/web/pages/faces-el/faces-el004.adoc similarity index 100% rename from src/main/asciidoc/faces-el/faces-el004.adoc rename to src/main/antora/modules/web/pages/faces-el/faces-el004.adoc diff --git a/src/main/asciidoc/faces-el/faces-el005.adoc b/src/main/antora/modules/web/pages/faces-el/faces-el005.adoc similarity index 81% rename from src/main/asciidoc/faces-el/faces-el005.adoc rename to src/main/antora/modules/web/pages/faces-el/faces-el005.adoc index a83af184..f62065f6 100644 --- a/src/main/asciidoc/faces-el/faces-el005.adoc +++ b/src/main/antora/modules/web/pages/faces-el/faces-el005.adoc @@ -1,6 +1,6 @@ == Operators -In addition to the `.` and `[]` operators discussed in <>, the EL provides the following operators, which can be used in rvalue expressions only. +In addition to the `.` and `[]` operators discussed in xref:faces-el/faces-el.adoc#_value_and_method_expressions[Value and Method Expressions], the EL provides the following operators, which can be used in rvalue expressions only. * Arithmetic: `+`, `-` (binary), `*`, `/` and `div`, `%` and `mod`, `-` (unary). diff --git a/src/main/asciidoc/faces-el/faces-el006.adoc b/src/main/antora/modules/web/pages/faces-el/faces-el006.adoc similarity index 98% rename from src/main/asciidoc/faces-el/faces-el006.adoc rename to src/main/antora/modules/web/pages/faces-el/faces-el006.adoc index 5710e2cb..780bb4a3 100644 --- a/src/main/asciidoc/faces-el/faces-el006.adoc +++ b/src/main/antora/modules/web/pages/faces-el/faces-el006.adoc @@ -11,4 +11,4 @@ The following words are reserved for the EL and should not be used as identifier |`ge` |`true` |`false` |`null` |`instanceof`|`empty`|`div` |`mod` -|=== \ No newline at end of file +|=== diff --git a/src/main/asciidoc/faces-el/faces-el007.adoc b/src/main/antora/modules/web/pages/faces-el/faces-el007.adoc similarity index 75% rename from src/main/asciidoc/faces-el/faces-el007.adoc rename to src/main/antora/modules/web/pages/faces-el/faces-el007.adoc index d47ea763..29001816 100644 --- a/src/main/asciidoc/faces-el/faces-el007.adoc +++ b/src/main/antora/modules/web/pages/faces-el/faces-el007.adoc @@ -1,8 +1,8 @@ == Examples of EL Expressions -<> contains example EL expressions and the result of evaluating them. +<<_example_expressions>> contains example EL expressions and the result of evaluating them. -[[example-expressions]] +[[_example_expressions]] .Example Expressions [width="80%",cols="40%,40%"] |=== @@ -48,7 +48,7 @@ |`${requestScope['jakarta.servlet.forward.servlet_path']}` |The value of the request-scoped attribute named `jakarta.servlet.forward.servlet_path` -|`#{customer.lName}` |Gets the value of the property `lName` from the `customer` bean during an initial request; sets the value of `lName` during a postback +|`#{customer.lName}` |Gets the value of the property `lName` from the `customer` bean during an initial request; sets the value of `lName` during a postback -|`#{customer.calcTotal}` |The return value of the method `calcTotal` of the `customer` bean +|`#{customer.calcTotal}` |The return value of the method `calcTotal` of the `customer` bean |=== diff --git a/src/main/asciidoc/faces-el/faces-el008.adoc b/src/main/antora/modules/web/pages/faces-el/faces-el008.adoc similarity index 100% rename from src/main/asciidoc/faces-el/faces-el008.adoc rename to src/main/antora/modules/web/pages/faces-el/faces-el008.adoc diff --git a/src/main/asciidoc/faces-facelets/faces-facelets.adoc b/src/main/antora/modules/web/pages/faces-facelets/faces-facelets.adoc similarity index 95% rename from src/main/asciidoc/faces-facelets/faces-facelets.adoc rename to src/main/antora/modules/web/pages/faces-facelets/faces-facelets.adoc index ab3acabc..e1af5ea3 100644 --- a/src/main/asciidoc/faces-facelets/faces-facelets.adoc +++ b/src/main/antora/modules/web/pages/faces-facelets/faces-facelets.adoc @@ -1,5 +1,7 @@ = Introduction to Facelets +include::ROOT:partial$not_updated.adoc[] + The term Facelets refers to the view declaration language for Jakarta Faces technology. Facelets is a part of the Jakarta Faces specification and also the preferred presentation technology for building Jakarta Faces technology–based applications. Jakarta Server Pages technology, previously used as the presentation technology for Jakarta Faces, does not support all the new features available in Jakarta Faces in the Jakarta EE platform. diff --git a/src/main/asciidoc/faces-facelets/faces-facelets001.adoc b/src/main/antora/modules/web/pages/faces-facelets/faces-facelets001.adoc similarity index 86% rename from src/main/asciidoc/faces-facelets/faces-facelets001.adoc rename to src/main/antora/modules/web/pages/faces-facelets/faces-facelets001.adoc index 9e1e5fe0..97435a5c 100644 --- a/src/main/asciidoc/faces-facelets/faces-facelets001.adoc +++ b/src/main/antora/modules/web/pages/faces-facelets/faces-facelets001.adoc @@ -31,9 +31,9 @@ By convention, web pages built with XHTML have an `.xhtml` extension. Jakarta Faces technology supports various tag libraries to add components to a web page. To support the Jakarta Faces tag library mechanism, Facelets uses XML namespace declarations. -<> lists the tag libraries supported by Facelets. +<<_tag_libraries_supported_by_facelets>> lists the tag libraries supported by Facelets. -[[tag-libraries-supported-by-facelets]] +[[_tag_libraries_supported_by_facelets]] .Tag Libraries Supported by Facelets [width="99%",cols="25%,25%,10%,15%,20%"] |=== @@ -71,10 +71,10 @@ To support the Jakarta Faces tag library mechanism, Facelets uses XML namespace |=== Facelets provides two namespaces to support HTML5-friendly markup. -For details, see <>. +For details, see xref:faces-facelets/faces-facelets.adoc#_html5_friendly_markup[HTML5-Friendly Markup]. Facelets supports tags for composite components, for which you can declare custom prefixes. -For more information on composite components, see <>. +For more information on composite components, see xref:faces-facelets/faces-facelets.adoc#_composite_components[Composite Components]. The namespace prefixes shown in the table are conventional, not mandatory. As is always the case when you declare an XML namespace, you can specify any prefix in your Facelets page. @@ -92,4 +92,4 @@ xmlns:cc="jakarta.faces.composite" Based on the Jakarta Faces support for Expression Language (EL) syntax, Facelets uses EL expressions to reference properties and methods of managed beans. EL expressions can be used to bind component objects or values to methods or properties of managed beans that are used as backing beans. -For more information on using EL expressions, see <>. +For more information on using EL expressions, see xref:faces-develop/faces-develop.adoc#_using_the_el_to_reference_managed_beans[Using the EL to Reference Managed Beans]. diff --git a/src/main/asciidoc/faces-facelets/faces-facelets002.adoc b/src/main/antora/modules/web/pages/faces-facelets/faces-facelets002.adoc similarity index 72% rename from src/main/asciidoc/faces-facelets/faces-facelets002.adoc rename to src/main/antora/modules/web/pages/faces-facelets/faces-facelets002.adoc index 6d48ca37..ac761b53 100644 --- a/src/main/asciidoc/faces-facelets/faces-facelets002.adoc +++ b/src/main/antora/modules/web/pages/faces-facelets/faces-facelets002.adoc @@ -1,12 +1,12 @@ == The Lifecycle of a Facelets Application The Jakarta Faces specification defines the lifecycle of a Jakarta Faces application. -For more information on this lifecycle, see <>. +For more information on this lifecycle, see xref:faces-intro/faces-intro.adoc#_the_lifecycle_of_a_jakarta_faces_application[The Lifecycle of a Jakarta Faces Application]. The following steps describe that process as applied to a Facelets-based application. . When a client, such as a browser, makes a new request to a page that is created using Facelets, a new component tree or `jakarta.faces.component.UIViewRoot` is created and placed in the `FacesContext`. -. [[step-2-of-lifecycle-of-facelets, Step 2]] The `UIViewRoot` is applied to the Facelets, and the view is populated with components for rendering. +. [[_step_2_of_lifecycle_of_facelets, Step 2]] The `UIViewRoot` is applied to the Facelets, and the view is populated with components for rendering. . The newly built view is rendered back as a response to the client. @@ -20,6 +20,6 @@ At this time, the saved view is restored from the stored state. . If the same view is requested, the stored view is rendered once again. -. If a new view is requested, then the process described in <> is continued. +. If a new view is requested, then the process described in <<_step_2_of_lifecycle_of_facelets>> is continued. . The new view is then rendered back as a response to the client. diff --git a/src/main/asciidoc/faces-facelets/faces-facelets003.adoc b/src/main/antora/modules/web/pages/faces-facelets/faces-facelets003.adoc similarity index 56% rename from src/main/asciidoc/faces-facelets/faces-facelets003.adoc rename to src/main/antora/modules/web/pages/faces-facelets/faces-facelets003.adoc index 9ebe0aa3..b3a11125 100644 --- a/src/main/asciidoc/faces-facelets/faces-facelets003.adoc +++ b/src/main/antora/modules/web/pages/faces-facelets/faces-facelets003.adoc @@ -18,7 +18,7 @@ The following tasks are usually required: The example used in this tutorial is the `guessnumber-faces` 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/faces/guessnumber-faces/` directory. +The source code for this application is in the `_jakartaee-examples_/tutorial/web/faces/guessnumber-faces/` directory. ==== Developing a Managed Bean @@ -34,86 +34,85 @@ package ee.jakarta.tutorial.guessnumber; import java.io.Serializable; import java.util.Random; -import jakarta.enterprise.context.SessionScoped; + +import jakarta.annotation.PostConstruct; +import jakarta.faces.view.ViewScoped; import jakarta.inject.Named; @Named -@SessionScoped +@ViewScoped public class UserNumberBean implements Serializable { - private static final long serialVersionUID = 5443351151396868724L; - Integer randomInt = null; - Integer userNumber = null; - String response = null; - private int maximum = 10; - private int minimum = 0; - - public UserNumberBean() { - Random randomGR = new Random(); - randomInt = new Integer(randomGR.nextInt(maximum + 1)); - // Print number to server log + private static final long serialVersionUID = 1L; + + private static final int MINIMUM = 0; + private static final int MAXIMUM = 10; + + private int randomInt; + private Integer userNumber; + private String response; + + @PostConstruct + public void init() { + randomInt = new Random().nextInt(maximum + 1); + // Print number to server log. System.out.println("Duke's number: " + randomInt); } - public void setUserNumber(Integer user_number) { - userNumber = user_number; + public void guess() { + if (userNumber.compareTo(randomInt) != 0) { + response = "Sorry, " + userNumber + " is incorrect."; + } + else { + response = "Yay! You got it!"; + } } public Integer getUserNumber() { return userNumber; } - public String getResponse() { - if ((userNumber == null) || (userNumber.compareTo(randomInt) != 0)) { - return "Sorry, " + userNumber + " is incorrect."; - } else { - return "Yay! You got it!"; - } + public void setUserNumber(Integer userNumber) { + this.userNumber = userNumber; } - public int getMaximum() { - return (this.maximum); - } - - public void setMaximum(int maximum) { - this.maximum = maximum; + public String getResponse() { + return response; } public int getMinimum() { - return (this.minimum); + return MINIMUM; } - public void setMinimum(int minimum) { - this.minimum = minimum; + public int getMaximum() { + return MAXIMUM; } } ---- Note the use of the `@Named` annotation, which makes the managed bean accessible through the EL. -The `@SessionScoped` annotation registers the bean scope as `session` to enable you to make multiple guesses as you run the application. +The `@ViewScoped` annotation registers the bean scope as `view` to enable you to reuse the same bean instance as long as you interact with the same web page without navigating away. ==== Creating Facelets Views To create a page or view, you add components to the pages, wire the components to backing bean values and properties, and register converters, validators, or listeners on the components. For the example application, XHTML web pages serve as the front end. -The first page of the example application is a page called `greeting.xhtml`. +The page of the example application is a page called `greeting.xhtml`. A closer look at various sections of this web page provides more information. -The first section of the web page declares the content type for the page, which is XHTML: +The first section of the web page declares the document type of the generated HTML output, which is HTML5: [source,xml] ---- - + ---- -The next section specifies the language of the XHTML page and then declares the XML namespace for the tag libraries that are used in the web page: +The next section specifies the language of the text embedded in the generated HTML output and then declares the XML namespace for the tag libraries that are used in the web page: [source,xml] ---- ---- @@ -123,34 +122,39 @@ The next section uses various tags to insert components into the web page: [source,xml] ---- - Guess Number Facelets Application + - -

+ +

Hi, my name is Duke. I am thinking of a number from #{userNumberBean.minimum} to #{userNumberBean.maximum}. Can you guess it? -

-

- +

+
+ + + - -

- + +
+
+ + + +
+
+ +
---- @@ -161,45 +165,15 @@ Note the use of the following tags: * The Facelets core tag `f:validateLongRange` to validate the user input -An `h:inputText` tag accepts user input and sets the value of the managed bean property `userNumber` through the EL expression `#{userNumberBean.userNumber}`. +An `h:inputText` tag accepts user input and sets the value of the managed bean property `userNumber` through the EL expression `#{userNumberBean.userNumber}`. The input value is validated for value range by the Jakarta Faces standard validator tag `f:validateLongRange`. -The image file, `wave.med.gif`, is added to the page as a resource, as is the style sheet. -For more details about the resources facility, see <>. - -An `h:commandButton` tag with the ID `submit` starts validation of the input data when a user clicks the button. -Using implicit navigation, the tag redirects the client to another page, `response.xhtml`, which shows the response to your input. -The page specifies only `response`, which by default causes the server to look for `response.xhtml`. - -You can now create the second page, `response.xhtml`, with the following content: - -[source,xml] ----- - - - - - - - Guess Number Facelets Application - - - - -

- -

- - - - ----- +The image file, `wave.svg`, is added to the page as a resource, as is the style sheet. +For more details about the resources facility, see xref:faces-facelets/faces-facelets.adoc#_web_resources[Web Resources]. -This page also uses implicit navigation, setting the `action` attribute for the Back button to send the user to the `greeting.xhtml` page. +An `h:commandButton` tag with the ID `guess` starts validation of the input data when a user clicks the button. +Using `f:ajax`, the tag updates the `h:message` associated with the `h:inputText` so that it can display any validation error messages. +Also the `h:outputText` is being updated which shows the response to your input. === Configuring the Application @@ -212,10 +186,10 @@ Here is an example `web.xml` file, showing this change in bold. [source,xml] ---- - + jakarta.faces.PROJECT_STAGE Development @@ -229,11 +203,6 @@ Here is an example `web.xml` file, showing this change in bold. Faces Servlet *.xhtml - - - 30 - - greeting.xhtml @@ -253,14 +222,14 @@ You can use either NetBeans IDE or Maven to build, package, deploy, and run the ==== To Build, Package, and Deploy the guessnumber-faces Example Using NetBeans IDE -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . From the *File* menu, choose *Open Project*. . In the Open Project dialog box, navigate to: + ---- -tut-install/examples/web/faces +jakartaee-examples/tutorial/web/faces ---- . Select the `guessnumber-faces` folder. @@ -273,12 +242,12 @@ This option builds the example application and deploys it to your GlassFish Serv ==== To Build, Package, and Deploy the guessnumber-faces Example Using Maven -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . In a terminal window, go to: + ---- -tut-install/examples/web/faces/guessnumber-faces/ +jakartaee-examples/tutorial/web/faces/guessnumber-faces/ ---- . Enter the following command: diff --git a/src/main/asciidoc/faces-facelets/faces-facelets004.adoc b/src/main/antora/modules/web/pages/faces-facelets/faces-facelets004.adoc similarity index 62% rename from src/main/asciidoc/faces-facelets/faces-facelets004.adoc rename to src/main/antora/modules/web/pages/faces-facelets/faces-facelets004.adoc index 26873348..410ece48 100644 --- a/src/main/asciidoc/faces-facelets/faces-facelets004.adoc +++ b/src/main/antora/modules/web/pages/faces-facelets/faces-facelets004.adoc @@ -5,9 +5,9 @@ Templating is a useful Facelets feature that allows you to create a page that wi By using templates, you can reuse code and avoid recreating similarly constructed pages. Templating also helps in maintaining a standard look and feel in an application with a large number of pages. -<> lists Facelets tags that are used for templating and their respective functionality. +<<_facelets_templating_tags>> lists Facelets tags that are used for templating and their respective functionality. -[[facelets-templating-tags]] +[[_facelets_templating_tags]] .Facelets Templating Tags [width="99%",cols="20%,80%"] |=== @@ -43,35 +43,31 @@ The Facelets tag library includes the main templating tag `ui:insert`. A template page that is created with this tag allows you to define a default structure for a page. A template page is used as a template for other pages, usually referred to as client pages. -Here is an example of a template saved as `template.xhtml`: +Here is an example of a template saved as `/WEB-INF/templates/template.xhtml`: [source,xml] ---- - - + - - - Facelets Template + + -
+
Top Section
-
- Left Section -
-
- Main Content -
+
+ Left Section +
+
+ Main Content +
@@ -87,29 +83,26 @@ A client page allows content to be inserted with the help of the `ui:define` tag [source,xml] ---- - - - - - - - Welcome to Template Client Page - - - - - - - - - - - - - + + xmlns:ui="jakarta.faces.facelets" + xmlns:h="jakarta.faces.html"> + +

Welcome to Template Client Page

+ + + +

You are in the Left Section.

+ + + +
+ +
+

You are in the Main Content Section.

+ + ---- You can use NetBeans IDE to create Facelets template and client pages. diff --git a/src/main/asciidoc/faces-facelets/faces-facelets005.adoc b/src/main/antora/modules/web/pages/faces-facelets/faces-facelets005.adoc similarity index 61% rename from src/main/asciidoc/faces-facelets/faces-facelets005.adoc rename to src/main/antora/modules/web/pages/faces-facelets/faces-facelets005.adoc index 479605d2..81e37cab 100644 --- a/src/main/asciidoc/faces-facelets/faces-facelets005.adoc +++ b/src/main/antora/modules/web/pages/faces-facelets/faces-facelets005.adoc @@ -13,9 +13,9 @@ This reusable, user-created component has a customized, defined functionality an With Facelets, any XHTML page that contains markup tags and other components can be converted into a composite component. Using the resources facility, the composite component can be stored in a library that is available to the application from the defined resources location. -<> lists the most commonly used composite tags and their functions. +<<_composite_component_tags>> lists the most commonly used composite tags and their functions. -[[composite-component-tags]] +[[_composite_component_tags]] .Composite Component Tags [width="99%",cols="20%,80%"] |=== @@ -40,69 +40,68 @@ If a `composite:interface` element appears, there must be a corresponding `compo For more information and a complete list of Facelets composite tags, see the Jakarta Faces Facelets Tag Library documentation. -The following example shows a composite component that accepts an email address as input: +The following example shows a composite component that renders an form field with a label, input and message component: [source,xml] ---- - - - - - This content will not be displayed - - - - - - - - - - - - + + + + + + + +
+ + + +
+ + ---- -Note the use of `cc.attrs.value` when defining the value of the `inputText` component. +Note the use of `cc.attrs.value` when defining the value of the `outputLabel` and `inputText` components. The word `cc` in Jakarta Faces is a reserved word for composite components. -The `#{cc.attrs._attribute-name_}` expression is used to access the attributes defined for the composite component's interface, which in this case happens to be `value`. +The `#{cc.attrs._attribute-name_}` expression is used to access the attributes defined for the composite component's interface, which in this case happens to be `value`. -The preceding example content is stored as a file named `email.xhtml` in a folder named `resources/emcomp`, under the application web root directory. -This directory is considered a library by Jakarta Faces, and a component can be accessed from such a library. For more information on resources, see <>. +The preceding example content is stored as a file named `field.xhtml` in a folder named `resources/mycomponents`, under the application web root directory. +This directory is considered a library by Jakarta Faces, and a component can be accessed from such a library. +The `mycomponents` folder name is free to your choice. +For more information on resources, see xref:faces-facelets/faces-facelets.adoc#_web_resources[Web Resources]. The web page that uses this composite component is generally called a using page. The using page includes a reference to the composite component, in the `xml` namespace declarations: [source,xml] ---- - - + + Using a sample composite component - + - + - + ---- -The local composite component library is defined in the `xmlns` namespace with the declaration `xmlns:em="jakarta.faces.composite.emcomp"`. -The component itself is accessed through the `em:email` tag. -The preceding example content can be stored as a web page named `emuserpage.xhtml` under the web root directory. +The local composite component library is defined in the `xmlns` namespace with the declaration `xmlns:my="jakarta.faces.composite/mycomponents"`. +The `my` XML namespace are free to your choice. The `/mycomponents` part must represent the folder name where the composite component files are located. +The component itself is accessed through the `my:field` tag. +The preceding example content can be stored as a web page named `userpage.xhtml` under the web root directory. When compiled and deployed on a server, it can be accessed with the following URL: ---- -http://localhost:8080/application-name/emuserpage.xhtml +http://localhost:8080/application-name/userpage.xhtml ---- -See xref:composite-components-advanced-topics-and-an-example[xrefstyle=full] for more information and an example. +See xref:faces-advanced-cc/faces-advanced-cc.adoc#_composite_components_advanced_topics_and_an_example[Composite Components: Advanced Topics and an Example] for more information and an example. diff --git a/src/main/asciidoc/faces-facelets/faces-facelets006.adoc b/src/main/antora/modules/web/pages/faces-facelets/faces-facelets006.adoc similarity index 100% rename from src/main/asciidoc/faces-facelets/faces-facelets006.adoc rename to src/main/antora/modules/web/pages/faces-facelets/faces-facelets006.adoc diff --git a/src/main/asciidoc/faces-facelets/faces-facelets007.adoc b/src/main/antora/modules/web/pages/faces-facelets/faces-facelets007.adoc similarity index 84% rename from src/main/asciidoc/faces-facelets/faces-facelets007.adoc rename to src/main/antora/modules/web/pages/faces-facelets/faces-facelets007.adoc index 8f591e8c..54c329e6 100644 --- a/src/main/asciidoc/faces-facelets/faces-facelets007.adoc +++ b/src/main/antora/modules/web/pages/faces-facelets/faces-facelets007.adoc @@ -22,4 +22,4 @@ For example, the following `h:outputScript` tag is placed within an `h:form` ele The `h:outputStylesheet` tag also supports resource relocation, in a similar way. Relocatable resources are essential for composite components that use stylesheets and can also be useful for composite components that use JavaScript. -See <> for an example. +See xref:faces-advanced-cc/faces-advanced-cc.adoc#_the_compositecomponentexample_example_application[The compositecomponentexample Example Application] for an example. diff --git a/src/main/asciidoc/faces-facelets/faces-facelets008.adoc b/src/main/antora/modules/web/pages/faces-facelets/faces-facelets008.adoc similarity index 87% rename from src/main/asciidoc/faces-facelets/faces-facelets008.adoc rename to src/main/antora/modules/web/pages/faces-facelets/faces-facelets008.adoc index 755b4669..133d1d05 100644 --- a/src/main/asciidoc/faces-facelets/faces-facelets008.adoc +++ b/src/main/antora/modules/web/pages/faces-facelets/faces-facelets008.adoc @@ -57,12 +57,12 @@ You need to use this element only if your application uses more than one contrac === The hello1-rlc Example Application -The `hello1-rlc` example modifies the simple `hello1` example from <> to use two resource library contracts. +The `hello1-rlc` example modifies the simple `hello1` example from xref:webapp/webapp.adoc#_a_web_module_that_uses_jakarta_faces_technology_the_hello1_example[A Web Module That Uses Jakarta 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/faces/hello1-rlc/` directory. +The source code for this application is in the `_jakartaee-examples_/tutorial/web/faces/hello1-rlc/` directory. ==== Configuring the hello1-rlc Example @@ -91,7 +91,7 @@ The application is organized as follows: ---- hello1-rlc pom.xml - src/main/java/ee/jakarta/tutorial/hello1rlc/Hello.java + src/main/java/jakarta/tutorial/hello1rlc/Hello.java src/main/webapp WEB-INF faces-config.xml @@ -128,14 +128,14 @@ The `default.css` stylesheets in the two contracts differ in only one respect: t ==== To Build, Package, and Deploy the hello1-rlc Example Using NetBeans IDE -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . From the *File* menu, choose *Open Project*. . In the Open Project dialog box, navigate to: + ---- -tut-install/examples/web/faces +jakartaee-examples/tutorial/web/faces ---- . Select the `hello1-rlc` folder. @@ -148,12 +148,12 @@ This option builds the example application and deploys it to your GlassFish Serv ==== To Build, Package, and Deploy the hello1-rlc Example Using Maven -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . In a terminal window, go to: + ---- -tut-install/examples/web/faces/hello1-rlc/ +jakartaee-examples/tutorial/web/faces/hello1-rlc/ ---- . Enter the following command: diff --git a/src/main/asciidoc/faces-facelets/faces-facelets009.adoc b/src/main/antora/modules/web/pages/faces-facelets/faces-facelets009.adoc similarity index 81% rename from src/main/asciidoc/faces-facelets/faces-facelets009.adoc rename to src/main/antora/modules/web/pages/faces-facelets/faces-facelets009.adoc index 2f569249..c3865064 100644 --- a/src/main/asciidoc/faces-facelets/faces-facelets009.adoc +++ b/src/main/antora/modules/web/pages/faces-facelets/faces-facelets009.adoc @@ -2,7 +2,7 @@ When you want to produce user interface features for which HTML does not have its own elements, you can create a custom Jakarta Faces component and insert it in your Facelets page. This mechanism can cause a simple element to create complex web code. -However, creating such a component is a significant task (see xref:creating-custom-ui-components-and-other-custom-objects[xrefstyle=full]). +However, creating such a component is a significant task (see xref:faces-custom/faces-custom.adoc#_creating_custom_ui_components_and_other_custom_objects[Creating Custom UI Components and Other Custom Objects]). HTML5 offers new elements and attributes that can make it unnecessary to write your own components. It also provides many new capabilities for existing components. @@ -35,11 +35,11 @@ For example, the following code declares the namespace with the short name `face Here, the `faces` 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. -<> shows how pass-through elements are rendered as Facelets tags. +<<_how_facelets_renders_html5_elements>> shows how pass-through elements are rendered as Facelets tags. The 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. -[[how-facelets-renders-html5-elements]] +[[_how_facelets_renders_html5_elements]] .How Facelets Renders HTML5 Elements [width="60%",cols="20%,20%,20%"] |=== @@ -171,7 +171,7 @@ For example: + [source,xml] ---- - + ---- @@ -199,13 +199,12 @@ The `reservation` example application provides a set of HTML5 `input` elements o 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/faces/reservation/` directory. +The source code for this application is in the `_jakartaee-examples_/tutorial/web/faces/reservation/` directory. ==== The Facelets Pages for the reservation Application The first important feature of the Facelets pages for the `reservation` application is the `DOCTYPE` header. -Most Facelets pages in Jakarta Faces applications refer to the XHTML DTD. -The facelets pages for this application begin simply with the following `DOCTYPE` header, which indicates an HTML5 page: +The facelets pages for this application begin simply with the following `DOCTYPE` header, which indicates that the XHTML-generated result is an HTML5 page: [source,xml] ---- @@ -217,64 +216,60 @@ The namespace declarations in the `html` element of the `reservation.xhtml` page [source,xml] ---- + xmlns:p="jakarta.faces.passthrough"> ---- -Next, an empty `h:head` tag followed by an `h:outputStylesheet` tag within the `h:body` tag illustrates the use of a relocatable resource (as described in <>): +Next, an `h:head` tag followed by an `h:outputStylesheet` tag within the `h:body` tag illustrates the use of a relocatable resource (as described in xref:faces-facelets/faces-facelets.adoc#_relocatable_resources[Relocatable Resources]): [source,xml] ---- + Reservation Application - + ---- -The `reservation.xhtml` page uses pass-through elements for most of the form fields on the page. -This allows it to use some HTML5-specific `input` element types, such as `date` and `email`. -For example, the following element renders both a date format and a calendar from which you can choose a date. -The `faces` prefix on the `id` attribute makes the element a pass-through one: +The `reservation.xhtml` page uses a HTML5-specific `input` element type on `h:inputText`, which is `date`. [source,xml] ---- - + ---- -The field for the number of tickets, however, uses the `h:passThroughAttributes` tag to pass a `Map` defined in the managed bean. +The field for the number of tickets uses the `f:passThroughAttributes` tag to pass a `Map` defined in the managed bean. It also recalculates the total in response to a change in the field: [source,xml] ---- - + ---- -The field for the price specifies the `number` type as a pass-through attribute of the `h:inputText` element, offering a range of four ticket prices. +The field for the price specifies the `min`, `max` and `step` as a pass-through attribute of the `h:inputText` element, offering a range of four ticket prices. Here, the `p` prefix on the HTML5 attributes passes them through to the browser uninterpreted by the Jakarta Faces input component: [source,xml] ---- - - + + ---- The output of the `calculateTotal` method that is specified as the listener for the Ajax event is rendered in the output element whose `id` and `name` value is `total`. -See <>, for more information. +See xref:faces-ajax/faces-ajax.adoc#_using_ajax_with_jakarta_faces_technology[Using Ajax with Jakarta Faces Technology], for more information. The second Facelets page, `confirmation.xhtml`, uses a pass-through `output` element to display the values entered by the user and provides a Facelets `h:commandButton` tag to allow the user to return to the `reservation.xhtml` page. @@ -285,14 +280,14 @@ It also contains two methods, `calculateTotal` and `clear`, that act as listener ==== To Build, Package, and Deploy the reservation Example Using NetBeans IDE -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . From the *File* menu, choose *Open Project*. . In the Open Project dialog box, navigate to: + ---- -tut-install/examples/web/faces +jakartaee-examples/tutorial/web/faces ---- . Select the `reservation` folder. @@ -305,12 +300,12 @@ This option builds the example application and deploys it to your GlassFish Serv ==== To Build, Package, and Deploy the reservation Example Using Maven -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . In a terminal window, go to: + ---- -tut-install/examples/web/faces/reservation/ +jakartaee-examples/tutorial/web/faces/reservation/ ---- . Enter the following command: diff --git a/src/main/asciidoc/faces-intro/faces-intro.adoc b/src/main/antora/modules/web/pages/faces-intro/faces-intro.adoc similarity index 91% rename from src/main/asciidoc/faces-intro/faces-intro.adoc rename to src/main/antora/modules/web/pages/faces-intro/faces-intro.adoc index fd38e11c..d3f53392 100644 --- a/src/main/asciidoc/faces-intro/faces-intro.adoc +++ b/src/main/antora/modules/web/pages/faces-intro/faces-intro.adoc @@ -1,5 +1,7 @@ = Jakarta Faces Technology +include::ROOT:partial$not_updated.adoc[] + Jakarta Faces technology is a server-side component framework for building Java technology–based web applications. include::faces-intro001.adoc[] diff --git a/src/main/asciidoc/faces-intro/faces-intro001.adoc b/src/main/antora/modules/web/pages/faces-intro/faces-intro001.adoc similarity index 100% rename from src/main/asciidoc/faces-intro/faces-intro001.adoc rename to src/main/antora/modules/web/pages/faces-intro/faces-intro001.adoc diff --git a/src/main/asciidoc/faces-intro/faces-intro002.adoc b/src/main/antora/modules/web/pages/faces-intro/faces-intro002.adoc similarity index 83% rename from src/main/asciidoc/faces-intro/faces-intro002.adoc rename to src/main/antora/modules/web/pages/faces-intro/faces-intro002.adoc index d502878d..badc384e 100644 --- a/src/main/asciidoc/faces-intro/faces-intro002.adoc +++ b/src/main/antora/modules/web/pages/faces-intro/faces-intro002.adoc @@ -18,12 +18,12 @@ In a Jakarta Faces application, managed beans serve as backing beans, which defi * Optionally, a set of custom tags for representing custom objects on the page. -<> shows the interaction between client and server in a typical Jakarta Faces application. +<<_responding_to_a_client_request_for_a_jakarta_faces_page>> shows the interaction between client and server in a typical Jakarta Faces application. In response to a client request, a web page is rendered by the web container that implements Jakarta Faces technology. -[[responding-to-a-client-request-for-a-jakarta-faces-page]] +[[_responding_to_a_client_request_for_a_jakarta_faces_page]] .Responding to a Client Request for a Jakarta Faces Page -image::jakartaeett_dt_014.svg["Diagram that shows a browser accessing the myfacelet.xhtml page using an HTTP Request and the server sending the rendered HTML page using an HTTP Response."] +image::common:jakartaeett_dt_014.svg["Diagram that shows a browser accessing the myfacelet.xhtml page using an HTTP Request and the server sending the rendered HTML page using an HTTP Response."] The web page, `myfacelet.xhtml`, is built using Jakarta Faces component tags. Component tags are used to add components to the `view` (represented by `myView` in the diagram), which is the server-side representation of the page. diff --git a/src/main/asciidoc/faces-intro/faces-intro003.adoc b/src/main/antora/modules/web/pages/faces-intro/faces-intro003.adoc similarity index 79% rename from src/main/asciidoc/faces-intro/faces-intro003.adoc rename to src/main/antora/modules/web/pages/faces-intro/faces-intro003.adoc index fd999a22..8f24dd62 100644 --- a/src/main/asciidoc/faces-intro/faces-intro003.adoc +++ b/src/main/antora/modules/web/pages/faces-intro/faces-intro003.adoc @@ -8,23 +8,23 @@ The separation of logic from presentation also allows each member of a web appli For example, page authors with no programming expertise can use Jakarta Faces technology tags in a web page to link to server-side objects without writing any scripts. Another important goal of Jakarta Faces technology is to leverage familiar component and web-tier concepts without limiting you to a particular scripting technology or markup language. -Jakarta Faces technology APIs are layered directly on top of the Servlet API, as shown in <>. +Jakarta Faces technology APIs are layered directly on top of the Servlet API, as shown in <<_web_application_technologies>>. -[[web-application-technologies]] +[[_web_application_technologies]] .Web Application Technologies -image::jakartaeett_dt_015.svg["Diagram of web application technologies. Jakarta Server Pages, the server pages Standard Tag Library, and Jakarta Faces rest on Jakarta Servlet technology."] +image::common:jakartaeett_dt_015.svg["Diagram of web application technologies. Jakarta Server Pages, the server pages Standard Tag Library, and Jakarta Faces rest on Jakarta Servlet technology."] This layering of APIs enables several important application use cases, such as using different presentation technologies, creating your own custom components directly from the component classes, and generating output for various client devices. Facelets technology, available as part of Jakarta Faces technology, is the preferred presentation technology for building Jakarta Faces technology–based web applications. -For more information on Facelets technology features, see xref:introduction-to-facelets[xrefstyle=full]. +For more information on Facelets technology features, see xref:faces-facelets/faces-facelets.adoc#_introduction_to_facelets[Introduction to Facelets]. Facelets technology offers several advantages. * Code can be reused and extended for components through the templating and composite component features. * You can use annotations to automatically register the managed bean as a resource available for Jakarta Faces applications. -In addition, implicit navigation rules allow developers to quickly configure page navigation (see <> for details). +In addition, implicit navigation rules allow developers to quickly configure page navigation (see xref:faces-intro/faces-intro.adoc#_navigation_model[Navigation Model] for details). These features reduce the manual configuration process for applications. * Most important, Jakarta Faces technology provides a rich architecture for managing component state, processing component data, validating user input, and handling events. diff --git a/src/main/asciidoc/faces-intro/faces-intro004.adoc b/src/main/antora/modules/web/pages/faces-intro/faces-intro004.adoc similarity index 79% rename from src/main/asciidoc/faces-intro/faces-intro004.adoc rename to src/main/antora/modules/web/pages/faces-intro/faces-intro004.adoc index 650da758..222903ef 100644 --- a/src/main/asciidoc/faces-intro/faces-intro004.adoc +++ b/src/main/antora/modules/web/pages/faces-intro/faces-intro004.adoc @@ -1,7 +1,7 @@ == A Simple Jakarta Faces Application Jakarta Faces technology provides an easy and user-friendly process for creating web applications. -Developing a simple Jakarta Faces application typically requires the following tasks, which have already been described in <>: +Developing a simple Jakarta Faces application typically requires the following tasks, which have already been described in xref:webapp/webapp.adoc#_a_web_module_that_uses_jakarta_faces_technology_the_hello1_example[A Web Module That Uses Jakarta Faces Technology: The hello1 Example]: * Creating web pages using component tags @@ -12,9 +12,9 @@ Developing a simple Jakarta Faces application typically requires the following t The `hello1` example includes a managed bean and two Facelets web pages. When accessed by a client, the first web page asks the user for his or her name, and the second page responds by providing a greeting. -For details on Facelets technology, see xref:introduction-to-facelets[xrefstyle=full]. -For details on using EL expressions, see xref:expression-language[xrefstyle=full]. -For details on the Jakarta Faces programming model and building web pages using Jakarta Faces technology, see xref:using-jakarta-faces-technology-in-web-pages[xrefstyle=full]. +For details on Facelets technology, see xref:faces-facelets/faces-facelets.adoc#_introduction_to_facelets[Introduction to Facelets]. +For details on using EL expressions, see xref:faces-el/faces-el.adoc#_expression_language[Expression Language]. +For details on the Jakarta Faces programming model and building web pages using Jakarta Faces technology, see xref:faces-page/faces-page.adoc#_using_jakarta_faces_technology_in_web_pages[Using Jakarta Faces Technology in Web Pages]. Every web application has a lifecycle. Common tasks, such as handling incoming requests, decoding parameters, modifying and saving state, and rendering web pages to the browser, are all performed during a web application lifecycle. @@ -64,4 +64,4 @@ The `hello1` example application goes through the following stages when it is de . On subsequent (postback) requests, the component tree is rebuilt, and the saved state is applied. -For full details on the lifecycle, see <>. +For full details on the lifecycle, see xref:faces-intro/faces-intro.adoc#_the_lifecycle_of_a_jakarta_faces_application[The Lifecycle of a Jakarta Faces Application]. diff --git a/src/main/asciidoc/faces-intro/faces-intro005.adoc b/src/main/antora/modules/web/pages/faces-intro/faces-intro005.adoc similarity index 84% rename from src/main/asciidoc/faces-intro/faces-intro005.adoc rename to src/main/antora/modules/web/pages/faces-intro/faces-intro005.adoc index 0bf91968..a1f0fe69 100644 --- a/src/main/asciidoc/faces-intro/faces-intro005.adoc +++ b/src/main/antora/modules/web/pages/faces-intro/faces-intro005.adoc @@ -27,7 +27,7 @@ This section briefly describes each of these pieces of the component architectur Jakarta 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 xref:creating-custom-ui-components-and-other-custom-objects[xrefstyle=full] for more information. +See xref:faces-custom/faces-custom.adoc#_creating_custom_ui_components_and_other_custom_objects[Creating Custom UI Components and Other Custom Objects] for more information. The abstract base class for all components is `jakarta.faces.component.UIComponent`. Jakarta Faces UI component classes extend the `UIComponentBase` class (a subclass of `UIComponent`), which defines the default state and behavior of a component. @@ -137,7 +137,7 @@ The `Button` or `Link` part of each tag corresponds to a separate `Renderer` cla 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 <> lists all supported component tags and illustrates how to use the tags in an example. +The section xref:faces-page/faces-page.adoc#_adding_components_to_a_page_using_html_tag_library_tags[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 Faces implementation provides a custom tag library for rendering components in HTML. @@ -164,7 +164,7 @@ To facilitate this, Jakarta Faces technology allows you to register a `jakarta.f 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 Faces implementation or create your own custom converter. -Custom converter creation is covered in xref:creating-custom-ui-components-and-other-custom-objects[xrefstyle=full]. +Custom converter creation is covered in xref:faces-custom/faces-custom.adoc#_creating_custom_ui_components_and_other_custom_objects[Creating Custom UI Components and Other Custom Objects]. === Event and Listener Model @@ -190,7 +190,7 @@ An example is selecting a check box, an action that results in the component's v 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 <>) 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. +Depending on the value of the `immediate` property (see xref:faces-page/faces-page.adoc#_the_immediate_attribute[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. @@ -204,15 +204,15 @@ There are two ways to cause your application to react to action events or value- * Implement a method of a managed bean to handle the event, and refer to the method with a method expression from the appropriate attribute of the component's tag. -See <> for information on how to implement an event listener. -See <> for information on how to register the listener on a component. +See xref:faces-custom/faces-custom.adoc#_implementing_an_event_listener[Implementing an Event Listener] for information on how to implement an event listener. +See xref:faces-page-core/faces-page-core.adoc#_registering_listeners_on_components[Registering Listeners on Components] for information on how to register the listener on a component. -See <> and <> for information on how to implement managed bean methods that handle these events. +See xref:faces-develop/faces-develop.adoc#_writing_a_method_to_handle_an_action_event[Writing a Method to Handle an Action Event] and xref:faces-develop/faces-develop.adoc#_writing_a_method_to_handle_a_value_change_event[Writing a Method to Handle a Value-Change Event] for information on how to implement managed bean methods that handle these events. -See <> for information on how to refer to the managed bean method from the component tag. +See xref:faces-page-core/faces-page-core.adoc#_referencing_a_managed_bean_method[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. -<> explains how to do this. +xref:faces-custom/faces-custom.adoc#_handling_events_for_custom_components[Handling Events for Custom Components] explains how to do this. === Validation Model @@ -221,13 +221,13 @@ This validation occurs before the corresponding model data is updated to match t Like the conversion model, the validation model defines a set of standard classes for performing common data validation checks. The Jakarta Faces core tag library also defines a set of tags that correspond to the standard `jakarta.faces.validator.Validator` implementations. -See <> for a list of all the standard validation classes and corresponding tags. +See xref:faces-page-core/faces-page-core.adoc#_using_the_standard_validators[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 <>. +For more information on default validators, see xref:faces-configure/faces-configure.adoc#_using_default_validators[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. @@ -244,4 +244,4 @@ 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 xref:introduction-to-jakarta-bean-validation[xrefstyle=full] and xref:bean-validation-advanced-topics[xrefstyle=full] for more information on Bean Validation. +See xref:beanvalidation:bean-validation/bean-validation.adoc#_introduction_to_jakarta_bean_validation[Introduction to Jakarta Bean Validation] and xref:beanvalidation:bean-validation-advanced/bean-validation-advanced.adoc#_bean_validation_advanced_topics[Bean Validation: Advanced Topics] for more information on Bean Validation. diff --git a/src/main/asciidoc/faces-intro/faces-intro006.adoc b/src/main/antora/modules/web/pages/faces-intro/faces-intro006.adoc similarity index 93% rename from src/main/asciidoc/faces-intro/faces-intro006.adoc rename to src/main/antora/modules/web/pages/faces-intro/faces-intro006.adoc index 34362952..317ee5c5 100644 --- a/src/main/asciidoc/faces-intro/faces-intro006.adoc +++ b/src/main/antora/modules/web/pages/faces-intro/faces-intro006.adoc @@ -134,8 +134,8 @@ The return value of `createdStudent` has a corresponding navigation case in the After the student is created, the user is returned to the Administration index page. -For more information on how to define navigation rules, see <>. +For more information on how to define navigation rules, see xref:faces-configure/faces-configure.adoc#_configuring_navigation_rules[Configuring Navigation Rules]. -For more information on how to implement action methods to handle navigation, see <>. +For more information on how to implement action methods to handle navigation, see xref:faces-develop/faces-develop.adoc#_writing_a_method_to_handle_an_action_event[Writing a Method to Handle an Action Event]. -For more information on how to reference outcomes or action methods from component tags, see <>. +For more information on how to reference outcomes or action methods from component tags, see xref:faces-page-core/faces-page-core.adoc#_referencing_a_method_that_performs_navigation[Referencing a Method That Performs Navigation]. diff --git a/src/main/asciidoc/faces-intro/faces-intro007.adoc b/src/main/antora/modules/web/pages/faces-intro/faces-intro007.adoc similarity index 90% rename from src/main/asciidoc/faces-intro/faces-intro007.adoc rename to src/main/antora/modules/web/pages/faces-intro/faces-intro007.adoc index 3e4e027b..4adbabbe 100644 --- a/src/main/asciidoc/faces-intro/faces-intro007.adoc +++ b/src/main/antora/modules/web/pages/faces-intro/faces-intro007.adoc @@ -15,10 +15,10 @@ During a web application lifecycle, common tasks are performed, including the fo The Jakarta Faces web application framework manages lifecycle phases automatically for simple applications or allows you to manage them manually for more complex applications as required. Jakarta Faces applications that use advanced features may require interaction with the lifecycle at certain phases. -For example, Ajax applications use partial processing features of the lifecycle (see <>). +For example, Ajax applications use partial processing features of the lifecycle (see xref:faces-intro/faces-intro.adoc#_partial_processing_and_partial_rendering[Partial Processing and Partial Rendering]). A clearer understanding of the lifecycle phases is key to creating well-designed components. -A simplified view of the Jakarta Faces lifecycle, consisting of the two main phases of a Jakarta Faces web application, is introduced in <>. +A simplified view of the Jakarta Faces lifecycle, consisting of the two main phases of a Jakarta Faces web application, is introduced in xref:faces-intro/faces-intro.adoc#_a_simple_jakarta_faces_application[A Simple Jakarta Faces Application]. This section examines the Jakarta Faces lifecycle in more detail. === Overview of the Jakarta Faces Lifecycle @@ -34,11 +34,11 @@ During the lifecycle, the Jakarta Faces implementation must build the view while When the client requests a page, the Jakarta 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 Faces implementation performs all these tasks as a series of steps in the Jakarta Faces request-response lifecycle. -<> illustrates these steps. +<<_jakarta_faces_standard_request_response_lifecycle>> illustrates these steps. -[[jakarta-faces-standard-request-response-lifecycle]] +[[_jakarta_faces_standard_request_response_lifecycle]] .Jakarta Faces Standard Request-Response Lifecycle -image::jakartaeett_dt_016.svg["Flow diagram of Faces request and Faces response, including event and validation processing, error handling, model updating, application invocation."] +image::common:jakartaeett_dt_016.svg["Flow diagram of Faces request and Faces response, including event and validation processing, error handling, model updating, application invocation."] 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. @@ -49,7 +49,7 @@ Conversely, when the lifecycle handles a postback, it executes all of the phases Usually, the first request for a Jakarta Faces page comes in from a client, as a result of clicking a link or button component on a Jakarta Faces page. To render a response that is another Jakarta Faces page, the application creates a new view and stores it in the `jakarta.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 <> of the lifecycle, as is shown by the arrows labelled Render Response in <>. +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 <<_jakarta_faces_standard_request_response_lifecycle>>. 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 Faces components. In these situations, the developer must skip the Render Response phase by calling the `FacesContext.responseComplete` method. @@ -59,24 +59,24 @@ The most common situation is that a Jakarta Faces component submits a request fo In this case, the Jakarta 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 <> rather than in a later phase. +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 Faces Specification documentation from https://jakarta.ee/specifications/faces/[^]. The Jakarta Faces application lifecycle Execute phase contains the following subphases: -* <> +* <<_restore_view_phase>> -* <> +* <<_apply_request_values_phase>> -* <> +* <<_process_validations_phase>> -* <> +* <<_update_model_values_phase>> -* <> +* <<_invoke_application_phase>> -* <> +* <<_render_response_phase>> === Restore View Phase @@ -99,7 +99,7 @@ If any `decode` methods or event listeners have called the `renderResponse` meth If any events have been queued during this phase, the Jakarta Faces implementation broadcasts the events to interested listeners. -If some components on the page have their `immediate` attributes (see <>) set to `true`, then the validations, conversions, and events associated with these components will be processed during this phase. +If some components on the page have their `immediate` attributes (see xref:faces-page/faces-page.adoc#_the_immediate_attribute[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. diff --git a/src/main/asciidoc/faces-intro/faces-intro008.adoc b/src/main/antora/modules/web/pages/faces-intro/faces-intro008.adoc similarity index 83% rename from src/main/asciidoc/faces-intro/faces-intro008.adoc rename to src/main/antora/modules/web/pages/faces-intro/faces-intro008.adoc index 2f74aee4..333d6225 100644 --- a/src/main/asciidoc/faces-intro/faces-intro008.adoc +++ b/src/main/antora/modules/web/pages/faces-intro/faces-intro008.adoc @@ -8,4 +8,4 @@ Once such a partial request enters the Jakarta Faces lifecycle, the information The Jakarta Faces lifecycle is still aware of such Ajax requests and modifies the component tree accordingly. The `execute` and `render` attributes of the `f:ajax` tag are used to identify which components may be executed and rendered. -For more information on these attributes, see xref:using-ajax-with-jakarta-faces-technology[xrefstyle=full]. +For more information on these attributes, see xref:faces-ajax/faces-ajax.adoc#_using_ajax_with_jakarta_faces_technology[Using Ajax with Jakarta Faces Technology]. diff --git a/src/main/asciidoc/faces-intro/faces-intro009.adoc b/src/main/antora/modules/web/pages/faces-intro/faces-intro009.adoc similarity index 100% rename from src/main/asciidoc/faces-intro/faces-intro009.adoc rename to src/main/antora/modules/web/pages/faces-intro/faces-intro009.adoc diff --git a/src/main/asciidoc/faces-page-core/faces-page-core.adoc b/src/main/antora/modules/web/pages/faces-page-core/faces-page-core.adoc similarity index 95% rename from src/main/asciidoc/faces-page-core/faces-page-core.adoc rename to src/main/antora/modules/web/pages/faces-page-core/faces-page-core.adoc index 437754c6..c76a25ce 100644 --- a/src/main/asciidoc/faces-page-core/faces-page-core.adoc +++ b/src/main/antora/modules/web/pages/faces-page-core/faces-page-core.adoc @@ -1,5 +1,7 @@ = Using Converters, Listeners, and Validators +include::ROOT:partial$not_updated.adoc[] + The previous chapter described components and explained how to add them to a web page. This chapter provides information on adding more functionality to the components through converters, listeners, and validators. diff --git a/src/main/asciidoc/faces-page-core/faces-page-core001.adoc b/src/main/antora/modules/web/pages/faces-page-core/faces-page-core001.adoc similarity index 90% rename from src/main/asciidoc/faces-page-core/faces-page-core001.adoc rename to src/main/antora/modules/web/pages/faces-page-core/faces-page-core001.adoc index a9ac5f64..ef9f6417 100644 --- a/src/main/asciidoc/faces-page-core/faces-page-core001.adoc +++ b/src/main/antora/modules/web/pages/faces-page-core/faces-page-core001.adoc @@ -2,14 +2,14 @@ The Jakarta Faces implementation provides a set of `Converter` implementations that you can use to convert component data. The purpose of conversion is to take the String-based data coming in from the Servlet API and convert it to strongly typed Java objects suitable for the business domain. -For more information on the conceptual details of the conversion model, see <>. +For more information on the conceptual details of the conversion model, see xref:faces-intro/faces-intro.adoc#_conversion_model[Conversion Model]. The standard `Converter` implementations are located in the `jakarta.faces.convert` package. Normally, converters are implicitly assigned based on the type of the EL expression pointed to by the value of the component. However, these converters can also be accessed by a converter ID. -<> shows the converter classes and their associated converter IDs. +<<_converter_classes_and_converter_ids>> shows the converter classes and their associated converter IDs. -[[converter-classes-and-converter-ids]] +[[_converter_classes_and_converter_ids]] .Converter Classes and Converter IDs [width="60%",cols="30%,30%"] |=== @@ -51,11 +51,11 @@ For example, the following error message appears if `BigIntegerConverter` fails {0} must be a number consisting of one or more digits ---- -In this case, the `{0}` substitution parameter will be replaced with the name of the input component on which the converter is registered. +In this case, the `\{0}` substitution parameter will be replaced with the name of the input component on which the converter is registered. Two of the standard converters (`DateTimeConverter` and `NumberConverter`) have their own tags, which allow you to configure the format of the component data using the tag attributes. -For more information about using `DateTimeConverter`, see <>. -For more information about using `NumberConverter`, see <>. +For more information about using `DateTimeConverter`, see <<_using_datetimeconverter>>. +For more information about using `NumberConverter`, see <<_using_numberconverter>>. The following section explains how to convert a component's value, including how to register other standard converters with a component. === Converting a Component's Value @@ -64,7 +64,7 @@ To use a particular converter to convert a component's value, you need to regist You can register any of the standard converters in one of the following ways. * Nest one of the standard converter tags inside the component's tag. -These tags are `f:convertDateTime` and `f:convertNumber`, which are described in <>, respectively. +These tags are `f:convertDateTime` and `f:convertNumber`, which are described in <<_using_numberconverter>>, respectively. * Bind the value of the component to a managed bean property of the same type as the converter. This is the most common technique. @@ -90,7 +90,7 @@ If you don't need to specify any formatting instructions using the `f:convertNum You can also nest an `f:converter` tag within the component tag and use either the converter tag's `converterId` attribute or its `binding` attribute to reference the converter. The `converterId` attribute must reference the converter's ID. -Here is an example that uses one of the converter IDs listed in <>: +Here is an example that uses one of the converter IDs listed in <<_converter_classes_and_converter_ids>>: [source,xml] ---- @@ -103,13 +103,13 @@ Instead of using the `converterId` attribute, the `f:converter` tag can use the The `binding` attribute must resolve to a bean property that accepts and returns an appropriate `Converter` instance. You can also create custom converters and register them on components using the `f:converter` tag. -For details, see <>. +For details, see xref:faces-custom/faces-custom.adoc#_creating_and_using_a_custom_converter[Creating and Using a Custom Converter]. === Using DateTimeConverter You can convert a component's data to a `java.util.Date` by nesting the `convertDateTime` tag inside the component tag. The `convertDateTime` tag has several attributes that allow you to specify the format and type of the data. -<> lists the attributes. +<<_attributes_for_the_fconvertdatetime_tag>> lists the attributes. Here is a simple example of a `convertDateTime` tag: @@ -157,7 +157,7 @@ jueves 24 de octubre de 2013 15:07:04 GMT Refer to the "Customizing Formats" lesson of the Java Tutorial at https://docs.oracle.com/javase/tutorial/i18n/format/simpleDateFormat.html[^] for more information on how to format the output using the `pattern` attribute of the `convertDateTime` tag. -[[attributes-for-the-fconvertDateTime-tag]] +[[_attributes_for_the_fconvertdatetime_tag]] .Attributes for the f:convertDateTime Tag [width="99%",cols="25%a,25%,50%"] |=== @@ -179,7 +179,7 @@ If not specified, the `Locale` returned by `FacesContext.getLocale` will be used |`pattern` |`String` a| Custom formatting pattern that determines how the date/time string should be formatted and parsed. If this attribute is specified, `dateStyle` and `timeStyle` attributes are ignored. -See <> for the default values when `pattern` is not specified. +See <<_type_attribute_and_default_pattern_values>> for the default values when `pattern` is not specified. |`timeStyle` |`String` a|Defines the format, as specified by `java.text.DateFormat`, of a `time` or the time part of a `date` string. Applied only if `type` is time and `pattern` is not defined. @@ -192,10 +192,10 @@ If no value is specified, `default` is used. Valid values are: `date`, `time`, `both`, `LocalDate`, `LocalTime`, `LocalDateTime`, `OffsetTime`, `OffsetDateTime`, or `ZonedDateTime`. If no value is specified, `date` is used. -See <> for additional information. +See <<_type_attribute_and_default_pattern_values>> for additional information. |=== -[[type-attribute-and-default-pattern-values]] +[[_type_attribute_and_default_pattern_values]] .Type Attribute and Default Pattern Values [width="99%",cols="25%,25%,50%"] |=== @@ -224,7 +224,7 @@ See <> for additional information. You can convert a component's data to a `java.lang.Number` by nesting the `convertNumber` tag inside the component tag. The `convertNumber` tag has several attributes that allow you to specify the format and type of the data. -<> lists the attributes. +<<_attributes_for_the_fconvertnumber_tag>> lists the attributes. The following example uses a `convertNumber` tag to display the total prices of the contents of a shopping cart: @@ -255,7 +255,7 @@ This result can also be displayed by using the following tag in which the curren See the "Customizing Formats" lesson of the Java Tutorial at https://docs.oracle.com/javase/tutorial/i18n/format/decimalFormat.html[^] for more information on how to format the output by using the `pattern` attribute of the `convertNumber` tag. -[[attributes-for-the-fconvertNumber-tag]] +[[_attributes_for_the_fconvertnumber_tag]] .Attributes for the f:convertNumber Tag [width="99%",cols="25%,25%,50%"] |=== diff --git a/src/main/asciidoc/faces-page-core/faces-page-core002.adoc b/src/main/antora/modules/web/pages/faces-page-core/faces-page-core002.adoc similarity index 86% rename from src/main/asciidoc/faces-page-core/faces-page-core002.adoc rename to src/main/antora/modules/web/pages/faces-page-core/faces-page-core002.adoc index d1368eea..5a77eca2 100644 --- a/src/main/asciidoc/faces-page-core/faces-page-core002.adoc +++ b/src/main/antora/modules/web/pages/faces-page-core/faces-page-core002.adoc @@ -4,7 +4,7 @@ An application developer can implement listeners as classes or as managed bean m If a listener is a managed bean method, the page author references the method from either the component's `valueChangeListener` attribute or its `actionListener` attribute. If the listener is a class, the page author can reference the listener from either an `f:valueChangeListener` tag or an `f:actionListener` tag and nest the tag inside the component tag to register the listener on the component. -<> and <> explain how a page author uses the `valueChangeListener` and `actionListener` attributes to reference managed bean methods that handle events. +xref:faces-page-core/faces-page-core.adoc#_referencing_a_method_that_handles_an_action_event[Referencing a Method That Handles an Action Event] and xref:faces-page-core/faces-page-core.adoc#_referencing_a_method_that_handles_a_value_change_event[Referencing a Method That Handles a Value-Change Event] explain how a page author uses the `valueChangeListener` and `actionListener` attributes to reference managed bean methods that handle events. This section explains how to register a `NameChanged` value-change listener and a `BookChange` action listener implementation on components. The Duke's Bookstore case study includes both of these listeners. @@ -12,9 +12,9 @@ The Duke's Bookstore case study includes both of these listeners. === Registering a Value-Change Listener on a Component A page author can register a `ValueChangeListener` implementation on a component that implements `EditableValueHolder` by nesting an `f:valueChangeListener` tag within the component's tag on the page. -The `f:valueChangeListener` tag supports the attributes shown in <>, one of which must be used. +The `f:valueChangeListener` tag supports the attributes shown in <<_attributes_for_the_fvaluechangelistener_tag>>, one of which must be used. -[[attributes-for-the-fvaluechangelistener-tag]] +[[_attributes_for_the_fvaluechangelistener_tag]] .Attributes for the f:valueChangeListener Tag [width="60%",cols="10%,50%"] |=== @@ -47,7 +47,7 @@ After this component tag is processed and local values have been validated, its The `binding` attribute is used to bind a `ValueChangeListener` implementation to a managed bean property. This attribute works in a similar way to the `binding` attribute supported by the standard converter tags. -See <> for more information. +See xref:faces-custom/faces-custom.adoc#_binding_component_values_and_instances_to_managed_bean_properties[Binding Component Values and Instances to Managed Bean Properties] for more information. === Registering an Action Listener on a Component @@ -68,7 +68,7 @@ Here is an example of an `h:commandLink` tag that references an `ActionListener` The `type` attribute of the `f:actionListener` tag specifies the fully qualified class name of the `ActionListener` implementation. Similarly to the `f:valueChangeListener` tag, the `f:actionListener` tag also supports the `binding` attribute. -See <> for more information about binding listeners to managed bean properties. +See xref:faces-custom/faces-custom.adoc#_binding_converters_listeners_and_validators_to_managed_bean_properties[Binding Converters, Listeners, and Validators to Managed Bean Properties] for more information about binding listeners to managed bean properties. In addition to the `actionListener` tag that allows you register a custom listener onto a component, the core tag library includes the `f:setPropertyActionListener` tag. You use this tag to register a special action listener onto the `ActionSource` instance associated with a component. diff --git a/src/main/asciidoc/faces-page-core/faces-page-core003.adoc b/src/main/antora/modules/web/pages/faces-page-core/faces-page-core003.adoc similarity index 77% rename from src/main/asciidoc/faces-page-core/faces-page-core003.adoc rename to src/main/antora/modules/web/pages/faces-page-core/faces-page-core003.adoc index 29644a47..3dcae6a1 100644 --- a/src/main/asciidoc/faces-page-core/faces-page-core003.adoc +++ b/src/main/antora/modules/web/pages/faces-page-core/faces-page-core003.adoc @@ -1,9 +1,9 @@ == Using the Standard Validators Jakarta Faces technology provides a set of standard classes and associated tags that page authors and application developers can use to validate a component's data. -<> lists all the standard validator classes and the tags that allow you to use the validators from the page. +<<_the_validator_classes>> lists all the standard validator classes and the tags that allow you to use the validators from the page. -[[the-validator-classes]] +[[_the_validator_classes]] .The Validator Classes [width="99%",cols="15%,15%,60%"] |=== @@ -39,35 +39,35 @@ For example, the error message that displays when the component's value exceeds {1}: Validation Error: Value is greater than allowable maximum of "{0}" ---- -In this case, the `{1}` substitution parameter is replaced by the component's label or `id`, and the `{0}` substitution parameter is replaced with the maximum value allowed by the validator. +In this case, the `\{1}` substitution parameter is replaced by the component's label or `id`, and the `\{0}` substitution parameter is replaced with the maximum value allowed by the validator. -See <> for information on how to display validation error messages on the page when validation fails. +See xref:faces-page/faces-page.adoc#_displaying_error_messages_with_the_hmessage_and_hmessages_tags[Displaying Error Messages with the h:message and h:messages Tags] for information on how to display validation error messages on the page when validation fails. Instead of using the standard validators, you can use Bean Validation to validate data. If you specify bean validation constraints on your managed bean properties, the constraints are automatically placed on the corresponding fields on your applications web pages. -See xref:introduction-to-jakarta-bean-validation[xrefstyle=full] for more information. +See xref:beanvalidation:bean-validation/bean-validation.adoc#_introduction_to_jakarta_bean_validation[Introduction to Jakarta Bean Validation] for more information. You do not need to specify the `validateBean` tag to use Bean Validation, but the tag allows you to use more advanced Bean Validation features. For example, you can use the `validationGroups` attribute of the tag to specify constraint groups. You can also create and register custom validators, although Bean Validation has made this feature less useful. -For details, see <>. +For details, see xref:faces-custom/faces-custom.adoc#_creating_and_using_a_custom_validator[Creating and Using a Custom Validator]. === Validating a Component's Value To validate a component's value using a particular validator, you need to register that validator on the component. You can do this in one of the following ways. -* Nest the validator's corresponding tag (shown in <>) inside the component's tag. -<> explains how to use the `validateLongRange` tag. +* Nest the validator's corresponding tag (shown in <<_the_validator_classes>>) inside the component's tag. +<<_using_validator_tags>> explains how to use the `validateLongRange` tag. You can use the other standard tags in the same way. * Refer to a method that performs the validation from the component tag's `validator` attribute. * Nest a validator tag inside the component tag, and use either the validator tag's `validatorId` attribute or its `binding` attribute to refer to the validator. -See <> for more information on using the `validator` attribute. +See xref:faces-page-core/faces-page-core.adoc#_referencing_a_method_that_performs_validation[Referencing a Method That Performs Validation] for more information on using the `validator` attribute. -The `validatorId` attribute works similarly to the `converterId` attribute of the `converter` tag, as described in <>. +The `validatorId` attribute works similarly to the `converterId` attribute of the `converter` tag, as described in xref:faces-page-core/faces-page-core.adoc#_converting_a_components_value[Converting a Component's Value]. Keep in mind that validation can be performed only on components that implement `EditableValueHolder`, because these components accept values that can be validated. diff --git a/src/main/asciidoc/faces-page-core/faces-page-core004.adoc b/src/main/antora/modules/web/pages/faces-page-core/faces-page-core004.adoc similarity index 79% rename from src/main/asciidoc/faces-page-core/faces-page-core004.adoc rename to src/main/antora/modules/web/pages/faces-page-core/faces-page-core004.adoc index 81aa44e5..96edb410 100644 --- a/src/main/asciidoc/faces-page-core/faces-page-core004.adoc +++ b/src/main/antora/modules/web/pages/faces-page-core/faces-page-core004.adoc @@ -1,9 +1,9 @@ == Referencing a Managed Bean Method A component tag has a set of attributes for referencing managed bean methods that can perform certain functions for the component associated with the tag. -These attributes are summarized in <>. +These attributes are summarized in <<_component_tag_attributes_that_reference_managed_bean_methods>>. -[[component-tag-attributes-that-reference-managed-bean-methods]] +[[_component_tag_attributes_that_reference_managed_bean_methods]] .Component Tag Attributes That Reference Managed Bean Methods [width="60%",cols="10%,50%"] |=== @@ -50,7 +50,7 @@ The following example shows how to reference a navigation method: action="#{cashierBean.submit}" /> ---- -See <> for information on how to write such a method. +See xref:faces-develop/faces-develop.adoc#_writing_a_method_to_handle_navigation[Writing a Method to Handle Navigation] for information on how to write such a method. === Referencing a Method That Handles an Action Event @@ -66,13 +66,13 @@ The following example shows how such a method could be referenced: The `actionListener` attribute of this component tag references the `chooseBookFromLink` method using a method expression. The `chooseBookFromLink` method handles the event when the user clicks the link rendered by this component. -See <> for information on how to write such a method. +See xref:faces-develop/faces-develop.adoc#_writing_a_method_to_handle_an_action_event[Writing a Method to Handle an Action Event] for information on how to write such a method. === Referencing a Method That Performs Validation If the input of one of the components on your page is validated by a managed bean method, refer to the method from the component's tag by using the `validator` attribute. -The following simplified example from <> shows how to reference a method that performs validation on `inputGuess`, an input component: +The following simplified example from xref:cdi:cdi-basicexamples/cdi-basicexamples.adoc#_the_guessnumber_cdi_cdi_example[The guessnumber-cdi CDI Example] shows how to reference a method that performs validation on `inputGuess`, an input component: [source,xml] ---- @@ -85,7 +85,7 @@ The following simplified example from <> shows ---- The managed bean method `validateNumberRange` verifies that the input value is within the valid range, which changes each time another guess is made. -See <> for information on how to write such a method. +See xref:faces-develop/faces-develop.adoc#_writing_a_method_to_perform_validation[Writing a Method to Perform Validation] for information on how to write such a method. === Referencing a Method That Handles a Value-Change Event @@ -104,4 +104,4 @@ If you want a component on your page to generate a value-change event and you wa The `valueChangeListener` attribute of this component tag references the `processValueChange` method of `CashierBean` by using a method expression. The `processValueChange` method handles the event of a user entering a name in the input field rendered by this component. -<> describes how to implement a method that handles a `ValueChangeEvent`. +xref:faces-develop/faces-develop.adoc#_writing_a_method_to_handle_a_value_change_event[Writing a Method to Handle a Value-Change Event] describes how to implement a method that handles a `ValueChangeEvent`. diff --git a/src/main/asciidoc/faces-page/faces-page.adoc b/src/main/antora/modules/web/pages/faces-page/faces-page.adoc similarity index 77% rename from src/main/asciidoc/faces-page/faces-page.adoc rename to src/main/antora/modules/web/pages/faces-page/faces-page.adoc index 356f92ba..b3f3c9b8 100644 --- a/src/main/asciidoc/faces-page/faces-page.adoc +++ b/src/main/antora/modules/web/pages/faces-page/faces-page.adoc @@ -1,12 +1,14 @@ = Using Jakarta Faces Technology in Web Pages +include::ROOT:partial$not_updated.adoc[] + Web pages (Facelets pages, in most cases) represent the presentation layer for web applications. The process of creating web pages for a Jakarta Faces application includes using component tags to add components to the page and wire them to backing beans, validators, listeners, converters, and other server-side objects that are associated with the page. This chapter explains how to create web pages using various types of component and core tags. In the next chapter, you will learn about adding converters, validators, and listeners to component tags to provide additional functionality to components. -Many of the examples in this chapter are taken from xref:dukes-bookstore-case-study-example[xrefstyle=full] +Many of the examples in this chapter are taken from xref:casestudies:dukes-bookstore/dukes-bookstore.adoc#_dukes_bookstore_case_study_example[Duke's Bookstore Case Study Example] include::faces-page001.adoc[] diff --git a/src/main/asciidoc/faces-page/faces-page001.adoc b/src/main/antora/modules/web/pages/faces-page/faces-page001.adoc similarity index 84% rename from src/main/asciidoc/faces-page/faces-page001.adoc rename to src/main/antora/modules/web/pages/faces-page/faces-page001.adoc index 975df041..e5821264 100644 --- a/src/main/asciidoc/faces-page/faces-page001.adoc +++ b/src/main/antora/modules/web/pages/faces-page/faces-page001.adoc @@ -37,4 +37,4 @@ For example, in the following web page the `form` tag must be referenced using t ---- -The sections <> and <> describe how to use the component tags from the Jakarta Faces standard HTML tag library and the core tags from the Jakarta Faces core tag library. +The sections xref:faces-page/faces-page.adoc#_adding_components_to_a_page_using_html_tag_library_tags[Adding Components to a Page Using HTML Tag Library Tags] and xref:faces-page/faces-page.adoc#_using_core_tags[Using Core Tags] describe how to use the component tags from the Jakarta Faces standard HTML tag library and the core tags from the Jakarta Faces core tag library. diff --git a/src/main/asciidoc/faces-page/faces-page002.adoc b/src/main/antora/modules/web/pages/faces-page/faces-page002.adoc similarity index 88% rename from src/main/asciidoc/faces-page/faces-page002.adoc rename to src/main/antora/modules/web/pages/faces-page/faces-page002.adoc index 0b897bec..1b75fb44 100644 --- a/src/main/asciidoc/faces-page/faces-page002.adoc +++ b/src/main/antora/modules/web/pages/faces-page/faces-page002.adoc @@ -3,9 +3,9 @@ The tags defined by the Jakarta Faces standard HTML tag library represent HTML form components and other basic HTML elements. These components display data or accept data from the user. This data is collected as part of a form and is submitted to the server, usually when the user clicks a button. -This section explains how to use each of the component tags shown in <>. +This section explains how to use each of the component tags shown in <<_the_component_tags>>. -[[the-component-tags]] +[[_the_component_tags]] .The Component Tags [width="99%",cols="15%,30%,30%,25%"] |=== @@ -67,18 +67,18 @@ For a standalone radio button, use the `group` attribute. |=== The tags correspond to components in the `jakarta.faces.component` package. -The components are discussed in more detail in xref:developing-with-jakarta-faces-technology[xrefstyle=full] +The components are discussed in more detail in xref:faces-develop/faces-develop.adoc#_developing_with_jakarta_faces_technology[Developing with Jakarta Faces Technology] The next section explains the important attributes that are common to most component tags. -For each of the components discussed in the following sections, <> explains how to write a bean property bound to that particular component or its value. +For each of the components discussed in the following sections, xref:faces-develop/faces-develop.adoc#_writing_bean_properties[Writing Bean Properties] explains how to write a bean property bound to that particular component or its value. For reference information about the tags and their attributes, see the https://jakarta.ee/specifications/faces/3.0/vdldoc/[Jakarta Faces Facelets Tag Library documentation^]. === Common Component Tag Attributes -Most of the component tags support the attributes shown in <>. +Most of the component tags support the attributes shown in <<_common_tag_attributes>>. -[[common-tag-attributes]] +[[_common_tag_attributes]] .Common Component Tag Attributes [width="80%",cols="20%,60%"] |=== @@ -100,7 +100,7 @@ If the condition is not satisfied, the component is not rendered. |`value` |Specifies the value of the component in the form of a value expression. |=== -All the tag attributes except `id` can accept expressions, as defined by the Expression Language, described in xref:expression-language[xrefstyle=full]. +All the tag attributes except `id` can accept expressions, as defined by the Expression Language, described in xref:faces-el/faces-el.adoc#_expression_language[Expression Language]. An attribute such as `rendered` or `value` can be set on the page and then modified in the backing bean for the page. @@ -108,8 +108,8 @@ An attribute such as `rendered` or `value` can be set on the page and then modif The `id` attribute is not usually required for a component tag but is used when another component or a server-side class must refer to the component. If you don't include an `id` attribute, the Jakarta Faces implementation automatically generates a component ID. -Unlike most other Jakarta Faces tag attributes, the `id` attribute takes expressions using only the evaluation syntax described in <>, which uses the `${}` delimiters. -For more information on expression syntax, see <>. +Unlike most other Jakarta Faces tag attributes, the `id` attribute takes expressions using only the evaluation syntax described in xref:faces-el/faces-el.adoc#_immediate_evaluation[Immediate Evaluation], which uses the `${}` delimiters. +For more information on expression syntax, see xref:faces-el/faces-el.adoc#_value_expressions[Value Expressions]. ==== The immediate Attribute @@ -171,18 +171,18 @@ For example, the `commandLink` component in the following section of a page is n ---- Unlike nearly every other Jakarta Faces tag attribute, the `rendered` attribute is restricted to using rvalue expressions. -As explained in <>, these rvalue expressions can only read data; they cannot write the data back to the data source. +As explained in xref:faces-el/faces-el.adoc#_value_and_method_expressions[Value and Method Expressions], these rvalue expressions can only read data; they cannot write the data back to the data source. Therefore, expressions used with `rendered` attributes can use the arithmetic operators and literals that rvalue expressions can use but lvalue expressions cannot use. For example, the expression in the preceding example uses the `>` operator. [NOTE] In this example and others, `bundle` refers to a `java.util.ResourceBundle` file that contains locale-specific strings to be displayed. -Resource bundles are discussed in xref:internationalizing-and-localizing-web-applications[xrefstyle=full]. +Resource bundles are discussed in xref:webi18n/webi18n.adoc#_internationalizing_and_localizing_web_applications[Internationalizing and Localizing Web Applications]. ==== The style and styleClass Attributes The `style` and `styleClass` attributes allow you to specify CSS styles for the rendered output of your tags. -<> describes an example of using the `style` attribute to specify styles directly in the attribute. +<<_displaying_error_messages_with_the_hmessage_and_hmessages_tags>> describes an example of using the `style` attribute to specify styles directly in the attribute. A component tag can instead refer to a CSS class. The following example shows the use of a `dataTable` tag that references the style class `list-background`: @@ -203,7 +203,7 @@ For more information on defining styles, see the Cascading Style Sheets specific A tag representing an output component uses the `value` and `binding` attributes to bind its component's value or instance, respectively, to a data object. The `value` attribute is used more commonly than the `binding` attribute, and examples appear throughout this chapter. -For more information on these attributes, see <>, <>, and <>. +For more information on these attributes, see xref:faces-develop/faces-develop.adoc#_creating_a_managed_bean[Creating a Managed Bean], xref:faces-develop/faces-develop.adoc#_writing_properties_bound_to_component_values[Writing Properties Bound to Component Values], and xref:faces-develop/faces-develop.adoc#_writing_properties_bound_to_component_instances[Writing Properties Bound to Component Instances]. === Adding HTML Head and Body Tags @@ -217,14 +217,13 @@ The following is an example of an XHTML page using the usual head and body marku [source,xml] ---- - - + + Add a title - Add Content +
Add content
---- @@ -233,32 +232,30 @@ The following is an example of an XHTML page using `h:head` and `h:body` tags: [source,xml] ---- - - + + - Add a title + Add a title - Add Content +
Add content
 ---- Both of the preceding example code segments render the same HTML elements. The head and body tags are useful mainly for resource relocation. -For more information on resource relocation, see <>. +For more information on resource relocation, see <<_resource_relocation_using_houtputscript_and_houtputstylesheet_tags>>. === Adding a Form Component An `h:form` tag represents an input form, which includes child components that can contain data that is either presented to the user or submitted with the form. -<> shows a typical login form in which a user enters a user name and password, then submits the form by clicking the Login button. +<<_a_typical_form>> shows a typical login form in which a user enters a user name and password, then submits the form by clicking the Login button. -[[a-typical-form]] +[[_a_typical_form]] .A Typical Form -image::jakartaeett_dt_065_frmcmpnt.svg["Form with User Name and Password text fields and a Login button."] +image::common:jakartaeett_dt_065_frmcmpnt.svg["Form with User Name and Password text fields and a Login button."] The `h:form` tag represents the form on the page and encloses all the components that display or collect data from the user, as shown here: @@ -285,11 +282,11 @@ The basic types of text components are as follows: * Password field, which is a type of field that displays a set of characters, such as asterisks, instead of the password text that the user enters -<> shows examples of these text components. +<<_example_text_components>> shows examples of these text components. -[[example-text-components]] +[[_example_text_components]] .Example Text Components -image::jakartaeett_dt_068_txtcmpnts.svg["A form. "User Name" labels a field. "Password" labels a password field. "Comments" labels a multi-line field."] +image::common:jakartaeett_dt_068_txtcmpnts.svg["A form. "User Name" labels a field. "Password" labels a password field. "Comments" labels a multi-line field."] Text components can be categorized as either input or output. A Jakarta Faces output component, such as a label, is rendered as read-only text. @@ -297,9 +294,9 @@ A Jakarta Faces input component, such as a field, is rendered as editable text. The input and output components can each be rendered in various ways to display more specialized text. -<> lists the tags that represent the input components. +<<_input_tags>> lists the tags that represent the input components. -[[input-tags]] +[[_input_tags]] .Input Tags [width="80%",cols="20%,60%"] |=== @@ -314,18 +311,18 @@ The input and output components can each be rendered in various ways to display |`h:inputTextarea` |The standard multiline field: accepts multiple lines of text |=== -The input tags support the tag attributes shown in <> in addition to those described in <>. +The input tags support the tag attributes shown in <<_input_tag_attributes>> in addition to those described in <<_common_component_tag_attributes>>. Note that this table does not include all the attributes supported by the input tags but just those that are used most often. For the complete list of attributes, refer to the https://jakarta.ee/specifications/faces/3.0/vdldoc/[Jakarta Faces Facelets Tag Library documentation^]. -[[input-tag-attributes]] +[[_input_tag_attributes]] .Input Tag Attributes [width="80%",cols="20%,60%"] |=== |Attribute |Description |`converter` |Identifies a converter that will be used to convert the component's local data. -See <> for more information on how to use this attribute. +See xref:faces-page-core/faces-page-core.adoc#_using_the_standard_converters[Using the Standard Converters] for more information on how to use this attribute. |`converterMessage` |Specifies an error message to display when the converter registered on the component fails. @@ -341,17 +338,17 @@ Acceptable values are `ltr`, meaning left to right, and `rtl`, meaning right to |`requiredMessage` |Specifies an error message to display when the user does not enter a value into the component. |`validator` |Identifies a method expression pointing to a managed bean method that performs validation on the component's data. -See <> for an example of using the `f:validator` tag. +See xref:faces-page-core/faces-page-core.adoc#_referencing_a_method_that_performs_validation[Referencing a Method That Performs Validation] for an example of using the `f:validator` tag. |`validatorMessage` |Specifies an error message to display when the validator registered on the component fails to validate the component's local value. |`valueChangeListener` |Identifies a method expression that points to a managed bean method that handles the event of entering a value in this component. -See <> for an example of using `valueChangeListener`. +See xref:faces-page-core/faces-page-core.adoc#_referencing_a_method_that_handles_a_value_change_event[Referencing a Method That Handles a Value-Change Event] for an example of using `valueChangeListener`. |=== -<> lists the tags that represent the output components. +<<_output_tags>> lists the tags that represent the output components. -[[output-tags]] +[[_output_tags]] .Output Tags [width="80%",cols="20%,60%"] |=== @@ -366,9 +363,9 @@ See <> for an example of |`h:outputText` |Displays a one-line text string |=== -The output tags support the `converter` tag attribute in addition to those listed in <>. +The output tags support the `converter` tag attribute in addition to those listed in <<_common_component_tag_attributes>>. -The rest of this section explains how to use some of the tags listed in <>. +The rest of this section explains how to use some of the tags listed in <<_output_tags>>. The other tags are written in a similar way. ==== Rendering a Field with the h:inputText Tag @@ -405,7 +402,7 @@ The Jakarta Faces implementation checks whether the value of the component is nu If your component must have a non-null value or a `String` value at least one character in length, you should add a `required` attribute to your tag and set its value to `true`. If your tag has a `required` attribute that is set to `true` and the value is null or a zero-length string, no other validators that are registered on the tag are called. If your tag does not have a `required` attribute set to `true`, other validators that are registered on the tag are called, but those validators must handle the possibility of a null or zero-length string. -See <> for more information. +See xref:beanvalidation:bean-validation/bean-validation.adoc#_validating_null_and_empty_strings[Validating Null and Empty Strings] for more information. ==== Rendering a Password Field with the h:inputSecret Tag @@ -490,7 +487,7 @@ Here is an example of an `h:outputFormat` tag: The `value` attribute specifies the `MessageFormat` pattern. The `f:param` tag specifies the substitution parameters for the message. -The value of the parameter replaces the `{0}` in the sentence. +The value of the parameter replaces the `\{0}` in the sentence. If the value of `"#{hello.name}"` is "Bill", the message displayed in the page is as follows: ---- @@ -509,7 +506,7 @@ Here is the preceding example modified with an additional parameter: ---- -The value of `{1}` is replaced by the second parameter. +The value of `\{1}` is replaced by the second parameter. The parameter is an EL expression, `bean.numVisitor`, in which the property `numVisitor` of the managed bean `bean` keeps track of visitors to the page. This is an example of a value-expression-enabled tag attribute accepting an EL expression. The message displayed in the page is now as follows: @@ -526,15 +523,15 @@ These tags are called command component tags because they perform an action when The `h:commandButton` tag is rendered as a button. The `h:commandLink` tag is rendered as a link. -In addition to the tag attributes listed in <>, the `h:commandButton` and `h:commandLink` tags can use the following attributes. +In addition to the tag attributes listed in <<_common_component_tag_attributes>>, the `h:commandButton` and `h:commandLink` tags can use the following attributes. * `action`, which is either a logical outcome `String` or a method expression pointing to a bean method that returns a logical outcome `String`. In either case, the logical outcome `String` is used to determine what page to access when the command component tag is activated. * `actionListener`, which is a method expression pointing to a bean method that processes an action event fired by the command component tag. -See <> for more information on using the `action` attribute. -See <> for details on using the `actionListener` attribute. +See xref:faces-page-core/faces-page-core.adoc#_referencing_a_method_that_performs_navigation[Referencing a Method That Performs Navigation] for more information on using the `action` attribute. +See xref:faces-page-core/faces-page-core.adoc#_referencing_a_method_that_handles_an_action_event[Referencing a Method That Handles an Action Event] for details on using the `actionListener` attribute. ==== Rendering a Button with the h:commandButton Tag @@ -551,7 +548,7 @@ Clicking the button will cause the `submit` method of `CashierBean` to be invoke The `submit` method performs some processing and returns a logical outcome. The `value` attribute of the example `h:commandButton` tag references the button's label. -For information on how to use the `action` attribute, see <>. +For information on how to use the `action` attribute, see xref:faces-page-core/faces-page-core.adoc#_referencing_a_method_that_performs_navigation[Referencing a Method That Performs Navigation]. ==== Rendering a Link with the h:commandLink Tag @@ -595,7 +592,7 @@ In a Jakarta Faces application, use the `h:graphicImage` tag to render an image In this example, the `url` attribute specifies the path to the image. The URL of the example tag begins with a slash (`/`), which adds the relative context path of the web application to the beginning of the path to the image. -Alternatively, you can use the facility described in <> to point to the image location. +Alternatively, you can use the facility described in xref:faces-facelets/faces-facelets.adoc#_web_resources[Web Resources] to point to the image location. Here are two examples: [source,xml] @@ -626,9 +623,9 @@ header { In a Jakarta Faces application, you use a panel as a layout container for a set of other components. A panel is rendered as an HTML table. -<> lists the tags used to create panels. +<<_panel_component_tags>> lists the tags used to create panels. -[[panel-component-tags]] +[[_panel_component_tags]] .Panel Component Tags [width="90%",cols="20%,50%,20%"] |=== @@ -707,9 +704,9 @@ Because the `h:panelGrid` tag specifies a `headerClass`, the `h:panelGrid` tag m The example `h:panelGrid` tag uses an `f:facet` tag for the header. Facets can have only one child, so an `h:panelGroup` tag is needed if you want to group more than one component within an `f:facet`. The example `h:panelGrid` tag has only one cell of data, so an `h:panelGroup` tag is not needed. -(For more information about facets, see <>. +(For more information about facets, see <<_using_data_bound_table_components>>. -The `h:panelGroup` tag has an attribute, `layout`, in addition to those listed in <>. +The `h:panelGroup` tag has an attribute, `layout`, in addition to those listed in <<_common_component_tag_attributes>>. If the `layout` attribute has the value `block`, an HTML `div` element is rendered to enclose the row; otherwise, an HTML `span` element is rendered to enclose the row. If you are specifying styles for the `h:panelGroup` tag, you should set the `layout` attribute to `block` in order for the styles to be applied to the components within the `h:panelGroup` tag. You should do this because styles, such as those that set width and height, are not applied to inline elements, which is how content enclosed by the `span` element is defined. @@ -734,11 +731,11 @@ The most common tags for this kind of component are as follows: * An `h:selectOneListbox` tag, displayed as an unscrollable list -<> shows examples of these components. +<<_example_components_for_selecting_one_item>> shows examples of these components. -[[example-components-for-selecting-one-item]] +[[_example_components_for_selecting_one_item]] .Example Components for Selecting One Item -image::jakartaeett_dt_067_slctn.svg["Options, check box, and lists."] +image::common:jakartaeett_dt_067_slctn.svg["Options, check box, and lists."] ==== Displaying a Check Box Using the h:selectBooleanCheckbox Tag @@ -788,7 +785,7 @@ You are not required to provide a value for the currently selected item. If you don't provide a value, the browser determines which one is selected. Like the `h:selectOneRadio` tag, the `h:selectOneMenu` tag must contain either an `f:selectItems` tag or a set of `f:selectItem` tags for representing the items in the list. -<> describes these tags. +<<_using_the_fselectitem_and_fselectitems_tags>> describes these tags. === Displaying Components for Selecting Multiple Values @@ -801,11 +798,11 @@ You can do this using one of the following component tags: * An `h:selectManyListbox` tag, displayed as a box -<> shows examples of these components. +<<_example_components_for_selecting_multiple_values>> shows examples of these components. -[[example-components-for-selecting-multiple-values]] +[[_example_components_for_selecting_multiple_values]] .Example Components for Selecting Multiple Values -image::jakartaeett_dt_066_slctmny.svg["Check box group, scrollable box, and unscrollable box."] +image::common:jakartaeett_dt_066_slctmny.svg["Check box group, scrollable box, and unscrollable box."] These tags allow the user to select zero or more values from a set of values. This section explains the `h:selectManyCheckbox` tag. @@ -868,7 +865,7 @@ The rest of this section shows you how to use the `f:selectItems` and `f:selectI ==== Using the f:selectItems Tag -The following example from <> shows how to use the `h:selectManyCheckbox` tag: +The following example from <<_displaying_components_for_selecting_multiple_values>> shows how to use the `h:selectManyCheckbox` tag: [source,xml] ---- @@ -882,12 +879,12 @@ The following example from <> for information on how to write a managed bean property for one of these tags. +See xref:faces-develop/faces-develop.adoc#_uiselectitems_properties[UISelectItems Properties] for information on how to write a managed bean property for one of these tags. ==== Using the f:selectItem Tag The `f:selectItem` tag represents a single item in a list of items. -Here is the example from <> once again: +Here is the example from <<_displaying_a_menu_using_the_hselectonemenu_tag>> once again: [source,xml] ---- @@ -913,7 +910,7 @@ These attributes can also define literal values, as shown in the example `h:sele If you display components that allow a user to select values, you may also want to display the result of the selection. -For example, you might want to thank a user who selected the checkbox to join the Duke Fan Club, as described in <>. +For example, you might want to thank a user who selected the checkbox to join the Duke Fan Club, as described in <<_displaying_a_check_box_using_the_hselectbooleancheckbox_tag>>. Because the checkbox is bound to the `specialOffer` property of `CashierBean`, a `UISelectBoolean` value, you can call the `isSelected` method of the property to determine whether to render a thank-you message: [source,xml] @@ -922,7 +919,7 @@ Because the checkbox is bound to the `specialOffer` property of `CashierBean`, a rendered="#{cashierBean.specialOffer.isSelected()}"/> ---- -Similarly, you might want to acknowledge that a user subscribed to newsletters using the `h:selectManyCheckbox` tag, as described in <>. +Similarly, you might want to acknowledge that a user subscribed to newsletters using the `h:selectManyCheckbox` tag, as described in <<_displaying_components_for_selecting_multiple_values>>. To do so, you can retrieve the value of the `newsletters` property, the `String` array that holds the selected items: [source,xml] @@ -938,7 +935,7 @@ To do so, you can retrieve the value of the `newsletters` property, the `String` An introductory thank-you message is displayed only if the `newsletters` array is not empty. Then a `ui:repeat` tag, a simple way to show values in a loop, displays the contents of the selected items in an itemized list. -(This tag is listed in <>.) +(This tag is listed in xref:faces-facelets/faces-facelets.adoc#_facelets_templating_tags[Facelets Templating Tags].) === Using Data-Bound Table Components @@ -1038,7 +1035,7 @@ This data can take the form of any of the following: All data sources for data components have a `DataModel` wrapper. Unless you explicitly construct a `DataModel` wrapper, the Jakarta Faces implementation will create one around data of any of the other acceptable types. -See <> for more information on how to write properties for use with a data component. +See xref:faces-develop/faces-develop.adoc#_writing_bean_properties[Writing Bean Properties] for more information on how to write properties for use with a data component. The `var` attribute specifies a name that is used by the components within the `h:dataTable` tag as an alias to the data referenced in the `value` attribute of `h:dataTable`. @@ -1056,9 +1053,9 @@ For example, if you wanted to display records 2 through 10 of the underlying dat When you display a subset of the data in your pages, you might want to consider including a link or button that causes subsequent rows to display when clicked. By default, both `first` and `rows` are set to zero, and this causes all the rows of the underlying data to display. -<> shows the optional attributes for the `h:dataTable` tag. +<<_optional_attributes_for_the_hdatatable_tag>> shows the optional attributes for the `h:dataTable` tag. -[[optional-attributes-for-the-hdatatable-tag]] +[[_optional_attributes_for_the_hdatatable_tag]] .Optional Attributes for the h:dataTable Tag [width="60%",cols="30%,30%"] |=== @@ -1077,7 +1074,7 @@ By default, both `first` and `rows` are set to zero, and this causes all the row |`styleClass` |The entire table |=== -Each of the attributes in <> can specify more than one style. +Each of the attributes in <<_optional_attributes_for_the_hdatatable_tag>> can specify more than one style. If `columnClasses` or `rowClasses` specifies more than one style, the styles are applied to the columns or rows in the order that the styles are listed in the attribute. For example, if `columnClasses` specifies styles `list-column-center` and `list-column-right`, and if the table has two columns, the first column will have style `list-column-center`, and the second column will have style `list-column-right`. @@ -1224,24 +1221,24 @@ The order in which the various parameter values are read is as follows: === The bookmarks Example Application -The `bookmarks` example application modifies the `hello1` application described in <> to use a bookmarkable URL that uses view parameters. +The `bookmarks` example application modifies the `hello1` application described in xref:webapp/webapp.adoc#_a_web_module_that_uses_jakarta_faces_technology_the_hello1_example[A Web Module That Uses Jakarta Faces Technology: The hello1 Example] to use a bookmarkable URL that uses view parameters. Like `hello1`, the application includes the `Hello.java` managed bean, an `index.xhtml` page, and a `response.xhtml` page. -In addition, it includes a `personal.xhtml page`, to which a bookmarkable URL and view parameters are passed from the `response.xhtml` page, as described in <>. +In addition, it includes a `personal.xhtml page`, to which a bookmarkable URL and view parameters are passed from the `response.xhtml` page, as described in <<_using_view_parameters_to_configure_bookmarkable_urls>>. You can use either NetBeans IDE or Maven to build, package, deploy, and run the `bookmarks` example. -The source code for this example is in the `_tut-install_/examples/web/faces/bookmarks/` directory. +The source code for this example is in the `_jakartaee-examples_/tutorial/web/faces/bookmarks/` directory. ==== To Build, Package, and Deploy the bookmarks Example Using NetBeans IDE -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . From the *File* menu, choose *Open Project*. . In the Open Project dialog box, navigate to: + ---- -tut-install/examples/web/faces +jakartaee-examples/tutorial/web/faces ---- . Select the `bookmarks` folder. @@ -1254,12 +1251,12 @@ This option builds the example application and deploys it to your GlassFish Serv ==== To Build, Package, and Deploy the bookmarks Example Using Maven -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . In a terminal window, go to: + ---- -tut-install/examples/web/faces/bookmarks/ +jakartaee-examples/tutorial/web/faces/bookmarks/ ---- . Enter the following command: diff --git a/src/main/asciidoc/faces-page/faces-page003.adoc b/src/main/antora/modules/web/pages/faces-page/faces-page003.adoc similarity index 55% rename from src/main/asciidoc/faces-page/faces-page003.adoc rename to src/main/antora/modules/web/pages/faces-page/faces-page003.adoc index 7672b8f2..cfa9315d 100644 --- a/src/main/asciidoc/faces-page/faces-page003.adoc +++ b/src/main/antora/modules/web/pages/faces-page/faces-page003.adoc @@ -2,9 +2,9 @@ The tags included in the Jakarta Faces core tag library are used to perform core actions that are not performed by HTML tags. -<> lists the event-handling core tags. +<<_event_handling_core_tags>> lists the event-handling core tags. -[[event-handling-core-tags]] +[[_event_handling_core_tags]] .Event-Handling Core Tags [width="99%",cols="30%,70%"] |=== @@ -19,9 +19,9 @@ The tags included in the Jakarta Faces core tag library are used to perform core |`f:valueChangeListener` |Adds a value-change listener to a parent component |=== -<> lists the data-conversion core tags. +<<_data_conversion_core_tags>> lists the data-conversion core tags. -[[data-conversion-core-tags]] +[[_data_conversion_core_tags]] .Data-Conversion Core Tags [width="99%",cols="30%,70%"] |=== @@ -34,9 +34,9 @@ The tags included in the Jakarta Faces core tag library are used to perform core |`f:convertNumber` a|Adds a `NumberConverter` instance to the parent component |=== -<> lists the facet core tags. +<<_facet_core_tags>> lists the facet core tags. -[[facet-core-tags]] +[[_facet_core_tags]] .Facet Core Tags [width="99%",cols="30%,70%"] |=== @@ -48,9 +48,9 @@ its enclosing tag |`f:metadata` a|Registers a `facet` on a parent component |=== -<> lists the core tags that represent items in a list. +<<_core_tags_that_represent_items_in_a_list>> lists the core tags that represent items in a list. -[[core-tags-that-represent-items-in-a-list]] +[[_core_tags_that_represent_items_in_a_list]] .Core Tags That Represent Items in a List [width="99%",cols="30%,70%"] |=== @@ -61,9 +61,9 @@ its enclosing tag |`f:selectItems` |Represents a set of items |=== -<> lists the validator core tags. +<<_validator_core_tags>> lists the validator core tags. -[[validator-core-tags]] +[[_validator_core_tags]] .Validator Core Tags [width="99%",cols="30%,70%"] |=== @@ -84,9 +84,9 @@ its enclosing tag |`f:validateRequired` |Enforces the presence of a value in a component |=== -<> lists the core tags that fall into other categories. +<<_miscellaneous_core_tags>> lists the core tags that fall into other categories. -[[miscellaneous-core-tags]] +[[_miscellaneous_core_tags]] .Miscellaneous Core Tags [width="99%",cols="25%,15%,60%"] |=== @@ -107,31 +107,31 @@ its enclosing tag These tags, which are used in conjunction with component tags, are explained in other sections of this tutorial. -<> lists the sections that explain how to use specific core tags. +<<_where_the_core_tags_are_explained>> lists the sections that explain how to use specific core tags. -[[where-the-core-tags-are-explained]] +[[_where_the_core_tags_are_explained]] .Where the Core Tags Are Explained [width="99%",cols="30%,70%"] |=== |Tags |Where Explained -|Event-handling tags | <> +|Event-handling tags | xref:faces-page-core/faces-page-core.adoc#_registering_listeners_on_components[Registering Listeners on Components] -|Data-conversion tags | <> +|Data-conversion tags | xref:faces-page-core/faces-page-core.adoc#_using_the_standard_converters[Using the Standard Converters] -|`f:facet` |<> and <> +|`f:facet` |xref:faces-page/faces-page.adoc#_using_data_bound_table_components[Using Data-Bound Table Components] and xref:faces-page/faces-page.adoc#_laying_out_components_with_the_hpanelgrid_and_hpanelgroup_tags[Laying Out Components with the h:panelGrid and h:panelGroup Tags] -|`f:loadBundle` | <> +|`f:loadBundle` | xref:webi18n/webi18n.adoc#_setting_the_resource_bundle[Setting the Resource Bundle] -|`f:metadata` | <> +|`f:metadata` | xref:faces-page/faces-page.adoc#_using_view_parameters_to_configure_bookmarkable_urls[Using View Parameters to Configure Bookmarkable URLs] -|`f:param` | <> +|`f:param` | xref:faces-page/faces-page.adoc#_displaying_a_formatted_message_with_the_houtputformat_tag[Displaying a Formatted Message with the h:outputFormat Tag] -|`f:selectItem` and `f:selectItems` | <> +|`f:selectItem` and `f:selectItems` | xref:faces-page/faces-page.adoc#_using_the_fselectitem_and_fselectitems_tags[Using the f:selectItem and f:selectItems Tags] -|Validator tags |<> +|Validator tags |xref:faces-page-core/faces-page-core.adoc#_using_the_standard_validators[Using the Standard Validators] -|`f:ajax` | xref:using-ajax-with-jakarta-faces-technology[xrefstyle=full] +|`f:ajax` | xref:faces-ajax/faces-ajax.adoc#_using_ajax_with_jakarta_faces_technology[Using Ajax with Jakarta Faces Technology] -|`f:websocket` | xref:using-websockets-with-jakarta-faces-technology[xrefstyle=full] +|`f:websocket` | xref:faces-ws/faces-ws.adoc#_using_websockets_with_jakarta_faces_technology[Using WebSockets with Jakarta Faces Technology] |=== diff --git a/src/main/asciidoc/faces-ws/faces-ws.adoc b/src/main/antora/modules/web/pages/faces-ws/faces-ws.adoc similarity index 88% rename from src/main/asciidoc/faces-ws/faces-ws.adoc rename to src/main/antora/modules/web/pages/faces-ws/faces-ws.adoc index 7250e1ed..3fa41aa4 100644 --- a/src/main/asciidoc/faces-ws/faces-ws.adoc +++ b/src/main/antora/modules/web/pages/faces-ws/faces-ws.adoc @@ -1,5 +1,7 @@ = Using WebSockets with Jakarta Faces Technology +include::ROOT:partial$not_updated.adoc[] + This chapter describes using WebSockets in Jakarta Faces web applications. include::faces-ws001.adoc[] diff --git a/src/main/asciidoc/faces-ws/faces-ws001.adoc b/src/main/antora/modules/web/pages/faces-ws/faces-ws001.adoc similarity index 100% rename from src/main/asciidoc/faces-ws/faces-ws001.adoc rename to src/main/antora/modules/web/pages/faces-ws/faces-ws001.adoc diff --git a/src/main/asciidoc/faces-ws/faces-ws002.adoc b/src/main/antora/modules/web/pages/faces-ws/faces-ws002.adoc similarity index 100% rename from src/main/asciidoc/faces-ws/faces-ws002.adoc rename to src/main/antora/modules/web/pages/faces-ws/faces-ws002.adoc diff --git a/src/main/asciidoc/faces-ws/faces-ws003.adoc b/src/main/antora/modules/web/pages/faces-ws/faces-ws003.adoc similarity index 94% rename from src/main/asciidoc/faces-ws/faces-ws003.adoc rename to src/main/antora/modules/web/pages/faces-ws/faces-ws003.adoc index d6e9c092..52d7cc82 100644 --- a/src/main/asciidoc/faces-ws/faces-ws003.adoc +++ b/src/main/antora/modules/web/pages/faces-ws/faces-ws003.adoc @@ -1,8 +1,8 @@ == Using the f:websocket Tag -<> describes the attributes of the `f:websocket` tag. +<<_attributes_of_the_fwebsocket_tag>> describes the attributes of the `f:websocket` tag. -[[attributes-of-the-fwebsocket-tag]] +[[_attributes_of_the_fwebsocket_tag]] .Attributes of the `f:websocket` Tag [width="85%",cols="15%,15%,55%"] |=== @@ -32,7 +32,7 @@ When the `user` attribute is specified, then the default scope is `session`. The user identifier of the WebSocket channel, so that user-targeted push messages can be sent. It must implement Serializable and preferably have a low memory footprint. -*Hint*: Use `\#{request.remoteUser}` or `#{someLoggedInUser.id}`. +*Hint*: Use `#{request.remoteUser}` or `#{someLoggedInUser.id}`. All open WebSockets on the same channel and user will receive the same push message from the server. diff --git a/src/main/asciidoc/faces-ws/faces-ws004.adoc b/src/main/antora/modules/web/pages/faces-ws/faces-ws004.adoc similarity index 96% rename from src/main/asciidoc/faces-ws/faces-ws004.adoc rename to src/main/antora/modules/web/pages/faces-ws/faces-ws004.adoc index 24ddfdce..eab4d54d 100644 --- a/src/main/asciidoc/faces-ws/faces-ws004.adoc +++ b/src/main/antora/modules/web/pages/faces-ws/faces-ws004.adoc @@ -30,7 +30,7 @@ For example, when you are using container managed authentication or a related fr ---- -Or, when you have a custom user entity accessible via EL, such as `#{someLoggedInUser}` which has an `id` property representing its identifier: +Or, when you have a custom user entity accessible via EL, such as `#\{someLoggedInUser}` which has an `id` property representing its identifier: [source,xml] ---- diff --git a/src/main/asciidoc/faces-ws/faces-ws005.adoc b/src/main/antora/modules/web/pages/faces-ws/faces-ws005.adoc similarity index 100% rename from src/main/asciidoc/faces-ws/faces-ws005.adoc rename to src/main/antora/modules/web/pages/faces-ws/faces-ws005.adoc diff --git a/src/main/asciidoc/faces-ws/faces-ws006.adoc b/src/main/antora/modules/web/pages/faces-ws/faces-ws006.adoc similarity index 100% rename from src/main/asciidoc/faces-ws/faces-ws006.adoc rename to src/main/antora/modules/web/pages/faces-ws/faces-ws006.adoc diff --git a/src/main/asciidoc/faces-ws/faces-ws007.adoc b/src/main/antora/modules/web/pages/faces-ws/faces-ws007.adoc similarity index 93% rename from src/main/asciidoc/faces-ws/faces-ws007.adoc rename to src/main/antora/modules/web/pages/faces-ws/faces-ws007.adoc index f39e32ab..e2cd2f34 100644 --- a/src/main/asciidoc/faces-ws/faces-ws007.adoc +++ b/src/main/antora/modules/web/pages/faces-ws/faces-ws007.adoc @@ -39,4 +39,4 @@ For example: ---- -If you pass a `Map` or a JavaBean as the push message object, then all entries or properties will transparently be available as request parameters in the command script method `#{bean.pushed}`. +If you pass a `Map` or a JavaBean as the push message object, then all entries or properties will transparently be available as request parameters in the command script method `#{bean.pushed}`. diff --git a/src/main/antora/modules/web/pages/jakarta-pages/jakarta-pages.adoc b/src/main/antora/modules/web/pages/jakarta-pages/jakarta-pages.adoc new file mode 100644 index 00000000..a4ed143f --- /dev/null +++ b/src/main/antora/modules/web/pages/jakarta-pages/jakarta-pages.adoc @@ -0,0 +1,11 @@ += Jakarta Pages + +Jakarta Pages was previously known as "JSP". + +It has been archived in favor of xref:web:faces-facelets/faces-facelets.adoc[Facelets]. + +* https://docs.oracle.com/javaee/5/tutorial/doc/bnagx.html[JavaServer Pages Technology] +* https://docs.oracle.com/javaee/5/tutorial/doc/bnajo.html[JavaServer Pages Documents] +* https://docs.oracle.com/javaee/5/tutorial/doc/bnalj.html[Custom Tags in JSP Pages] + +See also the https://jakarta.ee/specifications/pages[Jakarta Pages Specification]. diff --git a/src/main/antora/modules/web/pages/jakarta-tags/jakarta-tags.adoc b/src/main/antora/modules/web/pages/jakarta-tags/jakarta-tags.adoc new file mode 100644 index 00000000..f9cb3ebc --- /dev/null +++ b/src/main/antora/modules/web/pages/jakarta-tags/jakarta-tags.adoc @@ -0,0 +1,12 @@ += Jakarta Tags + +Jakarta Tags was previously known as "JSTL". + +A subset of Jakarta Tags has been archived in favor of Jakarta XML Binding, Jakarta Faces and Jakarta Persistence. +The Core Tag Library and JSTL Functions are still available in xref:web:faces-facelets/faces-facelets.adoc[Facelets]. + +* https://docs.oracle.com/javaee/5/tutorial/doc/bnakq.html[XML Tag Library] +* https://docs.oracle.com/javaee/5/tutorial/doc/bnakw.html[Internationalization Tag Library] +* https://docs.oracle.com/javaee/5/tutorial/doc/bnald.html[SQL Tag Library] + +See also the https://jakarta.ee/specifications/tags[Jakarta Tags Specification]. diff --git a/src/main/asciidoc/jsonb/jsonb.adoc b/src/main/antora/modules/web/pages/jsonb/jsonb.adoc similarity index 82% rename from src/main/asciidoc/jsonb/jsonb.adoc rename to src/main/antora/modules/web/pages/jsonb/jsonb.adoc index 09885888..799f7fa8 100644 --- a/src/main/asciidoc/jsonb/jsonb.adoc +++ b/src/main/antora/modules/web/pages/jsonb/jsonb.adoc @@ -1,8 +1,10 @@ = JSON Binding +include::ROOT:partial$not_updated.adoc[] + This chapter describes the Jakarta JSON Binding. JSON is a data exchange format widely used in web services and other connected applications. -For a brief overview of JSON, see <>. +For a brief overview of JSON, see xref:jsonp/jsonp.adoc#_introduction_to_json[Introduction to JSON]. The https://jakarta.ee/specifications/jsonb/[Jakarta JSON Binding^] specification provides a standard binding layer (metadata and runtime) between Java classes and JSON documents. One Jakarta JSON Binding reference implementation is Yasson, which is developed through Eclipse.org and is included as part of GlassFish Server. diff --git a/src/main/asciidoc/jsonb/jsonb001.adoc b/src/main/antora/modules/web/pages/jsonb/jsonb001.adoc similarity index 86% rename from src/main/asciidoc/jsonb/jsonb001.adoc rename to src/main/antora/modules/web/pages/jsonb/jsonb001.adoc index fc5db644..adda6847 100644 --- a/src/main/asciidoc/jsonb/jsonb001.adoc +++ b/src/main/antora/modules/web/pages/jsonb/jsonb001.adoc @@ -4,7 +4,7 @@ Jakarta EE includes support for the Jakarta JSON Binding spec, which provides an Jakarta JSON Binding contains the following packages: * The `jakarta.json.bind` package contains the binding interface, the builder interface, and a configuration class. -<> lists the main classes and interfaces in this package. +<<_main_classes_and_interfaces_in_bind>> lists the main classes and interfaces in this package. * The `jakarta.json.bind.adapter` package contains the `JsonbAdapter` interface, which provides methods for binding custom Java types by converting them to known types. @@ -12,15 +12,15 @@ Jakarta JSON Binding contains the following packages: Annotations can be used for field, JavaBean property, type, or package elements. * The `jakarta.json.bind.config` package interfaces and classes for customizing default binding behavior. -<> lists the main classes and interfaces in this package. +<<_main_classes_and_interfaces_in_config>> lists the main classes and interfaces in this package. * The `jakarta.json.bind.serializer` package contains interfaces that are used to create serialization and deserialization routines for custom types that cannot be easily mapped using the `JsonbAdapter` methods. -<> lists the main interfaces in this package. +<<_main_classes_and_interfaces_in_serializer>> lists the main interfaces in this package. * The `jakarta.json.bind.spi` package contains a Service Provider Interface (SPI) for creating JSON Binding implementations. This package contains the `JsonbProvider` class, which contains the methods that a service provider implements. -[[main-classes-and-interfaces-in-bind]] +[[_main_classes_and_interfaces_in_bind]] .Main Classes and Interfaces in jakarta.json.bind [width="99%",cols="25%,75%"] |=== @@ -36,7 +36,7 @@ Properties include binding strategies and properties for configuring custom seri |`JsonbException` | Indicates that a problem occurred during JSON binding. |=== -[[main-classes-and-interfaces-in-config]] +[[_main_classes_and_interfaces_in_config]] .Main Classes and Interfaces in jakarta.json.bind.config [width="99%",cols="25%,75%"] |=== @@ -51,7 +51,7 @@ Properties include binding strategies and properties for configuring custom seri |`PropertyOrderStrategy` | Used to set how properties are ordered during serialization. |=== -[[main-classes-and-interfaces-in-serializer]] +[[_main_classes_and_interfaces_in_serializer]] .Main Classes and Interfaces in jakarta.json.bind.serializer [width="99%",cols="25%,75%"] |=== diff --git a/src/main/asciidoc/jsonb/jsonb002.adoc b/src/main/antora/modules/web/pages/jsonb/jsonb002.adoc similarity index 94% rename from src/main/asciidoc/jsonb/jsonb002.adoc rename to src/main/antora/modules/web/pages/jsonb/jsonb002.adoc index 4bdb3a47..4ed6128c 100644 --- a/src/main/asciidoc/jsonb/jsonb002.adoc +++ b/src/main/antora/modules/web/pages/jsonb/jsonb002.adoc @@ -1,7 +1,7 @@ == Overview of the JSON Binding API This section provides basic instructions for using the Jakarta JSON Binding client API. -The instructions provide a basis for understanding the <>. +The instructions provide a basis for understanding the xref:jsonb/jsonb.adoc#_running_the_jsonbbasics_example_application[Running the jsonbbasics Example Application]. Refer to the http://json-b.net/index.html[Jakarta JSON Binding^] project page for API documentation and a more detailed User Guide. === Creating a jasonb Instance diff --git a/src/main/asciidoc/jsonb/jsonb003.adoc b/src/main/antora/modules/web/pages/jsonb/jsonb003.adoc similarity index 81% rename from src/main/asciidoc/jsonb/jsonb003.adoc rename to src/main/antora/modules/web/pages/jsonb/jsonb003.adoc index 6ce02c92..b83b3986 100644 --- a/src/main/asciidoc/jsonb/jsonb003.adoc +++ b/src/main/antora/modules/web/pages/jsonb/jsonb003.adoc @@ -3,7 +3,7 @@ This section describes how to build and run the `jsonbbasics` example application. This example is a web application that demonstrates how to serialize an object to JSON and how to deserialize JSON to an object. -The `jsonbbasics` example application is in the `_tut-install_/examples/web/jsonb/jsonbbasics` directory. +The `jsonbbasics` example application is in the `_jakartaee-examples_/tutorial/web/jsonb/jsonbbasics` directory. === Components of the jsonbbasics Example Application @@ -24,12 +24,12 @@ This section describes how to run the `jsonbbasics` example application from the To run the jsonbbasics example application using Maven: -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . In a terminal window, go to: + ---- -tut-install/examples/web/jsonb/jsonbbasics +jakartaee-examples/tutorial/web/jsonb/jsonbbasics ---- . Enter the following command to deploy the application: diff --git a/src/main/asciidoc/jsonb/jsonb004.adoc b/src/main/antora/modules/web/pages/jsonb/jsonb004.adoc similarity index 100% rename from src/main/asciidoc/jsonb/jsonb004.adoc rename to src/main/antora/modules/web/pages/jsonb/jsonb004.adoc diff --git a/src/main/asciidoc/jsonp/jsonp.adoc b/src/main/antora/modules/web/pages/jsonp/jsonp.adoc similarity index 92% rename from src/main/asciidoc/jsonp/jsonp.adoc rename to src/main/antora/modules/web/pages/jsonp/jsonp.adoc index 127290d8..a2dc8cc0 100644 --- a/src/main/asciidoc/jsonp/jsonp.adoc +++ b/src/main/antora/modules/web/pages/jsonp/jsonp.adoc @@ -1,5 +1,7 @@ = JSON Processing +include::ROOT:partial$not_updated.adoc[] + This chapter describes Jakarta JSON Processing. JSON is a data exchange format widely used in web services and other connected applications. Jakarta JSON Processing provides an API to parse, transform, and query JSON data using the object model or the streaming model. diff --git a/src/main/asciidoc/jsonp/jsonp001.adoc b/src/main/antora/modules/web/pages/jsonp/jsonp001.adoc similarity index 94% rename from src/main/asciidoc/jsonp/jsonp001.adoc rename to src/main/antora/modules/web/pages/jsonp/jsonp001.adoc index a8848516..5017fee6 100644 --- a/src/main/asciidoc/jsonp/jsonp001.adoc +++ b/src/main/antora/modules/web/pages/jsonp/jsonp001.adoc @@ -72,4 +72,4 @@ Each element can be processed or discarded by the application code, and then the This approach is adequate for local processing, in which the processing of an element does not require information from the rest of the data. The streaming model generates JSON output to a given stream by making a function call with one element at a time. -There are many JSON generators and parsers available for different programming languages and environments. <> describes the functionality provided by Jakarta JSON Processing. +There are many JSON generators and parsers available for different programming languages and environments. xref:jsonp/jsonp.adoc#_json_processing_in_the_jakarta_ee_platform[JSON Processing in the Jakarta EE Platform] describes the functionality provided by Jakarta JSON Processing. diff --git a/src/main/asciidoc/jsonp/jsonp002.adoc b/src/main/antora/modules/web/pages/jsonp/jsonp002.adoc similarity index 86% rename from src/main/asciidoc/jsonp/jsonp002.adoc rename to src/main/antora/modules/web/pages/jsonp/jsonp002.adoc index 4a34338c..9920642d 100644 --- a/src/main/asciidoc/jsonp/jsonp002.adoc +++ b/src/main/antora/modules/web/pages/jsonp/jsonp002.adoc @@ -1,20 +1,20 @@ == JSON Processing in the Jakarta EE Platform -Jakarta EE includes support for the Jakarta JSON Processing spec, which provides an API to parse, transform, and query JSON data using the object model or the streaming model described in <>. +Jakarta EE includes support for the Jakarta JSON Processing spec, which provides an API to parse, transform, and query JSON data using the object model or the streaming model described in xref:jsonp/jsonp.adoc#_generating_and_parsing_json_data[Generating and Parsing JSON Data]. Jakarta JSON Processing contains the following packages: * The `jakarta.json` package contains a reader interface, a writer interface, a model builder interface for the object model, and utility classes and Java types for JSON elements. This package also includes several classes that implement other JSON-related standards: https://tools.ietf.org/html/rfc6901[JSON Pointer^], https://tools.ietf.org/html/rfc6902[JSON Patch^], and https://tools.ietf.org/html/rfc7396[JSON Merge Patch^]. These standards are used to retrieve, transform or manipulate values in an object model. -<> lists the main classes and interfaces in this package. +<<_main_classes_and_interfaces_in_jakarta.json>> lists the main classes and interfaces in this package. * The `jakarta.json.stream` package contains a parser interface and a generator interface for the streaming model. -<> lists the main classes and interfaces in this package. +<<_main_classes_and_interfaces_in_jakarta.json.stream>> lists the main classes and interfaces in this package. * The `jakarta.json.spi` package contains a Service Provider Interface (SPI) to plug in implementations for JSON processing objects. This package contains the `JsonProvider` class, which contains the methods that a service provider implements. -[[main-classes-and-interfaces-in-jakarta.json]] +[[_main_classes_and_interfaces_in_jakarta.json]] .Main Classes and Interfaces in jakarta.json [width=99%,cols="25%,75%"] |=== @@ -52,7 +52,7 @@ These two interfaces are subtypes of `JsonValue`. |`JsonException` | Indicates that a problem occurred during JSON processing. |=== -[[main-classes-and-interfaces-in-jakarta.json.stream]] +[[_main_classes_and_interfaces_in_jakarta.json.stream]] .Main Classes and Interfaces in jakarta.json.stream [width=99%,cols="25%,75%"] |=== diff --git a/src/main/asciidoc/jsonp/jsonp003.adoc b/src/main/antora/modules/web/pages/jsonp/jsonp003.adoc similarity index 92% rename from src/main/asciidoc/jsonp/jsonp003.adoc rename to src/main/antora/modules/web/pages/jsonp/jsonp003.adoc index 2123ce33..a7e3dddd 100644 --- a/src/main/asciidoc/jsonp/jsonp003.adoc +++ b/src/main/antora/modules/web/pages/jsonp/jsonp003.adoc @@ -69,7 +69,7 @@ JsonObjectBuilder addNull(String name) The `JsonArrayBuilder` class contains similar `add` methods that do not have a name (key) parameter. You can nest arrays and objects by passing a new `JsonArrayBuilder` object or a new `JsonObjectBuilder` object to the corresponding `add` method, as shown in this example. -The resulting tree represents the JSON data from <>. +The resulting tree represents the JSON data from xref:jsonp/jsonp.adoc#_json_syntax[JSON Syntax]. === Navigating an Object Model @@ -116,7 +116,7 @@ public static void navigateTree(JsonValue tree, String key) { } ---- -The method `navigateTree` can be used with the models built in <> and <> as follows: +The method `navigateTree` can be used with the models built in <<_creating_an_object_model_from_json_data>> and <<_creating_an_object_model_from_application_code>> as follows: [source,java] ---- @@ -134,7 +134,7 @@ For objects, the `JsonObject.keySet` method returns a set of strings that contai For arrays, `JsonArray` implements the `List` interface. You can use enhanced `for` loops with the `Set` instance returned by `JsonObject.keySet` and with instances of `JsonArray`, as shown in this example. -The `navigateTree` method for the model built in <> produces the following output: +The `navigateTree` method for the model built in <<_creating_an_object_model_from_application_code>> produces the following output: ---- OBJECT @@ -156,7 +156,7 @@ OBJECT === Writing an Object Model to a Stream -The object models created in <> and <> can be written to a stream using the `JsonWriter` class as follows: +The object models created in <<_creating_an_object_model_from_json_data>> and <<_creating_an_object_model_from_application_code>> can be written to a stream using the `JsonWriter` class as follows: [source,java] ---- diff --git a/src/main/asciidoc/jsonp/jsonp004.adoc b/src/main/antora/modules/web/pages/jsonp/jsonp004.adoc similarity index 100% rename from src/main/asciidoc/jsonp/jsonp004.adoc rename to src/main/antora/modules/web/pages/jsonp/jsonp004.adoc diff --git a/src/main/asciidoc/jsonp/jsonp005.adoc b/src/main/antora/modules/web/pages/jsonp/jsonp005.adoc similarity index 61% rename from src/main/asciidoc/jsonp/jsonp005.adoc rename to src/main/antora/modules/web/pages/jsonp/jsonp005.adoc index 35dc28cb..ff377d0a 100644 --- a/src/main/asciidoc/jsonp/jsonp005.adoc +++ b/src/main/antora/modules/web/pages/jsonp/jsonp005.adoc @@ -1,9 +1,9 @@ == JSON in Jakarta EE RESTful Web Services This section explains how the Jakarta JSON Processing is related to other Jakarta EE packages that provide JSON support for RESTful web services. -See xref:building-restful-web-services-with-jakarta-rest[xrefstyle=full] for more information on RESTful web services. +See xref:websvcs:jaxrs/jaxrs.adoc#_building_restful_web_services_with_jakarta_rest[Building RESTful Web Services with Jakarta REST] for more information on RESTful web services. -Jersey, the Jakarta RESTful Web Services implementation included in GlassFish Server, provides support for binding JSON data from RESTful resource methods to Java objects using Jakarta XML Binding, as described in <> in xref:jakarta-rest-advanced-topics-and-an-example[xrefstyle=full]. +Jersey, the Jakarta RESTful Web Services implementation included in GlassFish Server, provides support for binding JSON data from RESTful resource methods to Java objects using Jakarta XML Binding, as described in xref:websvcs:jaxrs-advanced/jaxrs-advanced.adoc#_using_jakarta_rest_with_jakarta_xml_binding[Using Jakarta REST with Jakarta XML Binding] in xref:websvcs:jaxrs-advanced/jaxrs-advanced.adoc#_jakarta_rest_advanced_topics_and_an_example[Jakarta REST: Advanced Topics and an Example]. However, JSON support is not part of Jakarta RESTful Web Services or Jakarta XML Binding, so that procedure may not work for Jakarta EE implementations other than GlassFish Server. You can still use the Jakarta JSON Processing with Jakarta RESTful Web Services resource methods. diff --git a/src/main/asciidoc/jsonp/jsonp006.adoc b/src/main/antora/modules/web/pages/jsonp/jsonp006.adoc similarity index 74% rename from src/main/asciidoc/jsonp/jsonp006.adoc rename to src/main/antora/modules/web/pages/jsonp/jsonp006.adoc index 84e92bb0..92c53cb2 100644 --- a/src/main/asciidoc/jsonp/jsonp006.adoc +++ b/src/main/antora/modules/web/pages/jsonp/jsonp006.adoc @@ -3,7 +3,7 @@ This section describes how to build and run the `jsonpmodel` example application. This example is a web application that demonstrates how to create an object model from form data, how to parse JSON data, and how write JSON data using the object model API. -The `jsonpmodel` example application is in the `_tut-install_/examples/web/jsonp/jsonpmodel` directory. +The `jsonpmodel` example application is in the `_jakartaee-examples_/tutorial/web/jsonp/jsonpmodel` directory. === Components of the jsonpmodel Example Application @@ -20,9 +20,9 @@ The `jsonpmodel` example application contains the following files. * The `ObjectModelBean.java` managed bean, which is a session-scoped managed bean that stores the data from the form and directs the navigation between the Facelets pages. This file also contains code that uses the JSON object model API. -The code used in `ObjectModelBean.java` to create an object model from the data in the form is similar to the example in <>. -The code to write JSON output from the model is similar to the example in <>. -The code to navigate the object model tree is similar to the example in <>. +The code used in `ObjectModelBean.java` to create an object model from the data in the form is similar to the example in xref:jsonp/jsonp.adoc#_creating_an_object_model_from_application_code[Creating an Object Model from Application Code]. +The code to write JSON output from the model is similar to the example in xref:jsonp/jsonp.adoc#_writing_an_object_model_to_a_stream[Writing an Object Model to a Stream]. +The code to navigate the object model tree is similar to the example in xref:jsonp/jsonp.adoc#_navigating_an_object_model[Navigating an Object Model]. === Running the jsonpmodel Example Application @@ -30,14 +30,14 @@ This section describes how to run the `jsonpmodel` example application using Net ==== To Run the jsonpmodel Example Application Using NetBeans IDE -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . From the *File* menu, choose *Open Project*. . In the Open Project dialog box, navigate to: + ---- -tut-install/examples/web/jsonp +jakartaee-examples/tutorial/web/jsonp ---- . Select the `jsonpmodel` folder. @@ -60,12 +60,12 @@ The following page contains a table that lists the nodes of the object model tre ==== To Run the jsonpmodel Example Application Using Maven -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . In a terminal window, go to: + ---- -tut-install/examples/web/jsonp/jsonpmodel +jakartaee-examples/tutorial/web/jsonp/jsonpmodel ---- . Enter the following command to deploy the application: diff --git a/src/main/asciidoc/jsonp/jsonp007.adoc b/src/main/antora/modules/web/pages/jsonp/jsonp007.adoc similarity index 77% rename from src/main/asciidoc/jsonp/jsonp007.adoc rename to src/main/antora/modules/web/pages/jsonp/jsonp007.adoc index 928c4881..b8492a88 100644 --- a/src/main/asciidoc/jsonp/jsonp007.adoc +++ b/src/main/antora/modules/web/pages/jsonp/jsonp007.adoc @@ -3,7 +3,7 @@ This section describes how to build and run the `jsonpstreaming` example application. This example is a web application that demonstrates how to create JSON data from form data, how to parse JSON data, and how to write JSON output using the streaming API. -The `jsonpstreaming` example application is in the `_tut-install_/examples/web/jsonp/jsonpstreaming` directory. +The `jsonpstreaming` example application is in the `_jakartaee-examples_/tutorial/web/jsonp/jsonpstreaming` directory. === Components of the jsonpstreaming Example Application @@ -20,8 +20,8 @@ The `jsonpstreaming` example application contains the following files. * The `StreamingBean.java` managed bean, a session-scoped managed bean that stores the data from the form and directs the navigation between the Facelets pages. This file also contains code that uses the JSON streaming API. -The code used in `StreamingBean.java` to write JSON data to a file is similar to the example in <>. -The code to parse JSON data from a file is similar to the example in <>. +The code used in `StreamingBean.java` to write JSON data to a file is similar to the example in xref:jsonp/jsonp.adoc#_writing_json_data_using_a_generator[Writing JSON Data Using a Generator]. +The code to parse JSON data from a file is similar to the example in xref:jsonp/jsonp.adoc#_reading_json_data_using_a_parser[Reading JSON Data Using a Parser]. === Running the jsonpstreaming Example Application @@ -29,14 +29,14 @@ This section describes how to run the `jsonpstreaming` example application using ==== To Run the jsonpstreaming Example Application Using NetBeans IDE -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . From the *File* menu, choose *Open Project*. . In the Open Project dialog box, navigate to: + ---- -tut-install/examples/web/jsonp +jakartaee-examples/tutorial/web/jsonp ---- . Select the `jsonpstreaming` folder. @@ -59,12 +59,12 @@ The following page contains a table that lists the parser events for the JSON da ==== To Run the jsonpstreaming Example Application Using Maven -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . In a terminal window, go to: + ---- -tut-install/examples/web/jsonp/jsonpstreaming/ +jakartaee-examples/tutorial/web/jsonp/jsonpstreaming/ ---- . Enter the following command to deploy the application: diff --git a/src/main/asciidoc/jsonp/jsonp008.adoc b/src/main/antora/modules/web/pages/jsonp/jsonp008.adoc similarity index 100% rename from src/main/asciidoc/jsonp/jsonp008.adoc rename to src/main/antora/modules/web/pages/jsonp/jsonp008.adoc diff --git a/src/main/asciidoc/servlets/servlets.adoc b/src/main/antora/modules/web/pages/servlets/servlets.adoc similarity index 60% rename from src/main/asciidoc/servlets/servlets.adoc rename to src/main/antora/modules/web/pages/servlets/servlets.adoc index 80a017ce..defc7250 100644 --- a/src/main/asciidoc/servlets/servlets.adoc +++ b/src/main/antora/modules/web/pages/servlets/servlets.adoc @@ -1,6 +1,7 @@ -= Jakarta Servlet Technology += Jakarta Servlet -Jakarta Servlet technology provides dynamic, user-oriented content in web applications using a request-response programming model. +Jakarta Servlet is a corner stone web framework that can act as a presentation-oriented as well as a service-oriented web application. +Jakarta Servlet intends to reduce the boilerplate code needed to convert the HTTP request into a Java object and to offer a Java object as an HTTP response, and to manage all the lifecycle around them. include::servlets001.adoc[] @@ -12,6 +13,8 @@ include::servlets004.adoc[] include::servlets005.adoc[] +include::servlets019.adoc[] + include::servlets006.adoc[] include::servlets007.adoc[] diff --git a/src/main/antora/modules/web/pages/servlets/servlets001.adoc b/src/main/antora/modules/web/pages/servlets/servlets001.adoc new file mode 100644 index 00000000..302b08cc --- /dev/null +++ b/src/main/antora/modules/web/pages/servlets/servlets001.adoc @@ -0,0 +1,9 @@ +== What Is a Servlet? + +A servlet is a Java programming language class that directly or indirectly implements the `jakarta.servlet.Servlet` interface. +The `jakarta.servlet` and `jakarta.servlet.http` packages provide interfaces and classes for writing servlets. +All servlets must implement the `jakarta.servlet.Servlet` interface, which defines lifecycle methods such as `init`, `service`, and `destroy`. +When implementing a generic service, you can extend the `jakarta.servlet.GenericServlet` class which already implements the `Servlet` interface. +When implementing an HTTP service, you can extend the `jakarta.servlet.http.HttpServlet` class which already extends the `GenericServlet` class. + +In a typical Jakarta Servlet based web application, the class must extend `jakarta.servlet.http.HttpServlet` and override one of the `doXxx` methods where `Xxx` represents the HTTP method of interest. diff --git a/src/main/antora/modules/web/pages/servlets/servlets002.adoc b/src/main/antora/modules/web/pages/servlets/servlets002.adoc new file mode 100644 index 00000000..bc568a27 --- /dev/null +++ b/src/main/antora/modules/web/pages/servlets/servlets002.adoc @@ -0,0 +1,16 @@ +== Servlet Lifecycle + +The lifecycle of a servlet is controlled by the servlet container in which the servlet has been deployed. +When a request is mapped to a servlet, the servlet container performs the following steps: + +. If an instance of the servlet does not exist, the servlet container: +.. Loads the servlet class +.. Creates an instance of the servlet class +.. Initializes the servlet instance by calling the `init` method +. The servlet container invokes the `service` method, passing request and response objects. + +Initialization is covered in <>. +Service methods are discussed in <>. + +If it needs to remove the servlet, the servlet container finalizes the servlet by calling the servlet's `destroy` method. +For more information, see <>. diff --git a/src/main/antora/modules/web/pages/servlets/servlets003.adoc b/src/main/antora/modules/web/pages/servlets/servlets003.adoc new file mode 100644 index 00000000..b020f9c8 --- /dev/null +++ b/src/main/antora/modules/web/pages/servlets/servlets003.adoc @@ -0,0 +1,158 @@ +== Sharing Information + +Web components, like most objects, usually work with data to accomplish their tasks. +Web components can store this information in a data store or in a scoped bean, among others. + + +=== Using CDI Managed Beans + +CDI can be used to define scoped beans which can be injected in any container-managed objects such as web components. +These scoped beans can then be used to store and transfer information. + +CDI defines three basic scopes which can be used for this: + +`@jakarta.enterprise.context.RequestScoped`:: +In a servlet container, this is mapped to the `jakarta.servlet.ServletRequest`. +It lives from the time that the client has sent the request until it has retrieved the corresponding response. +It is not shared elsewhere. + +`@jakarta.enterprise.context.SessionScoped`:: +In a servlet container, this is mapped to the `jakarta.servlet.http.HttpSession`. +It lives for as long as the client is interacting with the web application with the same browser instance, and the session hasn't timed out at the server side. +It is shared among all requests in the same session. + +`@jakarta.enterprise.context.ApplicationScoped`:: +In a servlet container, this is mapped to the `jakarta.servlet.ServletContext`. +It lives for as long as the web application lives. +It is shared among all requests in all sessions. + +The below example illustrates how CDI `@SessionScoped` can be used to define a session scoped bean which stores the user preferences. + +[source,java] +---- +@Named +@SessionScoped +public class UserPreferences implements Serializable { + + private Locale language; + private ZoneId timeZone; + private boolean darkMode; + + // ... +} +---- + +It can be injected in any web component. +The below example illustrates how a servlet can be used to take a time zone offset in minutes and update the user preferences with it. + +[source,java] +---- +@WebServlet("/timeZoneHandler") +public class TimeZoneHandler extends HttpServlet { + + @Inject + private UserPreferences userPreferences; + + @Override + public void doPost + (HttpServletRequest request, HttpServletResponse response) + throws ServletException, IOException + { + var offsetInMinutes = request.getParameter("offsetInMinutes"); + + if (offsetInMinutes == null || !offsetInMinutes.matches("\\-?[0-9]{1,3}")) { + response.sendError(HttpServletResponse.SC_BAD_REQUEST); + return; + } + + var offsetInSeconds = TimeUnit.MINUTES.toSeconds(Long.valueOf(offsetInMinutes)); + ZoneId timeZone = ZoneOffset.ofTotalSeconds((int) offsetInSeconds); + userPreferences.setTimeZone(timeZone); + response.setStatus(HttpServletResponse.SC_NO_CONTENT); + } +} +---- + +For example JavaScript's `new Date().getTimeZoneOffset()` returns the local (negative) time zone offset in minutes. +This servlet can then be invoked as follows in JavaScript in order to inform the server about the client's time zone: + +[source,javascript] +---- +fetch("/context-path/timeZoneHandler", { + method: "POST", + body: new URLSearchParams({ + offsetInMinutes: -new Date().getTimezoneOffset() + }) +}); +---- + +=== Using Scope Objects Directly + +If CDI is not available, an alternative is to use Jakarta Servlet's own scope objects directly. +You can use `getAttribute` and `setAttribute` methods of the Jakarta Servlet class representing the scope. +<> lists the scope objects. + +[[scope-objects]] +.Scope Objects +[width="90%",cols="15%,25%,50%"] +|=== +|Scope Object |Class |Accessible From +|Application |`jakarta.servlet.ServletContext` |Web components within the web application. +See <>. +|Session |`jakarta.servlet.http.HttpSession` |Web components handling a request that belongs to the session. +See <>. +|Request |`jakarta.servlet.ServletRequest` |Web components handling the request. +|=== + +The below example illustrates how the previously shown servlet needs to be adjusted to manually manage the `UserPreferences` bean. + +[source,java] +---- +@WebServlet("/timeZoneHandler") +public class TimeZoneHandler extends HttpServlet { + + @Override + public void doPost + (HttpServletRequest request, HttpServletResponse response) + throws ServletException, IOException + { + var offsetInMinutes = request.getParameter("offsetInMinutes"); + + if (offsetInMinutes == null || !offsetInMinutes.matches("\\-?[0-9]{1,3}")) { + response.sendError(HttpServletResponse.SC_BAD_REQUEST); + return; + } + + var offsetInSeconds = TimeUnit.MINUTES.toSeconds(Long.valueOf(offsetInMinutes)); + ZoneId timeZone = ZoneOffset.ofTotalSeconds((int) offsetInSeconds); + HttpSession session = request.getSession(); + UserPreferenes userPreferences = session.getAttribute("userPreferences"); + + if (userPreferences == null) { + userPreferences = new UserPreferences(); + session.setAttribute("userPreferences", userPreferences); + } + + userPreferences.setTimeZone(timeZone); + response.setStatus(HttpServletResponse.SC_NO_CONTENT); + } +} +---- + +=== Controlling Concurrent Access to Shared Resources + +In a multithreaded server, shared resources can be accessed concurrently. +In addition to scope object attributes, shared resources include in-memory data, such as instance or class variables, and external objects, such as files, database connections, and network connections. + +Concurrent access can arise in several situations. + +* Multiple web components accessing objects stored in the application scope. +* Multiple web components accessing objects stored in the session scope. +* Multiple threads within a web component accessing instance variables. + +A web container will typically create a thread to handle each request. +When resources can be accessed concurrently, they can be used in an inconsistent fashion. +First step is to ensure that the variable representing the resource has the correct scope and use a as narrow as possible scope. +For example, request scoped information should not be stored in a session scoped bean nor be assigned as an instance variable of a servlet, and session scoped information should not be stored in an application scoped bean. + +If concurrent access is inevitable, then you prevent this by using synchronized or atomic objects such as wrapping a `Map` in `Collections.synchronizedMap()` before assigning it to a property of a session scoped bean. diff --git a/src/main/asciidoc/servlets/servlets004.adoc b/src/main/antora/modules/web/pages/servlets/servlets004.adoc similarity index 97% rename from src/main/asciidoc/servlets/servlets004.adoc rename to src/main/antora/modules/web/pages/servlets/servlets004.adoc index d88e8302..12e925df 100644 --- a/src/main/asciidoc/servlets/servlets004.adoc +++ b/src/main/antora/modules/web/pages/servlets/servlets004.adoc @@ -1,5 +1,7 @@ == Creating and Initializing a Servlet +include::ROOT:partial$not_updated.adoc[] + Use the `@WebServlet` annotation to define a servlet component in a web application. This annotation is specified on a class and contains metadata about the servlet being declared. The annotated servlet must specify at least one URL pattern. diff --git a/src/main/asciidoc/servlets/servlets005.adoc b/src/main/antora/modules/web/pages/servlets/servlets005.adoc similarity index 95% rename from src/main/asciidoc/servlets/servlets005.adoc rename to src/main/antora/modules/web/pages/servlets/servlets005.adoc index 92021f08..e132b32e 100644 --- a/src/main/asciidoc/servlets/servlets005.adoc +++ b/src/main/antora/modules/web/pages/servlets/servlets005.adoc @@ -82,11 +82,11 @@ Buffering allows content to be written before anything is sent back to the clien The method must be called before any content is written or before the response is committed. * Set localization information, such as locale and character encoding. -See xref:internationalizing-and-localizing-web-applications[xrefstyle=full] for details. +See xref:webi18n/webi18n.adoc#_internationalizing_and_localizing_web_applications[Internationalizing and Localizing Web Applications] for details. HTTP response objects, `jakarta.servlet.http.HttpServletResponse`, have fields representing HTTP headers, such as the following. * Status codes, which are used to indicate the reason a request is not satisfied or that a request has been redirected. * Cookies, which are used to store application-specific information at the client. -Sometimes, cookies are used to maintain an identifier for tracking a user's session (see <>). +Sometimes, cookies are used to maintain an identifier for tracking a user's session (see xref:servlets/servlets.adoc#_session_tracking[Session Tracking]). diff --git a/src/main/asciidoc/servlets/servlets006.adoc b/src/main/antora/modules/web/pages/servlets/servlets006.adoc similarity index 91% rename from src/main/asciidoc/servlets/servlets006.adoc rename to src/main/antora/modules/web/pages/servlets/servlets006.adoc index 90eed15f..14e5e0e7 100644 --- a/src/main/asciidoc/servlets/servlets006.adoc +++ b/src/main/antora/modules/web/pages/servlets/servlets006.adoc @@ -104,11 +104,11 @@ You specify a filter mapping list for a WAR in its deployment descriptor by eith If you want to log every request to a web application, you map the hit counter filter to the URL pattern `/*`. You can map a filter to one or more web resources, and you can map more than one filter to a web resource. -This is illustrated in <>, in which filter F1 is mapped to servlets S1, S2, and S3; filter F2 is mapped to servlet S2; and filter F3 is mapped to servlets S1 and S2. +This is illustrated in <<_filter_to_servlet_mapping>>, in which filter F1 is mapped to servlets S1, S2, and S3; filter F2 is mapped to servlet S2; and filter F3 is mapped to servlets S1 and S2. -[[filter-to-servlet-mapping]] +[[_filter_to_servlet_mapping]] .Filter-to-Servlet Mapping -image::jakartaeett_dt_018.svg["Diagram of filter-to-servlet mapping with filters F1-F3 and servlets S1-S3. F1 filters S1-S3, then F2 filters S2, then F3 filters S1 and S2."] +image::common:jakartaeett_dt_018.svg["Diagram of filter-to-servlet mapping with filters F1-F3 and servlets S1-S3. F1 filters S1-S3, then F2 filters S2, then F3 filters S1 and S2."] Recall that a filter chain is one of the objects passed to the `doFilter` method of a filter. This chain is formed indirectly by means of filter mappings. @@ -157,11 +157,11 @@ REQUEST:: Only when the request comes directly from the client ASYNC:: Only when the asynchronous request comes from the client -FORWARD:: Only when the request has been forwarded to a component (see <>) +FORWARD:: Only when the request has been forwarded to a component (see xref:servlets/servlets.adoc#_transferring_control_to_another_web_component[Transferring Control to Another Web Component]) -INCLUDE:: Only when the request is being processed by a component that has been included (see <>) +INCLUDE:: Only when the request is being processed by a component that has been included (see xref:servlets/servlets.adoc#_including_other_resources_in_the_response[Including Other Resources in the Response]) -ERROR:: Only when the request is being processed with the error page mechanism (see <>) +ERROR:: Only when the request is being processed with the error page mechanism (see xref:servlets/servlets.adoc#_handling_servlet_errors[Handling Servlet Errors]) You can direct the filter to be applied to any combination of the preceding situations by selecting multiple dispatcher types. If no types are specified, the default option is *REQUEST*. diff --git a/src/main/asciidoc/servlets/servlets007.adoc b/src/main/antora/modules/web/pages/servlets/servlets007.adoc similarity index 100% rename from src/main/asciidoc/servlets/servlets007.adoc rename to src/main/antora/modules/web/pages/servlets/servlets007.adoc diff --git a/src/main/asciidoc/servlets/servlets008.adoc b/src/main/antora/modules/web/pages/servlets/servlets008.adoc similarity index 100% rename from src/main/asciidoc/servlets/servlets008.adoc rename to src/main/antora/modules/web/pages/servlets/servlets008.adoc diff --git a/src/main/asciidoc/servlets/servlets009.adoc b/src/main/antora/modules/web/pages/servlets/servlets009.adoc similarity index 96% rename from src/main/asciidoc/servlets/servlets009.adoc rename to src/main/antora/modules/web/pages/servlets/servlets009.adoc index cd9a3d69..ce602033 100644 --- a/src/main/asciidoc/servlets/servlets009.adoc +++ b/src/main/antora/modules/web/pages/servlets/servlets009.adoc @@ -16,7 +16,7 @@ This method returns the current session associated with this request; or, if the You can associate object-valued attributes with a session by name. Such attributes are accessible by any web component that belongs to the same web context and is handling a request that is part of the same session. -Recall that your application can notify web context and session listener objects of servlet lifecycle events (<>). +Recall that your application can notify web context and session listener objects of servlet lifecycle events (xref:servlets/servlets.adoc#_handling_servlet_lifecycle_events[Handling Servlet Lifecycle Events]). You can also notify objects of certain events related to their association with a session, such as the following. * When the object is added to or removed from a session. diff --git a/src/main/asciidoc/servlets/servlets010.adoc b/src/main/antora/modules/web/pages/servlets/servlets010.adoc similarity index 100% rename from src/main/asciidoc/servlets/servlets010.adoc rename to src/main/antora/modules/web/pages/servlets/servlets010.adoc diff --git a/src/main/asciidoc/servlets/servlets011.adoc b/src/main/antora/modules/web/pages/servlets/servlets011.adoc similarity index 100% rename from src/main/asciidoc/servlets/servlets011.adoc rename to src/main/antora/modules/web/pages/servlets/servlets011.adoc diff --git a/src/main/asciidoc/servlets/servlets012.adoc b/src/main/antora/modules/web/pages/servlets/servlets012.adoc similarity index 97% rename from src/main/asciidoc/servlets/servlets012.adoc rename to src/main/antora/modules/web/pages/servlets/servlets012.adoc index ea13d171..35766a9f 100644 --- a/src/main/asciidoc/servlets/servlets012.adoc +++ b/src/main/antora/modules/web/pages/servlets/servlets012.adoc @@ -45,9 +45,9 @@ public void doGet(HttpServletRequest req, HttpServletResponse resp) { This call puts the request into asynchronous mode and ensures that the response is not committed after exiting the service method. You have to generate the response in the asynchronous context after the blocking operation completes or dispatch the request to another servlet. -<> describes the basic functionality provided by the `AsyncContext` class. +<<_functionality_provided_by_the_asynccontext_class>> describes the basic functionality provided by the `AsyncContext` class. -[[functionality-provided-by-the-asynccontext-class]] +[[_functionality_provided_by_the_asynccontext_class]] .Functionality Provided by the AsyncContext Class [width="90%",cols="20%,70%"] |=== diff --git a/src/main/asciidoc/servlets/servlets013.adoc b/src/main/antora/modules/web/pages/servlets/servlets013.adoc similarity index 82% rename from src/main/asciidoc/servlets/servlets013.adoc rename to src/main/antora/modules/web/pages/servlets/servlets013.adoc index 17d58527..552e76ff 100644 --- a/src/main/asciidoc/servlets/servlets013.adoc +++ b/src/main/antora/modules/web/pages/servlets/servlets013.adoc @@ -2,7 +2,7 @@ Web containers in application servers normally use a server thread per client request. To develop scalable web applications, you must ensure that threads associated with client requests are never sitting idle waiting for a blocking operation to complete. -<> provides a mechanism to execute application-specific blocking operations in a new thread, returning the thread associated with the request immediately to the container. +xref:servlets/servlets.adoc#_asynchronous_processing[Asynchronous Processing] provides a mechanism to execute application-specific blocking operations in a new thread, returning the thread associated with the request immediately to the container. Even if you use asynchronous processing for all the application-specific blocking operations inside your service methods, threads associated with client requests can be momentarily sitting idle because of input/output considerations. For example, if a client is submitting a large HTTP POST request over a slow network connection, the server can read the request faster than the client can provide it. @@ -11,7 +11,7 @@ Using traditional I/O, the container thread associated with this request would b Jakarta EE provides nonblocking I/O support for servlets and filters when processing requests in asynchronous mode. The following steps summarize how to use nonblocking I/O to process requests and write responses inside service methods. -. Put the request in asynchronous mode as described in <>. +. Put the request in asynchronous mode as described in xref:servlets/servlets.adoc#_asynchronous_processing[Asynchronous Processing]. . Obtain an input stream and/or an output stream from the request and response objects in the service method. @@ -19,10 +19,10 @@ The following steps summarize how to use nonblocking I/O to process requests and . Process the request and the response inside the listener's callback methods. -<> describe the methods available in the servlet input and output streams for nonblocking I/O support. -<> describes the interfaces for read listeners and write listeners. +<<_nonblocking_io_support_in_servletoutputstream>> describe the methods available in the servlet input and output streams for nonblocking I/O support. +<<_listener_interfaces_for_nonblocking_io_support>> describes the interfaces for read listeners and write listeners. -[[nonblocking-io-support-in-servletinputstream]] +[[_nonblocking_io_support_in_servletinputstream]] .Nonblocking I/O Support in jakarta.servlet.ServletInputStream [width="100%",cols="50%,50%"] |=== @@ -36,7 +36,7 @@ You provide the listener object as an anonymous class or use another mechanism t |`boolean isFinished()` |Returns true when all the data has been read. |=== -[[nonblocking-io-support-in-servletoutputstream]] +[[_nonblocking_io_support_in_servletoutputstream]] .Nonblocking I/O Support in jakarta.servlet.ServletOutputStream [width="100%",cols="50%,50%"] |=== @@ -48,7 +48,7 @@ You provide the write listener object as an anonymous class or use another mecha |`boolean isReady()` |Returns true if data can be written without blocking. |=== -[[listener-interfaces-for-nonblocking-io-support]] +[[_listener_interfaces_for_nonblocking_io_support]] .Listener Interfaces for Nonblocking I/O Support [width="100%",cols="20%,30%,50%"] |=== @@ -67,7 +67,7 @@ You provide the write listener object as an anonymous class or use another mecha === Reading a Large HTTP POST Request Using Nonblocking I/O -The code in this section shows how to read a large HTTP POST request inside a servlet by putting the request in asynchronous mode (as described in <>) and using the nonblocking I/O functionality from <> and <>. +The code in this section shows how to read a large HTTP POST request inside a servlet by putting the request in asynchronous mode (as described in xref:servlets/servlets.adoc#_asynchronous_processing[Asynchronous Processing]) and using the nonblocking I/O functionality from <<_nonblocking_io_support_in_servletinputstream>> and <<_listener_interfaces_for_nonblocking_io_support>>. [source,java] ---- diff --git a/src/main/asciidoc/servlets/servlets014.adoc b/src/main/antora/modules/web/pages/servlets/servlets014.adoc similarity index 91% rename from src/main/asciidoc/servlets/servlets014.adoc rename to src/main/antora/modules/web/pages/servlets/servlets014.adoc index cea2939e..53b37a3a 100644 --- a/src/main/asciidoc/servlets/servlets014.adoc +++ b/src/main/antora/modules/web/pages/servlets/servlets014.adoc @@ -29,9 +29,9 @@ OtherHeaderB: Value (XYZP data) ---- -Jakarta EE supports the HTTP protocol upgrade functionality in servlets, as described in <>. +Jakarta EE supports the HTTP protocol upgrade functionality in servlets, as described in <<_protocol_upgrade_support>>. -[[protocol-upgrade-support]] +[[_protocol_upgrade_support]] .Protocol Upgrade Support [width="80%",cols="20%,60%"] |=== @@ -57,12 +57,12 @@ You implement this method and free any resources associated with processing the |`WebConnection` | `ServletInputStream getInputStream()` The `getInputStream` method provides access to the input stream of the connection. -You can use <> with the returned stream to implement the new protocol. +You can use xref:servlets/servlets.adoc#_nonblocking_io[Nonblocking I/O] with the returned stream to implement the new protocol. |`WebConnection` | `ServletOutputStream getOutputStream()` The `getOutputStream` method provides access to the output stream of the connection. -You can use <> with the returned stream to implement the new protocol. +You can use xref:servlets/servlets.adoc#_nonblocking_io[Nonblocking I/O] with the returned stream to implement the new protocol. |=== The following code demonstrates how to accept an HTTP protocol upgrade request from a client: diff --git a/src/main/asciidoc/servlets/servlets014a.adoc b/src/main/antora/modules/web/pages/servlets/servlets014a.adoc similarity index 100% rename from src/main/asciidoc/servlets/servlets014a.adoc rename to src/main/antora/modules/web/pages/servlets/servlets014a.adoc diff --git a/src/main/asciidoc/servlets/servlets014b.adoc b/src/main/antora/modules/web/pages/servlets/servlets014b.adoc similarity index 100% rename from src/main/asciidoc/servlets/servlets014b.adoc rename to src/main/antora/modules/web/pages/servlets/servlets014b.adoc diff --git a/src/main/asciidoc/servlets/servlets015.adoc b/src/main/antora/modules/web/pages/servlets/servlets015.adoc similarity index 79% rename from src/main/asciidoc/servlets/servlets015.adoc rename to src/main/antora/modules/web/pages/servlets/servlets015.adoc index 79552be4..e6d9b0db 100644 --- a/src/main/asciidoc/servlets/servlets015.adoc +++ b/src/main/antora/modules/web/pages/servlets/servlets015.adoc @@ -1,6 +1,6 @@ == The mood Example Application -The `mood` example application, located in the `_tut-install_/examples/web/servlet/mood/` directory, is a simple example that displays Duke's moods at different times during the day. +The `mood` example application, located in the `_jakartaee-examples_/tutorial/web/servlet/mood/` directory, is a simple example that displays Duke's moods at different times during the day. The example shows how to develop a simple application by using the `@WebServlet`, `@WebFilter`, and `@WebListener` annotations to create a servlet, a listener, and a filter. === Components of the mood Example Application @@ -42,14 +42,14 @@ You can use either NetBeans IDE or Maven to build, package, deploy, and run the ==== To Run the mood Example Using NetBeans IDE -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . From the *File* menu, choose *Open Project*. . In the Open Project dialog box, navigate to: + ---- -tut-install/examples/web/servlet +jakartaee-examples/tutorial/web/servlet ---- . Select the `mood` folder. @@ -70,12 +70,12 @@ A web page appears with the title "Servlet MoodServlet at /mood", a text string ==== To Run the mood Example Using Maven -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . In a terminal window, go to: + ---- -tut-install/examples/web/servlet/mood/ +jakartaee-examples/tutorial/web/servlet/mood/ ---- . Enter the following command to deploy the application: diff --git a/src/main/asciidoc/servlets/servlets016.adoc b/src/main/antora/modules/web/pages/servlets/servlets016.adoc similarity index 89% rename from src/main/asciidoc/servlets/servlets016.adoc rename to src/main/antora/modules/web/pages/servlets/servlets016.adoc index 93a5cadb..357fabf6 100644 --- a/src/main/asciidoc/servlets/servlets016.adoc +++ b/src/main/antora/modules/web/pages/servlets/servlets016.adoc @@ -1,6 +1,6 @@ == The fileupload Example Application -The `fileupload` example, located in the `_tut-install_/examples/web/servlet/fileupload/` directory, illustrates how to implement and use the file upload feature. +The `fileupload` example, located in the `_jakartaee-examples_/tutorial/web/servlet/fileupload/` directory, illustrates how to implement and use the file upload feature. The Duke's Forest case study provides a more complex example that uploads an image file and stores its content in a database. @@ -40,16 +40,18 @@ The HTML form in `index.html` is as follows: File Upload - -
- File: -
- Destination: - -
- + +
+ +
+
+ +
+
+ +
@@ -175,14 +177,14 @@ You can use either NetBeans IDE or Maven to build, package, deploy, and run the ==== To Build, Package, and Deploy the fileupload Example Using NetBeans IDE -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . From the *File* menu, choose *Open Project*. . In the Open Project dialog box, navigate to: + ---- -tut-install/examples/web/servlet +jakartaee-examples/tutorial/web/servlet ---- . Select the `fileupload` folder. @@ -193,12 +195,12 @@ tut-install/examples/web/servlet ==== To Build, Package, and Deploy the fileupload Example Using Maven -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . In a terminal window, go to: + ---- -tut-install/examples/web/servlet/fileupload/ +jakartaee-examples/tutorial/web/servlet/fileupload/ ---- . Enter the following command to deploy the application: diff --git a/src/main/asciidoc/servlets/servlets017.adoc b/src/main/antora/modules/web/pages/servlets/servlets017.adoc similarity index 86% rename from src/main/asciidoc/servlets/servlets017.adoc rename to src/main/antora/modules/web/pages/servlets/servlets017.adoc index f7676c83..c2572806 100644 --- a/src/main/asciidoc/servlets/servlets017.adoc +++ b/src/main/antora/modules/web/pages/servlets/servlets017.adoc @@ -1,6 +1,6 @@ == The dukeetf Example Application -The `dukeetf` example application, located in the `_tut-install_/examples/web/dukeetf/` directory, demonstrates how to use asynchronous processing in a servlet to provide data updates to web clients. +The `dukeetf` example application, located in the `_jakartaee-examples_/tutorial/web/dukeetf/` directory, demonstrates how to use asynchronous processing in a servlet to provide data updates to web clients. The example resembles a service that provides periodic updates on the price and trading volume of an electronically traded fund (ETF). === Architecture of the dukeetf Example Application @@ -132,7 +132,7 @@ public class PriceVolumeBean { } ---- -See <> in xref:running-the-enterprise-bean-examples[xrefstyle=full] for more information on the timer service. +See xref:entbeans:ejb-basicexamples/ejb-basicexamples.adoc#_using_the_timer_service[Using the Timer Service] in xref:entbeans:ejb-basicexamples/ejb-basicexamples.adoc#_running_the_enterprise_bean_examples[Running the Enterprise Bean Examples] for more information on the timer service. ==== The HTML Page @@ -183,7 +183,7 @@ function makeAjaxRequest() { The `XMLHttpRequest` API is supported by most modern browsers, and it is widely used in Ajax web client development (Asynchronous JavaScript and XML). -See <> in xref:jakarta-websocket-2[xrefstyle=full] for an equivalent version of this example implemented using a WebSocket endpoint. +See xref:websocket/websocket.adoc#_the_dukeetf2_example_application[The dukeetf2 Example Application] in xref:websocket/websocket.adoc#_jakarta_websocket[Jakarta WebSocket] for an equivalent version of this example implemented using a WebSocket endpoint. === Running the dukeetf Example Application @@ -191,14 +191,14 @@ This section describes how to run the `dukeetf` example application using NetBea ==== To Run the dukeetf Example Application Using NetBeans IDE -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . From the *File* menu, choose *Open Project*. . In the Open Project dialog box, navigate to: + ---- -tut-install/examples/web/servlet +jakartaee-examples/tutorial/web/servlet ---- . Select the `dukeetf` folder. @@ -217,12 +217,12 @@ Open the same URL in a different web browser to see how both pages get price and ==== To Run the dukeetf Example Application Using Maven -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . In a terminal window, go to: + ---- -tut-install/examples/web/servlet/dukeetf/ +jakartaee-examples/tutorial/web/servlet/dukeetf/ ---- . Enter the following command to deploy the application: diff --git a/src/main/asciidoc/servlets/servlets018.adoc b/src/main/antora/modules/web/pages/servlets/servlets018.adoc similarity index 100% rename from src/main/asciidoc/servlets/servlets018.adoc rename to src/main/antora/modules/web/pages/servlets/servlets018.adoc diff --git a/src/main/asciidoc/servlets/servlets002.adoc b/src/main/antora/modules/web/pages/servlets/servlets019.adoc similarity index 76% rename from src/main/asciidoc/servlets/servlets002.adoc rename to src/main/antora/modules/web/pages/servlets/servlets019.adoc index 42747fee..cb0a8722 100644 --- a/src/main/asciidoc/servlets/servlets002.adoc +++ b/src/main/antora/modules/web/pages/servlets/servlets019.adoc @@ -1,28 +1,12 @@ -== Servlet Lifecycle +// Split from servlets002.adoc and currently not yet rewritten for EE10. -The lifecycle of a servlet is controlled by the container in which the servlet has been deployed. -When a request is mapped to a servlet, the container performs the following steps. -. If an instance of the servlet does not exist, the web container: - -.. Loads the servlet class - -.. Creates an instance of the servlet class - -.. Initializes the servlet instance by calling the `init` method (initialization is covered in <>) - -. The container invokes the `service` method, passing request and response objects. -Service methods are discussed in <>. - -If it needs to remove the servlet, the container finalizes the servlet by calling the servlet's `destroy` method. -For more information, see <>. - -=== Handling Servlet Lifecycle Events +== Handling Servlet Lifecycle Events You can monitor and react to events in a servlet's lifecycle by defining listener objects whose methods get invoked when lifecycle events occur. To use these listener objects, you must define and specify the listener class. -==== Defining the Listener Class +=== Defining the Listener Class You define a listener class as an implementation of a listener interface. <> lists the events that can be monitored and the corresponding interface that must be implemented. @@ -76,7 +60,7 @@ public class SimpleServletListener implements ServletContextListener, } ---- -=== Handling Servlet Errors +== Handling Servlet Errors Any number of exceptions can occur when a servlet executes. When an exception occurs, the web container generates a default page containing the following message: diff --git a/src/main/asciidoc/webapp/webapp.adoc b/src/main/antora/modules/web/pages/webapp/webapp.adoc similarity index 60% rename from src/main/asciidoc/webapp/webapp.adoc rename to src/main/antora/modules/web/pages/webapp/webapp.adoc index 1323bdab..f3b7b1f0 100644 --- a/src/main/asciidoc/webapp/webapp.adoc +++ b/src/main/antora/modules/web/pages/webapp/webapp.adoc @@ -1,16 +1,15 @@ = Getting Started with Web Applications -This chapter introduces web applications, which typically use Jakarta Faces technology and/or Jakarta Servlet technology. +The Web Profile allows you to get started developing Java web applications, which typically use Jakarta Servlet API as corner stone. include::webapp001.adoc[] include::webapp002.adoc[] -include::webapp003.adoc[] - include::webapp004.adoc[] +include::webapp003.adoc[] + include::webapp005.adoc[] include::webapp006.adoc[] - diff --git a/src/main/antora/modules/web/pages/webapp/webapp001.adoc b/src/main/antora/modules/web/pages/webapp/webapp001.adoc new file mode 100644 index 00000000..86f7f0d7 --- /dev/null +++ b/src/main/antora/modules/web/pages/webapp/webapp001.adoc @@ -0,0 +1,52 @@ +== Web Applications + +A web application, also known as a web app, is a software application that runs on one or more web servers. +It is typically accessed through a web browser over a network, such as the Internet. +The advantage over desktop and mobile applications is being platform-independent, as it can be accessed and used on different devices. +Web applications are of the following types: + +Presentation-oriented:: +A presentation-oriented web application (also called a "website") generates dynamic web pages in response to HTTP requests. +The response is usually represented as a HTML document along with assets, such as Cascading Style Sheets (CSS), JavaScript (JS) and images. +Presentation-oriented applications are often directly used by humans. +Development of presentation-oriented web applications is covered in "Building Web Services with Jakarta XML Web Services" (xref:9.1@websvcs:jaxws/jaxws.adoc#_building_web_services_with_jakarta_xml_web_services[available in a previous version of the tutorial,window=_blank]↗) through xref:servlets/servlets.adoc#_jakarta_servlet_technology[Jakarta Servlet Technology] + +Service-oriented:: +A service-oriented web application (also called a "service") generates dynamic data structures in response to HTTP requests. +The response is usually represented as a JSON object or as a XML document or even as plain text. +Service-oriented applications are often directly used by presentation-oriented web applications or other service-oriented applications. +Development of service-oriented web applications is covered in "Building Web Services with Jakarta XML Web Services" (xref:9.1@websvcs:jaxws/jaxws.adoc#_building_web_services_with_jakarta_xml_web_services[available in a previous version of the tutorial,window=_blank]↗) + +In the Jakarta EE platform, web applications are represented by web components as seen in xref:webapp/webapp.adoc#_jakarta_web_application_request_handling[Jakarta Web Application Request Handling]. +A web component can be represented by Jakarta Servlet, Jakarta Faces or Jakarta REST. + +[[_jakarta_web_application_request_handling]] +.Jakarta Web Application Request Handling +image::common:jakartaeett_dt_013.svg["Diagram of web application request handling. Clients and servlets communicate using HttpServletRequest and HttpServletResponse."] + +. The client sends an HTTP request to the web server. +. The web server module that supports Jakarta Servlet-based web components is called a servlet container. +. The servlet container converts the HTTP request into an `HttpServletRequest` object and prepares the `HttpServletResponse` object. +. These objects are delivered to a web component, which can interact with beans or a database to generate dynamic content. +. The web component can fill the `HttpServletResponse` object with the generated dynamic content or can pass the object to another web component to fill it. +. The servlet container ultimately converts the `HttpServletResponse` object to an HTTP response and the web server returns it to the client. + +Jakarta Servlet can be used to build both presentation and service-oriented web applications. +It intends to reduce the boilerplate code needed to convert the HTTP request into a Java object and to offer a Java object as an HTTP response, and to manage all the lifecycle around them. + +Jakarta Faces is a component-based MVC framework that can be executed on a servlet container and act as a presentation-oriented web application. +It intends to reduce the boilerplate code needed to collect the request parameters, convert and validate them, update bean properties with them, invoke bean methods, and generate HTML output as response. +It is designed to run in servlet and non-servlet environments such as a portlet container.footnote:[The portlet container is defined in https://jcp.org/en/jsr/detail?id=286[JSR 286 Portlet specification] which is not part of Jakarta EE.] + +Jakarta REST is a RESTful web service framework that can be executed on a servlet container and act as a service-oriented web application. +It intends to reduce the boilerplate code needed to convert the request parameters to a bean and further convert it to the desired response such as JSON or XML. +It is designed to run in servlet and non-servlet environments such as a microservice.footnote:[Some frameworks use Jakarta REST with non-blocking server such as Eclipse https://vertx.io[Vert.X] or https://netty.io[Netty].] + +A servlet container can be part of a Jakarta runtime such as an application server. +Certain aspects of web component behavior can be configured when the web application is installed, or deployed, to a servlet container. +The configuration information can be specified using annotations or can be maintained in a XML file called a deployment descriptor. +A deployment descriptor file must comply to the schema described in the specification associated with the web component. +When the same configuration is specified using annotations and in a deployment descriptor file, then the configuration in the deployment descriptor file will always have precedence. + +This chapter gives a brief overview of the activities involved in developing Jakarta Servlet-based web applications. +It explains how to compile, package, deploy, and run Jakarta Servlet-based web applications in a servlet container. diff --git a/src/main/antora/modules/web/pages/webapp/webapp002.adoc b/src/main/antora/modules/web/pages/webapp/webapp002.adoc new file mode 100644 index 00000000..8c5cdcd1 --- /dev/null +++ b/src/main/antora/modules/web/pages/webapp/webapp002.adoc @@ -0,0 +1,144 @@ +== The Web Application Archive + +A Jakarta Servlet-based web application can contain one or more of the following parts: + +* One or more web components, which can be represented by Jakarta Servlet, Jakarta Faces or Jakarta REST. +* Assets (also called static resource files), such as Cascading Style Sheets (CSS), JavaScript (JS) and images. +* Dependencies (also called helper libraries, third party libraries, "JARs"). +* Deployment descriptor files. + +The process for creating, deploying, and executing a Jakarta Servlet-based web application is different from that of Java classes which are packaged and executed as a Java application archive (JAR). +It can be summarized as follows: + +. Develop the web component code. +. Develop the deployment descriptor files, if necessary. +. Compile the web component code against the libraries of the servlet container and the helper libraries, if any. +. Package the compiled code along with helper libraries, assets and deployment descriptor files, if any, into a deployable unit, called a web application archive (WAR). +. Deploy the WAR into a servlet container. +. Run the web application by accessing a URL that references the web component. + +Developing the web component code and deployment descriptor files is covered in the later chapters. +Steps 3 through 6 are expanded on in the following sections and illustrated with two web applications, in Hello World–style. +The web applications take a name as an HTTP request parameter, generate the greeting and return it as an HTTP response. +This chapter discusses the following simple web applications: + +* `hello-servlet`, a Jakarta Servlet-based service-oriented web application +* `hello-faces`, a Jakarta Faces-based presentation-oriented web application + +They are used to illustrate tasks involved in compiling, packaging, deploying, and running a Jakarta Servlet-based web application that contains web component code. + +=== Building, Deploying and Running The Example Projects + +This describes steps 3 through 6. +You need Maven and a servlet container. + +==== Building The Example Projects + +This describes steps 3 and 4. +Maven is used to build the example projects. +Download and install it as per instructions in https://maven.apache.org/[maven.apache.org]. +A Maven WAR project has the following basic structure; not all mentioned resources are required, only the `pom.xml` is required and the rest is optional: + +[source] +---- + |-- src + | `-- main + | |-- java + | | `-- com + | | `-- example + | | |-- controller + | | | `-- Servlet.java + | | `-- model + | | `-- Bean.java + | |-- resources + | | `-- com + | | `-- example + | | `-- i18n + | | |-- text.properties + | | |-- text_en.properties + | | `-- text_es.properties + | `-- webapp + | |-- META-INF + | | `-- MANIFEST.MF + | |-- resources + | | |-- css + | | | `-- style.css + | | |-- img + | | | `-- logo.svg + | | `-- js + | | `-- script.js + | |-- WEB-INF + | | |-- beans.xml + | | |-- faces-config.xml + | | `-- web.xml + | |-- favicon.ico + | `-- index.xhtml + `-- pom.xml +---- + +In a terminal window, go to the folder containing the `pom.xml` and execute the following command: + +[source,shell] +---- +mvn install +---- + +This command compiles and packages the code as described in steps 3 and 4. +After the build, the resulting WAR file will be present in the automatically created `target` folder. +The WAR file is recognizable by having the `.war` extension. + +==== Deploying The Example Projects + +This describes step 5. +You need at least a servlet container in order to deploy a WAR file. +The https://jakarta.ee/compatibility/[Jakarta EE Compatible Products] page lists several Jakarta runtimes having a servlet container. +At least those compatible with "Web Profile" and "Jakarta EE Platform" have a servlet container. +Examples are Eclipse GlassFish, IBM Open Liberty and Red Hat WildFly. +They are available in both "Web Profile" and "Jakarta EE Platform" flavors. + +There are also partial Jakarta runtimes having a servlet container. +Partial as in, they do not fully implement "Web Profile". +One example is Apache Tomcat. +It does implement Jakarta Servlet, Jakarta Pages, Jakarta Expression Language, Jakarta WebSocket, and Jakarta Security. +But it does not implement Jakarta REST, Jakarta CDI, Jakarta Faces nor Jakarta Tags. + +Deploying a WAR file is generally done by placing the WAR file in the runtime-specific folder dedicated for (automatic) deployments. +The exact location depends on the runtime used: + +* In case of Eclipse GlassFish that's the `glassfish/domains/domain1/autodeploy` folder. +* In case of IBM Open Liberty that's the `config/dropins` folder. +* In case of Red Hat WildFly that's the `standalone/deployments` folder. +* In case of Apache Tomcat that's the `webapps` folder. + +Refer to the documentation for your runtime for the most recent information. + +Undeploying a WAR file is generally done by removing the WAR file from the folder. + +Some runtimes offer a graphical user interface (GUI) for administration tasks such as selecting, uploading and a deploying a WAR file. +For this you'll need to start the server first and then open a specific URL in your web browser representing the location of the admin console: + +* In case of Eclipse GlassFish that's reachable via `http://localhost:4848` +* In case of IBM Open Liberty that's reachable via `https://localhost:9443` +* In case of Red Hat WildFly that's reachable via `http://localhost:9990` +* In case of Apache Tomcat that's reachable via `http://localhost:8080/manager` + +Refer to the documentation for your runtime for the most recent information. + +You can also use an integrated development environment (IDE) to manage runtimes and deployments. +Examples are Eclipse IDE, IntelliJ IDEA and Apache NetBeans. +They can also automatically build the projects for you. + +==== Running The Example Projects + +This describes step 6. +You'll need to start the server first and then open a specific URL in your web browser representing the location of the WAR deployment. +By default, the URL has the following form: + +---- +http(s)://host:port/context-path +---- + +By default, the `context-path` is represented by the base file name of the WAR file, without the extension. +If there is no web component listening on the root of the context path, then you could face an HTTP 404 'Not Found' error page. +In that case you would need to use a more specific URL, depending on the configuration of the desired web component. +This will be detailed in xref:web:webapp/webapp.adoc#_mapping_urls_to_web_components[Mapping URLs to Web Components]. diff --git a/src/main/antora/modules/web/pages/webapp/webapp003.adoc b/src/main/antora/modules/web/pages/webapp/webapp003.adoc new file mode 100644 index 00000000..c3e877aa --- /dev/null +++ b/src/main/antora/modules/web/pages/webapp/webapp003.adoc @@ -0,0 +1,160 @@ +== Hello World Web Application Using Jakarta Faces + +The `hello-faces` application is a web application that uses Jakarta Faces take a name as an HTTP request parameter, generate the greeting and return it as an HTTP response. +As a presentation-oriented web application, the response is represented as a HTML document. + +The source code for this application is in the `_jakartaee-examples_/tutorial/web/faces/hello-faces/` directory. + +Jakarta Faces is a component-based MVC framework that provides its own servlet as controller (the "C" part of MVC), the `FacesServlet`. +The model and the view are usually provided by you, the web developer. + +=== The Model + +In a typical Jakarta Faces application, the model (the "M" part of MVC) is represented by a bean class. +Such a bean class is in the Jakarta Faces world called a _Backing Bean_. + +For this Hello World web application, the `src/main/java/jakarta/tutorial/web/faces/Hello.java` backing bean defines a `name` property along with a getter and setter, a `greeting` property along with a getter, and a `submit` action method which creates the `greeting` as output-based on `name` as input. + +[source,java] +---- +package jakarta.tutorial.web.faces; + +import jakarta.enterprise.context.RequestScoped; +import jakarta.inject.Named; + +@Named +@RequestScoped +public class Hello { + + private String name; + private String greeting; + + public void submit() { + greeting = "Hello, " + name + "!"; + } + + public String getName() { + return name; + } + + public void setName(String name) { + this.name = name; + } + + public String getGreeting() { + return greeting; + } +} +---- + +Note that a getter is required for output and that a setter is only required for input. + +In a typical Jakarta Faces application, CDI is used to manage the backing beans. +We'll briefly go through the CDI annotations that are used here: + +* `@Named` -- gives the backing bean a managed bean name, which is primarily used to reference it in Expression Language (EL). + Without any attributes this defaults to the simple class name with the first letter in lowercase. + This backing bean will thus be available as a managed bean via `#\{hello}` in EL. +* `@RequestScoped` -- gives the backing bean a managed bean scope, which essentially represents its lifespan. + In this case that lifespan is the duration of an HTTP request. + When the HTTP request ends, then the managed bean instance is destroyed. + +=== The View + +In a typical Jakarta Faces application, the view (the "V" part of MVC) is represented by a XHTML file. +Such a XHTML file is in the Jakarta Faces world called a _Facelets File_ or just _Facelet_. +In Jakarta Faces, the view technology is pluggable and Facelets is used as the default view technology. +XHTML markup is being used because it allows the framework to easily use a XML parser to find Jakarta Faces tags of interest and to generate HTML output. + +For this Hello World web application, the `src/main/webapp/hello.xhtml` Facelet defines a form with an input field, a command button and an output field. + +[source,xml] +---- + + + + Jakarta Faces Hello World + + +

Hello, what's your name?

+ + + + + + + + + + +---- + +We'll briefly go through the Jakarta Faces-specific XHTML tags that are used here. + +* `` -- generates the HTML ``. + It gives Jakarta Faces the opportunity to automatically include any necessary JS and CSS files in the generated HTML head. +* `` -- generates the HTML ``. + It gives Jakarta Faces the opportunity to automatically include any necessary JS files in the end of the generated HTML body. +* `` -- generates the HTML `
`. + It gives Jakarta Faces the opportunity to automatically include a hidden field representing the view state. +* `` -- generates the HTML ``. + It gives Jakarta Faces the opportunity to automatically get and set the value as a managed bean property specified in the `value` attribute, as well as to perform any conversion and validation on it. +* `` -- generates the HTML ``. + It gives Jakarta Faces the opportunity to automatically invoke the backing bean method specified in the `action` attribute. +* `` -- generates the HTML `
    ` or `
    ` or `` depending on state and configuration. + It gives you the opportunity to declare the place where any conversion and validation messages will be displayed. +* `` -- generates the necessary JavaScript code for Ajax behavior. + If gives you the opportunity to configure the form submit to be performed asynchronously using Ajax. +* `` -- generates the HTML ``. + This is the one being updated on completion of the Ajax submit and it will display the current value of the managed bean property specified in the `value` attribute. + +The `` tags define standard HTML components. +The `` tags define behavior. + +The input value is via EL value expression `#{hello.name}` connected to the `name` property of the `Hello` backing bean via its getter and setter. +The output value is via EL value expression `#{hello.greeting}` connected to the `greeting` property of the `Hello` backing bean via its getter. +The command button is via EL method expression `#{hello.submit}` connected to the `submit` method of the `Hello` backing bean. + +Note that for EL value expressions the physical field representing the property doesn't need to have exactly the same name nor that it needs to exist at all. +EL only looks for the getter and setter methods, not for the field. + +=== The Controller + +In a typical Jakarta Faces application, the controller (the "C" part of MVC) is registered in the Jakarta Servlet deployment descriptor file, the `src/main/webapp/WEB-INF/web.xml`. + +[source,xml] +---- + + + + facesServlet + jakarta.faces.webapp.FacesServlet + 1 + + + facesServlet + *.xhtml + + +---- + +It basically instructs the servlet container to create an instance of `jakarta.faces.webapp.FacesServlet` as `facesServlet` during startup and to execute it when the URL pattern of the HTTP request matches `*.xhtml`. + +=== Running the `hello-faces` example application + +Build and deploy as instructed in xref:webapp/webapp.adoc#_building_deploying_and_running_the_example_projects[Building, Deploying and Running The Example Projects]. + +In a web browser, open the following URL: + +---- +http://localhost:8080/hello-faces/hello.xhtml +---- + +It will show a web page with a form asking for your name. +Enter your name in the input field of the form, for example 'Duke', and click Submit. +This will show the text `Hello, Duke!` below the form. diff --git a/src/main/antora/modules/web/pages/webapp/webapp004.adoc b/src/main/antora/modules/web/pages/webapp/webapp004.adoc new file mode 100644 index 00000000..1472e6ca --- /dev/null +++ b/src/main/antora/modules/web/pages/webapp/webapp004.adoc @@ -0,0 +1,94 @@ +== Hello World Web Application Using Jakarta Servlet + +The `hello-servlet` application is a web application that uses Jakarta Servlet take a name as an HTTP request parameter, generate the greeting and return it as an HTTP response. +As a service-oriented web application, the response is in this minimal example represented as plain text. + +The source code for this application is in the `_jakartaee-examples_/tutorial/web/servlet/hello-servlet/` directory. + +=== The Servlet + +In a typical Jakarta Servlet-based web application, the class must extend `jakarta.servlet.http.HttpServlet` and override one of the `doXxx()` methods where `Xxx` represents the HTTP method of interest. +Such a class is in the Jakarta Servlet world called a _Servlet_. + +For this Hello World web application, the `src/main/java/jakarta/tutorial/web/servlet/Greeting.java` servlet listens on HTTP GET requests and extracts the `name` request parameter as input and creates the `greeting` as output. + +[source,java] +---- +package jakarta.tutorial.web.servlet; + +import java.io.IOException; + +import jakarta.servlet.ServletException; +import jakarta.servlet.annotation.WebServlet; +import jakarta.servlet.http.HttpServlet; +import jakarta.servlet.http.HttpServletRequest; +import jakarta.servlet.http.HttpServletResponse; + +@WebServlet("/greeting") +public class Greeting extends HttpServlet { + + @Override + public void doGet + (HttpServletRequest request, HttpServletResponse response) + throws ServletException, IOException + { + var name = request.getParameter("name"); + + if (name == null || name.isBlank()) { + response.sendError(HttpServletResponse.SC_BAD_REQUEST); + return; + } + + var greeting = "Hello, " + name + "!"; + + response.setContentType("text/plain"); + response.getWriter().write(greeting); + } +} +---- + +=== Mapping URLs to Web Components + +When the servlet container receives a request, it must determine which web component should handle the request. +The servlet container does so by mapping the URL contained in the request to a web component. +A URL contains the context path and, optionally, a URL pattern: + +---- +http(s)://host:port/context-path[/url-pattern] +---- + +You can set the URL pattern for a servlet by using the `@WebServlet` annotation in the servlet source file or by using `` entry in the Jakarta Servlet deployment descriptor file, the `src/main/webapp/WEB-INF/web.xml`. +In the `Greeting` servlet example the `@WebServlet` annotation indicates that the URL pattern is `/greeting`. +Therefore, when the servlet is deployed to a local server listening on `http://localhost:8080` with the context path set to `hello-servlet`, it is accessed with the following URL: + +---- +http://localhost:8080/hello-servlet/greeting +---- + +The Hello World example will return an HTTP 400 error as response indicating a 'Bad Request'. +When specifying the name as a request parameter in the following URL: + +---- +http://localhost:8080/hello-servlet/greeting?name=Duke +---- + +Then it will return the response `Hello, Duke!`. + +=== Running the `hello-servlet` example application + +Build and deploy as instructed in xref:webapp/webapp.adoc#_building_deploying_and_running_the_example_projects[Building, Deploying and Running The Example Projects]. + +In a web browser, open the following URL: + +---- +http://localhost:8080/hello-servlet/greeting?name=Duke +---- + +It will return the response `Hello, Duke!`. +You can edit the `name` parameter into something else to get a different response. + +---- +http://localhost:8080/hello-servlet/greeting?name=Joe +---- + +This will return the response `Hello, Joe!`. diff --git a/src/main/antora/modules/web/pages/webapp/webapp005.adoc b/src/main/antora/modules/web/pages/webapp/webapp005.adoc new file mode 100644 index 00000000..849ba10b --- /dev/null +++ b/src/main/antora/modules/web/pages/webapp/webapp005.adoc @@ -0,0 +1,205 @@ +== Jakarta Servlet Deployment Descriptor + +This section describes the following tasks involved with configuring Jakarta Servlet-based web applications: + +* Preparing deployment descriptor +* Setting context parameters +* Declaring welcome files +* Mapping errors to error screens +* Declaring resource references + + +=== Preparing Deployment Descriptor + +The Jakarta Servlet deployment descriptor is represented by the `WEB-INF/web.xml` file which is in a Maven-based project placed in `src/main/webapp` folder. +It must be a XML file with a `` root element conform the `web-app_X_Y.xsd` XML schema of the https://jakarta.ee/xml/ns/jakartaee[https://jakarta.ee/xml/ns/jakartaee] namespace. + +[source,xml] +---- + + + + + + +---- + + +=== Setting Context Parameters + +The web components in a web application share an object that represents their application context, the `jakarta.servlet.ServletContext`. +You define context-wide initialization parameters in the `web.xml` file. + +[source,xml] +---- + + com.example.THEME + blue + +---- + +You can obtain them in application code via `getInitParameter(String name)` method of the `ServletContext` instance. + +[source,java] +---- +String theme = servletContext.getInitParameter("com.example.THEME"); +---- + +These context parameters can be used to configure (default) application-wide variables, such as the web application's project stage, the path to save uploaded files, the path to a more specific configuration file, the maximum size of a cache, the expiration time of a cacheable resource, the name of the tenant/theme/scheme, or even helper library specific parameters, etcetera, but never passwords. +It are those variables which you'd normally define as constants in a Java class, but then without the need to recompile Java classes whenever you'd like to edit them. + + +=== Declaring Welcome Files + +The welcome files mechanism allows you to specify a list of files that the servlet container can return as a default resource when any folder is requested which does not map to an existing web component. +For example, suppose that you define two welcome files `index.xhtml` and `index.html`. +So, if for example the `/` folder is requested, and it does not map to a web component, then it'll search for `/index.xhtml` and `/index.html` files and return the first found one. +Or if there is none, then the servlet container will continue to perform the default behavior, which is usually displaying an HTTP 404 error page. +Note that this also applies to sub folders, so if for example the `/foo` folder is requested, then it'll search for `/foo/index.xhtml` and `/foo/index.html` files and return the first found one. +You specify welcome files in the `web.xml` file. + +[source,xml] +---- + + index.xhtml + index.html + +---- + +A specified welcome file must not have a leading slash (`/`) as it is interpreted independently of the requested folder. + + +=== Mapping Errors to Error Pages + +When an error occurs during execution of a web application, you can have the application display a specific error page 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 page. +You specify error pages in the `web.xml` file. + +[source,xml] +---- + + 401 + /WEB-INF/error-pages/unauthorized.xhtml + + + 403 + /WEB-INF/error-pages/unauthenticated.xhtml + + + 404 + /WEB-INF/error-pages/not-found.xhtml + + + 500 + /WEB-INF/error-pages/general-error.html + + + jakarta.faces.application.ViewExpiredException + /WEB-INF/error-pages/view-expired.html + + + + /WEB-INF/error-pages/unknown-error.html + +---- + +A specified location must have a leading slash (`/`) as it is interpreted as an absolute path within the context of the web application deployment. +The error page being placed in `/WEB-INF` folder is not technically required, but it is the best practice as it will prevent the client from being able to request or even bookmark them individually. + + +=== Declaring Resource References + +If your web application uses external resources, such as data sources or mail sessions, then you can specify it in `web.xml` and use the `@javax.annotation.Resource` annotation to inject it into a container-managed object of your web application. + +The `@Resource` annotation can be specified on a class, a method, or a field. +The container is responsible for instantiating and injecting references to resources declared by the `@Resource` annotation in container-managed objects and mapping it to the proper JNDI resources. + +Container-managed objects are primarily those objects which you do not explicitly instantiate yourself as in `new ContainerManagedObject()` but basically let the container do. +For example CDI managed beans in case of a CDI container, and web components in case of a servlet container. +CDI managed beans are recognizable as classes having a CDI scope annotation such as `@RequestScoped` or `@Dependent`. +Web components are recognizable as classes that extend or implement a class or interface of the `jakarta.servlet.*` package, and are registered via an annotation of the `jakarta.servlet.annotation.*` package or an entry in the `web.xml` file. + + +==== Declaring Data Source References + +If your web application uses data sources, then you can specify it in `web.xml` and use the `@Resource` annotation to inject it into a container-managed object of your web application as a `javax.sql.DataSource` instance. +The below example specifies a H2 data source listening on JNDI resource name of `java:global/YourDataSourceName`, using the `org.h2.jdbcx.JdbcDataSource` as `javax.sql.DataSource` implementation. + +[source,xml] +---- + + java:global/YourDataSourceName + org.h2.jdbcx.JdbcDataSource + jdbc:h2:mem:test + +---- + +If you have only one data source reference specified, then you can inject it as a `@Resource` of `javax.sql.DataSource` type without an explicit JNDI resource name. + +[source,java] +---- +@Resource +private DataSource dataSource; + +public Connection getConnection() { + return dataSource.getConnection(); +} +---- + +If you have more than one data source reference specified, then you need to explicitly specify the JNDI resource name. + +[source,java] +---- +@Resource(name="java:global/YourDataSourceName") +private DataSource dataSource; + +public Connection getConnection() { + return dataSource.getConnection(); +} +---- + +Do note that `javax.sql.DataSource` is not part of Jakarta EE but of Java SE and hence it has still the `javax` as root package. + +==== Declaring Mail Session References + +If your web application uses mail sessions, then you can specify it in `web.xml` and use the `@Resource` annotation to inject it into a container-managed object of your web application as a `jakarta.mail.Session` instance. +The below example specifies a SMTP mail session listening on JNDI name of `java:global/YourMailSessionName`, using the `smtp.example.com` host to create `jakarta.mail.Session` for. + +[source,xml] +---- + + java:global/YourMailSessionName + smtp.example.com + user@example.com + +---- + +If you have only one mail session reference specified, then you can inject it as a `@Resource` of `jakarta.mail.Session` type without an explicit JNDI resource name. + +[source,java] +---- +@Resource +private Session session; + +public void sendMail(YourMail mail) throws MessagingException { + Message message = new MimeMessage(session); + // ... +} +---- + +If you have more than one mail session reference specified, then you need to explicitly specify the JNDI resource name. + +[source,java] +---- +@Resource(name="java:global/YourMailSessionName") +private Session session; + +public void sendMail(YourMail mail) throws MessagingException { + Message message = new MimeMessage(session); + // ... +} +---- + diff --git a/src/main/antora/modules/web/pages/webapp/webapp006.adoc b/src/main/antora/modules/web/pages/webapp/webapp006.adoc new file mode 100644 index 00000000..d7b5acd6 --- /dev/null +++ b/src/main/antora/modules/web/pages/webapp/webapp006.adoc @@ -0,0 +1,9 @@ +== Further Information about Web Applications + +For more information on web applications, see + +* Jakarta Servlet 6.0 specification: + +https://jakarta.ee/specifications/servlet/6.0/[^] + +* Jakarta Faces 4.0 specification: + +https://jakarta.ee/specifications/faces/4.0/[^] diff --git a/src/main/asciidoc/webi18n/webi18n.adoc b/src/main/antora/modules/web/pages/webi18n/webi18n.adoc similarity index 94% rename from src/main/asciidoc/webi18n/webi18n.adoc rename to src/main/antora/modules/web/pages/webi18n/webi18n.adoc index da5345fc..d77f66c6 100644 --- a/src/main/asciidoc/webi18n/webi18n.adoc +++ b/src/main/antora/modules/web/pages/webi18n/webi18n.adoc @@ -1,5 +1,7 @@ = Internationalizing and Localizing Web Applications +include::ROOT:partial$not_updated.adoc[] + The process of preparing an application to support more than one language and data format is called internationalization. Localization is the process of adapting an internationalized application to support a specific region or locale. Examples of locale-dependent information include messages and user interface labels, character sets and encoding, and date and currency formats. diff --git a/src/main/asciidoc/webi18n/webi18n001.adoc b/src/main/antora/modules/web/pages/webi18n/webi18n001.adoc similarity index 81% rename from src/main/asciidoc/webi18n/webi18n001.adoc rename to src/main/antora/modules/web/pages/webi18n/webi18n001.adoc index a99bd741..e94ee7fc 100644 --- a/src/main/asciidoc/webi18n/webi18n001.adoc +++ b/src/main/antora/modules/web/pages/webi18n/webi18n001.adoc @@ -9,7 +9,7 @@ A resource bundle contains key-value pairs, where the keys uniquely identify a l A resource bundle can be backed by a text file (properties resource bundle) or a class (list resource bundle) containing the pairs. You construct a resource bundle instance by appending a locale string representation to a base name. -The Duke's Bookstore application (see xref:dukes-bookstore-case-study-example[xrefstyle=full]) contains resource bundles with the base name `messages.properties` for the locales `de` (German), `es` (Spanish), and `fr` (French). +The Duke's Bookstore application (see xref:casestudies:dukes-bookstore/dukes-bookstore.adoc#_dukes_bookstore_case_study_example[Duke's Bookstore Case Study Example]) contains resource bundles with the base name `messages.properties` for the locales `de` (German), `es` (Spanish), and `fr` (French). The default locale, `en` (English), which is specified in the `faces-config.xml` file, uses the resource bundle with the base name, `messages.properties`. For more details on internationalization and localization in the Java platform, see https://docs.oracle.com/javase/tutorial/i18n/index.html[^]. diff --git a/src/main/asciidoc/webi18n/webi18n002.adoc b/src/main/antora/modules/web/pages/webi18n/webi18n002.adoc similarity index 91% rename from src/main/asciidoc/webi18n/webi18n002.adoc rename to src/main/antora/modules/web/pages/webi18n/webi18n002.adoc index 2922db3e..4b203f1d 100644 --- a/src/main/asciidoc/webi18n/webi18n002.adoc +++ b/src/main/antora/modules/web/pages/webi18n/webi18n002.adoc @@ -70,7 +70,7 @@ The setting for Duke's Bookstore looks like this: ---- -After the locale is set, the controller of a web application could retrieve the resource bundle for that locale and save it as a session attribute (see <>) for use by other components or simply be used to return a text string appropriate for the selected locale: +After the locale is set, the controller of a web application could retrieve the resource bundle for that locale and save it as a session attribute (see xref:servlets/servlets.adoc#_associating_objects_with_a_session[Associating Objects with a Session]) for use by other components or simply be used to return a text string appropriate for the selected locale: [source,java] ---- @@ -93,7 +93,7 @@ This tag loads the correct resource bundle according to the locale stored in `Fa Resource bundles containing messages that are explicitly referenced from a Jakarta Faces tag attribute using a value expression must be registered using the `resource-bundle` element of the configuration file. -For more information on using this element, see <>. +For more information on using this element, see xref:faces-configure/faces-configure.adoc#_registering_application_messages[Registering Application Messages]. === Retrieving Localized Messages @@ -124,7 +124,7 @@ The following example shows a `message` tag that displays the error message queu id="errors1" for="userNo"/> ---- -For more information on using the `message` or `messages` tags, see <>. +For more information on using the `message` or `messages` tags, see xref:faces-page/faces-page.adoc#_displaying_error_messages_with_the_hmessage_and_hmessages_tags[Displaying Error Messages with the h:message and h:messages Tags]. Messages that are not queued on a component and are therefore not loaded automatically are referenced using a value expression. You can reference a localized message from almost any Jakarta Faces tag attribute. diff --git a/src/main/asciidoc/webi18n/webi18n003.adoc b/src/main/antora/modules/web/pages/webi18n/webi18n003.adoc similarity index 80% rename from src/main/asciidoc/webi18n/webi18n003.adoc rename to src/main/antora/modules/web/pages/webi18n/webi18n003.adoc index 00dda76a..3a70fd58 100644 --- a/src/main/asciidoc/webi18n/webi18n003.adoc +++ b/src/main/antora/modules/web/pages/webi18n/webi18n003.adoc @@ -13,4 +13,4 @@ For example, a shipping date could be converted as follows: ---- -For information on Jakarta Faces converters, see <>. +For information on Jakarta Faces converters, see xref:faces-page-core/faces-page-core.adoc#_using_the_standard_converters[Using the Standard Converters]. diff --git a/src/main/asciidoc/webi18n/webi18n004.adoc b/src/main/antora/modules/web/pages/webi18n/webi18n004.adoc similarity index 100% rename from src/main/asciidoc/webi18n/webi18n004.adoc rename to src/main/antora/modules/web/pages/webi18n/webi18n004.adoc diff --git a/src/main/asciidoc/websocket/websocket.adoc b/src/main/antora/modules/web/pages/websocket/websocket.adoc similarity index 93% rename from src/main/asciidoc/websocket/websocket.adoc rename to src/main/antora/modules/web/pages/websocket/websocket.adoc index e46b81b4..dc1a27d5 100644 --- a/src/main/asciidoc/websocket/websocket.adoc +++ b/src/main/antora/modules/web/pages/websocket/websocket.adoc @@ -1,5 +1,7 @@ = Jakarta WebSocket +include::ROOT:partial$not_updated.adoc[] + This chapter describes Jakarta WebSocket, which provides support for creating WebSocket applications. WebSocket is an application protocol that provides full-duplex communications between two peers over the TCP protocol. diff --git a/src/main/asciidoc/websocket/websocket001.adoc b/src/main/antora/modules/web/pages/websocket/websocket001.adoc similarity index 100% rename from src/main/asciidoc/websocket/websocket001.adoc rename to src/main/antora/modules/web/pages/websocket/websocket001.adoc diff --git a/src/main/asciidoc/websocket/websocket002.adoc b/src/main/antora/modules/web/pages/websocket/websocket002.adoc similarity index 100% rename from src/main/asciidoc/websocket/websocket002.adoc rename to src/main/antora/modules/web/pages/websocket/websocket002.adoc diff --git a/src/main/asciidoc/websocket/websocket003.adoc b/src/main/antora/modules/web/pages/websocket/websocket003.adoc similarity index 100% rename from src/main/asciidoc/websocket/websocket003.adoc rename to src/main/antora/modules/web/pages/websocket/websocket003.adoc diff --git a/src/main/asciidoc/websocket/websocket004.adoc b/src/main/antora/modules/web/pages/websocket/websocket004.adoc similarity index 83% rename from src/main/asciidoc/websocket/websocket004.adoc rename to src/main/antora/modules/web/pages/websocket/websocket004.adoc index c1308776..5e00e24e 100644 --- a/src/main/asciidoc/websocket/websocket004.adoc +++ b/src/main/antora/modules/web/pages/websocket/websocket004.adoc @@ -1,6 +1,6 @@ == Annotated Endpoints -The following example shows how to create the same endpoint from <> using annotations instead: +The following example shows how to create the same endpoint from xref:websocket/websocket.adoc#_programmatic_endpoints[Programmatic Endpoints] using annotations instead: [source,java] ---- @@ -18,11 +18,11 @@ public class EchoEndpoint { The annotated endpoint is simpler than the equivalent programmatic endpoint, and it is deployed automatically with the application to the relative path defined in the `ServerEndpoint` annotation. Instead of having to create an additional class for the message handler, this example uses the `OnMessage` annotation to designate the method invoked to handle messages. -<> lists the annotations available in the `jakarta.websocket` package to designate the methods that handle lifecycle events. +<<_websocket_endpoint_lifecycle_annotations>> lists the annotations available in the `jakarta.websocket` package to designate the methods that handle lifecycle events. The examples in the table show the most common parameters for these methods. See the API reference for details on what combinations of parameters are allowed in each case. -[[websocket-endpoint-lifecycle-annotations]] +[[_websocket_endpoint_lifecycle_annotations]] .WebSocket Endpoint Lifecycle Annotations [width="80%",cols="20%,20%,60%"] |=== diff --git a/src/main/asciidoc/websocket/websocket005.adoc b/src/main/antora/modules/web/pages/websocket/websocket005.adoc similarity index 91% rename from src/main/asciidoc/websocket/websocket005.adoc rename to src/main/antora/modules/web/pages/websocket/websocket005.adoc index 0cbb9ede..95a2821b 100644 --- a/src/main/asciidoc/websocket/websocket005.adoc +++ b/src/main/antora/modules/web/pages/websocket/websocket005.adoc @@ -10,7 +10,7 @@ Follow these steps to send messages in an endpoint. . Obtain the `Session` object from the connection. + -The `Session` object is available as a parameter in the annotated lifecycle methods of the endpoint, like those in <>. +The `Session` object is available as a parameter in the annotated lifecycle methods of the endpoint, like those in xref:websocket/websocket.adoc#_websocket_endpoint_lifecycle_annotations[Websocket Endpoint Lifecycle Annotations]. When your message is a response to a message from the peer, you have the `Session` object available inside the method that received the message (the method annotated with `@OnMessage`). If you have to send messages that are not responses, store the `Session` object as an instance variable of the endpoint class in the method annotated with `@OnOpen` so that you can access it from other methods. @@ -42,7 +42,7 @@ end a ping frame to the peer. + Send a pong frame to the peer. -The example in <> demonstrates how to use this procedure to reply to every incoming text message. +The example in xref:websocket/websocket.adoc#_annotated_endpoints[Annotated Endpoints] demonstrates how to use this procedure to reply to every incoming text message. ==== Sending Messages to All Peers Connected to an Endpoint diff --git a/src/main/asciidoc/websocket/websocket006.adoc b/src/main/antora/modules/web/pages/websocket/websocket006.adoc similarity index 100% rename from src/main/asciidoc/websocket/websocket006.adoc rename to src/main/antora/modules/web/pages/websocket/websocket006.adoc diff --git a/src/main/asciidoc/websocket/websocket007.adoc b/src/main/antora/modules/web/pages/websocket/websocket007.adoc similarity index 100% rename from src/main/asciidoc/websocket/websocket007.adoc rename to src/main/antora/modules/web/pages/websocket/websocket007.adoc diff --git a/src/main/asciidoc/websocket/websocket008.adoc b/src/main/antora/modules/web/pages/websocket/websocket008.adoc similarity index 100% rename from src/main/asciidoc/websocket/websocket008.adoc rename to src/main/antora/modules/web/pages/websocket/websocket008.adoc diff --git a/src/main/asciidoc/websocket/websocket009.adoc b/src/main/antora/modules/web/pages/websocket/websocket009.adoc similarity index 100% rename from src/main/asciidoc/websocket/websocket009.adoc rename to src/main/antora/modules/web/pages/websocket/websocket009.adoc diff --git a/src/main/asciidoc/websocket/websocket010.adoc b/src/main/antora/modules/web/pages/websocket/websocket010.adoc similarity index 100% rename from src/main/asciidoc/websocket/websocket010.adoc rename to src/main/antora/modules/web/pages/websocket/websocket010.adoc diff --git a/src/main/asciidoc/websocket/websocket011.adoc b/src/main/antora/modules/web/pages/websocket/websocket011.adoc similarity index 83% rename from src/main/asciidoc/websocket/websocket011.adoc rename to src/main/antora/modules/web/pages/websocket/websocket011.adoc index 63327051..6a95e437 100644 --- a/src/main/asciidoc/websocket/websocket011.adoc +++ b/src/main/antora/modules/web/pages/websocket/websocket011.adoc @@ -1,6 +1,6 @@ == The dukeetf2 Example Application -The `dukeetf2` example application, located in the `_tut-install_/examples/web/websocket/dukeetf2/` directory, demonstrates how to use a WebSocket endpoint to provide data updates to web clients. +The `dukeetf2` example application, located in the `_jakartaee-examples_/tutorial/web/websocket/dukeetf2/` directory, demonstrates how to use a WebSocket endpoint to provide data updates to web clients. The example resembles a service that provides periodic updates on the price and trading volume of an electronically traded fund (ETF). === Architecture of the dukeetf2 Sample Application @@ -108,7 +108,7 @@ public class PriceVolumeBean { ---- The enterprise bean calls the `send` method of the `ETFEndpoint` class in the timeout method. -See <> in xref: <> for more information on the timer service. +See xref:entbeans:ejb-basicexamples/ejb-basicexamples.adoc#_using_the_timer_service[Using the Timer Service] in xref:entbeans:ejb-basicexamples/ejb-basicexamples.adoc#_running_the_enterprise_bean_examples[Running the Enterprise Bean Examples] for more information on the timer service. ==== The HTML Page @@ -118,18 +118,19 @@ The table contains two fields referenced from JavaScript code: [source,html] ---- - -... - - ... -
    + + ... + ... - +
    --.--
    + ... + + ... + + ... +
    --.----
    ... - -- - ... - - + ---- @@ -159,14 +160,14 @@ This section describes how to run the `dukeetf2` example application using NetBe ==== To Run the dukeetf2 Example Application Using NetBeans IDE -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . From the *File* menu, choose *Open Project*. . In the Open Project dialog box, navigate to: + ---- -tut-install/examples/web/websocket +jakartaee-examples/tutorial/web/websocket ---- . Select the `dukeetf2` folder. @@ -185,12 +186,12 @@ Open the same URL on a different web browser tab or window to see how both pages ==== To Run the dukeetf2 Example Application Using Maven -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . In a terminal window, go to: + ---- -tut-install/examples/web/websocket/dukeetf2/ +jakartaee-examples/tutorial/web/websocket/dukeetf2/ ---- . Enter the following command to deploy the application: diff --git a/src/main/asciidoc/websocket/websocket012.adoc b/src/main/antora/modules/web/pages/websocket/websocket012.adoc similarity index 82% rename from src/main/asciidoc/websocket/websocket012.adoc rename to src/main/antora/modules/web/pages/websocket/websocket012.adoc index b5a85833..2458300b 100644 --- a/src/main/asciidoc/websocket/websocket012.adoc +++ b/src/main/antora/modules/web/pages/websocket/websocket012.adoc @@ -1,6 +1,6 @@ == The websocketbot Example Application -The `websocketbot` example application, located in the `_tut-install_/examples/web/websocket/websocketbot/` directory, demonstrates how to use a WebSocket endpoint to implement a chat. +The `websocketbot` example application, located in the `_jakartaee-examples_/tutorial/web/websocket/websocketbot/` directory, demonstrates how to use a WebSocket endpoint to implement a chat. The example resembles a chat room in which many users can join and have a conversation. Users can ask simple questions to a bot agent that is always available in the chat room. @@ -8,17 +8,17 @@ Users can ask simple questions to a bot agent that is always available in the ch The `websocketbot` example application consists of the following elements: -* <> – A CDI bean (`BotBean`) that contains the logic for the bot agent to reply to messages +* <<_the_cdi_bean>> – A CDI bean (`BotBean`) that contains the logic for the bot agent to reply to messages -* <> – A WebSocket endpoint (`BotEndpoint`) that implements the chat room +* <<_the_websocket_endpoint>> – A WebSocket endpoint (`BotEndpoint`) that implements the chat room -* <> – A set of classes (`Message`, `ChatMessage`, `InfoMessage`, `JoinMessage`, and `UsersMessage`) that represent application messages +* <<_the_application_messages>> – A set of classes (`Message`, `ChatMessage`, `InfoMessage`, `JoinMessage`, and `UsersMessage`) that represent application messages -* <> – A set of classes (`ChatMessageEncoder`, `InfoMessageEncoder`, `JoinMessageEncoder`, and `UsersMessageEncoder`) that encode application messages into WebSocket text messages as JSON data +* <<_the_encoder_classes>> – A set of classes (`ChatMessageEncoder`, `InfoMessageEncoder`, `JoinMessageEncoder`, and `UsersMessageEncoder`) that encode application messages into WebSocket text messages as JSON data -* <> – A class (`MessageDecoder`) the parses WebSocket text messages as JSON data and decodes them into `JoinMessage` or `ChatMessage` objects +* <<_the_message_decoder>> – A class (`MessageDecoder`) the parses WebSocket text messages as JSON data and decodes them into `JoinMessage` or `ChatMessage` objects -* <> – An HTML page (`index.html`) that uses JavaScript code to implement the client for the chat room +* <<_the_html_page>> – An HTML page (`index.html`) that uses JavaScript code to implement the client for the chat room ==== The CDI Bean @@ -119,7 +119,7 @@ If the message is a join message, the endpoint adds the new user to the list and If the message is a chat message, the endpoint forwards it to all connected clients. If a chat message is for the bot agent, the endpoint obtains a response using the `BotBean` instance and sends it to all connected clients. -The `sendAll` method is similar to the example in <>. +The `sendAll` method is similar to the example in xref:websocket/websocket.adoc#_sending_messages_to_all_peers_connected_to_an_endpoint[Sending Messages to All Peers Connected to an Endpoint]. ===== Asynchronous Processing and Concurrency Considerations @@ -132,7 +132,7 @@ This facilitates the development of WebSocket endpoints, because you are guarant When you introduce a new thread in an endpoint, as in this example, you must ensure that variables and methods accessed by more than one thread are thread safe. In this example, the code in `BotBean` is thread safe, and the `BotEndpoint.sendAll` method has been declared `synchronized`. -Refer to xref:jakarta-concurrency-2[xrefstyle=full] for more information on the managed executor service and Concurrency Utilities for Jakarta EE. +Refer to xref:supporttechs:concurrency-utilities/concurrency-utilities.adoc#_jakarta_concurrency[Jakarta Concurrency] for more information on the managed executor service and Concurrency Utilities for Jakarta EE. ==== The Application Messages @@ -173,7 +173,7 @@ public class ChatMessageEncoder implements Encoder.Text { } ---- -See xref:json-processing[xrefstyle=full] for more information on the Jakarta JSON Processing. +See xref:jsonp/jsonp.adoc#_json_processing[JSON Processing] for more information on the Jakarta JSON Processing. ==== The Message Decoder @@ -241,14 +241,14 @@ This section describes how to run the `websocketbot` example application using N ==== To Run the websocketbot Example Application Using NetBeans IDE -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . From the *File* menu, choose *Open Project*. . In the Open Project dialog box, navigate to: + ---- -tut-install/examples/web/websocket +jakartaee-examples/tutorial/web/websocket ---- . Select the `websocketbot` folder. @@ -263,16 +263,16 @@ This command builds and packages the application into a WAR file, `websocketbot. http://localhost:8080/websocketbot/ ---- + -See <> for more information. +See <<_to_test_the_websocketbot_example_application>> for more information. ==== To Run the websocketbot Example Application Using Maven -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . In a terminal window, go to: + ---- -tut-install/examples/web/websocket/websocketbot/ +jakartaee-examples/tutorial/web/websocket/websocketbot/ ---- . Enter the following command to deploy the application: @@ -288,7 +288,7 @@ mvn install http://localhost:8080/websocketbot/ ---- + -See <> for more information. +See <<_to_test_the_websocketbot_example_application>> for more information. ==== To Test the websocketbot Example Application diff --git a/src/main/asciidoc/websocket/websocket013.adoc b/src/main/antora/modules/web/pages/websocket/websocket013.adoc similarity index 100% rename from src/main/asciidoc/websocket/websocket013.adoc rename to src/main/antora/modules/web/pages/websocket/websocket013.adoc diff --git a/src/main/asciidoc/jaxrs-advanced/jaxrs-advanced.adoc b/src/main/antora/modules/websvcs/pages/jaxrs-advanced/jaxrs-advanced.adoc similarity index 73% rename from src/main/asciidoc/jaxrs-advanced/jaxrs-advanced.adoc rename to src/main/antora/modules/websvcs/pages/jaxrs-advanced/jaxrs-advanced.adoc index 17eda6b0..cf65275e 100644 --- a/src/main/asciidoc/jaxrs-advanced/jaxrs-advanced.adoc +++ b/src/main/antora/modules/websvcs/pages/jaxrs-advanced/jaxrs-advanced.adoc @@ -1,8 +1,10 @@ = Jakarta REST: Advanced Topics and an Example +include::ROOT:partial$not_updated.adoc[] + Jakarta RESTful Web Services (Jakarta REST) is designed to make it easy to develop applications that use the REST architecture. This chapter describes advanced features of Jakarta REST. -If you are new to Jakarta REST, see xref:building-restful-web-services-with-jakarta-rest[xrefstyle=full] before you proceed with this chapter. +If you are new to Jakarta REST, see xref:jaxrs/jaxrs.adoc#_building_restful_web_services_with_jakarta_rest[Building RESTful Web Services with Jakarta REST] before you proceed with this chapter. Jakarta REST is integrated with Jakarta Contexts and Dependency Injection (CDI), Jakarta Enterprise Beans technology, and Jakarta Servlet technology. diff --git a/src/main/asciidoc/jaxrs-advanced/jaxrs-advanced001.adoc b/src/main/antora/modules/websvcs/pages/jaxrs-advanced/jaxrs-advanced001.adoc similarity index 96% rename from src/main/asciidoc/jaxrs-advanced/jaxrs-advanced001.adoc rename to src/main/antora/modules/websvcs/pages/jaxrs-advanced/jaxrs-advanced001.adoc index 2c83c65d..62e08c80 100644 --- a/src/main/asciidoc/jaxrs-advanced/jaxrs-advanced001.adoc +++ b/src/main/antora/modules/websvcs/pages/jaxrs-advanced/jaxrs-advanced001.adoc @@ -2,9 +2,9 @@ Jakarta REST annotations for resource classes let you extract specific parts or values from a Uniform Resource Identifier (URI) or request header. -Jakarta REST provides the annotations listed in <>. +Jakarta REST provides the annotations listed in <<_advanced_jakarta_rest_annotations>>. -[[advanced-jakarta-rest-annotations]] +[[_advanced_jakarta_rest_annotations]] .Advanced Jakarta REST Annotations [width="99%",cols="5%,95%"] |=== @@ -45,7 +45,7 @@ public class EmpResource { } ---- -In this example, the `@Path` annotation defines the URI variables (or path parameters) pass:q[`{firstname}`, `{lastname}`], and `{domain}`. +In this example, the `@Path` annotation defines the URI variables (or path parameters) pass:q[`{firstname}`, `{lastname}`, and `{domain}`]. The `@PathParam` in the method parameter of the request method extracts the last name from the email address. If your HTTP request is `GET` `/employees/john.doe@example.com`, the value "`doe`" is injected into pass:q[`{lastname}`]. diff --git a/src/main/asciidoc/jaxrs-advanced/jaxrs-advanced002.adoc b/src/main/antora/modules/websvcs/pages/jaxrs-advanced/jaxrs-advanced002.adoc similarity index 100% rename from src/main/asciidoc/jaxrs-advanced/jaxrs-advanced002.adoc rename to src/main/antora/modules/websvcs/pages/jaxrs-advanced/jaxrs-advanced002.adoc diff --git a/src/main/asciidoc/jaxrs-advanced/jaxrs-advanced003.adoc b/src/main/antora/modules/websvcs/pages/jaxrs-advanced/jaxrs-advanced003.adoc similarity index 100% rename from src/main/asciidoc/jaxrs-advanced/jaxrs-advanced003.adoc rename to src/main/antora/modules/websvcs/pages/jaxrs-advanced/jaxrs-advanced003.adoc diff --git a/src/main/asciidoc/jaxrs-advanced/jaxrs-advanced004.adoc b/src/main/antora/modules/websvcs/pages/jaxrs-advanced/jaxrs-advanced004.adoc similarity index 100% rename from src/main/asciidoc/jaxrs-advanced/jaxrs-advanced004.adoc rename to src/main/antora/modules/websvcs/pages/jaxrs-advanced/jaxrs-advanced004.adoc diff --git a/src/main/asciidoc/jaxrs-advanced/jaxrs-advanced005.adoc b/src/main/antora/modules/websvcs/pages/jaxrs-advanced/jaxrs-advanced005.adoc similarity index 100% rename from src/main/asciidoc/jaxrs-advanced/jaxrs-advanced005.adoc rename to src/main/antora/modules/websvcs/pages/jaxrs-advanced/jaxrs-advanced005.adoc diff --git a/src/main/asciidoc/jaxrs-advanced/jaxrs-advanced006.adoc b/src/main/antora/modules/websvcs/pages/jaxrs-advanced/jaxrs-advanced006.adoc similarity index 100% rename from src/main/asciidoc/jaxrs-advanced/jaxrs-advanced006.adoc rename to src/main/antora/modules/websvcs/pages/jaxrs-advanced/jaxrs-advanced006.adoc diff --git a/src/main/asciidoc/jaxrs-advanced/jaxrs-advanced007.adoc b/src/main/antora/modules/websvcs/pages/jaxrs-advanced/jaxrs-advanced007.adoc similarity index 97% rename from src/main/asciidoc/jaxrs-advanced/jaxrs-advanced007.adoc rename to src/main/antora/modules/websvcs/pages/jaxrs-advanced/jaxrs-advanced007.adoc index af1ad2db..49910d4e 100644 --- a/src/main/asciidoc/jaxrs-advanced/jaxrs-advanced007.adoc +++ b/src/main/antora/modules/websvcs/pages/jaxrs-advanced/jaxrs-advanced007.adoc @@ -33,7 +33,7 @@ As you define the resources for your application, consider the type of data you You may already have a relational database that contains information you want to expose to users, or you may have static content that does not reside in a database but does need to be distributed as resources. Using Jakarta REST, you can distribute content from multiple sources. RESTful web services can use various types of input/output formats for request and response. -The `customer` example, described in <>, uses XML. +The `customer` example, described in xref:jaxrs-advanced/jaxrs-advanced.adoc#_the_customer_example_application[The customer Example Application], uses XML. Resources have representations. A resource representation is the content in the HTTP message that is sent to, or returned from, the resource using the URI. @@ -137,7 +137,7 @@ public class ProductService { ---- Some IDEs, such as NetBeans IDE, will run the schema generator tool automatically during the build process if you add Java classes that have Jakarta XML Binding annotations to your project. -For a detailed example, see <>. +For a detailed example, see xref:jaxrs-advanced/jaxrs-advanced.adoc#_the_customer_example_application[The customer Example Application]. The `customer` example contains a more complex relationship between the Java classes that model the data, which results in a more hierarchical XML representation. === Starting from an Existing XML Schema Definition diff --git a/src/main/asciidoc/jaxrs-advanced/jaxrs-advanced008.adoc b/src/main/antora/modules/websvcs/pages/jaxrs-advanced/jaxrs-advanced008.adoc similarity index 93% rename from src/main/asciidoc/jaxrs-advanced/jaxrs-advanced008.adoc rename to src/main/antora/modules/websvcs/pages/jaxrs-advanced/jaxrs-advanced008.adoc index e85e43a0..c8f84950 100644 --- a/src/main/asciidoc/jaxrs-advanced/jaxrs-advanced008.adoc +++ b/src/main/antora/modules/websvcs/pages/jaxrs-advanced/jaxrs-advanced008.adoc @@ -3,12 +3,12 @@ This section describes how to build and run the `customer` example application. This application is a RESTful web service that uses Jakarta XML Binding to perform the create, read, update, delete (CRUD) operations for a specific entity. -The `customer` sample application is in the `_tut-install_/examples/jaxrs/customer/` directory. -See xref:using-the-tutorial-examples[xrefstyle=full], for basic information on building and running sample applications. +The `customer` sample application is in the `_jakartaee-examples_/tutorial/jaxrs/customer/` directory. +See xref:intro:usingexamples/usingexamples.adoc#_using_the_tutorial_examples[Using the Tutorial Examples], for basic information on building and running sample applications. === Overview of the customer Example Application -The source files of this application are at `_tut-install_/examples/jaxrs/customer/src/main/java/`. +The source files of this application are at `_jakartaee-examples_/tutorial/jaxrs/customer/src/main/java/`. The application has three parts. * The `Customer` and `Address` entity classes. @@ -16,7 +16,7 @@ These classes model the data of the application and contain Jakarta XML Binding * The `CustomerService` resource class. This class contains Jakarta REST resource methods that perform operations on `Customer` instances represented as XML or JSON data using Jakarta XML Binding. -See <> for details. +See <<_the_customerservice_class>> for details. * The `CustomerBean` session bean that acts as a backing bean for the web client. `CustomerBean` uses the Jakarta REST client API to call the methods of `CustomerService`. @@ -327,14 +327,14 @@ You can use either NetBeans IDE or Maven to build, package, deploy, and run the ==== To Build, Package, and Deploy the customer Example Using NetBeans IDE -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . From the *File* menu, choose *Open Project*. . In the *Open Project* dialog box, navigate to: + ---- -tut-install/examples/jaxrs +jakartaee-examples/tutorial/jaxrs ---- . Select the `customer` folder. @@ -357,12 +357,12 @@ The web client allows you to create and view customers. ==== To Build, Package, and Deploy the customer Example Using Maven . Make sure that GlassFish Server has been started (see -<>). +xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . In a terminal window, go to: + ---- -tut-install/examples/jaxrs/customer/ +jakartaee-examples/tutorial/jaxrs/customer/ ---- . Enter the following command: diff --git a/src/main/asciidoc/jaxrs-client/jaxrs-client.adoc b/src/main/antora/modules/websvcs/pages/jaxrs-client/jaxrs-client.adoc similarity index 90% rename from src/main/asciidoc/jaxrs-client/jaxrs-client.adoc rename to src/main/antora/modules/websvcs/pages/jaxrs-client/jaxrs-client.adoc index 00855d0c..426d1c79 100644 --- a/src/main/asciidoc/jaxrs-client/jaxrs-client.adoc +++ b/src/main/antora/modules/websvcs/pages/jaxrs-client/jaxrs-client.adoc @@ -1,5 +1,7 @@ = Accessing REST Resources with the Jakarta REST Client API +include::ROOT:partial$not_updated.adoc[] + This chapter describes the Jakarta REST Client API and includes examples of how to access REST resources using the Java programming language. Jakarta REST provides a client API for accessing REST resources from other Java applications. diff --git a/src/main/asciidoc/jaxrs-client/jaxrs-client001.adoc b/src/main/antora/modules/websvcs/pages/jaxrs-client/jaxrs-client001.adoc similarity index 97% rename from src/main/asciidoc/jaxrs-client/jaxrs-client001.adoc rename to src/main/antora/modules/websvcs/pages/jaxrs-client/jaxrs-client001.adoc index 1f03d96e..b79f8a90 100644 --- a/src/main/asciidoc/jaxrs-client/jaxrs-client001.adoc +++ b/src/main/antora/modules/websvcs/pages/jaxrs-client/jaxrs-client001.adoc @@ -83,7 +83,7 @@ The `WebTarget.path` method creates a new `WebTarget` instance by appending the Path parameters in client requests can be specified as URI template parameters, similar to the template parameters used when defining a resource URI in a Jakarta REST service. Template parameters are specified by surrounding the template variable with braces (`{}`). -Call the `resolveTemplate` method to substitute the `{username}`, and then call the `queryParam` method to add another variable to pass. +Call the `resolveTemplate` method to substitute the `\{username}`, and then call the `queryParam` method to add another variable to pass. [source,java] ---- diff --git a/src/main/asciidoc/jaxrs-client/jaxrs-client002.adoc b/src/main/antora/modules/websvcs/pages/jaxrs-client/jaxrs-client002.adoc similarity index 95% rename from src/main/asciidoc/jaxrs-client/jaxrs-client002.adoc rename to src/main/antora/modules/websvcs/pages/jaxrs-client/jaxrs-client002.adoc index 8bd1b8f3..043073ef 100644 --- a/src/main/asciidoc/jaxrs-client/jaxrs-client002.adoc +++ b/src/main/antora/modules/websvcs/pages/jaxrs-client/jaxrs-client002.adoc @@ -5,7 +5,7 @@ This section describes how each example application uses the Client API. === The Client API in the rsvp Example Application -The `rsvp` application allows users to respond to event invitations using Jakarta REST resources, as explained in <>. +The `rsvp` application allows users to respond to event invitations using Jakarta REST resources, as explained in xref:jaxrs/jaxrs.adoc#_the_rsvp_example_application[The rsvp Example Application]. The web application uses the Client API in CDI backing beans to interact with the service resources, and the Facelets web interface displays the results. The `StatusManager` CDI backing bean retrieves all the current events in the system. @@ -79,7 +79,7 @@ public String changeStatus(ResponseEnum userResponse, === The Client API in the customer Example Application -The `customer` example application stores customer data in a database and exposes the resource as XML, as explained in <>. +The `customer` example application stores customer data in a database and exposes the resource as XML, as explained in xref:jaxrs-advanced/jaxrs-advanced.adoc#_the_customer_example_application[The customer Example Application]. The service resource exposes methods that create customers and retrieve all the customers. A Facelets web application acts as a client for the service resource, with a form for creating customers and displaying the list of customers in a table. diff --git a/src/main/asciidoc/jaxrs-client/jaxrs-client003.adoc b/src/main/antora/modules/websvcs/pages/jaxrs-client/jaxrs-client003.adoc similarity index 100% rename from src/main/asciidoc/jaxrs-client/jaxrs-client003.adoc rename to src/main/antora/modules/websvcs/pages/jaxrs-client/jaxrs-client003.adoc diff --git a/src/main/asciidoc/jaxrs/jaxrs.adoc b/src/main/antora/modules/websvcs/pages/jaxrs/jaxrs.adoc similarity index 89% rename from src/main/asciidoc/jaxrs/jaxrs.adoc rename to src/main/antora/modules/websvcs/pages/jaxrs/jaxrs.adoc index 6bb46dc1..c90e0782 100644 --- a/src/main/asciidoc/jaxrs/jaxrs.adoc +++ b/src/main/antora/modules/websvcs/pages/jaxrs/jaxrs.adoc @@ -1,5 +1,7 @@ = Building RESTful Web Services with Jakarta REST +include::ROOT:partial$not_updated.adoc[] + This chapter describes the REST architecture, RESTful web services, and the Jakarta RESTful Web Services. Jakarta REST makes it easy for developers to build RESTful web services using the Java programming language. diff --git a/src/main/asciidoc/jaxrs/jaxrs001.adoc b/src/main/antora/modules/websvcs/pages/jaxrs/jaxrs001.adoc similarity index 75% rename from src/main/asciidoc/jaxrs/jaxrs001.adoc rename to src/main/antora/modules/websvcs/pages/jaxrs/jaxrs001.adoc index 778435d3..5b6a617b 100644 --- a/src/main/asciidoc/jaxrs/jaxrs001.adoc +++ b/src/main/antora/modules/websvcs/pages/jaxrs/jaxrs001.adoc @@ -16,20 +16,20 @@ The following principles encourage RESTful applications to be simple, lightweigh * Resource identification through URI: A RESTful web service exposes a set of resources that identify the targets of the interaction with its clients. Resources are identified by URIs, which provide a global addressing space for resource and service discovery. -See <> for more information. +See xref:jaxrs/jaxrs.adoc#_the_path_annotation_and_uri_path_templates[The @Path Annotation and URI Path Templates] for more information. * Uniform interface: Resources are manipulated using a fixed set of four create, read, update, delete operations: PUT, GET, POST, and DELETE. PUT creates a new resource, which can be then deleted by using DELETE. GET retrieves the current state of a resource in some representation. POST transfers a new state onto a resource. -See <> for more information. +See xref:jaxrs/jaxrs.adoc#_responding_to_http_methods_and_requests[Responding to HTTP Methods and Requests] for more information. * Self-descriptive messages: Resources are decoupled from their representation so that their content can be accessed in a variety of formats, such as HTML, XML, plain text, PDF, JPEG, JSON, and other document formats. Metadata about the resource is available and used, for example, to control caching, detect transmission errors, negotiate the appropriate representation format, and perform authentication or access control. -See <> and <> for more information. +See xref:jaxrs/jaxrs.adoc#_responding_to_http_methods_and_requests[Responding to HTTP Methods and Requests] and xref:jaxrs/jaxrs.adoc#_using_entity_providers_to_map_http_response_and_request_entity_bodies[Using Entity Providers to Map HTTP Response and Request Entity Bodies] for more information. * Stateful interactions through links: Every interaction with a resource is stateless; that is, request messages are self-contained. Stateful interactions are based on the concept of explicit state transfer. Several techniques exist to exchange state, such as URI rewriting, cookies, and hidden form fields. State can be embedded in response messages to point to valid future states of the interaction. -See <> and <> in the Jakarta REST Overview document for more information. +See xref:jaxrs/jaxrs.adoc#_using_entity_providers_to_map_http_response_and_request_entity_bodies[Using Entity Providers to Map HTTP Response and Request Entity Bodies] and xref:jaxrs/jaxrs.adoc#_extracting_request_parameters[Extracting Request Parameters] in the Jakarta REST Overview document for more information. diff --git a/src/main/asciidoc/jaxrs/jaxrs002.adoc b/src/main/antora/modules/websvcs/pages/jaxrs/jaxrs002.adoc similarity index 95% rename from src/main/asciidoc/jaxrs/jaxrs002.adoc rename to src/main/antora/modules/websvcs/pages/jaxrs/jaxrs002.adoc index 50899b41..89c4ca40 100644 --- a/src/main/asciidoc/jaxrs/jaxrs002.adoc +++ b/src/main/antora/modules/websvcs/pages/jaxrs/jaxrs002.adoc @@ -13,10 +13,10 @@ Developers decorate Java programming language class files with Jakarta REST anno Jakarta REST annotations are runtime annotations; therefore, runtime reflection will generate the helper classes and artifacts for the resource. A Jakarta EE application archive containing Jakarta REST resource classes will have the resources configured, the helper classes and artifacts generated, and the resource exposed to clients by deploying the archive to a Jakarta EE server. -<> lists some of the Java programming annotations that are defined by Jakarta REST, with a brief description of how each is used. +<<_summary_of_jakarta_rest_annotations>> lists some of the Java programming annotations that are defined by Jakarta REST, with a brief description of how each is used. Further information on the Jakarta REST APIs can be viewed at https://jakarta.ee/specifications/platform/9/apidocs/[^]. -[[summary-of-jakarta-rest-annotations]] +[[_summary_of_jakarta_rest_annotations]] .Summary of Jakarta REST Annotations [width="99%",cols="10%,90%"] |=== @@ -24,7 +24,7 @@ Further information on the Jakarta REST APIs can be viewed at https://jakarta.ee |`@Path` |The `@Path` annotation's value is a relative URI path indicating where the Java class will be hosted: for example, `/helloworld`. You can also embed variables in the URIs to make a URI path template. -For example, you could ask for the name of a user and pass it to the application as a variable in the URI: `/helloworld/{username}`. +For example, you could ask for the name of a user and pass it to the application as a variable in the URI: `/helloworld/\{username}`. |`@GET` |The `@GET` annotation is a request method designator and corresponds to the similarly named HTTP method. The Java method annotated with this request method designator will process HTTP GET requests. @@ -195,9 +195,9 @@ The Jakarta REST runtime parses URI path templates the same way, whether or not A URI path template has one or more variables, with each variable name surrounded by braces: `{` to begin the variable name and `}` to end it. In the preceding example, `username` is the variable name. -At runtime, a resource configured to respond to the preceding URI path template will attempt to process the URI data that corresponds to the location of `{username}` in the URI as the variable data for `username`. +At runtime, a resource configured to respond to the preceding URI path template will attempt to process the URI data that corresponds to the location of `\{username}` in the URI as the variable data for `username`. -For example, if you want to deploy a resource that responds to the URI path template `\http://example.com/myContextRoot/resources/{name1}/{name2}/`, you must first deploy the application to a Jakarta EE server that responds to requests to the `\http://example.com/myContextRoot` URI and then decorate your resource with the following `@Path` annotation: +For example, if you want to deploy a resource that responds to the URI path template `\http://example.com/myContextRoot/resources/\{name1}/\{name2}/`, you must first deploy the application to a Jakarta EE server that responds to requests to the `\http://example.com/myContextRoot` URI and then decorate your resource with the following `@Path` annotation: [source,java] ---- @@ -224,7 +224,7 @@ For example, spaces in the value of a variable should be substituted with `%20`. When defining URI path templates, be careful that the resulting URI after substitution is valid. -<> lists some examples of URI path template variables and how the URIs are resolved after substitution. +<<_examples_of_uri_path_templates>> lists some examples of URI path template variables and how the URIs are resolved after substitution. The following variable names and values are used in the examples: * `name1`: `james` @@ -240,19 +240,19 @@ The following variable names and values are used in the examples: [NOTE] The value of the `name3` variable is an empty string. -[[examples-of-uri-path-templates]] +[[_examples_of_uri_path_templates]] .Examples of URI Path Templates [width="80%",cols="40%,40%"] |=== |URI Path Template |URI After Substitution -|\http://example.com/{name1}/{name2}/ |\http://example.com/james/gatz/ +|\http://example.com/\{name1}/\{name2}/ |\http://example.com/james/gatz/ -|\http://example.com/{question}/{question}/{question}/ |\http://example.com/why/why/why/ +|\http://example.com/\{question}/\{question}/\{question}/ |\http://example.com/why/why/why/ -|\http://example.com/maps/{location} |\http://example.com/maps/Main%20Street +|\http://example.com/maps/\{location} |\http://example.com/maps/Main%20Street -|\http://example.com/{name3}/home/ |\http://example.com//home/ +|\http://example.com/\{name3}/home/ |\http://example.com//home/ |=== === Responding to HTTP Methods and Requests @@ -296,7 +296,7 @@ For OPTIONS, the `Allow` response header will be set to the set of HTTP methods In addition, the Jakarta REST runtime will return a Web Application Definition Language (WADL) document describing the resource; see https://www.w3.org/Submission/wadl/[^] for more information. Methods decorated with request method designators must return `void`, a Java programming language type, or a `jakarta.ws.rs.core.Response` object. -Multiple parameters may be extracted from the URI by using the `@PathParam` or `@QueryParam` annotations, as described in <>. +Multiple parameters may be extracted from the URI by using the `@PathParam` or `@QueryParam` annotations, as described in <<_extracting_request_parameters>>. Conversion between Java types and an entity body is the responsibility of an entity provider, such as `MessageBodyReader` or `MessageBodyWriter`. Methods that need to provide additional metadata with a response should return an instance of the `Response` class. The `ResponseBuilder` class provides a convenient way to create a `Response` instance using a builder pattern. @@ -321,10 +321,10 @@ For HTTP requests, the `MessageBodyReader` is used to map an HTTP request entity On the response side, a return value is mapped to an HTTP response entity body by using a `MessageBodyWriter`. If the application needs to supply additional metadata, such as HTTP headers or a different status code, a method can return a `Response` that wraps the entity and that can be built by using `Response.ResponseBuilder`. -<> shows the standard types that are supported automatically for HTTP request and response entity bodies. +<<_types_supported_for_http_request_and_response_entity_bodies>> shows the standard types that are supported automatically for HTTP request and response entity bodies. You need to write an entity provider only if you are not choosing one of these standard types. -[[types-supported-for-http-request-and-response-entity-bodies]] +[[_types_supported_for_http_request_and_response_entity_bodies]] .Types Supported for HTTP Request and Response Entity Bodies [width="50%",cols="50%,50%",options="header"] |=== diff --git a/src/main/asciidoc/jaxrs/jaxrs003.adoc b/src/main/antora/modules/websvcs/pages/jaxrs/jaxrs003.adoc similarity index 84% rename from src/main/asciidoc/jaxrs/jaxrs003.adoc rename to src/main/antora/modules/websvcs/pages/jaxrs/jaxrs003.adoc index fa7e8fab..e54e0228 100644 --- a/src/main/asciidoc/jaxrs/jaxrs003.adoc +++ b/src/main/antora/modules/websvcs/pages/jaxrs/jaxrs003.adoc @@ -8,11 +8,11 @@ This section demonstrates the steps that are needed to create, build, deploy, an This section explains how to use NetBeans IDE to create a RESTful web service using a Maven archetype. The archetype generates a skeleton for the application, and you simply need to implement the appropriate method. -You can find a version of this application at `_tut-install_/examples/jaxrs/hello/`. +You can find a version of this application at `_jakartaee-examples_/tutorial/jaxrs/hello/`. ==== To Create a RESTful Web Service Using NetBeans IDE -. Ensure you have installed the tutorial archetypes as described in <>. +. Ensure you have installed the tutorial archetypes as described in xref:intro:usingexamples/usingexamples.adoc#_installing_the_tutorial_archetypes[Installing the Tutorial Archetypes]. . In NetBeans IDE, create a simple web application using the `jaxrs-service-archetype` Maven archetype. This archetype creates a very simple "Hello, World" web application. @@ -56,14 +56,14 @@ http://localhost:8080/HelloWorldApplication/HelloWorldApplication + A browser window opens and displays the return value of `Hello, World!!` -For other sample applications that demonstrate deploying and running Jakarta REST applications using NetBeans IDE, see <> and Your First Cup: An Introduction to the Jakarta EE Platform at https://eclipse-ee4j.github.io/jakartaee-firstcup/toc.html[^]. +For other sample applications that demonstrate deploying and running Jakarta REST applications using NetBeans IDE, see <<_the_rsvp_example_application>> and Your First Cup: An Introduction to the Jakarta EE Platform at https://eclipse-ee4j.github.io/jakartaee-firstcup/toc.html[^]. You may also look at the tutorials on the NetBeans IDE tutorial site, such as the one titled "Getting Started with RESTful Web Services" at https://netbeans.apache.org/kb/docs/websvc/rest.html[^]. This tutorial includes a section on creating a CRUD application from a database. Create, read, update, and delete (CRUD) are the four basic functions of persistent storage and relational databases. === The rsvp Example Application -The `rsvp` example application, located in the `_tut-install_/examples/jaxrs/rsvp/` directory, allows invitees to an event to indicate whether they will attend. +The `rsvp` example application, located in the `_jakartaee-examples_/tutorial/jaxrs/rsvp/` directory, allows invitees to an event to indicate whether they will attend. The events, people invited to the event, and the responses to the invite are stored in Apache Derby using Jakarta Persistence. The Jakarta REST resources in `rsvp` are exposed in a stateless session enterprise bean. @@ -135,7 +135,7 @@ The `rsvp.entity.Event`, `rsvp.entity.Person`, and `rsvp.entity.Response` entiti The `rsvp.util.ResponseEnum` class declares an enumerated type that represents all the possible response statuses an invitee may have. The web application also includes two CDI managed beans, `StatusManager` and `EventManager`, which use the Jakarta REST Client API to call the resources exposed in `StatusBean` and `ResponseBean`. -For information on how the Client API is used in `rsvp`, see <>. +For information on how the Client API is used in `rsvp`, see xref:jaxrs-client/jaxrs-client.adoc#_the_client_api_in_the_rsvp_example_application[The Client API in the rsvp Example Application]. ==== Running the rsvp Example Application @@ -143,16 +143,16 @@ Both NetBeans IDE and Maven can be used to deploy and run the `rsvp` example app ===== To Run the rsvp Example Application Using NetBeans IDE -. If the database server is not already running, start it by following the instructions in <>. +. If the database server is not already running, start it by following the instructions in xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_apache_derby[Starting and Stopping Apache Derby]. -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . From the *File* menu, choose *Open Project*. . In the *Open Project* dialog box, navigate to: + ---- -tut-install/examples/jaxrs +jakartaee-examples/tutorial/jaxrs ---- . Select the `rsvp` folder. @@ -178,14 +178,14 @@ The invitee's new status should now be displayed in the table of invitees and th ===== To Run the rsvp Example Application Using Maven -. If the database server is not already running, start it by following the instructions in <>. +. If the database server is not already running, start it by following the instructions in xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_apache_derby[Starting and Stopping Apache Derby]. -. Make sure that GlassFish Server has been started (see <>). +. Make sure that GlassFish Server has been started (see xref:intro:usingexamples/usingexamples.adoc#_starting_and_stopping_glassfish_server[Starting and Stopping GlassFish Server]). . In a terminal window, go to: + ---- -tut-install/examples/jaxrs/rsvp/ +jakartaee-examples/tutorial/jaxrs/rsvp/ ---- . Enter the following command: diff --git a/src/main/asciidoc/jaxrs/jaxrs004.adoc b/src/main/antora/modules/websvcs/pages/jaxrs/jaxrs004.adoc similarity index 100% rename from src/main/asciidoc/jaxrs/jaxrs004.adoc rename to src/main/antora/modules/websvcs/pages/jaxrs/jaxrs004.adoc diff --git a/src/main/antora/modules/websvcs/pages/xml-websvcs/xml-websvcs.adoc b/src/main/antora/modules/websvcs/pages/xml-websvcs/xml-websvcs.adoc new file mode 100644 index 00000000..0422993c --- /dev/null +++ b/src/main/antora/modules/websvcs/pages/xml-websvcs/xml-websvcs.adoc @@ -0,0 +1,7 @@ += XML Web Services + +You can find information about Jakarta XML Web Services in a previous version of the tutorial: + +* xref:9.1@websvcs:webservices-intro/webservices-intro.adoc[window=_blank]↗ + +* xref:9.1@websvcs:jaxws/jaxws.adoc[window=_blank]↗ diff --git a/src/main/asciidoc/cdi-adv-examples/cdi-adv-examples001.adoc b/src/main/asciidoc/cdi-adv-examples/cdi-adv-examples001.adoc deleted file mode 100644 index 08b867cb..00000000 --- a/src/main/asciidoc/cdi-adv-examples/cdi-adv-examples001.adoc +++ /dev/null @@ -1,10 +0,0 @@ -== Building and Running the CDI Advanced Examples - -The examples are in the `_tut-install_/examples/cdi/` directory. -To build and run the examples, you will do the following. - -. Use NetBeans IDE or the Maven tool to compile, package, and deploy the example. - -. Run the example in a web browser. - -See xref:using-the-tutorial-examples[xrefstyle=full], for basic information on installing, building, and running the examples. diff --git a/src/main/asciidoc/ejb-embedded/ejb-embedded.adoc b/src/main/asciidoc/ejb-embedded/ejb-embedded.adoc deleted file mode 100644 index 7df5413d..00000000 --- a/src/main/asciidoc/ejb-embedded/ejb-embedded.adoc +++ /dev/null @@ -1,9 +0,0 @@ -= Using the Embedded Enterprise Bean Container - -This chapter demonstrates how to use the embedded enterprise bean container to run enterprise bean applications in the Java SE environment, outside of a Jakarta EE server. - -include::ejb-embedded001.adoc[] - -include::ejb-embedded002.adoc[] - -include::ejb-embedded003.adoc[] diff --git a/src/main/asciidoc/ejb-embedded/ejb-embedded001.adoc b/src/main/asciidoc/ejb-embedded/ejb-embedded001.adoc deleted file mode 100644 index 78c65b67..00000000 --- a/src/main/asciidoc/ejb-embedded/ejb-embedded001.adoc +++ /dev/null @@ -1,8 +0,0 @@ -== Overview of the Embedded Enterprise Bean Container - -The embedded enterprise bean container is used to access enterprise bean components from client code executed in a Java SE environment. -The container and the client code are executed within the same virtual machine. -The embedded enterprise bean container is typically used for testing enterprise beans without having to deploy them to a server. - -Most of the services present in the enterprise bean container in a Jakarta EE server are available in the embedded enterprise bean container, including injection, container-managed transactions, and security. -Enterprise bean components execute similarly in both embedded and Jakakarta EE environments, and therefore the same enterprise bean can be easily reused in both standalone and networked applications. diff --git a/src/main/asciidoc/ejb-embedded/ejb-embedded002.adoc b/src/main/asciidoc/ejb-embedded/ejb-embedded002.adoc deleted file mode 100644 index 7e991b39..00000000 --- a/src/main/asciidoc/ejb-embedded/ejb-embedded002.adoc +++ /dev/null @@ -1,132 +0,0 @@ -== Developing Embeddable Enterprise Bean Applications - -All embeddable enterprise bean containers support the features listed in <>. - -[[required-enterprise-bean-features-in-the-embeddable-container]] -.Required Enterprise Bean Features in the Embeddable Container -[width="50%",cols="15%,25%"] -|=== -|Enterprise Bean Feature |Description - -|Local session beans |Local and no-interface view stateless, stateful, and singleton session beans. -All method access is synchronous. -Session beans must not be web service endpoints. - -|Transactions |Container-managed and bean-managed transactions. - -|Security |Declarative and programmatic security. - -|Interceptors |Class-level and method-level interceptors for session beans. - -|Deployment descriptor |The optional `ejb-jar.xml` deployment descriptor, with the same overriding rules for the enterprise bean container in Jakarta EE servers. -|=== - -Container providers are allowed to support the full set of features in enterprise beans, but applications that use the embedded container will not be portable if they use enterprise bean features not listed in <>, such as the timer service, session beans as web service endpoints, or remote business interfaces. - -=== Running Embedded Applications - -The embedded container, the enterprise bean components, and the client all are executed in the same virtual machine using the same classpath. As a result, developers can run an application that uses the embedded container just like a typical Java SE application, as follows: - -[source,shell] ----- -java -classpath mySessionBean.jar:containerProviderRuntime.jar:myClient.jar \ -com.example.ejb.client.Main ----- - -In the above example, `mySessionBean.jar` is an enterprise bean JAR containing a local stateless session bean, `containerProviderRuntime.jar` is a JAR file supplied by the enterprise bean provider that contains the needed runtime classes for the embedded container, and `myClient.jar` is a JAR file containing a Java SE application that calls the business methods in the session bean through the embedded container. - -In GlassFish Server, the runtime JAR that includes the classes for the embedded container is `glassfish-embedded-all.jar`. - -=== Creating the Enterprise Bean Container - -The `jakarta.ejb.embedded.EJBContainer` abstract class represents an instance of the enterprise bean container and includes factory methods for creating a container instance. -The `EJBContainer.createEJBContainer` method is used to create and initialize an embedded container instance. - -The following code snippet shows how to create an embedded container that is initialized with the container provider's default settings: - -[source,java] ----- -EJBContainer ec = EJBContainer.createEJBContainer(); ----- - -By default, the embedded container will search the virtual machine classpath for enterprise bean modules: directories containing a `META-INF/ejb-jar.xml` deployment descriptor, directories containing a class file with one of the enterprise bean component annotations (such as `@Stateless`), or JAR files containing an `ejb-jar.xml` deployment descriptor or class file with an enterprise bean annotation. -Any matching entries are considered enterprise bean modules within the same application. -Once all the valid enterprise bean modules have been found in the classpath, the container will begin initializing the modules. -When the `createEJBContainer` method successfully returns, the client application can obtain references to the client view of any enterprise bean module found by the embedded container. - -An alternate version of the `EJBContainer.createEJBContainer` method takes a `Map` of properties and settings for customizing the embeddable container instance: - -[source,java] ----- -Properties props = new Properties(); -props.setProperty(...); -... -EJBContainer ec = EJBContainer.createEJBContainer(props); ----- - -==== Explicitly Specifying Enterprise Bean Modules to Be Initialized - -Developers can specify exactly which enterprise bean modules the embedded container will initialize. -To explicitly specify the enterprise bean modules initialized by the embedded container, set the `EJBContainer.MODULES` property. - -The modules may be located either in the virtual machine classpath in which the embedded container and client code run, or alternately outside the virtual machine classpath. - -To specify modules in the virtual machine classpath, set `EJBContainer.MODULES` to a `String` to specify a single module name, or a `String` array containing the module names. -The embedded container searches the virtual machine classpath for enterprise bean modules matching the specified names: - -[source,java] ----- -Properties props = new Properties(); -props.setProperty(EJBContainer.MODULES, "mySessionBean"); -EJBContainer ec = EJBContainer.createEJBContainer(props); ----- - -To specify enterprise bean modules outside the virtual machine classpath, set `EJBContainer.MODULES` to a `java.io.File` object or an array of `File` objects. -Each `File` object refers to an enterprise bean JAR file, or a directory containing an expanded enterprise bean JAR file: - -[source,java] ----- -Properties props = new Properties(); -File ejbJarFile = new File(...); -props.setProperty(EJBContainer.MODULES, ejbJarFile); -EJBContainer ec = EJBContainer.createEJBContainer(props); ----- - -=== Looking Up Session Bean References - -To look up session bean references in an application using the embedded container: - -. Use an instance of `EJBContainer` to retrieve a `javax.naming.Context` object. -+ -Call the `EJBContainer.getContext` method to retrieve the `Context` object: -+ -[source,java] ----- -EJBContainer ec = EJBContainer.createEJBContainer(); -Context ctx = ec.getContext(); ----- -+ -References to session beans can then be obtained using the portable JNDI syntax detailed in <>. -For example, to obtain a reference to `MySessionBean`, a local session bean with a no-interface view, use the following code: -+ -[source,java] ----- -MySessionBean msb = (MySessionBean) - ctx.lookup("java:global/mySessionBean/MySessionBean"); ----- - -=== Shutting Down the Enterprise Bean Container - -To shut down the embedded container: - -. From the client, call the `close` method of the instance of `EJBContainer`. -+ -[source,java] ----- -EJBContainer ec = EJBContainer.createEJBContainer(); -... -ec.close(); ----- -+ -While clients are not required to shut down `EJBContainer` instances, doing so frees resources consumed by the embedded container. -This is particularly important when the virtual machine under which the client application is running has a longer lifetime than the client application. diff --git a/src/main/asciidoc/ejb-embedded/ejb-embedded003.adoc b/src/main/asciidoc/ejb-embedded/ejb-embedded003.adoc deleted file mode 100644 index 29a8f2c2..00000000 --- a/src/main/asciidoc/ejb-embedded/ejb-embedded003.adoc +++ /dev/null @@ -1,100 +0,0 @@ -== The standalone Example Application - -The `standalone` example application demonstrates how to create an instance of the embedded enterprise bean container in a JUnit test class and call a session bean business method. - -=== Overview of the standalone Example Application - -Testing the business methods of an enterprise bean in a unit test allows developers to exercise the business logic of an application separately from the other application layers, such as the presentation layer, and without having to deploy the application to a Jakarta EE server. - -The `standalone` example has two main components: `StandaloneBean`, a stateless session bean, and `StandaloneBeanTest`, a JUnit test class that acts as a client to `StandaloneBean` using the embedded container. - -`StandaloneBean` is a simple session bean exposing a local, no-interface view with a single business method, `returnMessage`, which returns "Greetings!" as a `String`: - -[source,java] ----- -@Stateless -public class StandaloneBean { - - private static final String message = "Greetings!"; - - public String returnMessage() { - return message; - } - -} ----- - -`StandaloneBeanTest` calls `StandaloneBean.returnMessage` and tests that the returned message is correct. -First, an embedded container instance and initial context are created within the `setUp` method, which is annotated with `org.junit.Before` to indicate that the method should be executed before the test methods: - -[source,java] ----- -@Before -public void setUp() { - ec = EJBContainer.createEJBContainer(); - ctx = ec.getContext(); -} ----- - -The `testReturnMessage` method, annotated with `org.junit.Test` to indicate that the method includes a unit test, obtains a reference to `StandaloneBean` through the `Context` instance, and calls `StandaloneBean.returnMessage`. -The result is compared with the expected result using a JUnit assertion, `assertEquals`. -If the string returned from `StandaloneBean.returnMessage` is equal to "Greetings!" the test passes: - -[source,java] ----- -@Test -public void testReturnMessage() throws Exception { - logger.info("Testing standalone.ejb.StandaloneBean.returnMessage()"); - StandaloneBean instance = (StandaloneBean) - ctx.lookup("java:global/classes/StandaloneBean"); - String expResult = "Greetings!"; - String result = instance.returnMessage(); - assertEquals(expResult, result); -} ----- - -Finally, the `tearDown` method, annotated with `org.junit.After` to indicate that the method should be executed after all the unit tests have run, closes the embedded container instance: - -[source,java] ----- -@After -public void tearDown() { - if (ec != null) { - ec.close(); - } -} ----- - -=== To Run the standalone Example Application Using NetBeans IDE - -. From the *File* menu, choose *Open Project*. - -. In the *Open Project* dialog box, navigate to: -+ ----- -tut-install/examples/ejb ----- - -. Select the `standalone` folder and click *Open Project*. - -. In the *Projects* tab, right-click `standalone` and select *Test*. -+ -This will execute the JUnit test class `StandaloneBeanTest`. -The Output tab shows the progress of the test and the output log. - -=== To Run the standalone Example Application Using Maven - -. In a terminal window, go to: -+ ----- -tut-install/examples/ejb/standalone/ ----- - -. Enter the following command: -+ -[source,shell] ----- -mvn install ----- -+ -This command compiles and packages the application into an JAR file, and executes the JUnit test class `StandaloneBeanTest`. diff --git a/src/main/asciidoc/ejb-gettingstarted/ejb-gettingstarted001.adoc b/src/main/asciidoc/ejb-gettingstarted/ejb-gettingstarted001.adoc deleted file mode 100644 index 965f0ec0..00000000 --- a/src/main/asciidoc/ejb-gettingstarted/ejb-gettingstarted001.adoc +++ /dev/null @@ -1,19 +0,0 @@ -== Starting With Enterprise Beans - -Here's an overview of the steps you'll follow: - -. Create the enterprise bean: `ConverterBean`. - -. Create the web client. - -. Deploy `converter` onto the server. - -. Using a browser, run the web client. - -Before proceeding, make sure that you've done the following: - -* Read xref:overview[xrefstyle=full] - -* Become familiar with enterprise beans (see xref:enterprise-beans[xrefstyle=full]) - -* Started the server (see <>) diff --git a/src/main/asciidoc/faces-advanced-cc/faces-advanced-cc002.adoc b/src/main/asciidoc/faces-advanced-cc/faces-advanced-cc002.adoc deleted file mode 100644 index c0c966e2..00000000 --- a/src/main/asciidoc/faces-advanced-cc/faces-advanced-cc002.adoc +++ /dev/null @@ -1,11 +0,0 @@ -== Invoking a Managed Bean - -To enable a composite component to handle server-side data - -. Invoke a managed bean in one of the following ways: - -* Pass the reference of the managed bean to the composite component. - -* Directly use the properties of the managed bean. -+ -The example application described in <> shows how to use a managed bean with a composite component by passing the reference of the managed bean to the component. diff --git a/src/main/asciidoc/images/jakartaeett_dt_001.svg b/src/main/asciidoc/images/jakartaeett_dt_001.svg deleted file mode 100644 index 3a30a62f..00000000 --- a/src/main/asciidoc/images/jakartaeett_dt_001.svg +++ /dev/null @@ -1,665 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - Pagina 1 - - - - Foglio.131 - - - - Foglio.1 - - - - Foglio.2 - - - - Foglio.3 - - - - Foglio.4 - - - - Foglio.5 - - - - Foglio.6 - Client Tier - - - - ClientTier - - Foglio.7 - Client Machine - - - - ClientMachine - - Foglio.8 - - - - Foglio.9 - - - - Foglio.10 - Database Server - - - - DatabaseServer - - Foglio.11 - Jakarta EE Application 1 - - - - Jakarta EE Application 1 - - Foglio.12 - Jakarta EE Application 2 - - - - Jakarta EE Application 2 - - Foglio.13 - Application Client - - - - ApplicationClient - - Foglio.14 - - - - Foglio.15 - - - - Foglio.16 - - - - Foglio.17 - - - - Foglio.18 - - - - Foglio.19 - - - - Foglio.20 - - - - Foglio.21 - - - - Foglio.22 - - - - Foglio.23 - - - - Foglio.24 - - - - Foglio.25 - - - - Foglio.26 - - - - Foglio.27 - - - - Foglio.28 - - - - Foglio.29 - - - - Foglio.30 - - - - Foglio.31 - - - - Foglio.32 - - - - Foglio.33 - - - - Foglio.34 - - - - Foglio.35 - - - - Foglio.36 - - - - Foglio.37 - - - - Foglio.38 - - - - Foglio.39 - - - - Foglio.40 - - - - Foglio.41 - - - - Foglio.42 - - - - Foglio.43 - - - - Foglio.44 - - - - Foglio.45 - - - - Foglio.46 - - - - Foglio.47 - - - - Foglio.48 - - - - Foglio.49 - - - - Foglio.50 - - - - Foglio.51 - - - - Foglio.52 - - - - Foglio.53 - - - - Foglio.54 - - - - Foglio.55 - - - - Foglio.56 - - - - Foglio.57 - - - - Foglio.58 - - - - Foglio.59 - - - - Foglio.60 - - - - Foglio.61 - - - - Foglio.62 - - - - Foglio.63 - - - - Foglio.64 - - - - Foglio.65 - - - - Foglio.66 - - - - Foglio.67 - - - - Foglio.68 - - - - Foglio.69 - - - - Foglio.70 - - - - Foglio.71 - - - - Foglio.72 - - - - Foglio.73 - - - - Foglio.74 - - - - Foglio.75 - - - - Foglio.76 - - - - Foglio.77 - - - - Foglio.78 - Web Pages - - - - WebPages - - Foglio.79 - - - - Foglio.80 - - - - Foglio.81 - - - - Foglio.82 - Jakarta EE Server - - - - Jakarta EEServer - - Foglio.83 - - - - Foglio.84 - Jakarta Server Pages Faces - - - - Jakarta ServerPagesFaces - - Foglio.85 - Web Tier - - - - WebTier - - Foglio.86 - - - - Foglio.87 - - - - Foglio.88 - - - - Foglio.89 - - - - Foglio.90 - - - - Foglio.91 - - - - Foglio.92 - - - - Foglio.93 - - - - Foglio.94 - - - - Foglio.95 - - - - Foglio.96 - - - - Foglio.97 - - - - Foglio.98 - Enterprise Beans - - - - EnterpriseBeans - - Foglio.99 - - - - Foglio.100 - - - - Foglio.101 - - - - Foglio.102 - - - - Foglio.103 - - - - Foglio.104 - Enterprise Beans - - - - EnterpriseBeans - - Foglio.105 - - - - Foglio.106 - - - - Foglio.107 - - - - Foglio.108 - - - - Foglio.109 - Business Tier - - - - BusinessTier - - Foglio.110 - - - - Foglio.111 - - - - Foglio.112 - EIS Tier - - - - EISTier - - Foglio.119 - Database - - - - Database - - Foglio.126 - Database - - - - Database - - Foglio.127 - - - - Foglio.128 - - - - Foglio.129 - - - - Foglio.130 - - - - Database, mini 3 - blue.114 - - Foglio.133 - - Foglio.134 - - - - Foglio.135 - - - - Foglio.136 - - - - Foglio.137 - - - - Foglio.138 - - - - - - Database, mini 3 - blue.113 - - Foglio.114 - - Foglio.115 - - - - Foglio.116 - - - - Foglio.117 - - - - Foglio.118 - - - - Foglio.120 - - - - - - diff --git a/src/main/asciidoc/images/jakartaeett_dt_002.svg b/src/main/asciidoc/images/jakartaeett_dt_002.svg deleted file mode 100644 index 994e93e7..00000000 --- a/src/main/asciidoc/images/jakartaeett_dt_002.svg +++ /dev/null @@ -1,1059 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Pagina 1 - - - Foglio.129 - - - - Foglio.1 - - - - Foglio.2 - - - - Foglio.3 - - - - Foglio.4 - - - - Foglio.5 - - - - Foglio.6 - Client Tier - - - - ClientTier - - Foglio.7 - Client Machine - - - - ClientMachine - - Foglio.8 - - - - Foglio.9 - - - - Foglio.10 - - - - Foglio.11 - Jakarta EE Server - - - - Jakarta EEServer - - Foglio.12 - Web Tier - - - - WebTier - - Foglio.13 - Business Tier - - - - BusinessTier - - Foglio.14 - - - - Foglio.15 - - - - Foglio.16 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - PC.118 - - Foglio.20 - - - - Foglio.21 - - - - Foglio.22 - - - - Foglio.23 - ` - - - - ` - - Foglio.24 - - - - Foglio.25 - - - - Foglio.26 - - - - Foglio.27 - - - - Foglio.28 - - - - Foglio.29 - - - - Foglio.30 - - - - Foglio.31 - - Foglio.32 - - - - Foglio.33 - - - - - Foglio.34 - - - - Foglio.35 - - - - - - - - - - - - - - Foglio.36 - - - - Foglio.37 - - - - Foglio.38 - - Foglio.39 - - - - Foglio.40 - - - - - - - - Foglio.41 - - - - - Foglio.42 - - - - Foglio.43 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Server.552 - - Foglio.45 - - - - Foglio.46 - - - - - Foglio.47 - - - - - Foglio.48 - - - - Foglio.49 - - - - Foglio.50 - - - - Foglio.51 - - - - - - Foglio.52 - - Foglio.53 - - - - Foglio.54 - - - - Foglio.55 - - - - Foglio.56 - - - - Foglio.57 - - - - Foglio.58 - - - - - - Foglio.59 - - - - - - - - - - - - - - - - - - - - - - Foglio.128 - - - - Foglio.60 - - - - Foglio.61 - - - - Foglio.62 - - - - Foglio.63 - - - - Foglio.64 - - - - Foglio.65 - - - - - - - - - - - - - - - - - - - - - - Foglio.18 - Web Browser, Web Pages, Applets, and Optional JavaBeans Compo... - - - - Web Browser, Web Pages, Applets, and Optional JavaBeans Components - - Foglio.17 - Application Client and Optional JavaBeans Components - - - - Application Client and Optional JavaBeans Components - - diff --git a/src/main/asciidoc/images/jakartaeett_dt_003.svg b/src/main/asciidoc/images/jakartaeett_dt_003.svg deleted file mode 100644 index 1fe885e4..00000000 --- a/src/main/asciidoc/images/jakartaeett_dt_003.svg +++ /dev/null @@ -1,1472 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Pagina 1 - - - Foglio.194 - - - - Foglio.1 - - - - Foglio.2 - - - - Foglio.3 - - - - Foglio.4 - - - - Foglio.5 - - - - Foglio.6 - Client Tier - - - - ClientTier - - Foglio.7 - Client Machine - - - - ClientMachine - - Foglio.8 - - - - Foglio.9 - - - - Foglio.10 - - - - Foglio.11 - Jakarta EE Server - - - - Jakarta EEServer - - Foglio.12 - Web Tier - - - - WebTier - - Foglio.13 - Business Tier - - - - BusinessTier - - Foglio.14 - - - - Foglio.15 - - - - Foglio.16 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - PC.118 - - Foglio.20 - - - - Foglio.21 - - - - Foglio.22 - - - - Foglio.23 - ` - - - - ` - - Foglio.24 - - - - Foglio.25 - - - - Foglio.26 - - - - Foglio.27 - - - - Foglio.28 - - - - Foglio.29 - - - - Foglio.30 - - - - Foglio.31 - - Foglio.32 - - - - Foglio.33 - - - - - Foglio.34 - - - - Foglio.35 - - - - - - - - - - - - - - Foglio.36 - - - - Foglio.37 - - - - Foglio.38 - - Foglio.39 - - - - Foglio.40 - - - - - - - - Foglio.41 - - - - - Foglio.42 - - - - Foglio.43 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Server.552 - - Foglio.45 - - - - Foglio.46 - - - - - Foglio.47 - - - - - Foglio.48 - - - - Foglio.49 - - - - Foglio.50 - - - - Foglio.51 - - - - - - Foglio.52 - - Foglio.53 - - - - Foglio.54 - - - - Foglio.55 - - - - Foglio.56 - - - - Foglio.57 - - - - Foglio.58 - - - - - - Foglio.59 - - - - - - - - - - - - - - - - - - - - - - Foglio.128 - - - - Foglio.60 - - - - Foglio.61 - - - - Foglio.62 - - - - Foglio.63 - - - - Foglio.64 - - - - Foglio.65 - - - - - - - - - - - - - - - - - - - - - - Foglio.18 - Web Browser, Web Pages, Applets, and Optional JavaBeans Compo... - - - - Web Browser, Web Pages, Applets, and Optional JavaBeans Components - - Foglio.17 - Application Client and Optional JavaBeans Components - - - - Application Client and Optional JavaBeans Components - - Foglio.180 - - - - Foglio.181 - JavaBeans Components (Optional) - - - - JavaBeans Components (Optional) - - Foglio.182 - - - - Foglio.183 - - - - Foglio.184 - - - - Foglio.185 - - - - Foglio.187 - - - - Foglio.188 - Web Pages, Servlets - - - - Web Pages, Servlets - - Foglio.189 - - - - Foglio.190 - - - - Foglio.191 - - - - Foglio.192 - - - - Foglio.193 - - - - - - - - - - - - - - - - - - - - - - Foglio.129 - - - - Foglio.130 - - - - Foglio.131 - - - - Foglio.132 - - - - Foglio.133 - - - - Foglio.134 - - - - Foglio.135 - - - - Foglio.136 - - - - Foglio.137 - - - - Foglio.138 - - - - Foglio.139 - - - - Foglio.140 - - - - Foglio.141 - - - - Foglio.142 - - - - Foglio.143 - - - - Foglio.144 - - - - Foglio.145 - - - - Foglio.146 - - - - Foglio.147 - - - - Foglio.148 - - - - Foglio.149 - - - - Foglio.150 - - - - Foglio.151 - - - - Foglio.152 - - - - Foglio.153 - - - - Foglio.155 - - - - Foglio.156 - - - - Foglio.157 - - - - Foglio.158 - - - - Foglio.159 - - - - Foglio.160 - - - - Foglio.161 - - - - Foglio.162 - - - - Foglio.163 - - - - Foglio.164 - - - - Foglio.165 - - - - Foglio.166 - - - - Foglio.167 - - - - Foglio.168 - - - - Foglio.169 - - - - Foglio.170 - - - - Foglio.171 - - - - Foglio.172 - - - - Foglio.173 - - - - Foglio.174 - - - - Foglio.175 - - - - Foglio.176 - - - - Foglio.177 - - - - Foglio.178 - - - - Foglio.179 - - - - Foglio.154 - - - - Foglio.186 - - - - diff --git a/src/main/asciidoc/images/jakartaeett_dt_004.svg b/src/main/asciidoc/images/jakartaeett_dt_004.svg deleted file mode 100644 index d8913f4c..00000000 --- a/src/main/asciidoc/images/jakartaeett_dt_004.svg +++ /dev/null @@ -1,1584 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Pagina 1 - - - - Foglio.221 - - - - Foglio.1 - - - - Foglio.2 - - - - Foglio.3 - - - - Foglio.4 - - - - Foglio.5 - - - - Foglio.6 - Client Tier - - - - ClientTier - - Foglio.7 - Client Machine - - - - ClientMachine - - Foglio.8 - - - - Foglio.9 - - - - Foglio.10 - - - - Foglio.11 - Jakarta EE Server - - - - Jakarta EEServer - - Foglio.12 - Web Tier - - - - WebTier - - Foglio.13 - Business Tier - - - - BusinessTier - - Foglio.14 - - - - Foglio.15 - - - - Foglio.16 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - PC.118 - - Foglio.20 - - - - Foglio.21 - - - - Foglio.22 - - - - Foglio.23 - ` - - - - ` - - Foglio.24 - - - - Foglio.25 - - - - Foglio.26 - - - - Foglio.27 - - - - Foglio.28 - - - - Foglio.29 - - - - Foglio.30 - - - - Foglio.31 - - Foglio.32 - - - - Foglio.33 - - - - - Foglio.34 - - - - Foglio.35 - - - - - - - - - - - - - - Foglio.36 - - - - Foglio.37 - - - - Foglio.38 - - Foglio.39 - - - - Foglio.40 - - - - - - - - Foglio.41 - - - - - Foglio.42 - - - - Foglio.43 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Server.552 - - Foglio.45 - - - - Foglio.46 - - - - - Foglio.47 - - - - - Foglio.48 - - - - Foglio.49 - - - - Foglio.50 - - - - Foglio.51 - - - - - - Foglio.52 - - Foglio.53 - - - - Foglio.54 - - - - Foglio.55 - - - - Foglio.56 - - - - Foglio.57 - - - - Foglio.58 - - - - - - Foglio.59 - - - - - - - - - - - - - - - - - - - - - - Foglio.128 - - - - Foglio.60 - - - - Foglio.61 - - - - Foglio.62 - - - - Foglio.63 - - - - Foglio.64 - - - - Foglio.65 - - - - - - - - - - - - - - - - - - - - - - Foglio.18 - Web Browser, Web Pages, Applets, and Optional JavaBeans Compo... - - - - Web Browser, Web Pages, Applets, and Optional JavaBeans Components - - Foglio.17 - Application Client and Optional JavaBeans Components - - - - Application Client and Optional JavaBeans Components - - Foglio.180 - - - - Foglio.181 - JavaBeans Components (Optional) - - - - JavaBeans Components (Optional) - - Foglio.182 - - - - Foglio.183 - - - - Foglio.184 - - - - Foglio.185 - - - - Foglio.187 - - - - Foglio.188 - Web Pages, Servlets - - - - Web Pages, Servlets - - Foglio.189 - - - - Foglio.190 - - - - Foglio.191 - - - - Foglio.192 - - - - Foglio.193 - - - - - - - - - - - - - - - - - - - - - - Foglio.129 - - - - Foglio.130 - - - - Foglio.131 - - - - Foglio.132 - - - - Foglio.133 - - - - Foglio.134 - - - - Foglio.135 - - - - Foglio.136 - - - - Foglio.137 - - - - Foglio.138 - - - - Foglio.139 - - - - Foglio.140 - - - - Foglio.141 - - - - Foglio.142 - - - - Foglio.143 - - - - Foglio.144 - - - - Foglio.145 - - - - Foglio.146 - - - - Foglio.147 - - - - Foglio.148 - - - - Foglio.149 - - - - Foglio.150 - - - - Foglio.151 - - - - Foglio.152 - - - - Foglio.153 - - - - Foglio.155 - - - - Foglio.156 - - - - Foglio.157 - - - - Foglio.158 - - - - Foglio.159 - - - - Foglio.160 - - - - Foglio.161 - - - - Foglio.162 - - - - Foglio.163 - - - - Foglio.164 - - - - Foglio.165 - - - - Foglio.166 - - - - Foglio.167 - - - - Foglio.168 - - - - Foglio.169 - - - - Foglio.170 - - - - Foglio.171 - - - - Foglio.172 - - - - Foglio.173 - - - - Foglio.174 - - - - Foglio.175 - - - - Foglio.176 - - - - Foglio.177 - - - - Foglio.178 - - - - Foglio.179 - - - - Foglio.194 - - - - Foglio.195 - - - - Foglio.196 - Database Server - - - - DatabaseServer - - Foglio.197 - EIS Tier - - - - EISTier - - Foglio.211 - Database and Legacy Systems - - - - Database and Legacy Systems - - Foglio.212 - - - - Foglio.213 - Jakarta Persistence Entities, Session Beans, Message-Driven B... - - - - Jakarta Persistence Entities, Session Beans, Message-Driven Beans - - Foglio.214 - - - - Foglio.215 - - - - Foglio.216 - - - - Foglio.217 - - - - Foglio.218 - - - - Foglio.219 - - - - Foglio.220 - - - - Database, mini 3 - blue - - Foglio.223 - - Foglio.224 - - - - Foglio.225 - - - - Foglio.226 - - - - Foglio.227 - - - - Foglio.228 - - - - - - Foglio.229 - - - - Foglio.154 - - - - diff --git a/src/main/asciidoc/images/jakartaeett_dt_005.svg b/src/main/asciidoc/images/jakartaeett_dt_005.svg deleted file mode 100644 index 6d5b4489..00000000 --- a/src/main/asciidoc/images/jakartaeett_dt_005.svg +++ /dev/null @@ -1,1364 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Pagina 1 - - - - Foglio.468 - - - - Foglio.229 - - - - Foglio.230 - - - - Foglio.234 - - - - Foglio.235 - - - - Foglio.238 - - - - Foglio.314 - Client Machine - - - - ClientMachine - - Foglio.315 - - - - Foglio.316 - - - - Foglio.317 - - - - Foglio.318 - Jakarta EE Server - - - - Jakarta EEServer - - Foglio.319 - Web Container - - - - WebContainer - - Foglio.320 - EJB Container - - - - EJBContainer - - Foglio.321 - - - - Foglio.322 - - - - Foglio.323 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - PC.118 - - Foglio.325 - - - - Foglio.326 - - - - Foglio.327 - - - - Foglio.328 - ` - - - - ` - - Foglio.329 - - - - Foglio.330 - - - - Foglio.331 - - - - Foglio.332 - - - - Foglio.333 - - - - Foglio.334 - - - - Foglio.335 - - - - Foglio.336 - - Foglio.362 - - - - Foglio.363 - - - - - Foglio.364 - - - - Foglio.365 - - - - - - - - - - - - - - Foglio.366 - - - - Foglio.367 - - - - Foglio.368 - - Foglio.369 - - - - Foglio.370 - - - - - - - - Foglio.371 - - - - - Foglio.372 - - - - Foglio.373 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Server.552 - - Foglio.375 - - - - Foglio.376 - - - - - Foglio.377 - - - - - Foglio.378 - - - - Foglio.379 - - - - Foglio.380 - - - - Foglio.381 - - - - - - Foglio.382 - - Foglio.383 - - - - Foglio.384 - - - - Foglio.385 - - - - Foglio.386 - - - - Foglio.387 - - - - Foglio.388 - - - - - - Foglio.390 - - - - Foglio.393 - - - - Foglio.395 - - - - Foglio.399 - - - - Foglio.405 - - - - Foglio.406 - Web Page - - - - Web Page - - Foglio.436 - - - - Foglio.438 - - - - Foglio.439 - - - - Foglio.440 - - - - Foglio.441 - - - - Foglio.442 - - - - Foglio.443 - - - - Foglio.444 - - - - Foglio.445 - - - - Foglio.446 - - - - Foglio.447 - - - - Foglio.448 - - - - Foglio.449 - - - - Foglio.450 - - - - Foglio.451 - - - - Foglio.452 - - - - Foglio.453 - - - - Foglio.454 - - - - Foglio.455 - - - - Foglio.456 - - - - Foglio.457 - - - - Foglio.458 - - - - Foglio.459 - - - - Foglio.460 - - - - Foglio.473 - Database - - - - Database - - Foglio.480 - - - - Foglio.481 - - - - Foglio.482 - - - - Foglio.167 - Application Client - - - - Application Client - - Foglio.174 - Application Client Container - - - - Application Client Container - - Foglio.249 - - - - Foglio.250 - - - - Foglio.251 - - - - Foglio.252 - - - - Foglio.253 - - - - Foglio.254 - - - - Foglio.255 - - - - Foglio.256 - - - - Foglio.257 - - - - Foglio.258 - - - - Foglio.259 - - - - Foglio.260 - - - - Foglio.261 - - - - Foglio.175 - Web Browser - - - - Web Browser - - Foglio.282 - - - - Foglio.284 - - - - Foglio.285 - - - - Foglio.286 - - - - Foglio.287 - - - - Foglio.288 - - - - Foglio.289 - - - - Foglio.290 - - - - Foglio.291 - - - - Foglio.292 - - - - Foglio.293 - - - - Foglio.294 - - - - Foglio.295 - - - - Foglio.296 - - - - Foglio.297 - - - - Foglio.298 - - - - Foglio.299 - - - - Foglio.300 - - - - Foglio.301 - - - - Foglio.302 - - - - Foglio.303 - - - - Foglio.304 - - - - Foglio.305 - - - - Foglio.306 - - - - Foglio.216 - - - - Foglio.223 - - - - Foglio.411 - - - - Foglio.437 - - - - Foglio.219 - Servlet - - - - Servlet - - Foglio.221 - - - - - - - - - - - - - - - - - - - - - - Foglio.165 - - - - Foglio.168 - Enterprise Bean - - - - Enterprise Bean - - Foglio.224 - - - - Foglio.225 - - - - Foglio.227 - - - - Foglio.228 - Enterprise Bean - - - - Enterprise Bean - - Foglio.231 - - - - Foglio.232 - - - - Foglio.233 - - - - Foglio.392 - - - - Foglio.394 - - - - Database, mini 3 - blue - - Foglio.462 - - Foglio.463 - - - - Foglio.464 - - - - Foglio.465 - - - - Foglio.466 - - - - Foglio.467 - - - - - - diff --git a/src/main/asciidoc/images/jakartaeett_dt_006.svg b/src/main/asciidoc/images/jakartaeett_dt_006.svg deleted file mode 100644 index 113edf8a..00000000 --- a/src/main/asciidoc/images/jakartaeett_dt_006.svg +++ /dev/null @@ -1,253 +0,0 @@ - - - - - - - - - - - - - - - - Pagina 1 - - - - Foglio.112 - - - - Foglio.114 - - - - Foglio.116 - - - - Foglio.118 - Client System - - - - Client System - - Foglio.126 - Browser - - - - Browser - - Database, mini 3 - blue - - Foglio.127 - - Foglio.128 - - - - Foglio.129 - - - - Foglio.130 - - - - Foglio.131 - - - - Foglio.132 - - - - - - Foglio.138 - Database - - - - Database - - Foglio.139 - - - - Foglio.125 - Application Client Container - - - - Application Client Container - - Foglio.140 - - - - Foglio.119 - Application Client - - - - Application Client - - Foglio.115 - - - - Foglio.141 - - - - Foglio.142 - Jakarta EE Server - - - - Jakarta EE Server - - Foglio.143 - Web Container - - - - Web Container - - Foglio.144 - - - - Foglio.145 - EJB Container - - - - EJB Container - - Foglio.146 - - - - Foglio.147 - EJB - - - - EJB - - Foglio.148 - - - - Foglio.149 - Jakarta Server Faces - - - - Jakarta Server Faces - - Foglio.150 - - - - Foglio.151 - Servlet - - - - Servlet - - Foglio.152 - - - - Foglio.153 - EJB - - - - EJB - - Foglio.154 - - - - Foglio.155 - - - - Foglio.156 - - - - Foglio.133 - - - - Foglio.134 - - - - Foglio.135 - - - - Foglio.136 - - - - Foglio.137 - - - - Foglio.157 - - - - Foglio.158 - - - - Foglio.159 - - - - Foglio.160 - - - - Foglio.161 - - - - diff --git a/src/main/asciidoc/images/jakartaeett_dt_007.svg b/src/main/asciidoc/images/jakartaeett_dt_007.svg deleted file mode 100644 index 5f6e489a..00000000 --- a/src/main/asciidoc/images/jakartaeett_dt_007.svg +++ /dev/null @@ -1,560 +0,0 @@ - - - - - - - - - - - - - - - - Pagina 1 - - - Foglio.7 - - - - Foglio.289 - - - - Foglio.290 - - - - Foglio.291 - - - - Foglio.292 - Java SE - - - - Java SE - - Foglio.293 - Web Container - - - - Web Container - - Foglio.295 - - - - Foglio.294 - WebSocket - - - - WebSocket - - Foglio.296 - - - - Foglio.297 - Concurrency Utilities - - - - Concurrency Utilities - - Foglio.298 - - - - Foglio.299 - Batch - - - - Batch - - Foglio.301 - - - - Foglio.302 - JSON-P - - - - JSON-P - - Foglio.300 - - - - Foglio.303 - Bean Validation - - - - Bean Validation - - Foglio.304 - - - - Foglio.305 - EJB Lite - - - - EJB Lite - - Foglio.306 - - - - Foglio.307 - EL - - - - EL - - Foglio.308 - - - - Foglio.309 - Jakarta Mail - - - - Jakarta Mail - - Foglio.310 - - - - Foglio.311 - JSP - - - - JSP - - Foglio.312 - - - - Foglio.313 - Connectors - - - - Connectors - - Foglio.314 - - - - Foglio.315 - Jakarta Persistence - - - - Jakarta Persistence - - Foglio.316 - - - - Foglio.317 - JMS - - - - JMS - - Foglio.318 - - - - Foglio.319 - Management - - - - Management - - Foglio.320 - - - - Foglio.321 - WS Metadata - - - - WS Metadata - - Foglio.322 - - - - Foglio.323 - Web Services - - - - Web Services - - Foglio.324 - - - - Foglio.325 - JACC - - - - JACC - - Foglio.326 - - - - Foglio.327 - JASPIC - - - - JASPIC - - Foglio.328 - - - - Foglio.329 - JAX-RS - - - - JAX-RS - - Foglio.330 - - - - Foglio.331 - JAX-WS - - - - JAX-WS - - Foglio.332 - - - - Foglio.333 - JSTL - - - - JSTL - - Foglio.336 - - - - Foglio.337 - Servlet - - - - Servlet - - Foglio.338 - - - - - - - - - - - - - - - - - - - - - - Foglio.339 - - - - Foglio.340 - Jakarta Server Faces - - - - Jakarta Server Faces - - Foglio.341 - - - - Foglio.342 - New in Jakarta EE - - - - New in Jakarta EE - - Foglio.1 - - - - Foglio.2 - JTA - - - - JTA - - Foglio.3 - - - - Foglio.4 - CDI - - - - CDI - - Foglio.5 - - - - Foglio.6 - Dependency Injection - - - - Dependency Injection - - diff --git a/src/main/asciidoc/images/jakartaeett_dt_008.svg b/src/main/asciidoc/images/jakartaeett_dt_008.svg deleted file mode 100644 index a00ef13a..00000000 --- a/src/main/asciidoc/images/jakartaeett_dt_008.svg +++ /dev/null @@ -1,279 +0,0 @@ - - - - - - - - - - - - - - - - Pagina 1 - - - Foglio.1 - - - - Foglio.2 - - - - Foglio.3 - - - - Foglio.5 - Java SE - - - - Java SE - - Foglio.9 - - - - Foglio.10 - Concurrency Utilities - - - - Concurrency Utilities - - Foglio.11 - - - - Foglio.12 - Batch - - - - Batch - - Foglio.13 - - - - Foglio.14 - JSON-P - - - - JSON-P - - Foglio.15 - - - - Foglio.16 - Bean Validation - - - - Bean Validation - - Foglio.21 - - - - Foglio.22 - Jakarta Mail - - - - Jakarta Mail - - Foglio.25 - - - - Foglio.26 - Connectors - - - - Connectors - - Foglio.27 - - - - Foglio.28 - Jakarta Persistence - - - - Jakarta Persistence - - Foglio.29 - - - - Foglio.30 - JMS - - - - JMS - - Foglio.31 - - - - Foglio.32 - Management - - - - Management - - Foglio.33 - - - - Foglio.34 - WS Metadata - - - - WS Metadata - - Foglio.35 - - - - Foglio.36 - Web Services - - - - Web Services - - Foglio.37 - - - - Foglio.38 - JACC - - - - JACC - - Foglio.39 - - - - Foglio.40 - JASPIC - - - - JASPIC - - Foglio.41 - - - - Foglio.42 - JAX-RS - - - - JAX-RS - - Foglio.43 - - - - Foglio.44 - JAX-WS - - - - JAX-WS - - Foglio.52 - - - - Foglio.53 - New in Jakarta EE - - - - New in Jakarta EE - - Foglio.54 - - - - Foglio.55 - JTA - - - - JTA - - Foglio.56 - - - - Foglio.57 - CDI - - - - CDI - - Foglio.58 - - - - Foglio.59 - Dependency Injection - - - - Dependency Injection - - Foglio.365 - EJB Container - - - - EJB Container - - Foglio.421 - - - - Foglio.422 - EJB - - - - EJB - - diff --git a/src/main/asciidoc/images/jakartaeett_dt_009.svg b/src/main/asciidoc/images/jakartaeett_dt_009.svg deleted file mode 100644 index 219fd8b9..00000000 --- a/src/main/asciidoc/images/jakartaeett_dt_009.svg +++ /dev/null @@ -1,203 +0,0 @@ - - - - - - - - - - - - - - - - Pagina 1 - - - Foglio.398 - - - - Foglio.11 - - - - Foglio.354 - WS Metadata - - - - WS Metadata - - Foglio.345 - - - - Foglio.348 - Application Client Container - - - - Application Client Container - - Foglio.349 - - - - Foglio.350 - Jakarta Persistence - - - - Jakarta Persistence - - Foglio.351 - - - - Foglio.352 - Management - - - - Management - - Foglio.355 - - - - Foglio.357 - - - - Foglio.359 - - - - Foglio.360 - JMS - - - - JMS - - Foglio.385 - - - - Foglio.386 - JAX-WS - - - - JAX-WS - - Foglio.394 - - - - Foglio.395 - Application Client - - - - Application Client - - Foglio.396 - - - - Foglio.397 - New in Jakarta EE - - - - New in Jakarta EE - - Foglio.1 - - - - Foglio.2 - Java SE - - - - Java SE - - Foglio.3 - - - - Foglio.4 - Bean Validation - - - - Bean Validation - - Foglio.5 - - - - Foglio.6 - Jakarta Mail - - - - Jakarta Mail - - Foglio.7 - - - - Foglio.8 - CDI - - - - CDI - - Foglio.9 - - - - Foglio.10 - Dependency Injection - - - - Dependency Injection - - Foglio.12 - Web Services - - - - Web Services - - Foglio.13 - JSON-P - - - - JSON-P - - diff --git a/src/main/asciidoc/index.adoc b/src/main/asciidoc/index.adoc deleted file mode 100644 index cf4853b4..00000000 --- a/src/main/asciidoc/index.adoc +++ /dev/null @@ -1,49 +0,0 @@ -= The Jakarta(R) EE Tutorial -:authors: Jakarta Platform Team, https://projects.eclipse.org/projects/ee4j.jakartaee-platform -:email: https://accounts.eclipse.org/mailing-list/jakartaee-platform-dev -:revnumber: Release 9.1 -:revdate: December 2021 -:revremark: Final -:version-label!: -:doctype: book -:license: Eclipse Public License v. 2.0 -:source-highlighter: coderay -:toc: left -:toclevels: 2 -:sectnumlevels: 1 -:sectnums: -:partnums: -:part-signifier: Part -:chapter-signifier: Chapter -:autoxref-chapter: 1 -:autoxref-chaptersectlevel: 1 -:autoxref-imagecaption: Figure %d-%d -:autoxref-tablecaption: Table %d-%d - -include::title.adoc[] - -include::preface.adoc[] - -include::partintro.adoc[] - -include::partplatform.adoc[] - -include::partwebtier.adoc[] - -include::partbeanvalidation.adoc[] - -include::partcdi.adoc[] - -include::partwebsvcs.adoc[] - -include::partentbeans.adoc[] - -include::partpersist.adoc[] - -include::partmessaging.adoc[] - -include::partsecurity.adoc[] - -include::partsupporttechs.adoc[] - -include::partcasestudies.adoc[] diff --git a/src/main/asciidoc/jaxws/jaxws.adoc b/src/main/asciidoc/jaxws/jaxws.adoc deleted file mode 100644 index b6bd16be..00000000 --- a/src/main/asciidoc/jaxws/jaxws.adoc +++ /dev/null @@ -1,14 +0,0 @@ -= Building Web Services with Jakarta XML Web Services - -This chapter describes Jakarta XML Web Services, a technology for building web services and clients that communicate using XML. -XML Web Services allows developers to write message-oriented as well as Remote Procedure Call–oriented (RPC-oriented) web services. - -include::jaxws001.adoc[] - -include::jaxws002.adoc[] - -include::jaxws003.adoc[] - -include::jaxws004.adoc[] - -include::jaxws005.adoc[] diff --git a/src/main/asciidoc/jaxws/jaxws001.adoc b/src/main/asciidoc/jaxws/jaxws001.adoc deleted file mode 100644 index b672b475..00000000 --- a/src/main/asciidoc/jaxws/jaxws001.adoc +++ /dev/null @@ -1,23 +0,0 @@ -== Overview of Jakarta XML Web Services - -In Jakarta XML Web Services, a web service operation invocation is represented by an XML-based protocol, such as SOAP. -The SOAP specification defines the envelope structure, encoding rules, and conventions for representing web service invocations and responses. -These calls and responses are transmitted as SOAP messages (XML files) over HTTP. - -Although SOAP messages are complex, the XML Web Services API hides this complexity from the application developer. -On the server side, the developer specifies the web service operations by defining methods in an interface written in the Java programming language. -The developer also codes one or more classes that implement those methods. -Client programs are also easy to code. -A client creates a proxy (a local object representing the service) and then simply invokes methods on the proxy. -With XML Web Services, the developer does not generate or parse SOAP messages. -It is the XML Web Services runtime system that converts the API calls and responses to and from SOAP messages. - -With XML Web Services, clients and web services have a big advantage: the platform independence of the Java programming language. -In addition, XML Web Services is not restrictive: A XML Web Services client can access a web service that is not running on the Java platform and vice versa. -This flexibility is possible because XML Web Services uses technologies defined by the W3C: HTTP, SOAP, and WSDL. -WSDL specifies an XML format for describing a service as a set of endpoints operating on messages. - -[NOTE] -Several files in the XML Web Services examples depend on the port that you specified when you installed GlassFish Server. -These tutorial examples assume that the server runs on the default port, 8080. -They do not run with a nondefault port setting. diff --git a/src/main/asciidoc/jaxws/jaxws002.adoc b/src/main/asciidoc/jaxws/jaxws002.adoc deleted file mode 100644 index 1b4e0f4e..00000000 --- a/src/main/asciidoc/jaxws/jaxws002.adoc +++ /dev/null @@ -1,459 +0,0 @@ -== Creating a Simple Web Service and Clients with XML Web Services - -This section shows how to build and deploy a simple web service and two clients: an application client and a web client. -The source code for the service is in the `_tut-install_/examples/jaxws/helloservice-war/` directory, and the clients are in the `_tut-install_/examples/jaxws/hello-appclient/` and `_tut-install_/examples/jaxws/hello-webclient/` directories. - -<> illustrates how XML Web Services technology manages communication between a web service and a client. - -[[communication-between-a-xml-web-service-and-a-client]] -.Communication between a XML Web Service and a Client -image::jakartaeett_dt_019.svg["Diagram showing a client and web service communicating through a SOAP message."] - -The starting point for developing a XML Web Services web service is a Java class annotated with the `jakarta.jws.WebService` annotation. -The `@WebService` annotation defines the class as a web service endpoint. - -A service endpoint interface or service endpoint implementation (SEI) is a Java interface or class, respectively, that declares the methods that a client can invoke on the service. -An interface is not required when building a XML Web Services endpoint. -The web service implementation class implicitly defines an SEI. - -You may specify an explicit interface by adding the `endpointInterface` element to the `@WebService` annotation in the implementation class. -You must then provide an interface that defines the public methods made available in the endpoint implementation class. - -=== Basic Steps for Creating a Web Service and Client - -The basic steps for creating a web service and client are as follows. - -. Code the implementation class. - -. Compile the implementation class. - -. Package the files into a WAR file. - -. Deploy the WAR file. -The web service artifacts, which are used to communicate with clients, are generated by GlassFish Server during deployment. - -. Code the client class. - -. Use the `wsimport` Maven goal to generate and compile the web service artifacts needed to connect to the service. - -. Compile the client class. - -. Run the client. - -If you use NetBeans IDE to create a service and client, the IDE performs the `wsimport` task for you. - -The sections that follow cover these steps in greater detail. - -=== Requirements of a XML Web Services Endpoint - -XML Web Services endpoints must follow these requirements. - -* The implementing class must be annotated with either the `jakarta.jws.WebService` or the `jakarta.jws.WebServiceProvider` annotation. - -* The implementing class may explicitly reference an SEI through the `endpointInterface` element of the `@WebService` annotation but is not required to do so. -If no `endpointInterface` is specified in `@WebService`, an SEI is implicitly defined for the implementing class. - -* The business methods of the implementing class must be public and must not be declared `static` or `final`. - -* Business methods that are exposed to web service clients must be annotated with `jakarta.jws.WebMethod`. - -* Business methods that are exposed to web service clients must have Jakarta XML Binding-compatible parameters and return types. -See the list of Jakarta XML Binding default data type bindings in <>. - -* The implementing class must not be declared `final` and must not be `abstract`. - -* The implementing class must have a default public constructor. - -* The implementing class must not define the `finalize` method. - -* The implementing class may use the `jakarta.annotation.PostConstruct` or the `jakarta.annotation.PreDestroy` annotations on its methods for lifecycle event callbacks. -+ -The `@PostConstruct` method is called by the container before the implementing class begins responding to web service clients. -+ -The `@PreDestroy` method is called by the container before the endpoint is removed from operation. - -=== Coding the Service Endpoint Implementation Class - -In this example, the implementation class, `Hello`, is annotated as a web service endpoint using the `@WebService` annotation. -`Hello` declares a single method named `sayHello`, annotated with the `@WebMethod` annotation, which exposes the annotated method to web service clients. -The `sayHello` method returns a greeting to the client, using the name passed to it to compose the greeting. -The implementation class also must define a default, public, no-argument constructor. - -[source,java] ----- -package ee.jakarta.tutorial.helloservice; - -import jakarta.jws.WebService; -import jakarta.jws.WebMethod; - -@WebService -public class Hello { - private final String message = "Hello, "; - - public Hello() { - } - - @WebMethod - public String sayHello(String name) { - return message + name + "."; - } -} ----- - -=== Building, Packaging, and Deploying the Service - -You can use either NetBeans IDE or Maven to build, package, and deploy the `helloservice-war` application. - -==== To Build, Package, and Deploy the Service Using NetBeans IDE - -. Make sure that GlassFish Server has been started (see <>). - -. From the *File* menu, choose *Open Project*. - -. In the *Open Project* dialog box, navigate to: -+ ----- -tut-install/examples/jaxws ----- - -. Select the `helloservice-war` folder. - -. Click *Open Project*. - -. In the *Projects* tab, right-click the `helloservice-war` project and select *Run*. -+ -This command builds and packages the application into a WAR file, `helloservice-war.war`, located in `_tut-install_/examples/jaxws/helloservice-war/target/`, and deploys this WAR file to your GlassFish Server instance. -It also opens the web service test interface at the URL shown in <>. - -You can view the WSDL file of the deployed service by requesting the URL http://localhost:8080/helloservice-war/HelloService?wsdl[^] in a web browser. -Now you are ready to create a client that accesses this service. - -==== To Build, Package, and Deploy the Service Using Maven - -. Make sure that GlassFish Server has been started (see <>). - -. In a terminal window, go to: -+ ----- -tut-install/examples/jaxws/helloservice-war/ ----- - -. Enter the following command: -+ -[source,shell] ----- -mvn install ----- -+ -This command builds and packages the application into a WAR file, `helloservice-war.war`, located in the `target` directory, and then deploys the WAR to GlassFish Server. - -You can view the WSDL file of the deployed service by requesting the URL http://localhost:8080/helloservice-war/HelloService?wsdl[^] in a web browser. -Now you are ready to create a client that accesses this service. - -=== Testing the Methods of a Web Service Endpoint - -GlassFish Server allows you to test the methods of a web service endpoint. - -==== To Test the Service without a Client - -To test the `sayHello` method of `HelloService`, follow these steps. - -. Open the web service test interface by entering the following URL in a web browser: -+ ----- -http://localhost:8080/helloservice-war/HelloService?Tester ----- - -. Under Methods, enter a name as the parameter to the `sayHello` method. - -. Click sayHello. -+ -This takes you to the `sayHello` Method invocation page. -+ -Under Method returned, you'll see the response from the endpoint. - -=== A Simple XML Web Services Application Client - -The `HelloAppClient` class is a stand-alone application client that accesses the `sayHello` method of `HelloService`. -This call is made through a port, a local object that acts as a proxy for the remote service. -The port is created at development time by the `wsimport` Maven goal, which generates XML Web Services portable artifacts based on a WSDL file. - -==== Coding the Application Client - -When invoking the remote methods on the port, the client performs these steps. - -. It uses the generated `helloservice.endpoint.HelloService` class, which represents the service at the URI of the deployed service's WSDL file: -+ -[source,java] ----- -import ee.jakarta.tutorial.helloservice.endpoint.HelloService; -import jakarta.xml.ws.WebServiceRef; - -public class HelloAppClient { - @WebServiceRef(wsdlLocation = - "http://localhost:8080/helloservice-war/HelloService?WSDL") - private static HelloService service; - ... -} ----- - -. It retrieves a proxy to the service, also known as a port, by invoking `getHelloPort` on the service: -+ -[source,java] ----- -ee.jakarta.tutorial.helloservice.endpoint.Hello port = service.getHelloPort(); ----- -+ -The port implements the SEI defined by the service. - -. It invokes the port's `sayHello` method, passing a string to the service: -+ -[source,java] ----- -return port.sayHello(arg0); ----- - -Here is the full source of `HelloAppClient.java`, which is located in the `_tut-install_/examples/jaxws/hello-appclient/src/main/java/ee/jakarta/tutorial/hello/appclient/` directory: - -[source,java] ----- -package ee.jakarta.tutorial.hello.appclient; - -import ee.jakarta.tutorial.helloservice.endpoint.HelloService; -import jakarta.xml.ws.WebServiceRef; - -public class HelloAppClient { - @WebServiceRef(wsdlLocation = - "http://localhost:8080/helloservice-war/HelloService?WSDL") - private static HelloService service; - - /** - * @param args the command line arguments - */ - public static void main(String[] args) { - System.out.println(sayHello("world")); - } - - private static String sayHello(java.lang.String arg0) { - ee.jakarta.tutorial.helloservice.endpoint.Hello port = - service.getHelloPort(); - return port.sayHello(arg0); - } -} ----- - -==== Running the Application Client - -You can use either NetBeans IDE or Maven to build, package, deploy, and run the `hello-appclient` application. -To build the client, you must first have deployed `helloservice-war`, as described in <>. - -===== To Run the Application Client Using NetBeans IDE - -. From the *File* menu, choose *Open Project*. - -. In the *Open Project* dialog box, navigate to: -+ ----- -tut-install/examples/jaxws ----- - -. Select the `hello-appclient` folder. - -. Click *Open Project*. - -. In the *Projects* tab, right-click the `hello-appclient` project and select *Build*. -+ -This command runs the `wsimport` goal, then builds, packages, and runs the client. -You will see the output of the application client in the hello-appclient output tab: -+ ----- ---- exec-maven-plugin:1.2.1:exec (run-appclient) @ hello-appclient --- -Hello, world. ----- - -===== To Run the Application Client Using Maven - -. In a terminal window, go to: -+ ----- -tut-install/examples/jaxws/hello-appclient/ ----- - -. Enter the following command: -+ -[source,shell] ----- -mvn install ----- -+ -This command runs the `wsimport` goal, then builds, packages, and runs the client. -The application client output looks like this: -+ ----- ---- exec-maven-plugin:1.2.1:exec (run-appclient) @ hello-appclient --- -Hello, world. ----- - -=== A Simple XML Web Services Web Client - -`HelloServlet` is a servlet that, like the Java client, calls the `sayHello` method of the web service. -Like the application client, it makes this call through a port. - -==== Coding the Servlet - -To invoke the method on the port, the client performs these steps. - -. It imports the `HelloService` endpoint and the `WebServiceRef` annotation: -+ -[source,java] ----- -import ee.jakarta.tutorial.helloservice.endpoint.HelloService; -... -import jakarta.xml.ws.WebServiceRef; ----- - -. It defines a reference to the web service by specifying the WSDL location: -+ -[source,java] ----- -@WebServiceRef(wsdlLocation = - "http://localhost:8080/helloservice-war/HelloService?WSDL") ----- - -. It declares the web service, then defines a private method that calls the `sayHello` method on the port: -+ -[source,java] ----- -private HelloService service; -... -private String sayHello(java.lang.String arg0) { - ee.jakarta.tutorial.helloservice.endpoint.Hello port = - service.getHelloPort(); - return port.sayHello(arg0); -} ----- - -. In the servlet, it calls this private method: -+ -[source,java] ----- -out.println("

    " + sayHello("world") + "

    "); ----- - -The significant parts of the `HelloServlet` code follow. -The code is located in the `_tut-install_/examples/jaxws/hello-webclient/src/java/ee/jakarta/tutorial/hello/ webclient/` directory. - -[source,java] ----- -package ee.jakarta.tutorial.hello.webclient; - -import ee.jakarta.tutorial.helloservice.endpoint.HelloService; -import java.io.IOException; -import java.io.PrintWriter; -import jakarta.servlet.ServletException; -import jakarta.servlet.annotation.WebServlet; -import jakarta.servlet.http.HttpServlet; -import jakarta.servlet.http.HttpServletRequest; -import jakarta.servlet.http.HttpServletResponse; -import jakarta.xml.ws.WebServiceRef; - -@WebServlet(name="HelloServlet", urlPatterns={"/HelloServlet"}) -public class HelloServlet extends HttpServlet { - @WebServiceRef(wsdlLocation = - "http://localhost:8080/helloservice-war/HelloService?WSDL") - private HelloService service; - - /** - * Processes requests for both HTTP GET - * and POST methods. - * @param request servlet request - * @param response servlet response - * @throws ServletException if a servlet-specific error occurs - * @throws IOException if an I/O error occurs - */ - protected void processRequest(HttpServletRequest request, - HttpServletResponse response) - throws ServletException, IOException { - response.setContentType("text/html;charset=UTF-8"); - try (PrintWriter out = response.getWriter()) { - - out.println(""); - out.println(""); - out.println("Servlet HelloServlet"); - out.println(""); - out.println(""); - out.println("

    Servlet HelloServlet at " + - request.getContextPath () + "

    "); - out.println("

    " + sayHello("world") + "

    "); - out.println(""); - out.println(""); - } - } - - // doGet and doPost methods, which call processRequest, and - // getServletInfo method - - private String sayHello(java.lang.String arg0) { - ee.jakarta.tutorial.helloservice.endpoint.Hello port = - service.getHelloPort(); - return port.sayHello(arg0); - } -} ----- - -==== Running the Web Client - -You can use either NetBeans IDE or Maven to build, package, deploy, and run the `hello-webclient` application. -To build the client, you must first have deployed `helloservice-war`, as described in <>. - -===== To Run the Web Client Using NetBeans IDE - -. From the *File* menu, choose *Open Project*. - -. In the *Open Project* dialog box, navigate to: -+ ----- -tut-install/examples/jaxws ----- - -. Select the `hello-webclient` folder. - -. Click *Open Project*. - -. In the *Projects* tab, right-click the `hello-webclient` project and select *Build*. -+ -This task runs the `wsimport` goal, builds and packages the application into a WAR file, `hello-webclient.war`, located in the `target` directory, and deploys it to GlassFish Server. - -. In a web browser, enter the following URL: -+ ----- -http://localhost:8080/hello-webclient/HelloServlet ----- -+ -The output of the `sayHello` method appears in the window. - -===== To Run the Web Client Using Maven - -. In a terminal window, go to: -+ ----- -tut-install/examples/jaxws/hello-webclient/ ----- - -. Enter the following command: -+ -[source,shell] ----- -mvn install ----- -+ -This command runs the `wsimport` goal, then build and packages the application into a WAR file, `hello-webclient.war`, located in the `target` directory. -The WAR file is then deployed to GlassFish Server. - -. In a web browser, enter the following URL: -+ ----- -http://localhost:8080/hello-webclient/HelloServlet ----- -+ -The output of the `sayHello` method appears in the window. diff --git a/src/main/asciidoc/jaxws/jaxws003.adoc b/src/main/asciidoc/jaxws/jaxws003.adoc deleted file mode 100644 index cb4c0cd6..00000000 --- a/src/main/asciidoc/jaxws/jaxws003.adoc +++ /dev/null @@ -1,109 +0,0 @@ -== Types Supported by XML Web Services - -XML Web Services delegates the mapping of Java programming language types to and from XML definitions to Jakarta XML Binding. -Application developers don't need to know the details of these mappings but should be aware that not every class in the Java language can be used as a method parameter or return type in XML Web Services. - -The following sections explain the default schema-to-Java and Java-to-schema data type bindings: - -* <> - -* <> - -=== Schema-to-Java Mapping - -The Java language provides a richer set of data types than XML schema. -<> lists the mapping of XML data types to Java data types. - -[[mapping-of-xml-data-types-to-java-data-types]] -.Mapping of XML Data Types to Java Data Types -[width="50%",cols="20%,30%"] -|=== -|XML Schema Type |Java Data Type - -|`xsd:string` |`java.lang.String` - -|`xsd:integer` |`java.math.BigInteger` - -|`xsd:int` |`int` - -|`xsd.long` |`long` - -|`xsd:short` |`short` - -|`xsd:decimal` |`java.math.BigDecimal` - -|`xsd:float` |`float` - -|`xsd:double` |`double` - -|`xsd:boolean` |`boolean` - -|`xsd:byte` |`byte` - -|`xsd:QName` |`javax.xml.namespace.QName` - -|`xsd:dateTime` |`javax.xml.datatype.XMLGregorianCalendar` - -|`xsd:base64Binary` |`byte[]` - -|`xsd:hexBinary` |`byte[]` - -|`xsd:unsignedInt` |`long` - -|`xsd:unsignedShort` |`int` - -|`xsd:unsignedByte` |`short` - -|`xsd:time` |`javax.xml.datatype.XMLGregorianCalendar` - -|`xsd:date` |`javax.xml.datatype.XMLGregorianCalendar` - -|`xsd:g` |`javax.xml.datatype.XMLGregorianCalendar` - -|`xsd:anySimpleType` |`java.lang.Object` - -|`xsd:anySimpleType` |`java.lang.String` - -|`xsd:duration` |`javax.xml.datatype.Duration` - -|`xsd:NOTATION` |`javax.xml.namespace.QName` -|=== - -=== Java-to-Schema Mapping - -<> shows the default mapping of Java classes to XML data types. - -[[mapping-of-java-classes-to-xml-data-types]] -.Mapping of Java Classes to XML Data Types -[width="50%",cols="30%,20%"] -|=== -|Java Class |XML Data Type - -|`java.lang.String` |`xs:string` - -|`java.math.BigInteger` |`xs:integer` - -|`java.math.BigDecimal` |`xs:decimal` - -|`java.util.Calendar` |`xs:dateTime` - -|`java.util.Date` |`xs:dateTime` - -|`javax.xml.namespace.QName` |`xs:QName` - -|`java.net.URI` |`xs:string` - -|`javax.xml.datatype.XMLGregorianCalendar` |`xs:anySimpleType` - -|`javax.xml.datatype.Duration` |`xs:duration` - -|`java.lang.Object` |`xs:anyType` - -|`java.awt.Image` |`xs:base64Binary` - -|`jakarta.activation.DataHandler` |`xs:base64Binary` - -|`javax.xml.transform.Source` |`xs:base64Binary` - -|`java.util.UUID` |`xs:string` -|=== diff --git a/src/main/asciidoc/jaxws/jaxws004.adoc b/src/main/asciidoc/jaxws/jaxws004.adoc deleted file mode 100644 index d47c52d0..00000000 --- a/src/main/asciidoc/jaxws/jaxws004.adoc +++ /dev/null @@ -1,7 +0,0 @@ -== Web Services Interoperability and Jakarta XML Web Services - -Jakarta XML Web Services supports the Web Services Interoperability (WS-I) Basic Profile Version 1.1. -The WS-I Basic Profile is a document that clarifies the SOAP 1.1 and WSDL 1.1 specifications to promote SOAP interoperability. -For links related to WS-I, see <>. - -To support WS-I Basic Profile Version 1.1, the JAX-WS runtime supports doc/literal and rpc/literal encodings for services, static ports, dynamic proxies, and the Dynamic Invocation Interface (DII). diff --git a/src/main/asciidoc/jaxws/jaxws005.adoc b/src/main/asciidoc/jaxws/jaxws005.adoc deleted file mode 100644 index 4ebaa79b..00000000 --- a/src/main/asciidoc/jaxws/jaxws005.adoc +++ /dev/null @@ -1,18 +0,0 @@ -== Further Information about Jakarta XML Web Services - -For more information about Jakarta XML Web Services and related technologies, see - -* Jakarta XML Web Services 3.0 specification: + -https://jakarta.ee/specifications/xml-web-services/3.0/[^] - -* Jakarta XML Web Services home: + -https://eclipse-ee4j.github.io/metro-jax-ws/[^] - -* Simple Object Access Protocol (SOAP) 1.2 W3C Note: + -https://www.w3.org/TR/soap/[^] - -* Web Services Description Language (WSDL) 1.1 W3C Note: + -https://www.w3.org/TR/wsdl[^] - -* WS-I Basic Profile 1.2 and 2.0: + -http://www.ws-i.org[^] diff --git a/src/main/asciidoc/jms-examples/jms-examples002.adoc b/src/main/asciidoc/jms-examples/jms-examples002.adoc deleted file mode 100644 index 4faf1e2e..00000000 --- a/src/main/asciidoc/jms-examples/jms-examples002.adoc +++ /dev/null @@ -1,42 +0,0 @@ -== Overview of the Jakarta Messaging Examples - -The following tables list the examples used in this chapter, describe what they do, and link to the section that describes them fully. -The example directory for each example is relative to the `_tut-install_/examples/jms/` directory. - -.Jakarta Messaging Examples That Show the Use of Jakarta EE Application Clients -[width="80%",cols="20%,60%"] -|=== -|Example Directory |Description - -|`simple/producer` |Using an application client to send messages; see <> - -|`simple/synchconsumer` |Using an application client to receive messages synchronously; see <> - -|`simple/asynchconsumer` |Using an application client to receive messages asynchronously; see <> - -|`simple/messagebrowser` |Using an application client to use a `QueueBrowser` to browse a queue; see <> - -|`simple/clientackconsumer` |Using an application client to acknowledge messages received synchronously; see <> - -|`durablesubscriptionexample` |Using an application client to create a durable subscription on a topic; see <> - -|`transactedexample` |Using an application client to send and receive messages in local transactions (also uses request-reply messaging); see <> - -|`shared/sharedconsumer` |Using an application client to create shared nondurable topic subscriptions; see <> - -|`shared/shareddurableconsumer` |Using an application client to create shared durable topic subscriptions; see <> -|=== - -.Jakarta Messaging Examples That Show the Use of Jakarta EE Web and Enterprise Bean Components -[width="80%",cols="20%,60%"] -|=== -|Example Directory |Description - -|`websimplemessage` |Using managed beans to send messages and to receive messages synchronously; see <> - -|`simplemessage` |Using an application client to send messages, and using a message-driven bean to receive messages asynchronously; see <> - -|`clientsessionmdb` |Using a session bean to send messages, and using a message-driven bean to receive messages; see <> - -|`clientmdbentity` |Using an application client, two message-driven beans, and JPA persistence to create a simple HR application; see <> -|=== diff --git a/src/main/asciidoc/overview/overview.adoc b/src/main/asciidoc/overview/overview.adoc deleted file mode 100644 index d5977f8c..00000000 --- a/src/main/asciidoc/overview/overview.adoc +++ /dev/null @@ -1,24 +0,0 @@ -= 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. - -include::overview001.adoc[] - -include::overview002.adoc[] - -include::overview003.adoc[] - -include::overview004.adoc[] - -include::overview005.adoc[] - -include::overview006.adoc[] - -include::overview007.adoc[] - -include::overview008.adoc[] - -include::overview009.adoc[] - -include::overview010.adoc[] diff --git a/src/main/asciidoc/overview/overview001.adoc b/src/main/asciidoc/overview/overview001.adoc deleted file mode 100644 index 860e2142..00000000 --- a/src/main/asciidoc/overview/overview001.adoc +++ /dev/null @@ -1,25 +0,0 @@ -== 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. diff --git a/src/main/asciidoc/overview/overview002.adoc b/src/main/asciidoc/overview/overview002.adoc deleted file mode 100644 index a9c21fe3..00000000 --- a/src/main/asciidoc/overview/overview002.adoc +++ /dev/null @@ -1,38 +0,0 @@ -== 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 diff --git a/src/main/asciidoc/overview/overview003.adoc b/src/main/asciidoc/overview/overview003.adoc deleted file mode 100644 index 5c523392..00000000 --- a/src/main/asciidoc/overview/overview003.adoc +++ /dev/null @@ -1,19 +0,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. diff --git a/src/main/asciidoc/overview/overview004.adoc b/src/main/asciidoc/overview/overview004.adoc deleted file mode 100644 index 71eaba16..00000000 --- a/src/main/asciidoc/overview/overview004.adoc +++ /dev/null @@ -1,134 +0,0 @@ -== 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. - -<> shows two multitiered Jakarta EE applications divided into the tiers described in the following list. The Jakarta EE application parts shown in <> are presented in <>. - -* 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 <>, 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. - -[[multitiered-applications]] -.Multitiered Applications -image::jakartaeett_dt_001.svg[ "Diagram of multitiered application structure, including client tier, web tier, business tier, and EIS tier."] - -=== 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 - -<> 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. - -[[server-communication]] -.Server Communication -image::jakartaeett_dt_002.svg["Diagram of client-server communication. Application clients access the business tier directly. Browsers, web pages, and applets access the web tier."] - -=== 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 <>, 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. - -[[web-tier-and-jakarta-ee-applications]] -.Web Tier and Jakarta EE Applications -image::jakartaeett_dt_003.svg["Diagram of client-server communication showing detail of JavaBeans components and web pages in the web tier."] - -=== 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. -<> 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. - -[[business-and-eis-tiers]] -.Business and EIS Tiers -image::jakartaeett_dt_004.svg["Diagram of client-server communication showing detail of entities, session beans, and message-driven beans in the business tier."] - -=== 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. diff --git a/src/main/asciidoc/overview/overview005.adoc b/src/main/asciidoc/overview/overview005.adoc deleted file mode 100644 index 58ad8bc1..00000000 --- a/src/main/asciidoc/overview/overview005.adoc +++ /dev/null @@ -1,54 +0,0 @@ -== 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 <>. - -=== Container Types - -The deployment process installs Jakarta EE application components in the Jakarta EE containers, as illustrated in <>. - -[[jakarta-ee-server-and-containers]] -.Jakarta EE Server and Containers -image::jakartaeett_dt_005.svg["Diagram of client-server communication showing servlets and web pages in the web tier and enterprise beans in the business tier."] - -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. diff --git a/src/main/asciidoc/overview/overview006.adoc b/src/main/asciidoc/overview/overview006.adoc deleted file mode 100644 index 8498dfd8..00000000 --- a/src/main/asciidoc/overview/overview006.adoc +++ /dev/null @@ -1,45 +0,0 @@ -== 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. diff --git a/src/main/asciidoc/overview/overview007.adoc b/src/main/asciidoc/overview/overview007.adoc deleted file mode 100644 index 3ee7e79b..00000000 --- a/src/main/asciidoc/overview/overview007.adoc +++ /dev/null @@ -1,12 +0,0 @@ -== 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. diff --git a/src/main/asciidoc/overview/overview008.adoc b/src/main/asciidoc/overview/overview008.adoc deleted file mode 100644 index 06f025c4..00000000 --- a/src/main/asciidoc/overview/overview008.adoc +++ /dev/null @@ -1,370 +0,0 @@ -== Jakarta EE APIs - - -<> shows the relationships among the Jakarta EE -containers. - -[[jakarta-ee-containers-2]] -.Jakarta EE Containers -image::jakartaeett_dt_006.svg["Diagram of Jakarta EE containers and their relationships"] - -<> shows the availability of the Jakarta EE APIs in the web container. - -[[jakarta-ee-apis-in-the-web-container]] -.Jakarta EE APIs in the Web Container -image::jakartaeett_dt_007.svg["Diagram of Jakarta EE APIs in the web container"] - -<> shows the availability of the Jakarta EE APIs in the enterprise bean container. - -[[jakarta-ee-apis-in-the-enterprise-bean-container]] -.Jakarta EE APIs in the enterprise bean Container -image::jakartaeett_dt_008.svg[ "Diagram of Jakarta EE APIs in the enterprise bean container"] - -<> shows the availability of the Jakarta EE APIs in the application client container. - -[[jakarta-ee-apis-in-the-application-client-container]] -.Jakarta EE APIs in the Application Client Container -image::jakartaeett_dt_009.svg["Diagram of Jakarta EE APIs in the application client container"] - -The following sections give a brief summary of the technologies required by the Jakarta EE platform and the APIs used in Jakarta EE applications. - -=== Jakarta Enterprise Beans Technology - -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. - -* A session bean represents a transient conversation with a client. -When the client finishes executing, the session bean and its data are gone. - -* A message-driven bean combines features of a session bean and a message listener, allowing a business component to receive messages asynchronously. -Commonly, these are Jakarta Messaging messages. - -The Jakarta EE 9 platform requires Jakarta Enterprise Beans 4.0 and Jakarta Interceptors 2.0. - -=== Jakarta Servlet Technology - -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: - -* Server Push - -* HTTP Trailer - -The Jakarta EE 9 platform requires Servlet 5.0. - -=== Jakarta Faces Technology - -Jakarta Faces technology is a user interface framework for building web applications. -The main components of Jakarta Faces technology are as follows: - -* A GUI component framework. - -* A flexible model for rendering components in different kinds of HTML or different markup languages and technologies. -A `Renderer` object generates the markup to render the component and converts the data stored in a model object to types that can be represented in a view. - -* A standard `RenderKit` for generating HTML 4.01 markup. - -The following features support the GUI components: - -* Input validation - -* Event handling - -* Data conversion between model objects and components - -* Managed model object creation - -* Page navigation configuration - -* Jakarta Expression Language - -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: - -* Direct support for WebSockets via the new `` tag - -* Class-level bean validation via the new `` tag - -* A Jakarta Contexts and Dependency Injection compatible `@ManagedProperty` annotation - -* Enhanced component search expression framework - -The Jakarta EE 9 platform requires Jakarta Faces 3.0 and Jakarta Expression Language 4.0. - -=== Jakarta Server Pages Technology - -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: - -* Static data, which can be expressed in any text-based format, such as HTML or XML - -* JSP elements, which determine how the page constructs dynamic content - -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 https://docs.oracle.com/javaee/5/tutorial/doc/[^]. - -The Jakarta EE 9 platform requires Jakarta Server Pages 3.0 for compatibility with earlier releases but recommends the use of Facelets as the display technology in new applications. - -=== Jakarta Standard Tag Library - -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 9 platform requires Jakarta Standard Tag Library 2.0. - -=== Jakarta Persistence - -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 Persistence - -* The query language - -* Object/relational mapping metadata - -The Jakarta EE 9 platform requires Jakarta Persistence 3.0. - -=== Jakarta Transactions - -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 9 platform requires Jakarta Transactions 2.0. - -=== Jakarta RESTful Web Services - -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: - -* Reactive Client API + -When the results of an invocation on a target resource are received, enhancements to the completion stage APIs in Java SE allow the sequence of those results to be specified, prioritized, combined, or concatenated, and how exceptions can be handled. - -* Enhancements in support for server-sent events + -Clients may subscribe to server-issued event notifications using a long-running connection. Support for a new media type, text/event-stream, has been added. - -* Support for Jakarta JSON Binding objects, and improved integration with Jakarta Contexts and Dependency Injection, Jakarta Servlet, and Jakarta Bean Validation technologies - -The Jakarta EE 9 platform requires Jakarta RESTful Web Services 3.0. - -=== Jakarta Managed Beans - -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. - -The Jakarta Managed Beans specification is part of the Jakarta EE 9 platform specification. -The Jakarta EE 9 platform requires Jakarta Managed Beans 2.0. - -=== Jakarta Contexts and Dependency Injection - -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: - -* An API for bootstrapping a CDI container in Java SE 8 - -* Support for observer ordering, which determines the order in which the observer methods for a particular event are invoked, and support for firing events asynchronously - -* Configurators interfaces, which are used for dynamically defining and modifying CDI objects - -* Built-in annotation literals, a convenience feature for creating instances of annotations, and more - -The Jakarta EE 9 platform requires Jakarta Contexts and Dependency Injection 3.0. - -=== Jakarta Dependency Injection - -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 9 platform requires Jakarta Dependency Injection 2.0. - -=== Jakarta Bean Validation - -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: - -* Support for new features in Java SE 8, such as the Date-Time API - -* Addition of new built-in Jakarta Bean Validation constraints - -The Jakarta EE 9 platform requires Jakarta Bean Validation 3.0. - -=== Jakarta Messaging - -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 9 platform requires Jakarta Messaging 3.0. - -=== Jakarta Connectors - -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 9 platform requires Jakarta Connectors 2.0. - -=== Jakarta Mail - -Jakarta EE applications use the Jakarta Mail to send email notifications. -The Jakarta Mail has two parts: - -* An application-level interface used by the application components to send mail - -* A service provider interface - -The Jakarta EE platform includes the Jakarta Mail with a service provider that allows application components to send Internet mail. - -The Jakarta EE 9 platform requires Jakarta Mail 2.0. - -=== Jakarta Authorization - -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 9 platform requires Jakarta Authorization 2.0. - -=== Jakarta Authentication - -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 9 platform requires Jakarta Authentication 2.0. - -=== Jakarta Security - -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 9 platform requires Jakarta Security 2.0. - -=== Jakarta WebSocket - -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 9 platform requires Jakarta WebSocket 2.0. - -=== Jakarta JSON Processing - -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: - -* JSON Pointer + -Defines a string syntax for referencing a specific value within a JSON document. JSON Pointer includes APIs for extracting values from a target document and transforming them to create a new JSON document. - -* JSON Patch + -Defines a format for expressing a sequence of operations to be applied to a JSON document. - -* JSON Merge Patch + -Defines a format and processing rules for applying operations to a JSON document that are based upon specific content of the target document. - -* The addition of editing and transformation functions to basic JSON document processing. - -* Helper classes and methods, called JSON Collectors, which leverage features of the Stream API that was introduced in Java SE 8. - -The Jakarta EE 9 platform requires Jakarta JSON Processing 2.0. - -=== Jakarta JSON Binding - -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. - -The Jakarta EE 9 platform requires Jakarta JSON Binding 2.0. - -=== Jakarta Concurrency - -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 9 platform requires Jakarta Concurrency 2.0. - -=== Jakarta Batch - -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 9 platform requires Jakarta Batch 2.0. - -=== Jakarta Activation - -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 Jakarta EE 9 platform requires Jakarta Activation 2.0. - -=== Jakarta XML Binding - -The Jakarta XML Binding provides a convenient way to bind an XML schema to a representation in Java language programs. -XML Binding 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 XML Binding API. - -The Jakarta EE 9 platform requires Jakarta XML Binding 3.0. - -=== Jakarta XML Web Services - -The Jakarta XML Web Services specification provides support for web services that use the Jakarta XML Binding 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 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 9 platform requires Jakarta XML Web Services 3.0. - -=== Jakarta SOAP with Attachments - -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. - -=== Jakarta Annotations - -Annotations enable a declarative style of programming in the Java platform. - -The Jakarta EE 9 platform requires Jakarta Annotations 2.0. diff --git a/src/main/asciidoc/overview/overview009.adoc b/src/main/asciidoc/overview/overview009.adoc deleted file mode 100644 index 157942c0..00000000 --- a/src/main/asciidoc/overview/overview009.adoc +++ /dev/null @@ -1,50 +0,0 @@ -== Jakarta EE 9 APIs in the Java Platform, Standard Edition 8 - -Several APIs that are required by the Jakarta EE 9 platform are included in the Java Platform, Standard Edition 8 (Java SE 8) and are thus available to Jakarta EE applications. - -=== Java Database Connectivity API - -The Java Database Connectivity (JDBC) API lets you invoke SQL commands from Java programming language methods. -You use the JDBC API in an enterprise bean when you have a session bean access the database. -You can also use the JDBC API from a servlet or a JSP page to access the database directly without going through an enterprise bean. - -The JDBC API has two parts: - -* An application-level interface used by the application components to access a database - -* A service provider interface to attach a JDBC driver to the Jakarta EE platform - -The Jakarta EE 9 platform requires JDBC 4.1. - -=== Java Naming and Directory Interface API - -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 Messaging connection factory, and a Transactions `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. - -=== Java API for XML Processing - -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 https://www.w3.org/XML/Schema[^]. - -=== Java Authentication and Authorization Service - -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. diff --git a/src/main/asciidoc/overview/overview010.adoc b/src/main/asciidoc/overview/overview010.adoc deleted file mode 100644 index 72c2f296..00000000 --- a/src/main/asciidoc/overview/overview010.adoc +++ /dev/null @@ -1,41 +0,0 @@ -== Eclipse GlassFish Server Tools - -Eclipse GlassFish Server is a compliant implementation of the Jakarta EE platform. -In addition to supporting all the APIs described in the previous sections, Eclipse GlassFish Server includes a number of Jakarta EE tools that are not part of the Jakarta EE platform but are provided as a convenience to the developer. - -This section briefly summarizes the tools that make up Eclipse GlassFish Server. -Instructions for starting and stopping Eclipse GlassFish Server, starting the Administration Console, and starting and stopping Apache Derby are in xref:using-the-tutorial-examples[xrefstyle=full]. - -Eclipse GlassFish Server contains the tools listed in <>. -Basic usage information for many of the tools appears throughout the tutorial. -For detailed information, see the online help in the GUI tools. - -[[glassfish-server-tools]] -.Eclipse GlassFish Server Tools -[width="85%" cols="20%,65%"] -|=== -|Tool |Description - -|Administration Console |A web-based GUI Eclipse GlassFish Server administration utility. -Used to stop Eclipse GlassFish Server and to manage users, resources, and applications. - -|`asadmin` |A command-line Eclipse GlassFish Server administration utility. -Used to start and stop Eclipse GlassFish Server and to manage users, resources, and applications. - -|`appclient` |A command-line tool that launches the application client container and invokes the client application packaged in the application client JAR file. - -|`capture-schema` |A command-line tool to extract schema information from a database, producing a schema file that Eclipse GlassFish Server can use for container-managed persistence. - -|`package-appclient` |A command-line tool to package the application client container libraries and JAR files. - -|Apache Derby |A copy of Apache Derby database. - -|`xjc` |A command-line tool to transform, or bind, a source XML schema to a set of JAXB content classes in the Java programming language. - -|`schemagen` |A command-line tool to create a schema file for each namespace referenced in your Java classes. - -|`wsimport` |A command-line tool to generate Jakarta XML Web Services portable artifacts for a given WSDL file. -After generation, these artifacts can be packaged in a WAR file with the WSDL and schema documents, along with the endpoint implementation, and then deployed. - -|`wsgen` |A command-line tool to read a web service endpoint class and generate all the required Jakarta XML Web Services portable artifacts for web service deployment and invocation. -|=== diff --git a/src/main/asciidoc/partbeanvalidation.adoc b/src/main/asciidoc/partbeanvalidation.adoc deleted file mode 100644 index cae3ba44..00000000 --- a/src/main/asciidoc/partbeanvalidation.adoc +++ /dev/null @@ -1,11 +0,0 @@ -= Bean Validation - -Part IV explores Jakarta Bean Validation. - -:leveloffset: +1 - -include::bean-validation/bean-validation.adoc[] - -include::bean-validation-advanced/bean-validation-advanced.adoc[] - -:leveloffset: -1 diff --git a/src/main/asciidoc/partcasestudies.adoc b/src/main/asciidoc/partcasestudies.adoc deleted file mode 100644 index 57ed1d36..00000000 --- a/src/main/asciidoc/partcasestudies.adoc +++ /dev/null @@ -1,13 +0,0 @@ -= Case Studies - -Part XII presents case studies that use a variety of Jakarta EE technologies. - -:leveloffset: +1 - -include::dukes-bookstore/dukes-bookstore.adoc[] - -include::dukes-tutoring/dukes-tutoring.adoc[] - -include::dukes-forest/dukes-forest.adoc[] - -:leveloffset: -1 diff --git a/src/main/asciidoc/partcdi.adoc b/src/main/asciidoc/partcdi.adoc deleted file mode 100644 index 7ea1fe93..00000000 --- a/src/main/asciidoc/partcdi.adoc +++ /dev/null @@ -1,17 +0,0 @@ -= Jakarta EE Contexts and Dependency Injection - -Part V explores Jakarta EE Contexts and Dependency Injection (CDI). - -:leveloffset: +1 - -include::cdi-basic/cdi-basic.adoc[] - -include::cdi-basicexamples/cdi-basicexamples.adoc[] - -include::cdi-adv/cdi-adv.adoc[] - -include::cdi-bootstrap-se8/cdi-bootstrap-se8.adoc[] - -include::cdi-adv-examples/cdi-adv-examples.adoc[] - -:leveloffset: -1 diff --git a/src/main/asciidoc/partentbeans.adoc b/src/main/asciidoc/partentbeans.adoc deleted file mode 100644 index 8cb75c47..00000000 --- a/src/main/asciidoc/partentbeans.adoc +++ /dev/null @@ -1,17 +0,0 @@ -= Enterprise Beans - -Part VII explores Jakarta Enterprise Beans components. - -:leveloffset: +1 - -include::ejb-intro/ejb-intro.adoc[] - -include::ejb-gettingstarted/ejb-gettingstarted.adoc[] - -include::ejb-basicexamples/ejb-basicexamples.adoc[] - -include::ejb-embedded/ejb-embedded.adoc[] - -include::ejb-async/ejb-async.adoc[] - -:leveloffset: -1 diff --git a/src/main/asciidoc/partintro.adoc b/src/main/asciidoc/partintro.adoc deleted file mode 100644 index ebe1997d..00000000 --- a/src/main/asciidoc/partintro.adoc +++ /dev/null @@ -1,11 +0,0 @@ -= Introduction - -Part I introduces the platform, the tutorial, and the examples. - -:leveloffset: +1 - -include::overview/overview.adoc[] - -include::usingexamples/usingexamples.adoc[] - -:leveloffset: -1 diff --git a/src/main/asciidoc/partmessaging.adoc b/src/main/asciidoc/partmessaging.adoc deleted file mode 100644 index e53e364a..00000000 --- a/src/main/asciidoc/partmessaging.adoc +++ /dev/null @@ -1,11 +0,0 @@ -= Messaging - -Part IX introduces messaging. - -:leveloffset: +1 - -include::jms-concepts/jms-concepts.adoc[] - -include::jms-examples/jms-examples.adoc[] - -:leveloffset: -1 diff --git a/src/main/asciidoc/partpersist.adoc b/src/main/asciidoc/partpersist.adoc deleted file mode 100644 index 03e59794..00000000 --- a/src/main/asciidoc/partpersist.adoc +++ /dev/null @@ -1,23 +0,0 @@ -= Persistence - -Part VIII explores Jakarta Persistence. - -:leveloffset: +1 - -include::persistence-intro/persistence-intro.adoc[] - -include::persistence-basicexamples/persistence-basicexamples.adoc[] - -include::persistence-querylanguage/persistence-querylanguage.adoc[] - -include::persistence-criteria/persistence-criteria.adoc[] - -include::persistence-string-queries/persistence-string-queries.adoc[] - -include::persistence-locking/persistence-locking.adoc[] - -include::persistence-entitygraphs/persistence-entitygraphs.adoc[] - -include::persistence-cache/persistence-cache.adoc[] - -:leveloffset: -1 diff --git a/src/main/asciidoc/partplatform.adoc b/src/main/asciidoc/partplatform.adoc deleted file mode 100644 index 79e88f1d..00000000 --- a/src/main/asciidoc/partplatform.adoc +++ /dev/null @@ -1,13 +0,0 @@ -= Platform Basics - -Part II introduces platform basics. - -:leveloffset: +1 - -include::resource-creation/resource-creation.adoc[] - -include::injection/injection.adoc[] - -include::packaging/packaging.adoc[] - -:leveloffset: -1 diff --git a/src/main/asciidoc/partsecurity.adoc b/src/main/asciidoc/partsecurity.adoc deleted file mode 100644 index 3176c8ef..00000000 --- a/src/main/asciidoc/partsecurity.adoc +++ /dev/null @@ -1,17 +0,0 @@ -= Security - -Part X explores security concepts and examples. - -:leveloffset: +1 - -include::security-intro/security-intro.adoc[] - -include::security-webtier/security-webtier.adoc[] - -include::security-jakartaee/security-jakartaee.adoc[] - -include::security-api/security-api.adoc[] - -include::security-advanced/security-advanced.adoc[] - -:leveloffset: -1 diff --git a/src/main/asciidoc/partsupporttechs.adoc b/src/main/asciidoc/partsupporttechs.adoc deleted file mode 100644 index 80ab184b..00000000 --- a/src/main/asciidoc/partsupporttechs.adoc +++ /dev/null @@ -1,20 +0,0 @@ -= Jakarta EE Supporting Technologies - -Part XI explores several technologies that support the Jakarta EE -platform. - -:leveloffset: +1 - -include::transactions/transactions.adoc[] - -include::resources/resources.adoc[] - -include::connectorexample/connectorexample.adoc[] - -include::interceptors/interceptors.adoc[] - -include::batch-processing/batch-processing.adoc[] - -include::concurrency-utilities/concurrency-utilities.adoc[] - -:leveloffset: -1 diff --git a/src/main/asciidoc/partwebsvcs.adoc b/src/main/asciidoc/partwebsvcs.adoc deleted file mode 100644 index f26563ee..00000000 --- a/src/main/asciidoc/partwebsvcs.adoc +++ /dev/null @@ -1,17 +0,0 @@ -= Web Services - -Part VI explores web services. - -:leveloffset: +1 - -include::webservices-intro/webservices-intro.adoc[] - -include::jaxws/jaxws.adoc[] - -include::jaxrs/jaxrs.adoc[] - -include::jaxrs-client/jaxrs-client.adoc[] - -include::jaxrs-advanced/jaxrs-advanced.adoc[] - -:leveloffset: -1 diff --git a/src/main/asciidoc/partwebtier.adoc b/src/main/asciidoc/partwebtier.adoc deleted file mode 100644 index b949eccf..00000000 --- a/src/main/asciidoc/partwebtier.adoc +++ /dev/null @@ -1,41 +0,0 @@ -= The Web Tier - -Part III explores the technologies in the web tier. - -:leveloffset: +1 - -include::webapp/webapp.adoc[] - -include::faces-intro/faces-intro.adoc[] - -include::faces-facelets/faces-facelets.adoc[] - -include::faces-el/faces-el.adoc[] - -include::faces-page/faces-page.adoc[] - -include::faces-page-core/faces-page-core.adoc[] - -include::faces-develop/faces-develop.adoc[] - -include::faces-ajax/faces-ajax.adoc[] - -include::faces-advanced-cc/faces-advanced-cc.adoc[] - -include::faces-custom/faces-custom.adoc[] - -include::faces-configure/faces-configure.adoc[] - -include::faces-ws/faces-ws.adoc[] - -include::servlets/servlets.adoc[] - -include::websocket/websocket.adoc[] - -include::jsonp/jsonp.adoc[] - -include::jsonb/jsonb.adoc[] - -include::webi18n/webi18n.adoc[] - -:leveloffset: -1 diff --git a/src/main/asciidoc/preface.adoc b/src/main/asciidoc/preface.adoc deleted file mode 100644 index ed573526..00000000 --- a/src/main/asciidoc/preface.adoc +++ /dev/null @@ -1,90 +0,0 @@ -[preface] -== 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(TM) Tutorials https://docs.oracle.com/javase/tutorial/index.html[^]. - -=== Related Documentation - -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. - -[width="99%",cols="20%,38%,37%"] -|=== -|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. - -[width="99%",cols="20%,38%,38%"] -|=== -|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` -|=== diff --git a/src/main/asciidoc/servlets/servlets001.adoc b/src/main/asciidoc/servlets/servlets001.adoc deleted file mode 100644 index cb930291..00000000 --- a/src/main/asciidoc/servlets/servlets001.adoc +++ /dev/null @@ -1,10 +0,0 @@ -== What Is a Servlet? - -A servlet is a Java programming language class used to extend the capabilities of servers that host applications accessed by means of a request-response programming model. -Although servlets can respond to any type of request, they are commonly used to extend the applications hosted by web servers. -For such applications, Jakarta Servlet technology defines HTTP-specific servlet classes. - -The `jakarta.servlet` and `jakarta.servlet.http` packages provide interfaces and classes for writing servlets. -All servlets must implement the `Servlet` interface, which defines lifecycle methods. -When implementing a generic service, you can use or extend the `GenericServlet` class provided with the Jakarta Servlet API. -The `HttpServlet` class provides methods, such as `doGet` and `doPost`, for handling HTTP-specific services. diff --git a/src/main/asciidoc/servlets/servlets003.adoc b/src/main/asciidoc/servlets/servlets003.adoc deleted file mode 100644 index 3b94f985..00000000 --- a/src/main/asciidoc/servlets/servlets003.adoc +++ /dev/null @@ -1,58 +0,0 @@ -== Sharing Information - -Web components, like most objects, usually work with other objects to accomplish their tasks. -Web components can do so by doing the following. - -* Using private helper objects (for example, JavaBeans components). - -* Sharing objects that are attributes of a public scope. - -* Using a database. - -* Invoking other web resources. -The Jakarta Servlet technology mechanisms that allow a web component to invoke other web resources are described in <>. - -=== Using Scope Objects - -Collaborating web components share information by means of objects that are maintained as attributes of four scope objects. -You access these attributes by using the `getAttribute` and `setAttribute` methods of the class representing the scope. -<> lists the scope objects. - -[[scope-objects]] -.Scope Objects -[width="90%",cols="15%,25%,50%"] -|=== -|Scope Object |Class |Accessible From - -|Web context |`jakarta.servlet.ServletContext` |Web components within a web context. -See <>. - -|Session |`jakarta.servlet.http.HttpSession` |Web components handling a request that belongs to the session. -See <>. - -|Request |Subtype of `jakarta.servlet.ServletRequest` |Web components handling the request. - -|Page |`jakarta.servlet.jsp.JspContext` |The Jakarta Server Pages page that creates the object. -|=== - -=== Controlling Concurrent Access to Shared Resources - -In a multithreaded server, shared resources can be accessed concurrently. -In addition to scope object attributes, shared resources include in-memory data, such as instance or class variables, and external objects, such as files, database connections, and network connections. - -Concurrent access can arise in several situations. - -* Multiple web components accessing objects stored in the web context. - -* Multiple web components accessing objects stored in a session. - -* Multiple threads within a web component accessing instance variables. - -A web container will typically create a thread to handle each request. -To ensure that a servlet instance handles only one request at a time, a servlet can implement the `SingleThreadModel` interface. -If a servlet implements this interface, no two threads will execute concurrently in the servlet's service method. -A web container can implement this guarantee by synchronizing access to a single instance of the servlet or by maintaining a pool of web component instances and dispatching each new request to a free instance. -This interface does not prevent synchronization problems that result from web components' accessing shared resources, such as static class variables or external objects. - -When resources can be accessed concurrently, they can be used in an inconsistent fashion. -You prevent this by controlling the access using the synchronization techniques described in the Threads lesson at https://docs.oracle.com/javase/tutorial/essential/concurrency/[^]. diff --git a/src/main/asciidoc/title.adoc b/src/main/asciidoc/title.adoc deleted file mode 100644 index 7402ecfd..00000000 --- a/src/main/asciidoc/title.adoc +++ /dev/null @@ -1,24 +0,0 @@ -[subs="normal"] ----- -{doctitle} - -Version: {revnumber} - -Status: {revremark} - -Release: {revdate} ----- - -Copyright (C) 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. diff --git a/src/main/asciidoc/webapp/webapp001.adoc b/src/main/asciidoc/webapp/webapp001.adoc deleted file mode 100644 index e7325a6c..00000000 --- a/src/main/asciidoc/webapp/webapp001.adoc +++ /dev/null @@ -1,46 +0,0 @@ -== Web Applications - -A web application is a dynamic extension of a web or application server. -Web applications are of the following types: - -Presentation-oriented:: -A presentation-oriented web application generates interactive web pages containing various types of markup language (HTML, XHTML, XML, and so on) and dynamic content in response to requests. -Development of presentation-oriented web applications is covered in xref:jakarta-faces-technology-2[xrefstyle=full] through xref:jakarta-servlet-technology-2[xrefstyle=full] - -Service-oriented:: -A service-oriented web application implements the endpoint of a web service. -Presentation-oriented applications are often clients of service-oriented web applications. -Development of service-oriented web applications is covered in xref:building-web-services-with-jakarta-xml-web-services[xrefstyle=full] and xref:building-restful-web-services-with-jakarta-rest[xrefstyle=full] in xref:web-services[xrefstyle=full] - -In the Jakarta EE platform, web components provide the dynamic extension capabilities for a web server. -Web components can be Jakarta servlets, web pages implemented with Jakarta Faces technology, web service endpoints, or Jakarta Server Pages. -xref:jakarta-web-application-request-handling[xrefstyle=short] illustrates the interaction between a web client and a web application that uses a servlet. -The client sends an HTTP request to the web server. -A web server that implements Jakarta Servlet and Jakarta Server Pages technology converts the request into an `HTTPServletRequest` object. -This object is delivered to a web component, which can interact with JavaBeans components or a database to generate dynamic content. -The web component can then generate an `HTTPServletResponse` or can pass the request to another web component. -A web component eventually generates a `HTTPServletResponse` object. -The web server converts this object to an HTTP response and returns it to the client. - -[[jakarta-web-application-request-handling]] -.Jakarta Web Application Request Handling -image::jakartaeett_dt_013.svg["Diagram of web application request handling. Clients and servlets communicate using HttpServletRequest and HttpServletResponse."] - -Servlets are Java programming language classes that dynamically process requests and construct responses. -Java technologies, such as Jakarta Faces and Facelets, are used for building interactive web applications. -(Frameworks can also be used for this purpose.) -Although servlets and Jakarta Faces and Facelets pages can be used to accomplish similar things, each has its own strengths. -Servlets are best suited for service-oriented applications (web service endpoints can be implemented as servlets) and the control functions of a presentation-oriented application, such as dispatching requests and handling nontextual data. -Jakarta Faces and Facelets pages are more appropriate for generating text-based markup, such as XHTML, and are generally used for presentation-oriented applications. - -Web components are supported by the services of a runtime platform called a web container. -A web container provides such services as request dispatching, security, concurrency, and lifecycle management. -A web container also gives web components access to such APIs as naming, transactions, and email. - -Certain aspects of web application behavior can be configured when the application is installed, or deployed, to the web container. -The configuration information can be specified using Jakarta EE annotations or can be maintained in a text file in XML format called a web application deployment descriptor (DD). -A web application DD must conform to the schema described in the Jakarta Servlet specification. - -This chapter gives a brief overview of the activities involved in developing web applications. -First, it summarizes the web application lifecycle and explains how to package and deploy very simple web applications on GlassFish Server. -The chapter then moves on to configuring web applications and discusses how to specify the most commonly used configuration parameters. diff --git a/src/main/asciidoc/webapp/webapp002.adoc b/src/main/asciidoc/webapp/webapp002.adoc deleted file mode 100644 index 3bb0a473..00000000 --- a/src/main/asciidoc/webapp/webapp002.adoc +++ /dev/null @@ -1,32 +0,0 @@ -== Web Application Lifecycle - -A web application consists of web components; static resource files, such as images and cascading style sheets (CSS); and helper classes and libraries. -The web container provides many supporting services that enhance the capabilities of web components and make them easier to develop. -However, because a web application must take these services into account, the process for creating and running a web application is different from that of traditional stand-alone Java classes. - -The process for creating, deploying, and executing a web application can be summarized as follows: - -. Develop the web component code. - -. Develop the web application deployment descriptor, if necessary. - -. Compile the web application components and helper classes referenced by the components. - -. Optionally, package the application into a deployable unit. - -. Deploy the application into a web container. - -. Access a URL that references the web application. - -Developing web component code is covered in the later chapters. -Steps 2 through 6 are expanded on in the following sections and illustrated with a Hello, World–style, presentation-oriented application. -This application allows a user to enter a name into an HTML form and then displays a greeting after the name is submitted. - -The Hello application contains two web components that generate the greeting and the response. -This chapter discusses the following simple applications: - -* `hello1`, a Jakarta Faces technology–based application that uses two XHTML pages and a managed bean - -* `hello2`, a servlet-based web application in which the components are implemented by two servlet classes - -The applications are used to illustrate tasks involved in packaging, deploying, configuring, and running an application that contains web components. diff --git a/src/main/asciidoc/webapp/webapp003.adoc b/src/main/asciidoc/webapp/webapp003.adoc deleted file mode 100644 index ec1a7066..00000000 --- a/src/main/asciidoc/webapp/webapp003.adoc +++ /dev/null @@ -1,359 +0,0 @@ -== A Web Module That Uses Jakarta Faces Technology: The hello1 Example - -The `hello1` application is a web module that uses Jakarta Faces technology to display a greeting and response. -You can use a text editor to view the application files, or you can use NetBeans IDE. - -The source code for this application is in the `_tut-install_/examples/web/faces/hello1/` directory. - -=== To View the hello1 Web Module Using NetBeans IDE - -To view the `hello1` web module using NetBeans IDE: - -. From the *File* menu, choose *Open Project*. - -. In the Open Project dialog box, navigate to: -+ ----- -tut-install/examples/web/faces ----- - -. Select the `hello1` folder and click *Open Project*. - -. Expand the *Web Pages* node and double-click the `index.xhtml` file to view it in the editor. -+ -The `index.xhtml` file is the default landing page for a Facelets application. -In a typical Facelets application, web pages are created in XHTML. -For this application, the page uses simple tag markup to display a form with a graphic image, a header, a field, and two command buttons: -+ -[source,xml] ----- - - - - Facelets Hello Greeting - - - - -

    Hello, my name is Duke. What's yours?

    - -

    - - - - -     - ... -     - ----- -+ -The most complex element on the page is the `inputText` field. -The `maxlength` attribute specifies the maximum length of the field. -The `required` attribute specifies that the field must be filled out; the `requiredMessage` attribute provides the error message to be displayed if the field is left empty. -The `title` attribute provides the text to be used by screen readers for the visually disabled. -Finally, the `value` attribute contains an expression that will be provided by the `Hello` managed bean. -+ -The web page connects to the `Hello` managed bean through the Expression Language (EL) value expression `#{hello.name}`, which retrieves the value of the `name` property from the managed bean. -Note the use of `hello` to reference the managed bean `Hello`. -If no name is specified in the `@Named` annotation of the managed bean, the managed bean is always accessed with the first letter of the class name in lowercase. -+ -The Submit `commandButton` element specifies the action as `response`, meaning that when the button is clicked, the `response.xhtml` page is displayed. - -. Double-click the `response.xhtml` file to view it. -+ -The response page appears.Even simpler than the greeting page, the response page contains a graphic image, a header that displays the expression provided by the managed bean, and a single button whose `action` element transfers you back to the `index.xhtml` page: -+ -[source,xml] ----- - - - - Facelets Hello Response - - - - -

    Hello, #{hello.name}!

    -

    - -     -     - ----- - -. Expand the Source Packages node, then the `ee.jakarta.tutorial.hello1` node. - -. [[hello1-nb-step-7, Step 7]] Double-click the `Hello.java` file to view it. -+ -The `Hello` class, called a managed bean class, provides getter and setter methods for the `name` property used in the Facelets page expressions. -By default, the expression language refers to the class name, with the first letter in lowercase (`hello.name`). -+ -[source,java] ----- -package ee.jakarta.tutorial.hello1; - -import jakarta.enterprise.context.RequestScoped; -import jakarta.inject.Named; - -@Named -@RequestScoped -public class Hello { - - private String name; - - public Hello() { - } - - public String getName() { - return name; - } - - public void setName(String user_name) { - this.name = user_name; - } -} ----- -+ -If you use the default name for the bean class, you can specify `@Model` as the annotation instead of having to specify both `@Named` and `@RequestScoped`. -The `@Model` annotation is called a stereotype, a term for an annotation that encapsulates other annotations. -It is described later in <>. -Some examples will use `@Model` where it is appropriate. - -. Under the Web Pages node, expand the WEB-INF node and double-click the `web.xml` file to view it. -+ -The `web.xml` file contains several elements that are required for a Facelets application. -All of the following are created automatically when you use NetBeans IDE to create an application. - -* A context parameter specifying the project stage: -+ -[source,xml] ----- - - jakarta.faces.PROJECT_STAGE - Development - ----- -+ -A context parameter provides configuration information needed by a web application. -An application can define its own context parameters. -In addition, Jakarta Faces technology and Jakarta Servlet technology define context parameters that an application can use. - -* A `servlet` element and its `servlet-mapping` element specifying the `FacesServlet`. All files with the `.xhtml` suffix will be matched: -+ -[source,xml] ----- - - Faces Servlet - jakarta.faces.webapp.FacesServlet - 1 - - - Faces Servlet - *.xhtml - ----- - -* A `welcome-file-list` element specifying the location of the landing page: -+ -[source,xml] ----- - - index.xhtml - ----- - -==== Introduction to Scopes - -In the `Hello.java` class, the annotations `jakarta.inject.Named` and `jakarta.enterprise.context.RequestScoped` identify the class as a managed bean using request scope. -Scope defines how application data persists and is shared. - -The most commonly used scopes in Jakarta Faces applications are the following: - -Request (`@RequestScoped`):: Request scope persists during a single HTTP request in a web application. -In an application like `hello1`, in which the application consists of a single request and response, the bean uses request scope. - -Session (`@SessionScoped`):: Session scope persists across multiple HTTP requests in a web application. -When an application consists of multiple requests and responses where data needs to be maintained, beans use session scope. - -Application (`@ApplicationScoped`):: Application scope persists across all users' interactions with a web application. - -For more information on scopes in Jakarta Faces technology, see <>. - -=== Packaging and Deploying the hello1 Web Module - -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: - -* Using NetBeans IDE - -* Using the `asadmin` command - -* Using the Administration Console - -* Copying the WAR file into the `_domain-dir_/autodeploy/` directory - -Throughout the tutorial, you will use NetBeans IDE or Maven for packaging and deploying. - -==== To Build, Package and Deploy the hello1 Web Module Using NetBeans IDE - -To build and package the `hello1` web module using NetBeans IDE: - -. Start GlassFish Server as described in <>, if you have not already done so. - -. From the *File* menu, choose *Open Project*. - -. In the Open Project dialog box, navigate to: -+ ----- -tut-install/examples/web/faces ----- - -. Select the `hello1` folder. - -. Click *Open Project*. - -. In the *Projects* tab, right-click the `hello1` project and select *Build*. This command deploys the project to the server. - -==== To Build, Package and Deploy the hello1 Web Module Using Maven - -To build and package the `hello1` web module using Maven: - -. Start GlassFish Server as described in <>, if you have not already done so. - -. In a terminal window, go to: -+ ----- -tut-install/examples/web/faces/hello1/ ----- - -. Enter the following command: -+ -[source,shell] ----- -mvn install ----- -+ -This command spawns any necessary compilations and creates the WAR file in `_tut-install_/examples/web/faces/hello1/target/`. -It then deploys the project to the server. - -=== Viewing Deployed Web Modules - -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. - -==== To View Deployed Web Modules Using the Administration Console - -To view deployed web modules using the Administration Console: - -. Open the URL http://localhost:4848/[^] in a browser. - -. Select the Applications node. -+ -The deployed web modules appear in the Deployed Applications table. - -==== To View Deployed Web Modules Using the asadmin Command - -Enter the following command: - -[source,shell] ----- -asadmin list-applications ----- - -==== To View Deployed Web Modules Using NetBeans IDE - -To view deployed web modules using NetBeans IDE: - -. In the *Services* tab, expand the *Servers* node, then expand the *GlassFish Server* node. - -. Expand the *Applications* node to view the deployed modules. - -=== Running the Deployed hello1 Web Module - -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: - -. Open a web browser. - -. Enter the following URL: -+ ----- -http://localhost:8080/hello1/ ----- - -. In the field, enter your name and click Submit. -+ -The response page displays the name you submitted. Click Back to try again. - -==== Dynamic Reloading of Deployed Modules - -If dynamic reloading is enabled, you do not have to redeploy an application or module when you change its code or deployment descriptors. -All you have to do is copy the changed pages or class files into the deployment directory for the application or module. -The deployment directory for a web module named context-root is `_domain-dir_/applications/_context-root_`. -The server checks for changes periodically and redeploys the application, automatically and dynamically, with the changes. - -This capability is useful in a development environment because it allows code changes to be tested quickly. -Dynamic reloading is not recommended for a production environment, however, because it may degrade performance. -In addition, whenever a reload takes place, the sessions at that time become invalid, and the client must restart the session. - -In GlassFish Server, dynamic reloading is enabled by default. - -=== Undeploying the hello1 Web Module - -You can undeploy web modules and other types of enterprise applications by using either NetBeans IDE or Maven. - -==== To Undeploy the hello1 Web Module Using NetBeans IDE - -To undeploy the `hello1` web module using NetBeans IDE: - -. In the *Services* tab, expand the *Servers* node, then expand the *GlassFish Server* node. - -. Expand the *Applications* node. - -. Right-click the `hello1` module and select *Undeploy*. - -. To delete the class files and other build artifacts, go back to the *Projects* tab, right-click the project, and select *Clean*. - -==== To Undeploy the hello1 Web Module Using Maven - -To undeploy the `hello1` web module using Maven: - -. In a terminal window, go to: -+ ----- -tut-install/examples/web/faces/hello1/ ----- - -. Enter the following command: -+ -[source,shell] ----- -mvn cargo:undeploy ----- - -. To delete the class files and other build artifacts, enter the following command: -+ -[source,shell] ----- -mvn clean ----- diff --git a/src/main/asciidoc/webapp/webapp004.adoc b/src/main/asciidoc/webapp/webapp004.adoc deleted file mode 100644 index 0d8b06ff..00000000 --- a/src/main/asciidoc/webapp/webapp004.adoc +++ /dev/null @@ -1,202 +0,0 @@ -== A Web Module That Uses Jakarta Servlet Technology: The hello2 Example - -The `hello2` application is a web module that uses Jakarta Servlet technology to display a greeting and response. -You can use a text editor to view the application files, or you can use NetBeans IDE. - -The source code for this application is in the `_tut-install_/examples/web/servlet/hello2/` directory. - -=== Mapping URLs to Web Components - -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: - ----- -http://host:port/context-root[/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`: - -[source,java] ----- -@WebServlet("/greeting") -public class GreetingServlet extends HttpServlet { - ... -} ----- - -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: - ----- -http://localhost:8080/hello2/greeting ----- - -To access the servlet by using only the context root, specify `"/"` as the URL pattern. - -=== Examining the hello2 Web Module - -The `hello2` application behaves almost identically to the `hello1` application, but it is implemented using Jakarta Servlet technology instead of Jakarta Faces technology. -You can use a text editor to view the application files, or you can use NetBeans IDE. - -==== To View the hello2 Web Module Using NetBeans IDE - -To view the `hello2` web module using NetBeans IDE: - -. From the *File* menu, choose *Open Project*. - -. In the Open Project dialog box, navigate to: -+ ----- -tut-install/examples/web/servlet ----- - -. Select the `hello2` folder and click *Open Project*. - -. Expand the *Source Packages* node, then expand the `ee.jakarta.tutorial.hello2` node. - -. Double-click the `GreetingServlet.java` file to view it. -+ -This servlet overrides the `doGet` method, implementing the `GET` method of HTTP. -The servlet displays a simple HTML greeting form whose Submit button, like that of `hello1`, specifies a response page for its action. -The following excerpt begins with the `@WebServlet` annotation, which specifies the URL pattern relative to the context root: -+ -[source,java] ----- -@WebServlet("/greeting") -public class GreetingServlet extends HttpServlet { - - @Override - public void doGet(HttpServletRequest request, - HttpServletResponse response) - throws ServletException, IOException { - - response.setContentType("text/html"); - response.setBufferSize(8192); - try (PrintWriter out = response.getWriter()) { - out.println("" - + "Servlet Hello"); - - // then write the data of the response - out.println("" - + "" - + "" - + "

    Hello, my name is Duke. What's yours?

    " - + "" - + "

    " - + "" - + "" - + ""); - - String username = request.getParameter("username"); - if (username != null && username.length() > 0) { - RequestDispatcher dispatcher = - getServletContext().getRequestDispatcher("/response"); - - if (dispatcher != null) { - dispatcher.include(request, response); - } - } - out.println(""); - } - } - ... -} ----- - -. Double-click the `ResponseServlet.java` file to view it. -+ -This servlet also overrides the `doGet` method, displaying only the response. -The following excerpt begins with the `@WebServlet` annotation, which specifies the URL pattern relative to the context root: -+ -[source,java] ----- -@WebServlet("/response") -public class ResponseServlet extends HttpServlet { - - @Override - public void doGet(HttpServletRequest request, - HttpServletResponse response) - throws ServletException, IOException { - try (PrintWriter out = response.getWriter()) { - - // then write the data of the response - String username = request.getParameter("username"); - if (username != null && username.length() > 0) { - out.println("

    Hello, " + username + "!

    "); - } - } - } - ... -} ----- - -=== Running the hello2 Example - -You can use either NetBeans IDE or Maven to build, package, deploy, and run the `hello2` example. - -==== To Build, Package, Deploy and Run the hello2 Example Using NetBeans IDE - -To build, package, deploy and run the `hello2` example using NetBeans IDE: - -. Start GlassFish Server as described in <>, if you have not already done so. - -. From the *File* menu, choose *Open Project*. - -. In the Open Project dialog box, navigate to: -+ ----- -tut-install/examples/web/servlet ----- - -. Select the `hello2` folder. - -. Click *Open Project*. - -. In the *Projects* tab, right-click the `hello2` project and select *Build* to package and deploy the project. - -. In a web browser, open the following URL: -+ ----- -http://localhost:8080/hello2/greeting ----- -+ -The URL specifies the context root, followed by the URL pattern. -+ -The application looks much like the `hello1` application. -The major difference is that after you click Submit the response appears below the greeting, not on a separate page. - -==== To Build, Package, Deploy and Run the hello2 Example Using Maven - -To build, package, deploy and run the `hello2` example using Maven: - -. Start GlassFish Server as described in <>, if you have not already done so. - -. In a terminal window, go to: -+ ----- -tut-install/examples/web/servlet/hello2/ ----- - -. Enter the following command: -+ -[source,shell] ----- -mvn install ----- -+ -This target builds the WAR file, copies it to the `_tut-install_/examples/web/hello2/target/` directory, and deploys it. - -. In a web browser, open the following URL: -+ ----- -http://localhost:8080/hello2/greeting ----- -+ -The URL specifies the context root, followed by the URL pattern. -+ -The application looks much like the `hello1` application. -The major difference is that after you click Submit the response appears below the greeting, not on a separate page. diff --git a/src/main/asciidoc/webapp/webapp005.adoc b/src/main/asciidoc/webapp/webapp005.adoc deleted file mode 100644 index 1dda42fa..00000000 --- a/src/main/asciidoc/webapp/webapp005.adoc +++ /dev/null @@ -1,225 +0,0 @@ -== Configuring Web Applications - -This section describes the following tasks involved with configuring web applications: - -* Setting context parameters - -* Declaring welcome files - -* Mapping errors to error screens - -* Declaring resource references - -=== Setting Context Parameters - -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 <>. - -==== To Add a Context Parameter Using NetBeans IDE - -These steps apply generally to web applications but do not apply specifically to the examples in this chapter. - -To add a context parameter using NetBeans IDE: - -. Open the project. - -. Expand the project's node in the *Projects* tree. - -. Expand the *Web Pages* node and then the *WEB-INF* node. - -. Double-click `web.xml`. -+ -If the project does not have a `web.xml` file, create one by following the steps in <>. - -. Click *General* at the top of the editor window. - -. Expand the *Context Parameters* node. - -. Click *Add*. - -. In the *Add Context Parameter* dialog box, in the *Parameter Name* field, enter the name that specifies the context object. - -. In the *Parameter Value* field, enter the parameter to pass to the context object. - -. Click *OK*. - -==== To Create a web.xml File Using NetBeans IDE - -To create a `web.xml` file using NetBeans IDE: - -. From the *File* menu, choose *New File*. - -. In the New File wizard, select the *Web* category, then select *Standard Deployment Descriptor* under *File Types*. - -. Click *Next*. - -. Click *Finish*. -+ -A basic `web.xml` file appears in `web/WEB-INF/`. - -=== Declaring Welcome Files - -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: - -[source,xml] ----- - - index.xhtml - ----- - -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`. - -=== Mapping Errors to Error Screens - -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. - -==== To Set Up Error Mapping Using NetBeans IDE - -These steps apply generally to web applications but do not apply specifically to the examples in this chapter. - -To set up error mapping using NetBeans IDE: - -. Open the project. - -. Expand the project's node in the *Projects* tab. - -. Expand the *Web Pages* node and then the *WEB-INF* node. - -. Double-click `web.xml`. -+ -If the project does not have a `web.xml` file, create one by following the steps in <>. - -. Click *Pages* at the top of the editor window. - -. Expand the *Error Pages* node. - -. Click *Add*. - -. In the Add Error Page dialog box, click *Browse* to locate the page that you want to act as the error page. - -. Specify either an error code or an exception type. -+ -* To specify an error code, in the Error Code field enter the HTTP status code that will cause the error page to be opened, or leave the field blank to include all error codes. - -* To specify an exception type, in the Exception Type field enter the exception that will cause the error page to load. To specify all throwable errors and exceptions, enter `java.lang.Throwable`. - -. Click *OK*. - -=== Declaring Resource References - -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 xref:web-components-that-accept-resource-injections[xrefstyle=short]. - -This section explains how to use a couple of the annotations supported by a web container to inject resources. -xref:running-the-persistence-examples[xrefstyle=full], explains how web applications use annotations supported by Jakarta Persistence. -xref:getting-started-securing-web-applications[xrefstyle=full], explains how to use annotations to specify information about securing web applications. -See xref:resource-adapters-and-contracts[xrefstyle=full], for more information on resources. - -[[web-components-that-accept-resource-injections]] -.Web Components That Accept Resource Injections -[width="50%",cols="20%,30%"] -|=== -|Component |Interface/Class - -|Servlets |`jakarta.servlet.Servlet` - -|Servlet filters |`jakarta.servlet.ServletFilter` - -|Event listeners | `jakarta.servlet.ServletContextListener` - -`jakarta.servlet.ServletContextAttributeListener` - -`jakarta.servlet.ServletRequestListener` - -`jakarta.servlet.ServletRequestAttributeListener` - -`jakarta.servlet.http.HttpSessionListener` - -`jakarta.servlet.http.HttpSessionAttributeListener` - -`jakarta.servlet.http.HttpSessionBindingListener` - -|Managed beans |Plain Old Java Objects -|=== - -==== Declaring a Reference to a Resource - -The `@Resource` annotation is used to declare a reference to a resource, such as a data source, an enterprise bean, or an environment entry. - -The `@Resource` annotation is specified on a class, a method, or a field. -The container is responsible for injecting references to resources declared by the `@Resource` annotation and mapping it to the proper JNDI resources. - -In the following example, the `@Resource` annotation is used to inject a data source into a component that needs to make a connection to the data source, as is done when using JDBC technology to access a relational database: - -[source,java] ----- -@Resource javax.sql.DataSource catalogDS; -public getProductsByCategory() { - // get a connection and execute the query - Connection conn = catalogDS.getConnection(); - ... -} ----- - -The container injects this data source prior to the component's being made available to the application. -The data source JNDI mapping is inferred from the field name, `catalogDS`, and the type, `javax.sql.DataSource`. - -If you have multiple resources that you need to inject into one component, you need to use the `@Resources` annotation to contain them, as shown by the following example: - -[source,java] ----- -@Resources ({ - @Resource(name="myDB" type=javax.sql.DataSource.class), - @Resource(name="myMQ" type=jakarta.jms.ConnectionFactory.class) -}) ----- - -The web application examples in this tutorial use Jakarta Persistence to access relational databases. -This API does not require you to explicitly create a connection to a data source. -Therefore, the examples do not use the `@Resource` annotation to inject a data source. -However, this API supports the `@PersistenceUnit` and `@PersistenceContext` annotations for injecting `EntityManagerFactory` and `EntityManager` instances, respectively. -<> describes these annotations and the use of the Jakarta Persistence in web applications. - -==== Declaring a Reference to a Web Service - -The `@WebServiceRef` annotation provides a reference to a web service. -The following example shows uses the `@WebServiceRef` annotation to declare a reference to a web service. -`WebServiceRef` uses the `wsdlLocation` element to specify the URI of the deployed service's WSDL file: - -[source,java] ----- -... -import jakarta.xml.ws.WebServiceRef; -... -public class ResponseServlet extends HTTPServlet { -@WebServiceRef(wsdlLocation="http://localhost:8080/helloservice/hello?wsdl") -static HelloService service; ----- diff --git a/src/main/asciidoc/webapp/webapp006.adoc b/src/main/asciidoc/webapp/webapp006.adoc deleted file mode 100644 index 46a9eac6..00000000 --- a/src/main/asciidoc/webapp/webapp006.adoc +++ /dev/null @@ -1,9 +0,0 @@ -== Further Information about Web Applications - -For more information on web applications, see - -* Jakarta Faces 3.0 specification: + -https://jakarta.ee/specifications/faces/3.0/[^] - -* Jakarta Servlet 5.0 specification: + -https://jakarta.ee/specifications/servlet/5.0/[^] diff --git a/src/main/asciidoc/webservices-intro/webservices-intro.adoc b/src/main/asciidoc/webservices-intro/webservices-intro.adoc deleted file mode 100644 index 64cb5d5d..00000000 --- a/src/main/asciidoc/webservices-intro/webservices-intro.adoc +++ /dev/null @@ -1,10 +0,0 @@ -= Introduction to Web Services - -This part of the tutorial discusses Jakarta EE web services technologies. -These technologies include Jakarta XML Web Services and Jakarta RESTful Web Services. - -include::webservices-intro001.adoc[] - -include::webservices-intro002.adoc[] - -include::webservices-intro003.adoc[] diff --git a/src/main/asciidoc/webservices-intro/webservices-intro001.adoc b/src/main/asciidoc/webservices-intro/webservices-intro001.adoc deleted file mode 100644 index d07eb82c..00000000 --- a/src/main/asciidoc/webservices-intro/webservices-intro001.adoc +++ /dev/null @@ -1,7 +0,0 @@ -== What Are Web Services? - -Web services are client and server applications that communicate over the World Wide Web's (WWW) HyperText Transfer Protocol (HTTP). -As described by the World Wide Web Consortium (W3C), web services provide a standard means of interoperating between software applications running on a variety of platforms and frameworks. -Web services are characterized by their great interoperability and extensibility as well as their machine-processable descriptions, thanks to the use of XML. -Web services can be combined in a loosely coupled way to achieve complex operations. -Programs providing simple services can interact with each other to deliver sophisticated added-value services. diff --git a/src/main/asciidoc/webservices-intro/webservices-intro002.adoc b/src/main/asciidoc/webservices-intro/webservices-intro002.adoc deleted file mode 100644 index 00e1e583..00000000 --- a/src/main/asciidoc/webservices-intro/webservices-intro002.adoc +++ /dev/null @@ -1,69 +0,0 @@ -== Types of Web Services - -On the conceptual level, a service is a software component provided through a network-accessible endpoint. -The service consumer and provider use messages to exchange invocation request and response information in the form of self-containing documents that make very few assumptions about the technological capabilities of the receiver. - -On a technical level, web services can be implemented in various ways. -The two types of web services discussed in this section can be distinguished as "big" web services and "RESTful" web services. - -=== "Big" Web Services - -Jakarta XML Web Services provides the functionality for "big" web services, which are described in xref:building-web-services-with-jakarta-xml-web-services[xrefstyle=full]. -Big web services use XML messages that follow the Simple Object Access Protocol (SOAP) standard, an XML language defining a message architecture and message formats. -Such systems often contain a machine-readable description of the operations offered by the service, written in the Web Services Description Language (WSDL), an XML language for defining interfaces syntactically. - -[NOTE] -Historically the Java API for XML Web Services (JAX-WS) was moved to Java SE 8 but was later removed in Java SE 11. -Jakarta XML Web Services is now included in the Jakarta EE platform as an optional technology under the `jakarta` namespace. - -The SOAP message format and the WSDL interface definition language have gained widespread adoption. -Many development tools, such as NetBeans IDE, can reduce the complexity of developing web service applications. - -A SOAP-based design must include the following elements. - -* A formal contract must be established to describe the interface that the web service offers. -WSDL can be used to describe the details of the contract, which may include messages, operations, bindings, and the location of the web service. -You may also process SOAP messages in a JAX-WS service without publishing a WSDL. - -* The architecture must address complex nonfunctional requirements. -Many web service specifications address such requirements and establish a common vocabulary for them. -Examples include transactions, security, addressing, trust, coordination, and so on. - -* The architecture needs to handle asynchronous processing and invocation. -In such cases, the infrastructure provided by standards, such as Web Services Reliable Messaging (WSRM), and APIs, such as JAX-WS, with their client-side asynchronous invocation support, can be leveraged out of the box. - -=== RESTful Web Services - -In Jakarta EE, Jakarta RESTful Web Services provides the functionality for Representational State Transfer (RESTful) web services. -REST is well suited for basic, ad hoc integration scenarios. -RESTful web services, often better integrated with HTTP than SOAP-based services are, do not require XML messages or WSDL service-API definitions. - -Project Jersey is a production-ready implementation for the Jakarta RESTful Web Services specification. -Jersey implements support for the annotations defined in the Jakarta RESTful Web Services specification, making it easy for developers to build RESTful web services with Java and the Java Virtual Machine (JVM). - -Because RESTful web services use existing well-known W3C and Internet Engineering Task Force (IETF) standards (HTTP, XML, URI, MIME) and have a lightweight infrastructure that allows services to be built with minimal tooling, developing RESTful web services is inexpensive and thus has a very low barrier for adoption. -You can use a development tool such as NetBeans IDE to further reduce the complexity of developing RESTful web services. - -A RESTful design may be appropriate when the following conditions are met. - -* The web services are completely stateless. -A good test is to consider whether the interaction can survive a restart of the server. - -* A caching infrastructure can be leveraged for performance. -If the data that the web service returns is not dynamically generated and can be cached, the caching infrastructure that web servers and other intermediaries inherently provide can be leveraged to improve performance. -However, the developer must take care because such caches are limited to the HTTP `GET` method for most servers. - -* The service producer and service consumer have a mutual understanding of the context and content being passed along. -Because there is no formal way to describe the web services interface, both parties must agree out of band on the schemas that describe the data being exchanged and on ways to process it meaningfully. -In the real world, most commercial applications that expose services as RESTful implementations also distribute so-called value-added toolkits that describe the interfaces to developers in popular programming languages. - -* Bandwidth is particularly important and needs to be limited. -REST is particularly useful for limited-profile devices, such as PDAs and mobile phones, for which the overhead of headers and additional layers of SOAP elements on the XML payload must be restricted. - -* Web service delivery or aggregation into existing websites can be enabled easily with a RESTful style. -Developers can use such technologies as JAX-RS and Asynchronous JavaScript with XML (Ajax) and such toolkits as Direct Web Remoting (DWR) to consume the services in their web applications. -Rather than starting from scratch, services can be exposed with XML and consumed by HTML pages without significantly refactoring the existing website architecture. -Existing developers will be more productive because they are adding to something they are already familiar with rather than having to start from scratch with new technology. - -RESTful web services are discussed in xref:building-restful-web-services-with-jakarta-rest[xrefstyle=full]. -This chapter contains information about generating the skeleton of a RESTful web service using both NetBeans IDE and the Maven project-management tool. diff --git a/src/main/asciidoc/webservices-intro/webservices-intro003.adoc b/src/main/asciidoc/webservices-intro/webservices-intro003.adoc deleted file mode 100644 index 7df56998..00000000 --- a/src/main/asciidoc/webservices-intro/webservices-intro003.adoc +++ /dev/null @@ -1,10 +0,0 @@ -== Deciding Which Type of Web Service to Use - -Basically, you want to use RESTful web services for integration over the web and big web services in enterprise application–integration scenarios that have advanced quality-of-service (QoS) requirements. - -Jakarta XML Web Services:: Addresses advanced QoS requirements that commonly occur in enterprise computing. -When compared to Jakarta RESTful Web Services, XML Web Services makes it easier to support the WS-* set of protocols, which provide standards for security and reliability, among other things, and interoperate with other WS-* conforming clients and servers. - -Jakarta RESTful Web Services:: Makes it easier to write web applications that apply some or all of the constraints of the REST style to induce desirable properties in the application, such as loose coupling (evolving the server is easier without breaking existing clients), scalability (start small and grow), and architectural simplicity (use off-the-shelf components, such as proxies or HTTP routers). -You would choose to use Jakarta RESTful Web Services for your web application because it is easier for many types of clients to consume RESTful web services while enabling the server side to evolve and scale. -Clients can choose to consume some or all aspects of the service and mash it up with other web-based services. diff --git a/src/main/jbake/assets/img/icons/computer.svg b/src/main/jbake/assets/img/icons/computer.svg deleted file mode 100644 index cb81e3be..00000000 --- a/src/main/jbake/assets/img/icons/computer.svg +++ /dev/null @@ -1,5124 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - image/svg+xml - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/src/main/ruby/autoxref-treeprocessor.rb b/src/main/ruby/autoxref-treeprocessor.rb deleted file mode 100644 index ca692baf..00000000 --- a/src/main/ruby/autoxref-treeprocessor.rb +++ /dev/null @@ -1,140 +0,0 @@ -# coding: utf-8 -# autoxref-treeprocessor.rb: Automatic cross-reference generator. -# -# Copyright (c) 2016, 2021 Takahiro Yoshimura -# All rights reserved. -# -# Redistribution and use in source and binary forms, with or without -# modification, are permitted provided that the following conditions -# are met: -# -# 1. Redistributions of source code must retain the above copyright -# notice, this list of conditions and the following disclaimer. -# -# 2. Redistributions in binary form must reproduce the above copyright -# notice, this list of conditions and the following disclaimer in the -# documentation and/or other materials provided with the distribution. -# -# 3. Neither the name of the copyright holder nor the names of its -# contributors may be used to endorse or promote products derived from -# this software without specific prior written permission. -# -# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS -# FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE -# COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, -# INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, -# BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; -# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER -# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN -# ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE -# POSSIBILITY OF SUCH DAMAGE. -require 'asciidoctor/extensions' - -include Asciidoctor - -Extensions.register do - treeprocessor AutoXrefTreeprocessor -end - -# A treeprocessor that allows refering sections and titled -# images/listings/tables with their reference number (e.g. Figure -# .1, .2, ... for images). -# -# Works by assigning reference number-based captions (RNBCs) for -# targets, and updates reference table in the document with them. -# -# Run using: -# -# asciidoctor -r ./lib/autoxref-treeprocessor.rb lib/autoxref-treeprocessor/sample.adoc -class AutoXrefTreeprocessor < Extensions::Treeprocessor - def process document - # The initial value of the chapter counter. - initial_chapter = attr_of(document, 'autoxref-chapter') { 1 } - - # The section level we should treat as chapters. - chapter_section_level = (document.attr 'autoxref-chaptersectlevel', 2).to_i - - # Captions should we use. - captions = { - :section => (document.attr 'autoxref-sectcaption', "Section %d.%d"), - :image => (document.attr 'autoxref-imagecaption', "Figure %d.%d"), - :listing => (document.attr 'autoxref-listingcaption', "Listing %d.%d"), - :table => (document.attr 'autoxref-tablecaption', "Table %d.%d") - } - - # Reference number counter. Reference numbers are reset by chapters. - counter = { - :chapter => initial_chapter, - :section => 1, - :image => 1, - :listing => 1, - :table => 1 - } - - seen = false - - # Scan for chapters. - document.find_by(context: :section).each do |chapter| - next unless not seen or chapter.numbered && chapter.level == chapter_section_level - seen = true - - # XXX crude care for chapterless documents - if chapter.level != chapter_section_level then - chapter = document - end - - # Assign chapter number and reset our reference numbers. - chap = attr_of(chapter, 'autoxref-chapter') { get_and_tally_counter_of(:chapter, counter) } - counter.update( - { - :section => 1, - :image => 1, - :listing => 1, - :table => 1 - } - ) - - # Scan for sections, titled images/listings/tables in the chapter. - [:section, :image, :listing, :table].each do |type| - chapter.find_by(context: type).each do |el| - # Generate RNBCs for eligible targets and update reference table in the document. For non-sections, we also overwrite their captions with RNBCs. - if type != :section then - if el.title? then - replaced = captions[type] % [chap, get_and_tally_counter_of(type, counter)] - replaced_caption = replaced + ' ' - el.attributes['caption'] = replaced_caption - el.attributes['reftext'] = replaced - el.caption = replaced_caption - document.references[:ids][el.attributes['id']] = replaced - end - elsif el.level == chapter_section_level + 1 then - replaced = captions[type] % [chap, get_and_tally_counter_of(type, counter)] - document.references[:ids][el.attributes['id']] = replaced - end - end - end - end - nil - end - - # Gets and increments the value for the given type in the given - # counter. - def get_and_tally_counter_of type, counter - t = counter[type] - counter[type] = counter[type] + 1 - t - end - - # Retrieves the associated value for the given key. Lazily retrieve - # default value if no attr is set on the given key. - def attr_of target, key, &default - begin - (target.attr key, :none).to_i - rescue NoMethodError - if not default.nil? then default.call else 0 end - end - end -end \ No newline at end of file diff --git a/tutorial.xml b/tutorial.xml deleted file mode 100644 index 4c3b13e0..00000000 --- a/tutorial.xml +++ /dev/null @@ -1,42 +0,0 @@ - - - - - tutorial - - zip - - jakartaee-tutorial - - - target/generated-docs - - - - target/staging - doc - - _config.yml - _layouts/** - assets/** - *.md - - - -