Merge branch 'main' into feature/servlet_api_update_74

.gitignore

@@ -5,6 +5,7 @@ src/main/jbake/content/toc.adoc
 .settings/
 *.classpath
 *.project
+bin/
 
 # IntelliJ #
 .idea/

CONTRIBUTING.md

@@ -1,60 +1,86 @@
-# Contributing to Jakarta EE Platform
+# Contributing to Jakarta EE Documentation
 
 Thanks for your interest in this project.
 
 ## Project description
 
 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.
 
-Link TBD
+Eclipse project page: https://projects.eclipse.org/projects/ee4j.jakartaee-documentation
 
 ## Developer resources
 
-Information regarding source code management, builds, coding standards, and
-more.
+The project maintains the following source code repositories
 
-* [https://projects.eclipse.org/projects/ee4j.jakartaee-platform/developer](https://projects.eclipse.org/projects/ee4j.jakartaee-platform/developer)
+* [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
 
-The project maintains the following source code repositories
+#### 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)`
 
-* [jakartaee-tutorial-playbook](https://github.com/virtua-tech/jakartaee-tutorial-playbook)
-* [jakartaee-tutorial](https://github.com/virtua-tech/jakartaee-tutorial)
-* [jakartaee-tutorial-ui](https://github.com/virtua-tech/jakartaee-tutorial-ui)
+##### 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/asciidoc/images`.
+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 3 formats:
+For portability and maintainability, make sure that the diagram is saved/exported into following three formats:
 
-- `*.drawio`
-- `*.vsdx`
-- `*.svg`
+- `*.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)
+      ![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)
+      ![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)
+      ![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)
+      ![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.
+  along with black and white (you can use opacity to affect the depth of the color).
     - Primary colors:
         - Blue: `#1B208B`
         - Orange: `#F98200`
@@ -65,6 +91,28 @@ The `*.svg` format is ultimately used to embed the diagram in the tutorial docum
         - 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
 
 Before your contribution can be accepted by the project team contributors must
@@ -83,6 +131,5 @@ For more information, please see the Eclipse Committer Handbook:
 
 ## Contact
 
-Contact the project developers via the project's "dev" list.
-
-* [TBD]
+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.

README.md

@@ -11,11 +11,6 @@ which is a tool for building documentation sites.
 You can always find the most recent build of the Jakarta EE Documentation site here:
 https://jakartaee.github.io/jakartaee-documentation/.
 
-> NOTE: We're currently in the process of updating the tutorial site and
-> refreshing the content for Jakarta EE 10 and beyond. This is a work in progress.
-> For the current production version of the tutorial, see
-> [jakartaee/jakartaee-tutorial](https://github.com/jakartaee/jakartaee-tutorial).
-
 ## A Note about Images
 
 We keep the source files (VSD) and the published format (SVG)
@@ -29,7 +24,7 @@ Guidelines for generating new images can be found in the [Contributing guide](CO
 ## Building
 
 The contents of this repo are built by
-the [jakartaee-tutorial-playbook repository](https://github.com/jakartaee/jakartaee-documentation).
+the [jakartaee-documentation repository](https://github.com/jakartaee/jakartaee-documentation).
 See that repo for details.
 
 ## Related Repositories
@@ -42,11 +37,15 @@ See that repo for details.
 
 This project is open for contributions, and your
 help is greatly appreciated. 
-The easiest way to contribute is by opening an issue in this project
+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. 
-You can also create PRs directly while viewing the published documentation.
+
+You can also create PRs directly while viewing the published documentation by using the Edit button in the UI.
+
+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).
 
 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.
 
+[Join us on Slack](https://join.slack.com/t/eclipsefoundationhq/shared_invite/zt-2shajguc7-1ZwbvVtZkKrB4acy4U4aLQ) in the [#jakartaee-tutorial](https://eclipsefoundationhq.slack.com/archives/C050VD73M7C) channel to discuss open issues and plan updates.

STYLE_GUIDE.adoc

@@ -91,6 +91,26 @@ See the https://docs.antora.org/antora/latest/page/xref/[Antora xref docs^] for
 
 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.
 
+== Titles for Images and Tables 
+
+Images and tables should be given a title using the asciidoc title syntax starting with a dot. This can be preceded with an anchor using underscores. For example:
+
+[source, asciidoc]
+----
+[[_anchor_name]]
+.Image Title
+image::image-path.svg["Image Alt Text"]
+----
+
+Links to the image or table can be created using the anchor name and either the internal or external link instructions as given for headers above. For example:
+
+[source, asciidoc]
+----
+ <<_anchor_name>>
+----
+
+Note the labels for table captions can be turned on and off using the _table-caption_ document attribute in antora.yml 
+
 == Definitions
 
 Use bold for a word when defining it.
@@ -107,3 +127,6 @@ For details, see https://sembr.org/[Semantic Line Breaks].
 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].

src/main/antora/antora.yml

@@ -3,6 +3,7 @@ title: Jakarta EE Tutorial
 version: 10
 asciidoc:
   attributes:
+    page-pdf-download-name: jakarta-ee-tutorial.pdf
     source-language: asciidoc@
     table-caption: false
     xrefstyle: full

src/main/antora/modules/ROOT/nav.adoc

@@ -1,12 +1,20 @@
 
-.Introduction
+xref:index.adoc[]
 
-* 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
@@ -19,11 +27,11 @@
 
 * Jakarta REST
 
-** xref:websvcs:jaxrs/jaxrs.adoc[]
+** xref:websvcs:rest/rest.adoc[]
 
-** xref:websvcs:jaxrs-client/jaxrs-client.adoc[]
+** xref:websvcs:rest-client/rest-client.adoc[]
 
-** xref:websvcs:jaxrs-advanced/jaxrs-advanced.adoc[]
+** xref:websvcs:rest-advanced/rest-advanced.adoc[]
 
 * Jakarta JSON
 

src/main/antora/modules/ROOT/pages/index.adoc

@@ -1,50 +1,47 @@
 [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
+= Preface
 
-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.
+include::ROOT:partial$draft.adoc[]
 
-== Before You Read This Book
+== Legal
 
-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[^].
+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.
 
-== Related Documentation
+SPDX-License-Identifier: EPL-2.0
 
-The GlassFish Server documentation set describes deployment planning and system installation.
-To obtain the GlassFish Server documentation, go to https://glassfish.org/docs[^].
+Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.
 
-The Jakarta EE 9 API specification can be viewed at https://jakarta.ee/specifications/platform/9/[^].
+== About this Tutorial
 
-Additionally, the Jakarta EE Specifications at https://jakarta.ee/specifications[^] might be useful.
+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.
 
-For information about creating enterprise applications in the NetBeans Integrated Development Environment (IDE), see https://netbeans.apache.org/kb/[^].
+== Prerequisites
 
-For information about Apache Derby for use with GlassFish Server, see https://db.apache.org/derby/docs/10.14/adminguide/[^].
+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].
 
-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/[^].
+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
 
-The following table describes the typographic conventions that are used in this book.
+Throughout this tutorial, we use the following typographic conventions:
 
 [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*.
+|*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.
 
-A *cache* is a copy that is 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.
 
@@ -61,26 +58,28 @@ 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 Solaris operating system, Linux operating system, and Mac operating system:
+|`_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 the Solaris operating system, Linux operating system, and Mac operating system:
+|`_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, all installations:
+Windows:
 
 `_SystemDrive_:\glassfish6`
 

src/main/antora/modules/ROOT/partials/draft.adoc

@@ -0,0 +1,4 @@
+[NOTE]
+====
+This section is currently a draft, and is subject to change.
+====

src/main/antora/modules/beanvalidation/pages/bean-validation/bean-validation002.adoc

@@ -330,6 +330,6 @@ For more information on using validation constraints, see the following:
 
 * 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:websvcs:rest-advanced/rest-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]

src/main/antora/modules/casestudies/pages/dukes-bookstore/dukes-bookstore002.adoc

@@ -116,7 +116,6 @@ See xref:web:faces-custom/faces-custom.adoc#_creating_custom_component_classes[C
 See xref:web:faces-custom/faces-custom.adoc#_handling_events_for_custom_components[Handling Events for Custom Components].
 
 * `model`: Contains the `ImageArea` class.
-See xref:web:faces-custom/faces-custom.adoc#_configuring_model_data[Configuring Model Data] for more information.
 
 * `renderers`: Contains the `MapRenderer` and `AreaRenderer` classes.
 See xref:web:faces-custom/faces-custom.adoc#_delegating_rendering_to_a_renderer[Delegating Rendering to a Renderer].