diff --git a/pom.xml b/pom.xml index 55b0cca7..0f9e6aad 100644 --- a/pom.xml +++ b/pom.xml @@ -30,15 +30,8 @@ Jakarta EE Tutorial - ${project.build.directory}/staging true - 1.5.7.1 - - 1.6.2 - 1.5.0-alpha.16 - 9.2.6.0 - - DRAFT + 2.0.0-RC.1 scm:git:git@github.com:eclipse-ee4j/jakartaee-tutorial.git @@ -55,133 +48,37 @@ package - org.apache.maven.plugins - maven-enforcer-plugin - 1.4.1 - - - enforce-versions - - enforce - - - - - [1.8.0,1.9.0) - You need JDK8 or lower - - - - - - - - org.glassfish.doc - glassfish-doc-maven-plugin + org.asciidoctor + asciidoctor-maven-plugin + ${asciidoctor.maven.plugin.version} - generate-toc + asciidoc-to-html generate-resources - toc + process-asciidoc - - [0-9]+\s.*,Preface.*,Part\s.* - - JEET.* + html5 + + book + ${status} + + font + left + font + true + + - + true + - - generate-book - generate-resources - - book - - - - - - com.blazebit - jbake-maven-plugin - 1.0.0 - - ${site.output.dir} - - ${status} - - - - - build-site - generate-resources - - build - - - - - org.asciidoctor - asciidoctorj - 1.5.5 - - - - - org.asciidoctor - asciidoctor-maven-plugin - ${asciidoctor.maven.plugin.version} - - - org.jruby - jruby-complete - ${jruby.version} - - - org.asciidoctor - asciidoctorj - ${asciidoctorj.version} - - - org.asciidoctor - asciidoctorj-pdf - ${asciidoctorj.pdf.version} - - - ${project.build.directory}/book - book.adoc - - ${project.build.directory}/staging/ - pdf - JakartaEETutorial.pdf - - ${project.basedir}/src/theme - jakartaee - book - ${status} - - font - - - font - true - - - - true - true - + index.adoc + coderay - - - generate-pdf-doc - generate-resources - - process-asciidoc - - - org.apache.maven.plugins @@ -200,43 +97,7 @@ - - - - maven-assembly-plugin - false - - - package - - single - - - - tutorial.xml - - - - - - - - - - org.glassfish.doc - glassfish-doc-maven-plugin - 1.2 - - - org.apache.maven.plugins - maven-assembly-plugin - 2.4 - - - diff --git a/src/main/asciidoc/batch-processing/batch-processing.adoc b/src/main/asciidoc/batch-processing/batch-processing.adoc new file mode 100644 index 00000000..df84ae78 --- /dev/null +++ b/src/main/asciidoc/batch-processing/batch-processing.adoc @@ -0,0 +1,30 @@ += Batch Processing + +[[GKJIQ6]][[batch-processing]] + +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. The batch framework is composed of a job specification +language based on XML, a Java API, and a batch runtime. + +include::batch-processing001.adoc[] + +include::batch-processing002.adoc[] + +include::batch-processing003.adoc[] + +include::batch-processing004.adoc[] + +include::batch-processing005.adoc[] + +include::batch-processing006.adoc[] + +include::batch-processing007.adoc[] + +include::batch-processing008.adoc[] + +include::batch-processing009.adoc[] + +include::batch-processing010.adoc[] + diff --git a/src/main/jbake/content/batch-processing001.adoc b/src/main/asciidoc/batch-processing/batch-processing001.adoc similarity index 93% rename from src/main/jbake/content/batch-processing001.adoc rename to src/main/asciidoc/batch-processing/batch-processing001.adoc index 7b71cd20..da665add 100644 --- a/src/main/jbake/content/batch-processing001.adoc +++ b/src/main/asciidoc/batch-processing/batch-processing001.adoc @@ -1,16 +1,6 @@ -type=page -status=published -title=Introduction to Batch Processing -next=batch-processing002.html -prev=batch-processing.html -~~~~~~ -Introduction to Batch Processing -================================ - [[BCGJDEEH]][[introduction-to-batch-processing]] -Introduction to Batch Processing --------------------------------- +== Introduction to Batch Processing Some enterprise applications contain tasks that can be executed without user interaction. These tasks are executed periodically or when resource @@ -48,8 +38,7 @@ other common characteristics of batch frameworks. [[sthref261]][[steps-in-batch-jobs]] -Steps in Batch Jobs -~~~~~~~~~~~~~~~~~~~ +=== Steps in Batch Jobs A step is an independent and sequential phase of a batch job. Batch jobs contain chunk-oriented steps and task-oriented steps. @@ -86,7 +75,7 @@ batch job. [[BABFJBAH]] .*Figure 58-1 Chunk Steps in a Batch Job* -image:img/jakartaeett_dt_058.png[ +image:jakartaeett_dt_058.png[ "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 @@ -109,8 +98,7 @@ files from the bills generated for the previous month. [[sthref263]][[parallel-processing]] -Parallel Processing -~~~~~~~~~~~~~~~~~~~ +=== Parallel Processing Batch jobs often process large amounts of data or perform computationally expensive operations. Batch applications can benefit @@ -127,8 +115,7 @@ run in parallel. [[sthref264]][[status-and-decision-elements]] -Status and Decision Elements -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Status and Decision Elements Batch frameworks keep track of a status for every step in a job. The status indicates if a step is running or if it has completed. If the @@ -150,7 +137,7 @@ chunk steps, task steps and a decision element. [[BCGDCDCA]] .*Figure 58-2 Steps and Decision Elements in a Job* -image:img/jakartaeett_dt_059.png[ +image:jakartaeett_dt_059.png[ "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 @@ -160,8 +147,7 @@ ends."] [[sthref266]][[batch-framework-functionality]] -Batch Framework Functionality -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Batch Framework Functionality Batch applications have the following common requirements. diff --git a/src/main/jbake/content/batch-processing002.adoc b/src/main/asciidoc/batch-processing/batch-processing002.adoc similarity index 67% rename from src/main/jbake/content/batch-processing002.adoc rename to src/main/asciidoc/batch-processing/batch-processing002.adoc index de456269..fde64449 100644 --- a/src/main/jbake/content/batch-processing002.adoc +++ b/src/main/asciidoc/batch-processing/batch-processing002.adoc @@ -1,34 +1,14 @@ -type=page -status=published -title=Batch Processing in Jakarta EE -next=batch-processing003.html -prev=batch-processing001.html -~~~~~~ -= Batch Processing in Jakarta EE - - [[BCGGIBHA]][[batch-processing-in-jakarta-ee]] -Batch Processing in Jakarta EE ------------------------------- +== Batch Processing in Jakarta EE This section lists the components of the batch processing framework in Jakarta EE and provides an overview of the steps you have to follow to create a batch application. -The following topics are addressed here: - -* link:#BABEAFJI[The Batch Processing Framework] -* link:#BABCGDHJ[Creating Batch Applications] -* link:#BABDGDJB[Elements of a Batch Job] -* link:#BABHJEJC[Properties and Parameters] -* link:#BABHJGDH[Job Instances and Job Executions] -* link:#BABBFGEF[Batch and Exit Status] - [[BABEAFJI]][[the-batch-processing-framework]] -The Batch Processing Framework -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== The Batch Processing Framework Jakarta EE includes a batch processing framework that consists of the following elements: @@ -50,34 +30,19 @@ Java classes to run the jobs in a batch application. [[BABCGDHJ]][[creating-batch-applications]] -Creating Batch Applications -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Creating Batch Applications The process for creating a batch application in Jakarta EE is the following. -1. Design the batch application. -1. Identify the input sources, the format of the input data, the -desired final result, and the required processing phases. -2. Organize the application as a job with chunk-oriented steps, -task-oriented steps, and decision elements. Determine the dependencies -between them. -3. Determine the order of execution in terms of transitions between -steps. -4. Identify steps that can run in parallel and steps that can run in -more than one thread. -2. Create the batch artifacts as Java classes by implementing the -interfaces specified by the framework for steps, decision elements, and -so on. These Java classes contain the code to read data from input -sources, format items, process items, and store results. Batch artifacts -can access context objects from the batch runtime using dependency -injection. -3. Define jobs, steps, and their execution flow in XML files using the -Job Specification Language. The elements in the XML files reference -batch artifacts implemented as Java classes. The batch artifacts can -access properties declared in the XML files, such as names of files and -databases. -4. Use the Java API provided by the batch runtime to launch the batch +. Design the batch application. +.. Identify the input sources, the format of the input data, the desired final result, and the required processing phases. +.. Organize the application as a job with chunk-oriented steps, task-oriented steps, and decision elements. Determine the dependencies between them. +.. Determine the order of execution in terms of transitions between steps. +.. Identify steps that can run in parallel and steps that can run in more than one thread. +. Create the batch artifacts as Java classes by implementing the interfaces specified by the framework for steps, decision elements, and so on. These Java classes contain the code to read data from input sources, format items, process items, and store results. Batch artifacts can access context objects from the batch runtime using dependency injection. +. Define jobs, steps, and their execution flow in XML files using the Job Specification Language. The elements in the XML files reference batch artifacts implemented as Java classes. The batch artifacts can access properties declared in the XML files, such as names of files and databases. +. Use the Java API provided by the batch runtime to launch the batch application. The following sections describe in detail how to use the components of @@ -85,8 +50,7 @@ the batch processing framework in Jakarta EE to create batch applications. [[BABDGDJB]][[elements-of-a-batch-job]] -Elements of a Batch Job -~~~~~~~~~~~~~~~~~~~~~~~ +=== Elements of a Batch Job A batch job can contain one or more of the following elements: @@ -96,7 +60,7 @@ A batch job can contain one or more of the following elements: * Decision elements Steps are described in -link:batch-processing001.html#BCGJDEEH[Introduction to Batch Processing], +link:#BCGJDEEH[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 @@ -116,8 +80,7 @@ the next step or to terminate the batch job. [[BABHJEJC]][[properties-and-parameters]] -Properties and Parameters -~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Properties and Parameters Jobs and steps can have a number of properties associated with them. You define properties in the job definition file, and batch artifacts access @@ -127,9 +90,9 @@ the job from the business logic and to reuse batch artifacts in different job definition files. Specifying properties is described in -link:batch-processing004.html#BCGDDBBG[Using the Job Specification +link:#BCGDDBBG[Using the Job Specification Language], and accessing properties in batch artifacts is described in -link:batch-processing005.html#BCGHDHGH[Creating Batch Artifacts]. +link:#BCGHDHGH[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 @@ -138,27 +101,25 @@ partitioned steps, since each partition needs to know, for example, what range of items to process. Specifying parameters when submitting jobs is described in -link:batch-processing006.html#BCGCAHCB[Submitting Jobs to the Batch +link:#BCGCAHCB[Submitting Jobs to the Batch Runtime]. Specifying parameters for partitioned steps and accessing them in batch artifacts is demonstrated in -link:batch-processing009.html#BCGFCACD[The phonebilling Example +link:#BCGFCACD[The phonebilling Example Application]. [[BABHJGDH]][[job-instances-and-job-executions]] -Job Instances and Job Executions -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== 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 -link:batch-processing006.html#BCGIBGFC[Checking the Status of a Job]. +link:#BCGIBGFC[Checking the Status of a Job]. [[BABBFGEF]][[batch-and-exit-status]] -Batch and Exit Status -~~~~~~~~~~~~~~~~~~~~~ +=== 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 @@ -184,12 +145,12 @@ link:#BCGJBGDF[Table 58-1]. They are represented as strings. Jakarta EE applications can submit jobs and access the batch status of a job using the `JobOperator` interface, as described in -link:batch-processing006.html#BCGCAHCB[Submitting Jobs to the Batch +link:#BCGCAHCB[Submitting Jobs to the Batch Runtime]. Job definition files can refer to batch status values using the Job Specification Language (JSL), as described in -link:batch-processing004.html#BCGDDBBG[Using the Job Specification +link:#BCGDDBBG[Using the Job Specification Language]. Batch artifacts can access batch status values using context -objects, as described in link:batch-processing005.html#BCGCJEEF[Using the +objects, as described in link:#BCGCJEEF[Using the Context Objects from the Batch Runtime]. For flows, the batch status is that of its last step. For splits, the diff --git a/src/main/jbake/content/batch-processing003.adoc b/src/main/asciidoc/batch-processing/batch-processing003.adoc similarity index 93% rename from src/main/jbake/content/batch-processing003.adoc rename to src/main/asciidoc/batch-processing/batch-processing003.adoc index aa0e3cd3..33160e1c 100644 --- a/src/main/jbake/content/batch-processing003.adoc +++ b/src/main/asciidoc/batch-processing/batch-processing003.adoc @@ -1,16 +1,6 @@ -type=page -status=published -title=Simple Use Case -next=batch-processing004.html -prev=batch-processing002.html -~~~~~~ -Simple Use Case -=============== - [[BCGHBJIG]][[simple-use-case]] -Simple Use Case ---------------- +== Simple Use Case This section demonstrates how to define a simple job using the Job Specification Language (JSL) and how to implement the corresponding @@ -20,7 +10,7 @@ detailed descriptions of the elements in the batch framework. The following job definition specifies a chunk step and a task step as follows: -[source,oac_no_warn] +[source,xml] ---- @@ -66,8 +56,7 @@ child elements. [[sthref270]][[the-job-element]] -The job Element -~~~~~~~~~~~~~~~ +=== The job Element The `job` element is always the top-level element in a job definition file. Its main attributes are `id` and `restartable`. The `job` element @@ -75,7 +64,7 @@ can contain one `properties` element and zero or more of each of the following elements: `listener`, `step`, `flow`, and `split`. For example: -[source,oac_no_warn] +[source,xml] ---- @@ -96,7 +85,7 @@ 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 `javax.batch.api.listener.JobListener` -interface. See link:batch-processing008.html#BCGCCFAC[The Listener Batch +interface. See link:#BCGCCFAC[The Listener Batch Artifacts] for an example of a job listener implementation. The first `step`, `flow`, or `split` element inside the `job` element @@ -104,8 +93,7 @@ executes first. [[sthref271]][[the-step-element]] -The step Element -~~~~~~~~~~~~~~~~ +=== The step Element The `step` element can be a child of the `job` and `flow` elements. Its main attributes are `id` and `next`. The `step` element can contain the @@ -133,7 +121,7 @@ implementations of the following interfaces: `StepListener`, For task steps, the batch artifact for these listeners must be an implementation of the `StepListener` interface. + -See link:batch-processing008.html#BCGCCFAC[The Listener Batch Artifacts] +See link:#BCGCCFAC[The Listener Batch Artifacts] for an example of an item processor listener implementation. * One `partition` element (optional). + @@ -155,7 +143,7 @@ step, a flow, a split, or a decision element. The following is an example of a chunk step: -[source,oac_no_warn] +[source,xml] ---- ... @@ -173,7 +161,7 @@ The following is an example of a chunk step: The following is an example of a task step: -[source,oac_no_warn] +[source,xml] ---- ... @@ -184,8 +172,7 @@ The following is an example of a task step: [[sthref272]][[the-chunk-element]] -The chunk Element -^^^^^^^^^^^^^^^^^ +==== 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 link:#BCGJCIEI[Table @@ -282,7 +269,7 @@ rolled back by default when an exception occurs. The following is an example of a chunk-oriented step: -[source,oac_no_warn] +[source,xml] ---- @@ -336,8 +322,7 @@ This example defines a batch step and specifies its batch artifact. [[sthref275]][[the-partition-element]] -The partition Element -^^^^^^^^^^^^^^^^^^^^^ +==== The partition Element The `partition` element is a child of the `step` element. It indicates that a step is partitioned. Most partitioned steps are chunk steps where @@ -378,8 +363,8 @@ properties to specify a range of items for each partition, and one that relies on a `PartitionMapper` implementation to determine partition-specific information. -See link:batch-processing009.html#BCGGGAHB[The Phone Billing Chunk Step] -in link:batch-processing009.html#BCGFCACD[The phonebilling Example +See link:#BCGGGAHB[The Phone Billing Chunk Step] +in link:#BCGFCACD[The phonebilling Example Application] for a complete example of a partitioned chunk step. The `partition` element can contain the following elements. @@ -420,7 +405,7 @@ implementation of the `PartitionAnalyzer` interface. The following is an example of a partitioned step using the `plan` element: -[source,oac_no_warn] +[source,xml] ---- @@ -454,7 +439,7 @@ element. The `PartitionMapper` implementation dynamically provides the same information as the `plan` element provides in the job definition file: -[source,oac_no_warn] +[source,xml] ---- @@ -471,14 +456,13 @@ file: ---- -Refer to link:batch-processing009.html#BCGFCACD[The phonebilling Example +Refer to link:#BCGFCACD[The phonebilling Example Application] for an example implementation of the `PartitionMapper` interface. [[sthref276]][[the-flow-element]] -The flow Element -~~~~~~~~~~~~~~~~ +=== The flow Element The `flow` element can be a child of the `job`, `flow`, and `split` elements. Its attributes are `id` and `next`. Flows can transition to @@ -496,7 +480,7 @@ elements outside the flow. The following is an example of the `flow` element: -[source,oac_no_warn] +[source,xml] ---- ... @@ -513,8 +497,7 @@ last step does not have the `next` attribute. The flow transitions to [[sthref277]][[the-split-element]] -The split Element -~~~~~~~~~~~~~~~~~ +=== The split Element The `split` element can be a child of the `job` and `flow` elements. Its attributes are `id` and `next`. Splits can transition to splits, steps, @@ -525,7 +508,7 @@ elements in the split. The following is an example of a split with three flows that execute concurrently: -[source,oac_no_warn] +[source,xml] ---- ... @@ -536,8 +519,7 @@ concurrently: [[sthref278]][[the-decision-element]] -The decision Element -~~~~~~~~~~~~~~~~~~~~ +=== The decision Element The `decision` element can be a child of the `job` and `flow` elements. Its attributes are `id` and `next`. Steps, flows, and splits can @@ -561,7 +543,7 @@ This element sets the batch status to `FAILED`. The following is an example of the `decider` element: -[source,oac_no_warn] +[source,xml] ---- diff --git a/src/main/jbake/content/batch-processing005.adoc b/src/main/asciidoc/batch-processing/batch-processing005.adoc similarity index 91% rename from src/main/jbake/content/batch-processing005.adoc rename to src/main/asciidoc/batch-processing/batch-processing005.adoc index 354946a8..777de009 100644 --- a/src/main/jbake/content/batch-processing005.adoc +++ b/src/main/asciidoc/batch-processing/batch-processing005.adoc @@ -1,16 +1,6 @@ -type=page -status=published -title=Creating Batch Artifacts -next=batch-processing006.html -prev=batch-processing004.html -~~~~~~ -= Creating Batch Artifacts - - [[BCGHDHGH]][[creating-batch-artifacts]] -Creating Batch Artifacts ------------------------- +== Creating Batch Artifacts After you define a job in terms of its batch artifacts using the Job Specification Language (JSL), you create these artifacts as Java classes @@ -21,20 +11,13 @@ This section lists the main batch artifact interfaces, demonstrates how to access context objects from the batch runtime, and provides some examples. -The following topics are addressed here: - -* link:#BABDAIBI[Batch Artifact Interfaces] -* link:#BCGIFJBB[Dependency Injection in Batch Artifacts] -* link:#BCGCJEEF[Using the Context Objects from the Batch Runtime] - [[BABDAIBI]][[batch-artifact-interfaces]] -Batch Artifact Interfaces -~~~~~~~~~~~~~~~~~~~~~~~~~ +=== 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 link:batch-processing004.html#BCGDDBBG[Using the +elements described in link:#BCGDDBBG[Using the Job Specification Language]. link:#BCGGCIDC[Table 58-3] lists the interfaces to implement batch @@ -174,8 +157,7 @@ referenced from the `listener` element inside the `step` element. [[BCGIFJBB]][[dependency-injection-in-batch-artifacts]] -Dependency Injection in Batch Artifacts -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Dependency Injection in Batch Artifacts To ensure that Jakarta Contexts and Dependency Injection (CDI) works in your batch artifacts, follow these steps. @@ -186,7 +168,7 @@ the `Named` annotation. For example, define an item reader implementation in a chunk step as follows: + -[source,oac_no_warn] +[source,java] ---- @Named("MyItemReaderImpl") public class MyItemReaderImpl implements ItemReader { @@ -198,7 +180,7 @@ artifacts. + For example, provide the following constructor for the artifact above: + -[source,oac_no_warn] +[source,java] ---- public MyItemReaderImpl() {} ---- @@ -207,7 +189,7 @@ file, instead of using the fully qualified name of the class. + For example, define the step for the artifact above as follows: + -[source,oac_no_warn] +[source,xml] ---- @@ -226,7 +208,7 @@ or by including an empty `beans.xml` deployment description with your application. For example, the following batch artifact is annotated with `@Dependent`: + -[source,oac_no_warn] +[source,java] ---- @Dependent @Named("MyItemReaderImpl") @@ -234,8 +216,8 @@ public class MyItemReaderImpl implements ItemReader { ... } ---- + For more information on bean archives, see -link:cdi-adv001.html#CACDCFDE[Packaging CDI Applications] in -link:cdi-adv.html#GJEHI[Chapter 27, "Jakarta Contexts and Dependency Injection: Advanced Topics"]. +link:#CACDCFDE[Packaging CDI Applications] in +link:#GJEHI[Chapter 27, "Jakarta Contexts and Dependency Injection: Advanced Topics"]. [width="100%",cols="100%",] @@ -258,8 +240,7 @@ injected objects. [[BCGCJEEF]][[using-the-context-objects-from-the-batch-runtime]] -Using the Context Objects from the Batch Runtime -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Using the Context Objects from the Batch Runtime The batch runtime provides context objects that implement the `JobContext` and `StepContext` interfaces in the @@ -279,7 +260,7 @@ writers, batchlets, listeners, and so on. The following example demonstrates how to access property values from the job definition file in an item reader implementation: -[source,oac_no_warn] +[source,java] ---- @Dependent @Named("MyItemReaderImpl") diff --git a/src/main/jbake/content/batch-processing006.adoc b/src/main/asciidoc/batch-processing/batch-processing006.adoc similarity index 77% rename from src/main/jbake/content/batch-processing006.adoc rename to src/main/asciidoc/batch-processing/batch-processing006.adoc index 79bf55fc..5055207b 100644 --- a/src/main/jbake/content/batch-processing006.adoc +++ b/src/main/asciidoc/batch-processing/batch-processing006.adoc @@ -1,16 +1,6 @@ -type=page -status=published -title=Submitting Jobs to the Batch Runtime -next=batch-processing007.html -prev=batch-processing005.html -~~~~~~ -Submitting Jobs to the Batch Runtime -==================================== - [[BCGCAHCB]][[submitting-jobs-to-the-batch-runtime]] -Submitting Jobs to the Batch Runtime ------------------------------------- +== Submitting Jobs to the Batch Runtime The `JobOperator` interface in the `javax.batch.operations` package enables you to submit jobs to the batch runtime and obtain information @@ -26,13 +16,12 @@ the `getJobOperator` factory method to obtain `JobOperator` objects. [[sthref282]][[starting-a-job]] -Starting a Job -~~~~~~~~~~~~~~ +=== Starting a Job The following example code demonstrates how to obtain a `JobOperator` object and submit a batch job: -[source,oac_no_warn] +[source,java] ---- JobOperator jobOperator = BatchRuntime.getJobOperator(); Properties props = new Properties(); @@ -49,8 +38,7 @@ is only known at runtime. [[BCGIBGFC]][[checking-the-status-of-a-job]] -Checking the Status of a Job -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Checking the Status of a Job The `JobExecution` interface in the `javax.batch.runtime` package provides methods to obtain information about submitted jobs. This @@ -64,7 +52,7 @@ interface provides the following functionality. The following example code demonstrates how to obtain the batch status of a job using its execution ID: -[source,oac_no_warn] +[source,java] ---- JobExecution jobExec = jobOperator.getJobExecution(execID); String status = jobExec.getBatchStatus().toString(); @@ -72,16 +60,15 @@ String status = jobExec.getBatchStatus().toString(); [[sthref283]][[invoking-the-batch-runtime-in-your-application]] -Invoking the Batch Runtime in Your Application -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Invoking the Batch Runtime in Your Application 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 link:batch-processing008.html#BCGJHEHJ[The webserverlog Example -Application] and link:batch-processing009.html#BCGFCACD[The phonebilling +See link:#BCGJHEHJ[The webserverlog Example +Application] and link:#BCGFCACD[The phonebilling Example Application] for details on how to invoke the batch runtime from a managed bean driven by a Jakarta Server Faces user interface. diff --git a/src/main/jbake/content/batch-processing007.adoc b/src/main/asciidoc/batch-processing/batch-processing007.adoc similarity index 75% rename from src/main/jbake/content/batch-processing007.adoc rename to src/main/asciidoc/batch-processing/batch-processing007.adoc index 33f94045..d6a3c125 100644 --- a/src/main/jbake/content/batch-processing007.adoc +++ b/src/main/asciidoc/batch-processing/batch-processing007.adoc @@ -1,16 +1,6 @@ -type=page -status=published -title=Packaging Batch Applications -next=batch-processing008.html -prev=batch-processing006.html -~~~~~~ -Packaging Batch Applications -============================ - [[BCGBBGJI]][[packaging-batch-applications]] -Packaging Batch Applications ----------------------------- +== Packaging Batch Applications Job definition files and batch artifacts do not require separate packaging and can be included in any Jakarta EE application. @@ -27,7 +17,7 @@ if you define a job as follows, and you are packaging your application as a WAR file, include the job definition file in `WEB-INF/classes/META-INF/batch-jobs/simplejob.xml`: -[source,oac_no_warn] +[source,xml] ---- diff --git a/src/main/jbake/content/batch-processing008.adoc b/src/main/asciidoc/batch-processing/batch-processing008.adoc similarity index 85% rename from src/main/jbake/content/batch-processing008.adoc rename to src/main/asciidoc/batch-processing/batch-processing008.adoc index bbf62fc3..0f0c34ef 100644 --- a/src/main/jbake/content/batch-processing008.adoc +++ b/src/main/asciidoc/batch-processing/batch-processing008.adoc @@ -1,16 +1,6 @@ -type=page -status=published -title=The webserverlog Example Application -next=batch-processing009.html -prev=batch-processing007.html -~~~~~~ -The webserverlog Example Application -==================================== - [[BCGJHEHJ]][[the-webserverlog-example-application]] -The webserverlog Example Application ------------------------------------- +== The webserverlog Example Application The `webserverlog` example application, located in the tut-install`/examples/batch/webserverlog/` directory, demonstrates how @@ -18,15 +8,9 @@ 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. -The following topics are addressed here: - -* link:#BABCHDFB[Architecture of the webserverlog Example Application] -* link:#BABFIHJA[Running the webserverlog Example Application] - [[BABCHDFB]][[architecture-of-the-webserverlog-example-application]] -Architecture of the webserverlog Example Application -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Architecture of the webserverlog Example Application The `webserverlog` example application consists of the following elements: @@ -58,14 +42,13 @@ the job, and reads the results from a text file. [[BABFGCEC]][[the-job-definition-file]] -The Job Definition File -^^^^^^^^^^^^^^^^^^^^^^^ +==== The Job Definition File The `webserverlog.xml` job definition file is located in the `WEB-INF/classes/META-INF/batch-jobs/` directory. The file specifies seven job-level properties and two steps: -[source,oac_no_warn] +[source,xml] ---- @@ -110,7 +93,7 @@ with `@Named`. The second step is defined as follows: -[source,oac_no_warn] +[source,java] ---- @@ -123,13 +106,12 @@ implements it. This is the last step of the job. [[BABIHBFF]][[the-logline-and-logfilteredline-items]] -The LogLine and LogFilteredLine Items -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== The LogLine and LogFilteredLine Items The `LogLine` class represents entries in the web server log file and it is defined as follows: -[source,oac_no_warn] +[source,java] ---- public class LogLine { private final String datetime; @@ -146,15 +128,14 @@ fields: the IP address of the client and the URL. [[sthref284]][[the-chunk-step-batch-artifacts]] -The Chunk Step Batch Artifacts -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== The Chunk Step Batch Artifacts The first step is composed of the `LogLineReader`, `LogLineProcessor`, and `LogFilteredLineWriter` batch artifacts. The `LogLineReader` artifact reads records from the web server log file: -[source,oac_no_warn] +[source,java] ---- @Dependent @Named("LogLineReader") @@ -177,7 +158,7 @@ file with a buffered reader. In this example, the log file has been included with the application under `webserverlog/WEB-INF/classes/log1.txt`: -[source,oac_no_warn] +[source,java] ---- fileName = jobCtx.getProperties().getProperty("log_file_name"); ClassLoader classLoader = Thread.currentThread().getContextClassLoader(); @@ -193,7 +174,7 @@ from the last committed chunk. The `readItem` method returns a new `LogLine` object or null at the end of the log file: -[source,oac_no_warn] +[source,java] ---- @Override public Object readItem() throws Exception { @@ -210,7 +191,7 @@ public Object readItem() throws Exception { The `LogLineProcessor` artifact obtains a list of browsers from the job properties and filters the log entries according to the list: -[source,oac_no_warn] +[source,java] ---- @Override public Object processItem(Object item) { @@ -240,7 +221,7 @@ If a checkpoint object is provided, the artifact continues writing at the end of the file; otherwise, it overwrites the file if it exists. The `writeItems` method writes filtered items to the output file: -[source,oac_no_warn] +[source,java] ---- @Override public void writeItems(List items) throws Exception { @@ -255,13 +236,12 @@ public void writeItems(List items) throws Exception { [[BCGCCFAC]][[the-listener-batch-artifacts]] -The Listener Batch Artifacts -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== The Listener Batch Artifacts The `InfoJobListener` batch artifact implements a simple listener that writes log messages when the job starts and when it ends: -[source,oac_no_warn] +[source,java] ---- @Dependent @Named("InfoJobListener") @@ -280,7 +260,7 @@ public class InfoJobListener implements JobListener { The `InfoItemProcessListener` batch artifact implements the `ItemProcessListener` interface for chunk steps: -[source,oac_no_warn] +[source,java] ---- @Dependent @Named("InfoItemProcessListener") @@ -297,13 +277,12 @@ public class InfoItemProcessListener implements ItemProcessListener { [[sthref285]][[the-task-step-batch-artifact]] -The Task Step Batch Artifact -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== The Task Step Batch Artifact The task step is implemented by the `MobileBatchlet` artifact, which computes what percentage of the filtered log entries are purchases: -[source,oac_no_warn] +[source,java] ---- @Override public String process() throws Exception { @@ -327,14 +306,13 @@ public String process() throws Exception { [[sthref286]][[the-javaserver-faces-pages]] -The Jakarta Server Faces Pages -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== The Jakarta Server Faces Pages The `index.xhtml` page contains a text area that shows the web server log. The page provides a button for the user to submit the batch job and navigate to the next page: -[source,oac_no_warn] +[source,xml] ---- ... @@ -354,7 +332,7 @@ submit the batch job. The `jobstarted.xhtml` page provides a button to check the current status of the batch job and displays the results when the job finishes: -[source,oac_no_warn] +[source,xml] ----

Current Status of the Job: #{jsfBean.jobStatus}

#{jsfBean.showResults()}

@@ -367,15 +345,14 @@ status of the batch job and displays the results when the job finishes: [[sthref287]][[the-managed-bean]] -The Managed Bean -^^^^^^^^^^^^^^^^ +==== The Managed Bean The `JsfBean` managed bean submits the job to the batch runtime, checks on the status of the job, and reads the results from a text file. The `startBatchJob` method submits the job to the batch runtime: -[source,oac_no_warn] +[source,java] ---- /* Submit the batch job to the batch runtime. * JSF Navigation method (return the name of the next page) */ @@ -388,7 +365,7 @@ public String startBatchJob() { The `getJobStatus` method checks the status of the job: -[source,oac_no_warn] +[source,java] ---- /* Get the status of the job from the batch runtime */ public String getJobStatus() { @@ -400,31 +377,22 @@ The `showResults` method reads the results from a text file. [[BABFIHJA]][[running-the-webserverlog-example-application]] -Running the webserverlog Example Application -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Running the webserverlog Example Application You can use either NetBeans IDE or Maven to build, package, deploy, and run the `webserverlog` example application. -The following topics are addressed here: - -* link:#BABHIJBE[To Run the webserverlog Example Application Using -NetBeans IDE] -* link:#BABGACCD[To Run the webserverlog Example Application Using -Maven] - [[BABHIJBE]][[to-run-the-webserverlog-example-application-using-netbeans-ide]] -To Run the webserverlog Example Application Using NetBeans IDE -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== To Run the webserverlog Example Application Using NetBeans IDE 1. Make sure that GlassFish Server has been started (see -link:usingexamples002.html#BNADI[Starting and Stopping GlassFish +link:#BNADI[Starting and Stopping GlassFish Server]). 2. From the File menu, choose Open Project. 3. In the Open Project dialog box, navigate to: + -[source,oac_no_warn] +[source,java] ---- tut-install/examples/batch ---- @@ -437,34 +405,33 @@ This command builds and packages the application into a WAR file, `webserverlog.war`, located in the `target/` directory; deploys it to the server; and launches a web browser window at the following URL: + -[source,oac_no_warn] +[source,java] ---- http://localhost:8080/webserverlog/ ---- [[BABGACCD]][[to-run-the-webserverlog-example-application-using-maven]] -To Run the webserverlog Example Application Using Maven -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== To Run the webserverlog Example Application Using Maven 1. Make sure that GlassFish Server has been started (see -link:usingexamples002.html#BNADI[Starting and Stopping GlassFish +link:#BNADI[Starting and Stopping GlassFish Server]). 2. In a terminal window, go to: + -[source,oac_no_warn] +[source,java] ---- tut-install/examples/batch/webserverlog/ ---- 3. Enter the following command to deploy the application: + -[source,oac_no_warn] +[source,java] ---- mvn install ---- 4. Open a web browser window at the following URL: + -[source,oac_no_warn] +[source,java] ---- http://localhost:8080/webserverlog/ ---- diff --git a/src/main/jbake/content/batch-processing009.adoc b/src/main/asciidoc/batch-processing/batch-processing009.adoc similarity index 88% rename from src/main/jbake/content/batch-processing009.adoc rename to src/main/asciidoc/batch-processing/batch-processing009.adoc index 801c2a28..e7aaec03 100644 --- a/src/main/jbake/content/batch-processing009.adoc +++ b/src/main/asciidoc/batch-processing/batch-processing009.adoc @@ -1,16 +1,6 @@ -type=page -status=published -title=The phonebilling Example Application -next=batch-processing010.html -prev=batch-processing008.html -~~~~~~ -The phonebilling Example Application -==================================== - [[BCGFCACD]][[the-phonebilling-example-application]] -The phonebilling Example Application ------------------------------------- +== The phonebilling Example Application The `phonebilling` example application, located in the tut-install`/examples/batch/phonebilling/` directory, demonstrates how @@ -18,15 +8,9 @@ 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. -The following topics are addressed here: - -* link:#BABDEIFG[Architecture of the phonebilling Example Application] -* link:#BABBGDAA[Running the phonebilling Example Application] - [[BABDEIFG]][[architecture-of-the-phonebilling-example-application]] -Architecture of the phonebilling Example Application -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Architecture of the phonebilling Example Application The `phonebilling` example application consists of the following elements. @@ -61,14 +45,13 @@ the job, and reads the text files for each bill. [[sthref288]][[the-job-definition-file]] -The Job Definition File -^^^^^^^^^^^^^^^^^^^^^^^ +==== The Job Definition File The `phonebilling.xml` job definition file is located in the `WEB-INF/classes/META-INF/batch-jobs/` directory. The file specifies three job-level properties and two steps: -[source,oac_no_warn] +[source,xml] ---- @@ -103,7 +86,7 @@ with `@Named`. The second step is defined as follows: -[source,oac_no_warn] +[source,xml] ---- @@ -125,12 +108,11 @@ element. [[sthref289]][[the-callrecord-and-phonebill-entities]] -The CallRecord and PhoneBill Entities -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== The CallRecord and PhoneBill Entities The `CallRecord` entity is defined as follows: -[source,oac_no_warn] +[source,java] ---- @Entity public class CallRecord implements Serializable { @@ -162,7 +144,7 @@ The second constructor creates a `CallRecord` object from an entry of JSON data in the log file using Jakarta JSON Processing. Log entries look as follows: -[source,oac_no_warn] +[source,java] ---- {"datetime":"03/01/2013 04:03","from":"555-0101", "to":"555-0114","length":"03:39"} @@ -170,7 +152,7 @@ look as follows: The `PhoneBill` entity is defined as follows: -[source,oac_no_warn] +[source,java] ---- @Entity public class PhoneBill implements Serializable { @@ -213,21 +195,20 @@ The batch artifacts use instances of these two entities as items to read, process, and write. For more information on Jakarta Persistence, see -link:persistence-intro.html#BNBPZ[Chapter 40, "Introduction to Jakarta +link:#BNBPZ[Chapter 40, "Introduction to Jakarta Persistence"]. For more information on Jakarta JSON Processing, see -link:jsonp.html#GLRBB[Chapter 20, "JSON Processing"]. +link:#GLRBB[Chapter 20, "JSON Processing"]. [[sthref290]][[the-call-records-chunk-step]] -The Call Records Chunk Step -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== The Call Records Chunk Step The first step is composed of the `CallRecordReader`, `CallRecordProcessor`, and `CallRecordWriter` batch artifacts. The `CallRecordReader` artifact reads call records from the log file: -[source,oac_no_warn] +[source,java] ---- @Dependent @Named("CallRecordReader") @@ -246,7 +227,7 @@ public class CallRecordReader implements ItemReader { The `open` method reads the `log_filename` property and opens the log file with a buffered reader: -[source,oac_no_warn] +[source,java] ---- fileName = jobCtx.getProperties().getProperty("log_file_name"); breader = new BufferedReader(new FileReader(fileName)); @@ -260,7 +241,7 @@ from the last committed chunk. The `readItem` method returns a new `CallRecord` object or null at the end of the log file: -[source,oac_no_warn] +[source,java] ---- @Override public Object readItem() throws Exception { @@ -284,7 +265,7 @@ and stores the bill in the database. This artifact overrides the `open`, `close`, `writeItems`, and `checkpointInfo` methods. The `writeItems` method looks like this: -[source,oac_no_warn] +[source,java] ---- @Override public void writeItems(List callList) throws Exception { @@ -307,8 +288,7 @@ public void writeItems(List callList) throws Exception { [[BCGGGAHB]][[the-phone-billing-chunk-step]] -The Phone Billing Chunk Step -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== The Phone Billing Chunk Step The second step is composed of the `BillReader`, `BillProcessor`, `BillWriter`, and `BillPartitionMapper` batch artifacts. This step gets @@ -325,7 +305,7 @@ It provides a partition plan object that overrides the `getPartitions` and `getPartitionProperties` methods of the `PartitionPlan` interface. The `getPartitions` method looks like this: -[source,oac_no_warn] +[source,java] ---- @Override public Properties[] getPartitionProperties() { @@ -357,7 +337,7 @@ public Properties[] getPartitionProperties() { The `BillReader` artifact obtains the partition parameters as follows: -[source,oac_no_warn] +[source,java] ---- @Dependent @Named("BillReader") @@ -392,7 +372,7 @@ public class BillReader implements ItemReader { This artifact also obtains an iterator to read items from the Jakarta Persistence entity manager: -[source,oac_no_warn] +[source,java] ---- /* Obtain an iterator for the bills in this partition */ String query = "SELECT b FROM PhoneBill b ORDER BY b.phoneNumber"; @@ -408,14 +388,13 @@ The `BillWriter` artifact writes each bill to a plain text file. [[sthref291]][[the-javaserver-faces-pages]] -The Jakarta Server Faces Pages -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== The Jakarta Server Faces Pages The `index.xhtml` page contains a text area that shows the log file of call records. The page provides a button for the user to submit the batch job and navigate to the next page: -[source,oac_no_warn] +[source,xml] ----

The Phone Billing Example Application

@@ -437,7 +416,7 @@ submit the batch job. The `jobstarted.xhtml` page provides a button to check the current status of the batch job and displays the bills when the job finishes: -[source,oac_no_warn] +[source,xml] ----

Current Status of the Job: #{jsfBean.jobStatus}

employeesList; @@ -201,7 +184,7 @@ While validating the object or the object graph, it may be necessary to validate Jakarta Bean validation provides in-built value extractors for most commonly used container types such as List, Iterable, and others. However, it is also possible to implement and register value-extractor implementations for custom container types or override the in-built value-extractor implementations. Consider a Statistics Calculator for a group of 'Person' entity and 'Employee' is one of the sub-type of the entity 'Person'. -[source,oac_no_warn] +[source,java] ---- public class StatsCalculator { @@ -247,7 +230,7 @@ public class StatsCalculator { When the `StatsCalculator` is validated, the "members" field is also validated. The in-built value extractor for `List` is used to extract the values of `List` to validate the elements in `List`. In the case of an employee based List, each "Employee” element is validated. For example, an employee’s "phone" is validated using the `@USPhoneNumber` constraint. In the following example, let us consider a `StatisticsPrinter` that prints the statistics or displays the statistics on screen. -[source,oac_no_warn] +[source,java] ---- public class StatisticsPrinter { private StatsCalculator<@Valid Employee> calculator; @@ -267,7 +250,7 @@ public class StatisticsPrinter { } ---- The container `StatisticsPrinter` uses `StatisticsCalculator`. When `StatisticsPrinter` is validated, the `StatisticsCalculator` is also validated by using the cascading validation such as `@Valid` annotation. However, in order to retrieve the values of `StatsCalculator` container type, a value extractor is required. An implementation of `ValueExtractor` for `StatsCalculator` is as follows: -[source,oac_no_warn] +[source,java] ---- public class ExtractorForStatsCalculator implements ValueExtractor>{ @@ -281,7 +264,7 @@ public class ExtractorForStatsCalculator implements ValueExtractor - - javax.faces.INTERPRET_EMPTY_STRING_SUBMITTED_VALUES_AS_NULL - + javax.faces.INTERPRET_EMPTY_STRING_SUBMITTED_VALUES_AS_NULL true ---- diff --git a/src/main/jbake/content/bean-validation004.adoc b/src/main/asciidoc/bean-validation/bean-validation004.adoc similarity index 85% rename from src/main/jbake/content/bean-validation004.adoc rename to src/main/asciidoc/bean-validation/bean-validation004.adoc index 21218048..c5399524 100644 --- a/src/main/jbake/content/bean-validation004.adoc +++ b/src/main/asciidoc/bean-validation/bean-validation004.adoc @@ -1,22 +1,12 @@ -type=page -status=published -title=Validating Constructors and Methods -next=bean-validation005.html -prev=bean-validation003.html -~~~~~~ -# Validating Constructors and Methods - - [[CACJIBEJ]][[validating-constructors-and-methods]] -Validating Constructors and Methods ------------------------------------ +== Validating Constructors and Methods Jakarta Bean Validation constraints may be placed on the parameters of nonstatic methods and constructors and on the return values of nonstatic methods. Static methods and constructors will not be validated. -[source,oac_no_warn] +[source,java] ---- public class Employee { ... @@ -44,18 +34,17 @@ constraint. If you add method constraints to classes in an object hierarchy, special care must be taken to avoid unintended behavior by subtypes. See -link:bean-validation-advanced004.html#CIHGJBGI[Using Method Constraints +link:#CIHGJBGI[Using Method Constraints in Type Hierarchies] for more information. [[sthref122]][[cross-parameter-constraints]] -Cross-Parameter Constraints -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Cross-Parameter Constraints Constraints that apply to multiple parameters are called cross-parameter constraints, and may be applied at the method or constructor level. -[source,oac_no_warn] +[source,java] ---- @ConsistentPhoneParameters @NotNull @@ -96,20 +85,19 @@ validation constraint. [[validating_type_arguments_of_parameterized_types]] In Jakarta Bean Validation 2.0, you can apply constraints to the type arguments of parameterized types. For example: `List<@NotNull Long> numbers;` Constraints can be applied to elements of container types such as `List`, `Map`, `Optional`, and others. -[source,oac_no_warn] +[source,java] ---- List<@Email String> emails; 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 link:bean-validation-advanced001.html#GKAIA[Using the Built-In Constraints to Make a New Constraint]. +In this sample, `@Email` is an in-built constraint supported by Bean Validation, and `@USPhoneNumber` is a user-defined constraint. See link:#GKAIA[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. [[sthref123]][[identifying-parameter-constraint-violations]] -Identifying Parameter Constraint Violations -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Identifying Parameter Constraint Violations If a `ConstraintViolationException` occurs during a method call, the Bean Validation runtime returns a parameter index to identify which @@ -119,13 +107,12 @@ starts at 0 for the first parameter of the method or constructor. [[sthref124]][[adding-constraints-to-method-return-values]] -Adding Constraints to Method Return Values -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Adding Constraints to Method Return Values To validate the return value for a method, you can apply constraints directly to the method or constructor declaration. -[source,oac_no_warn] +[source,java] ---- @NotNull public Employee getEmployee() { ... } @@ -139,11 +126,11 @@ annotation definition with the default set to either `ConstraintTarget.RETURN_VALUE` or `ConstraintTarget.PARAMETERS` to explicitly set the target of the validation constraint. -[source,oac_no_warn] +[source,java] ---- @Manager(validationAppliesTo=ConstraintTarget.RETURN_VALUE) public Employee getManager(Employee employee) { ... } ---- -See link:bean-validation-advanced001.html#CIHCICAI[Removing Ambiguity in +See link:#CIHCICAI[Removing Ambiguity in Constraint Targets] for more information. diff --git a/src/main/asciidoc/bean-validation/bean-validation005.adoc b/src/main/asciidoc/bean-validation/bean-validation005.adoc new file mode 100644 index 00000000..97427e6e --- /dev/null +++ b/src/main/asciidoc/bean-validation/bean-validation005.adoc @@ -0,0 +1,12 @@ +[[CACDECFE]][[further-information-about-bean-validation]] + +== Further Information about Jakarta Bean Validation + +For more information on Jakarta Bean Validation, see + +* Jakarta Bean Validation 2.0 Specification: ++ +`https://jakarta.ee/specifications/bean-validation/2.0/` +* Bean Validation Specification website: ++ +`http://beanvalidation.org/` diff --git a/src/main/asciidoc/cdi-adv-examples/cdi-adv-examples.adoc b/src/main/asciidoc/cdi-adv-examples/cdi-adv-examples.adoc new file mode 100644 index 00000000..27d795b2 --- /dev/null +++ b/src/main/asciidoc/cdi-adv-examples/cdi-adv-examples.adoc @@ -0,0 +1,20 @@ += Running the Advanced Contexts and Dependency Injection Examples + + +[[GKHRE]][[running-the-advanced-contexts-and-dependency-injection-examples]] + +This chapter describes in detail how to build and run several advanced +examples that use CDI. + +include::cdi-adv-examples001.adoc[] + +include::cdi-adv-examples002.adoc[] + +include::cdi-adv-examples003.adoc[] + +include::cdi-adv-examples004.adoc[] + +include::cdi-adv-examples005.adoc[] + +include::cdi-adv-examples006.adoc[] + diff --git a/src/main/asciidoc/cdi-adv-examples/cdi-adv-examples001.adoc b/src/main/asciidoc/cdi-adv-examples/cdi-adv-examples001.adoc new file mode 100644 index 00000000..4f85b793 --- /dev/null +++ b/src/main/asciidoc/cdi-adv-examples/cdi-adv-examples001.adoc @@ -0,0 +1,15 @@ +[[A1251406]][[building-and-running-the-cdi-advanced-examples]] + +== 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. + +1. Use NetBeans IDE or the Maven tool to compile, package, and deploy +the example. +2. Run the example in a web browser. + +See link:#GFIUD[Chapter 2, "Using the Tutorial +Examples"], for basic information on installing, building, and running +the examples. + diff --git a/src/main/jbake/content/cdi-adv-examples002.adoc b/src/main/asciidoc/cdi-adv-examples/cdi-adv-examples002.adoc similarity index 83% rename from src/main/jbake/content/cdi-adv-examples002.adoc rename to src/main/asciidoc/cdi-adv-examples/cdi-adv-examples002.adoc index 6d2744be..c280848f 100644 --- a/src/main/jbake/content/cdi-adv-examples002.adoc +++ b/src/main/asciidoc/cdi-adv-examples/cdi-adv-examples002.adoc @@ -1,20 +1,10 @@ -type=page -status=published -title=The encoder Example: Using Alternatives -next=cdi-adv-examples003.html -prev=cdi-adv-examples001.html -~~~~~~ -= The encoder Example: Using Alternatives - - [[GKHPU]][[the-encoder-example-using-alternatives]] -The encoder Example: Using Alternatives ---------------------------------------- +== The encoder Example: Using Alternatives The `encoder` example shows how to use alternatives to choose between two beans at deployment time, as described in -link:cdi-adv002.html#GJSDF[Using Alternatives in CDI Applications]. The +link:#GJSDF[Using Alternatives in CDI Applications]. The example includes an interface and two implementations of it, a managed bean, a Facelets page, and configuration files. @@ -22,22 +12,15 @@ The source files are located in the `_tut-install_/examples/cdi/encoder/src/main/java/jakarta/tutorial/encoder/` directory. -The following topics are addressed here: - -* link:#GKHQA[The Coder Interface and Implementations] -* link:#GKHPM[The encoder Facelets Page and Managed Bean] -* link:#GKHQQ[Running the encoder Example] - [[GKHQA]][[the-coder-interface-and-implementations]] -The Coder Interface and Implementations -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== The Coder Interface and Implementations The `Coder` interface contains just one method, `codeString`, that takes two arguments: a string, and an integer value that specifies how the letters in the string should be transposed. -[source,oac_no_warn] +[source,java] ---- public interface Coder { @@ -55,7 +38,7 @@ generals.) The implementation in `TestCoderImpl` merely displays the values of the arguments. The `TestCoderImpl` implementation is annotated `@Alternative`: -[source,oac_no_warn] +[source,java] ---- import javax.enterprise.inject.Alternative; @@ -73,7 +56,7 @@ The `beans.xml` file for the `encoder` example contains an `alternatives` element for the `TestCoderImpl` class, but by default the element is commented out: -[source,oac_no_warn] +[source,xml] ---- @@ -62,7 +52,7 @@ certain that this is the protection scheme you intend to define. The following example shows a constraint that lists the GET method and thus defines no protection on any of the other possible HTTP methods: + -[source,oac_no_warn] +[source,xml] ---- @@ -90,7 +80,7 @@ For example, to permit GET and POST, where POST requires authentication and GET is permitted without constraint, you could define the following constraints: + -[source,oac_no_warn] +[source,xml] ---- @@ -125,7 +115,7 @@ For example, the following constraint excludes access to all methods except GET and POST at the resources matched by the pattern `/company/*`: + -[source,oac_no_warn] +[source,xml] ---- @@ -142,7 +132,7 @@ except GET and POST at the resources matched by the pattern If you want to extend these exclusions to the unconstrained parts of your application, also include the URL pattern `/` (forward slash): + -[source,oac_no_warn] +[source,xml] ---- @@ -163,7 +153,7 @@ associate it with the URL pattern `/`. The URL pattern `/` is the weakest matching pattern. Do not list any HTTP methods in this constraint: + -[source,oac_no_warn] +[source,xml] ---- diff --git a/src/main/jbake/content/security-advanced005.adoc b/src/main/asciidoc/security-advanced/security-advanced005.adoc similarity index 85% rename from src/main/jbake/content/security-advanced005.adoc rename to src/main/asciidoc/security-advanced/security-advanced005.adoc index e221237c..e25d8d95 100644 --- a/src/main/jbake/content/security-advanced005.adoc +++ b/src/main/asciidoc/security-advanced/security-advanced005.adoc @@ -1,16 +1,6 @@ -type=page -status=published -title=Securing Application Clients -next=security-advanced006.html -prev=security-advanced004.html -~~~~~~ -Securing Application Clients -============================ - [[GLIGC]][[securing-application-clients]] -Securing Application Clients ----------------------------- +== Securing Application Clients The Jakarta EE authentication requirements for application clients are the same as for other Jakarta EE components, and the same authentication @@ -20,15 +10,15 @@ 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. -link:security-webtier002.html#BNCBN[Specifying an Authentication +link:#BNCBN[Specifying an Authentication Mechanism in the Deployment Descriptor] describes how to specify HTTP basic authentication and HTTP login-form authentication. -link:security-advanced002.html#GLIEQ[Client Authentication] describes how +link:#GLIEQ[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 -link:security-jakartaee002.html#BNBYL[Securing Enterprise Beans]. +link:#BNBYL[Securing Enterprise Beans]. An application client makes use of an authentication service provided by the application client container for authenticating its users. The @@ -47,8 +37,7 @@ package. [[GLIDW]][[using-login-modules]] -Using Login Modules -~~~~~~~~~~~~~~~~~~~ +=== Using Login Modules An application client can use the Java Authentication and Authorization Service (JAAS) to create login modules for authentication. A JAAS-based @@ -82,13 +71,12 @@ name. For more information on using JAAS for authentication in login modules, refer to the documentation listed in -link:security-advanced008.html#BABBGBBF[Further Information about +link:#BABBGBBF[Further Information about Advanced Security Topics]. [[GLIHQ]][[using-programmatic-login]] -Using Programmatic Login -~~~~~~~~~~~~~~~~~~~~~~~~ +=== Using Programmatic Login Programmatic login enables the client code to supply user credentials. If you are using an enterprise bean client, you can use the diff --git a/src/main/jbake/content/security-advanced006.adoc b/src/main/asciidoc/security-advanced/security-advanced006.adoc similarity index 84% rename from src/main/jbake/content/security-advanced006.adoc rename to src/main/asciidoc/security-advanced/security-advanced006.adoc index 32b50b52..68c87987 100644 --- a/src/main/jbake/content/security-advanced006.adoc +++ b/src/main/asciidoc/security-advanced/security-advanced006.adoc @@ -1,32 +1,13 @@ -type=page -status=published -title=Securing Enterprise Information Systems Applications -next=security-advanced007.html -prev=security-advanced005.html -~~~~~~ -= Securing Enterprise Information Systems Applications - [[GLIFD]][[securing-enterprise-information-systems-applications]] -Securing Enterprise Information Systems Applications ----------------------------------------------------- +== Securing Enterprise Information Systems Applications In Enterprise Information Systems (EIS) applications, components request a connection to an EIS resource. -The following topics are addressed here: - -* link:#overview-of-securing-enterprise-information-systems-applications[Overview of Securing Enterprise Information Systems -Applications] -* link:#container-managed-sign-on[Container-Managed Sign-On] -* link:#component-managed-sign-on[Component-Managed Sign-On] -* link:#configuring-resource-adapter-security[Configuring Resource Adapter Security] -* link:#mapping-an-application-principal-to-eis-principals[Mapping an Application Principal to EIS Principals] - [[BABBJHIC]][[overview-of-securing-enterprise-information-systems-applications]] -Overview of Securing Enterprise Information Systems Applications -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Overview of Securing Enterprise Information Systems Applications As part of this connection, the EIS can require a sign-on for the requester to access the resource. The application component provider has @@ -44,15 +25,14 @@ link:#GLIGS[Configuring Resource Adapter Security]. [[GLIHL]][[container-managed-sign-on]] -Container-Managed Sign-On -~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Container-Managed Sign-On In container-managed sign-on, an application component does not have to pass any sign-on security information to the `getConnection()` method. The security information is supplied by the container, as shown in the following example (the method call is highlighted in bold): -[source,oac_no_warn] +[source,java] ---- // Business method in an application component Context initctx = new InitialContext(); @@ -68,8 +48,7 @@ javax.resource.cci.Connection cx = cxf.getConnection(); [[GLIDP]][[component-managed-sign-on]] -Component-Managed Sign-On -~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Component-Managed Sign-On In component-managed sign-on, an application component is responsible for passing the needed sign-on security information for the resource to @@ -77,7 +56,7 @@ the `getConnection` method. For example, security information might be a user name and password, as shown here (the method call is highlighted in bold): -[source,oac_no_warn] +[source,java] ---- // Method in an application component Context initctx = new InitialContext(); @@ -100,8 +79,7 @@ javax.resource.cci.Connection cx = [[GLIGS]][[configuring-resource-adapter-security]] -Configuring Resource Adapter Security -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Configuring Resource Adapter Security A resource adapter is a system-level software component that typically implements network connectivity to an external resource manager. A @@ -120,7 +98,7 @@ edit the resource adapter descriptor file, `ra.xml`. Here is an example of the part of an `ra.xml` file that configures security properties for a resource adapter: -[source,oac_no_warn] +[source,xml] ---- @@ -147,14 +125,14 @@ There are two supported mechanism types: ** `BasicPassword`, which supports the following interface: + -[source,oac_no_warn] +[source,java] ---- javax.resource.spi.security.PasswordCredential ---- ** `Kerbv5`, which supports the following interface: + -[source,oac_no_warn] +[source,java] ---- javax.resource.spi.security.GenericCredential ---- @@ -177,7 +155,7 @@ in the connector specification. + For more information on the implementation of the security permission specification, see the security policy file documentation listed in -link:security-advanced008.html#BABBGBBF[Further Information about +link:#BABBGBBF[Further Information about Advanced Security Topics]. In addition to specifying resource adapter security in the `ra.xml` @@ -189,8 +167,7 @@ various principals or user groups in the application. [[GLIGW]][[mapping-an-application-principal-to-eis-principals]] -Mapping an Application Principal to EIS Principals -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Mapping an Application Principal to EIS Principals When using GlassFish Server, you can use security maps to map the caller identity of the application (principal or user group) to a suitable EIS diff --git a/src/main/jbake/content/security-advanced007.adoc b/src/main/asciidoc/security-advanced/security-advanced007.adoc similarity index 79% rename from src/main/jbake/content/security-advanced007.adoc rename to src/main/asciidoc/security-advanced/security-advanced007.adoc index 5af1dbfa..21d631dd 100644 --- a/src/main/jbake/content/security-advanced007.adoc +++ b/src/main/asciidoc/security-advanced/security-advanced007.adoc @@ -1,15 +1,6 @@ -type=page -status=published -title=Configuring Security Using Deployment Descriptors -next=security-advanced008.html -prev=security-advanced006.html -~~~~~~ -= Configuring Security Using Deployment Descriptors - [[GKHRL]][[configuring-security-using-deployment-descriptors]] -Configuring Security Using Deployment Descriptors -------------------------------------------------- +== Configuring Security Using Deployment Descriptors The recommended way to configure security in the Jakarta EE 8 platform is with annotations. If you wish to override the security settings at @@ -18,17 +9,9 @@ deployment descriptor to do so. This section describes how to use the deployment descriptor to specify basic authentication and to override default principal-to-role mapping. -The following topics are addressed here: - -* link:#specifying-security-for-basic-authentication-in-the-deployment-descriptor[Specifying Security for Basic Authentication in the -Deployment Descriptor] -* link:#specifying-non-default-principal-to-role-mapping-in-the-deployment-descriptor[Specifying Non-Default Principal-to-Role Mapping in the -Deployment Descriptor] - [[BNCCM]][[specifying-security-for-basic-authentication-in-the-deployment-descriptor]] -Specifying Security for Basic Authentication in the Deployment Descriptor -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Specifying Security for Basic Authentication in the Deployment Descriptor The elements of the deployment descriptor that add basic authentication to an example tell the server or browser to perform the following tasks. @@ -43,7 +26,7 @@ descriptor that could be used in the example of basic authentication found in the tut-install`/examples/security/hello2_basicauth/` directory: -[source,oac_no_warn] +[source,xml] ---- SecurityConstraint @@ -76,8 +59,7 @@ it from being read in transit. [[GKAFQ]][[specifying-non-default-principal-to-role-mapping-in-the-deployment-descriptor]] -Specifying Non-Default Principal-to-Role Mapping in the Deployment Descriptor -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Specifying Non-Default Principal-to-Role Mapping in the Deployment Descriptor Jakarta Security requires that group principal names be mapped to roles of the same name by default. GlassFish adheres to this standard, by default, @@ -93,7 +75,7 @@ security role used in the application and one or more groups or principals defined for the applicable realm of GlassFish Server. An example for the `glassfish-web.xml` file is shown below: -[source,oac_no_warn] +[source,xml] ---- diff --git a/src/main/jbake/content/security-advanced008.adoc b/src/main/asciidoc/security-advanced/security-advanced008.adoc similarity index 67% rename from src/main/jbake/content/security-advanced008.adoc rename to src/main/asciidoc/security-advanced/security-advanced008.adoc index 46819aa7..f297b6e8 100644 --- a/src/main/jbake/content/security-advanced008.adoc +++ b/src/main/asciidoc/security-advanced/security-advanced008.adoc @@ -1,16 +1,6 @@ -type=page -status=published -title=Further Information about Advanced Security Topics -next=partsupporttechs.html -prev=security-advanced007.html -~~~~~~ -Further Information about Advanced Security Topics -================================================== - [[BABBGBBF]][[further-information-about-advanced-security-topics]] -Further Information about Advanced Security Topics --------------------------------------------------- +== Further Information about Advanced Security Topics For more information about the security topics covered in this chapter, see diff --git a/src/main/asciidoc/security-api/security-api.adoc b/src/main/asciidoc/security-api/security-api.adoc new file mode 100644 index 00000000..ecd79fcf --- /dev/null +++ b/src/main/asciidoc/security-api/security-api.adoc @@ -0,0 +1,18 @@ += Using Jakarta Security + +[[using-the-jakarta-ee-security-api]] + +This chapter describes the authentication and credential validation +functionality provided by Jakarta Security. The API also +defines a SecurityContext access point for programmatic security. + +include::security-api001.adoc[] + +include::security-api002.adoc[] + +include::security-api003.adoc[] + +include::security-api004.adoc[] + +include::security-api005.adoc[] + diff --git a/src/main/jbake/content/security-api001.adoc b/src/main/asciidoc/security-api/security-api001.adoc similarity index 97% rename from src/main/jbake/content/security-api001.adoc rename to src/main/asciidoc/security-api/security-api001.adoc index 4fffd37f..b767eb0b 100644 --- a/src/main/jbake/content/security-api001.adoc +++ b/src/main/asciidoc/security-api/security-api001.adoc @@ -1,14 +1,5 @@ -type=page -status=published -title=About Jakarta Security -next=security-api002.html -prev=security-api.html -~~~~~~ -= About the Jakarta Security - [[about-the-jakarta-ee-security-api]] -About Jakarta Security ----------------------- +== About Jakarta Security Jakarta EE includes support for Jakarta Security, which defines portable, plug-in interfaces for authentication and identity stores, and a new injectable-type SecurityContext diff --git a/src/main/jbake/content/security-api002.adoc b/src/main/asciidoc/security-api/security-api002.adoc similarity index 92% rename from src/main/jbake/content/security-api002.adoc rename to src/main/asciidoc/security-api/security-api002.adoc index dd35c89e..64440ffe 100644 --- a/src/main/jbake/content/security-api002.adoc +++ b/src/main/asciidoc/security-api/security-api002.adoc @@ -1,15 +1,5 @@ -type=page -status=published -title=Overview of the HTTP Authentication Mechanism Interface -next=security-api003.html -prev=security-api001.html -~~~~~~ -= Overview of the HTTP Authentication Mechanism Interface - - [[overview-of-the-http-authentication-mechanism-interface]] -Overview of the HTTP Authentication Mechanism Interface -------------------------------------------------------- +== Overview of the HTTP Authentication Mechanism Interface The `HttpAuthenticationMechanism` interface defines an SPI for writing authentication mechanisms that can be provided with an application and diff --git a/src/main/jbake/content/security-api003.adoc b/src/main/asciidoc/security-api/security-api003.adoc similarity index 94% rename from src/main/jbake/content/security-api003.adoc rename to src/main/asciidoc/security-api/security-api003.adoc index 5cd71b06..6f796074 100644 --- a/src/main/jbake/content/security-api003.adoc +++ b/src/main/asciidoc/security-api/security-api003.adoc @@ -1,22 +1,12 @@ -type=page -status=published -title=Overview of the Identity Store Interfaces -next=security-api004.html -prev=security-api002.html -~~~~~~ -= Overview of the Identity Store Interfaces - [[overview-of-the-identity-store-interfaces]] -Overview of the Identity Store Interfaces ------------------------------------------ +== Overview of the Identity Store Interfaces The Identity Store Interfaces are described in the following sections: * link:#the-identitystore-interface[The IdentityStore Interface] * link:#the-remembermeidentitystore-interface[The RememberMeIdentityStore Interface] [[the-identitystore-interface]] -The IdentityStore Interface -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== The IdentityStore Interface The `IdentityStore` interface defines an SPI for interacting with identity stores, which are directories or databases containing user account information. An implementation of the `IdentityStore` interface can validate users' credentials, @@ -43,9 +33,9 @@ configuring a Database Identity Store. See link:#the-passwordhash-interface[The 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: -* link:security-api004.html#running-the-built-in-database-identity-store-example[Running the Built-In Database Identity Store Example] +* link:#running-the-built-in-database-identity-store-example[Running the Built-In Database Identity Store Example] -* link:security-api005.html#running-the-custom-identity-store-example[Running the Custom Identity Store Example] +* link:#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. @@ -57,8 +47,7 @@ Multiple implementations of `IdentityStore` may be present. If so, they are invo under the control of an `IdentityStoreHandler`. [[identitystorehandler]] -IdentityStoreHandler -^^^^^^^^^^^^^^^^^^^^ +==== IdentityStoreHandler Authentication mechanisms do not interact with `IdentityStore` directly; instead, they call an `IdentityStoreHandler`. An implementation of the `IdentityStoreHandler` interface provides a single method, `validate(Credential)`, which, when invoked, @@ -85,8 +74,7 @@ desired algorithm to select and invoke on IdentityStores, and return an aggregated (or non-aggregated) result. [[identitystoreinterface-methods]] -IdentityStore Interface Methods -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== IdentityStore Interface Methods The IdentityStore interface itself has four methods: @@ -114,8 +102,7 @@ and the built-in IdentityStoreHandler invokes the `getCallerGroups()` method in the context of a `PrivilegedAction` block. [[the-passwordhash-interface]] -The PasswordHash Interface -^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== The PasswordHash Interface Unlike some types of identity stores, for example LDAP directories, databases can store and retrieve user passwords, but can't verify them natively. @@ -180,8 +167,7 @@ the password value based on the timing of failed attempts. * A new random salt should be used each time a new password hash value is generated. [[the-remembermeidentitystore-interface]] -The RememberMeIdentityStore Interface -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== The RememberMeIdentityStore Interface The `RememberMeIdentityStore` interface represents a special type of identity store. It is not directly related to the `IdentityStore` interface; that is, it does not implement or extend it. It does, however, perform a similar, albeit specialized, function. diff --git a/src/main/jbake/content/security-api004.adoc b/src/main/asciidoc/security-api/security-api004.adoc similarity index 83% rename from src/main/jbake/content/security-api004.adoc rename to src/main/asciidoc/security-api/security-api004.adoc index 055046a2..ca059600 100644 --- a/src/main/jbake/content/security-api004.adoc +++ b/src/main/asciidoc/security-api/security-api004.adoc @@ -1,15 +1,5 @@ -type=page -status=published -title=Running the Built-In Database Identity Store Example -next=security-api005.html -prev=security-api003.html -~~~~~~ -= Running the Built-In Database Identity Store Example - - [[running-the-built-in-database-identity-store-example]] -Running the Built-In Database Identity Store Example ----------------------------------------------------- +== Running the Built-In Database Identity Store Example The example described in this section demonstrates how to use the built-in database identity store for credential validation. @@ -19,8 +9,7 @@ Topics include: * link:#running-the-built-in-db-id-store-example[Running the built-in-db-identity-store Example] [[overview-of-the-built-in-database-identity-store-example]] -Overview of the Built-In Database Identity Store Example -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Overview of the Built-In Database Identity Store Example Jakarta Security mandates that a Jakarta EE container MUST support a built-in `IdentityStore` backed by a database. To support this mandatory requirement, `DatabaseIdentityStore` is bundled with GlassFish. @@ -54,7 +43,7 @@ Note that in GlassFish, if the user provides the wrong credentials when using `BasicAuthenticationMechanism`, then the `realmName` is presented to user, as a hint. -[source,oac_no_warn] +[source,java] ---- curl -I -u Joe http://localhost:8080/built-in-db-identity-store/servlet Enter host password for user 'Joe': @@ -69,8 +58,7 @@ Content-Type: text/html [[define-the-users-and-groups-in-the-identity-store]] -Define the Users and Groups in the Identity Store -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== Define the Users and Groups in the Identity Store The following table shows the users, passwords, and groups used in this example. @@ -90,7 +78,7 @@ users in the `DatabaseSetup.java` file. With `@Startup` annotation, this singleton enterprise bean is initialized during application startup and the credentials are set in the underlying database. -[source,oac_no_warn] +[source,java] ---- import java.sql.Connection; @@ -137,14 +125,13 @@ public class DatabaseSetup { [[map-the-databaseidentitystore-to-the-default-data-source]] -Map the DatabaseIdentityStore to the Default Data source -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== Map the DatabaseIdentityStore to the Default Data source Use the `@DatabaseIdentityStoreDefinition` annotation to map the built-in `DatabaseIdentityStore` to the `DefaultDataSource` in the `ApplicationConfig.java` file. This example also demonstrates the use of the `Pbkdf2PasswordHash` interface. -[source,oac_no_warn] +[source,java] ---- // Database Definition for built-in DatabaseIdentityStore @@ -170,8 +157,7 @@ public class ApplicationConfig { } ---- [[specify-the-authentication-mechanism]] -Specify the Authentication Mechanism -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== Specify the Authentication Mechanism In this application, credentials are validated using the BASIC authentication mechanism. Specify the `@BasicAuthenticationMechanismDefinition` annotation in the `ApplicationConfig.java` @@ -183,7 +169,7 @@ to `org.glassfish.soteria.mechanisms.jaspic.HttpBridgeServerAuthModule`, which then invokes the `BasicAuthenticationMechanism#validateRequest` method, and gets the credential from the request. -[source,oac_no_warn] +[source,java] ---- @BasicAuthenticationMechanismDefinition( realmName = "file" @@ -191,14 +177,13 @@ the credential from the request. ---- [[declare-roles-in-the-servlet-container]] -Declare Roles in the Servlet Container -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== Declare Roles in the Servlet Container When a request is made to the application, the roles the user is in are returned as part of the response. Note that the container needs to be made aware of the supported roles, which are defined using the `@DeclareRoles({ "foo", "bar", "kaz" })` annotation as shown below. -[source,oac_no_warn] +[source,java] ---- @WebServlet("/servlet") @DeclareRoles({ "foo", "bar", "kaz" }) @@ -230,8 +215,7 @@ not need to bundle web.xml with the application to provide mapping between roles and groups. [[running-the-built-in-db-identity-store-example]] -Running the built-in-db-identity-store Example -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Running the built-in-db-identity-store Example 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: @@ -242,21 +226,20 @@ 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 NetBeans IDE -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== To Build, Package, and Deploy the built-in-db-identity-store Example Using NetBeans IDE 1. 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 link:usingexamples004.html#starting-and-stopping-the-java-db-server[Starting and Stopping Apache Derby]. +See link:#starting-and-stopping-the-java-db-server[Starting and Stopping Apache Derby]. 2. If you have not already done so, start the GlassFish server. See -link:usingexamples002.html#starting-and-stopping-glassfish-server[Starting and Stopping GlassFish Server]. +link:#starting-and-stopping-glassfish-server[Starting and Stopping GlassFish Server]. 3. From the File menu, choose Open Project. 4. In the Open Project dialog box, navigate to: + -[source,oac_no_warn] +[source,java] ---- tut-install/examples/security/security-api ---- @@ -270,26 +253,25 @@ GlassFish Server instance. [[to-build-package-and-deploy-the-built-in-db-identity-store-example-using-using-maven]] -To Build, Package, and Deploy the built-in-db-identity-store Example Using Maven -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== To Build, Package, and Deploy the built-in-db-identity-store Example Using Maven 1. 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 link:usingexamples004.html#starting-and-stopping-the-java-db-server[Starting and Stopping Apache Derby]. +See link:#starting-and-stopping-the-java-db-server[Starting and Stopping Apache Derby]. 2. If you have not already done so, start the GlassFish server. See -link:usingexamples002.html#starting-and-stopping-glassfish-server[Starting and Stopping GlassFish Server]. +link:#starting-and-stopping-glassfish-server[Starting and Stopping GlassFish Server]. 3. In a terminal window, go to: + -[source,oac_no_warn] +[source,java] ---- tut-install/examples/security/security-api/built-in-db-identity-store ---- 4. Enter the following command: + -[source,oac_no_warn] +[source,java] ---- mvn install ---- @@ -299,19 +281,18 @@ This command builds and packages the application into a WAR file, deploys the WAR file. [[to-run-the-built-in-db-identity-store-example]] -To Run the built-in-db-identity-store Example -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== To Run the built-in-db-identity-store Example In this example, use the credentials of user Joe to make a request and to validate the response according to the credentials/roles defined in `DatabaseSetup.java`. -1. Make a request to the deployed application by entering +. Make a request to the deployed application by entering the following request URL in your web browser: + Request URL: + -[source,oac_no_warn] +[source,java] ---- http://localhost:8080/built-in-db-identity-store/servlet ---- @@ -319,7 +300,7 @@ http://localhost:8080/built-in-db-identity-store/servlet Because BASIC authentication is being used here, the container responds back prompting for username and password. -2. Enter the username `Joe`, and the password `secret1` at the prompt. +. Enter the username `Joe`, and the password `secret1` at the prompt. + Once you provide the credentials, the following process occurs: + @@ -342,7 +323,7 @@ in question and the following response is returned to the end user. + Response: + -[source,oac_no_warn] +[source,java] ---- web username: Joe web user has role "foo": true @@ -350,13 +331,13 @@ web user has role "bar": true web user has role "kaz": false ---- -3. Test the authentication using invalid credentials. Make a request to the +. Test the authentication using invalid credentials. Make a request to the deployed application by entering the following request URL in your web browser: + Request URL: + -[source,oac_no_warn] +[source,java] ---- http://localhost:8080/built-in-db-identity-store/servlet ---- @@ -364,14 +345,13 @@ http://localhost:8080/built-in-db-identity-store/servlet Again, because BASIC authentication is being used here, the container responds back prompting for username and password. -2. Enter an invalid username and password. +. Enter an invalid username and password. You are promted to enter the credentials again, but you are not authenticated. - + When you click Cancel in the Authentication required window, the following response is returned: + -[source,oac_no_warn] +[source,java] ---- HTTP Status 401 - Unauthorized diff --git a/src/main/jbake/content/security-api005.adoc b/src/main/asciidoc/security-api/security-api005.adoc similarity index 77% rename from src/main/jbake/content/security-api005.adoc rename to src/main/asciidoc/security-api/security-api005.adoc index e201a978..3a755a47 100644 --- a/src/main/jbake/content/security-api005.adoc +++ b/src/main/asciidoc/security-api/security-api005.adoc @@ -1,15 +1,5 @@ -type=page -status=published -title=Running the Custom Identity Store Example -next=security-advanced.html -prev=security-api004.html -~~~~~~ -= Running the Custom Identity Store Example - - [[running-the-custom-identity-store-example]] -Running the Custom Identity Store Example ------------------------------------------ +== Running the Custom Identity Store Example The example described in this section demonstrates how to bundle and use a custom identity store in your application for credential validation. @@ -19,8 +9,7 @@ Topics include: * link:#running-the-custom-id-store-example[Running the custom-identity-store Example] [[overview-of-the-custom-identity-store-example]] -Overview of the Custom Identity Store Example -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Overview of the Custom Identity Store Example As an alternative to using a built-in identity store, an application can provide its own IdentityStore. When bundled with the application, this custom identity store can then be used for authentication and authorization. @@ -37,9 +26,9 @@ the `TestIdentityStore`. Note that the configuration described in these sections already been completed in the application files, but is provided here to illustrate what you need to do to use a custom identity store. -* link:#define-the-users-and-groups-in-the-identity-store[Define the Users and Groups in the Identity Store] -* link:#specify-the-authentication-mechanism[Specify the Authentication Mechanism] -* link:#declare-roles-in-the-servlet-container[Declare Roles in the Servlet Container] +* link:#define-the-users-and-groups-in-the-identity-store-2[Define the Users and Groups in the Identity Store] +* link:#specify-the-authentication-mechanism-2[Specify the Authentication Mechanism] +* link:#declare-roles-in-the-servlet-container-2[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 @@ -52,7 +41,7 @@ Note that in GlassFish, if the user provides the wrong credentials when using `BasicAuthenticationMechanism`, then the `realmName` is presented to user, as a hint. -[source,oac_no_warn] +[source,java] ---- curl -I -u Joe http://localhost:8080/custom-identity-store/servlet Enter host password for user 'Joe': @@ -65,9 +54,9 @@ Content-Language: Content-Type: text/html ---- -[[define-the-users-and-groups-in-the-identity-store]] -Define the Users and Groups in the Identity Store -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +[[define-the-users-and-groups-in-the-identity-store-2]] + +==== Define the Users and Groups in the Identity Store The following table shows the user, password, and group used in this example. @@ -81,22 +70,23 @@ The following table shows the user, password, and group used in this example. The following code snippet shows how you define the credentials and the roles assigned to users in the `TestIdentityStore.java` file. -[source,oac_no_warn] +[source,java] ---- if (usernamePasswordCredential.compareTo("Joe", "secret1")) { return new CredentialValidationResult("Joe", new HashSet<>(asList("foo", "bar"))); } ---- -[[specify-the-authentication-mechanism]] -Specify the Authentication Mechanism -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +[[specify-the-authentication-mechanism-2]] + +==== Specify the Authentication Mechanism In this application, credentials are validated using the BASIC authentication mechanism. Specify the `@BasicAuthenticationMechanismDefinition` annotation in the `ApplicationConfig.java` to ensure that the `BasicAuthenticationMechanism` is used to perform credential validation. -[source,oac_no_warn] +[source,java] ---- @BasicAuthenticationMechanismDefinition( @@ -112,15 +102,16 @@ public class ApplicationConfig { ---- -[[declare-roles-in-the-servlet-container]] -Declare Roles in the Servlet Container -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +[[declare-roles-in-the-servlet-container-2]] + +==== Declare Roles in the Servlet Container + When a request is made to the application, the roles the user is in are returned as part of the response. Note that the container needs to be made aware of the supported roles, which are defined using the `@Declareroles({ "foo", "bar", "kaz" })` annotation as shown below. -[source,oac_no_warn] +[source,java] ---- @DeclareRoles({ "foo", "bar", "kaz" }) @WebServlet("/servlet") @@ -151,8 +142,7 @@ not need to bundle `web.xml` with the application to provide mapping between rol and groups. [[running-the-custom-id-store-example]] -Running the custom-identity-store Example -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== 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: @@ -163,15 +153,14 @@ 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 NetBeans IDE -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== To Build, Package, and Deploy the custom-identity-store Example Using NetBeans IDE 1. If you have not already done so, start the GlassFish server. See -link:usingexamples002.html#starting-and-stopping-glassfish-server[Starting and Stopping GlassFish Server]. +link:#starting-and-stopping-glassfish-server[Starting and Stopping GlassFish Server]. 2. From the File menu, choose Open Project. 3. In the Open Project dialog box, navigate to: + -[source,oac_no_warn] +[source,java] ---- tut-install/examples/security/security-api ---- @@ -183,22 +172,21 @@ select Build. This command builds and deploys the example application to your GlassFish Server instance. -[[GJQZH]][[to-build-package-and-deploy-the-custom-identity-store-example-using-using-maven]] +[[to-build-package-and-deploy-the-custom-identity-store-example-using-using-maven]] -To Build, Package, and Deploy the custom-identity-store Example Using Maven -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== To Build, Package, and Deploy the custom-identity-store Example Using Maven 1. If you have not already done so, start the GlassFish server. See -link:usingexamples002.html#starting-and-stopping-glassfish-server[Starting and Stopping GlassFish Server].. +link:#starting-and-stopping-glassfish-server[Starting and Stopping GlassFish Server].. 2. In a terminal window, go to: + -[source,oac_no_warn] +[source,java] ---- tut-install/examples/security/security-api/custom-identity-store ---- 3. Enter the following command: + -[source,oac_no_warn] +[source,java] ---- mvn install ---- @@ -208,8 +196,7 @@ This command builds and packages the application into a WAR file, deploys the WAR file. [[to-run-the-custom-identity-store-example]] -To Run the custom-identity-store Example -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== To Run the custom-identity-store Example In this example, use the credentials of user `Joe` to make a request and to validate the response according to the credentials defined in `TestIdentityStore`. @@ -218,14 +205,14 @@ the following request URL in your web browser: + Request URL: + -[source,oac_no_warn] +[source,java] ---- http://localhost:8080/custom-identity-store/servlet?name=Joe&password=secret1 ---- + Response: + -[source,oac_no_warn] +[source,java] ---- web username: Joe web user has role "foo": true @@ -239,14 +226,14 @@ in your web browser: + Request URL: + -[source,oac_no_warn] +[source,java] ---- http://localhost:8080/custom-identity-store/servlet?name=Joe&password=secret3 ---- + Response: + -[source,oac_no_warn] +[source,java] ---- HTTP Status 401 - Unauthorized diff --git a/src/main/asciidoc/security-intro/security-intro.adoc b/src/main/asciidoc/security-intro/security-intro.adoc new file mode 100644 index 00000000..73cdc6f3 --- /dev/null +++ b/src/main/asciidoc/security-intro/security-intro.adoc @@ -0,0 +1,36 @@ += Introduction to Security in the Jakarta EE Platform + +[[BNBWJ]][[introduction-to-security-in-the-jakarta-ee-platform]] + +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 8 specification. + +[width="100%",cols="100%",] +|======================================================================= +a| +*Note:* + +The SDK may include additional material demonstrating key features of Jakarta Security. Please check the latest SDK release notes for additional details. + +|======================================================================= + + +include::security-intro001.adoc[] + +include::security-intro002.adoc[] + +include::security-intro003a.adoc[] + +include::security-intro003.adoc[] + +include::security-intro004.adoc[] + +include::security-intro005a.adoc[] + +include::security-intro005.adoc[] + +include::security-intro006.adoc[] + +include::security-intro007.adoc[] + diff --git a/src/main/jbake/content/security-intro001.adoc b/src/main/asciidoc/security-intro/security-intro001.adoc similarity index 87% rename from src/main/jbake/content/security-intro001.adoc rename to src/main/asciidoc/security-intro/security-intro001.adoc index 2a1a3d1b..468e9ee9 100644 --- a/src/main/jbake/content/security-intro001.adoc +++ b/src/main/asciidoc/security-intro/security-intro001.adoc @@ -1,15 +1,6 @@ -type=page -status=published -title=Overview of Jakarta Security -next=security-intro002.html -prev=security-intro.html -~~~~~~ -= Overview of Jakarta Security - [[BNBWK]][[overview-of-jakarta-ee-security]] -Overview of Jakarta Security ----------------------------- +== Overview of Jakarta Security Every enterprise that has either sensitive resources that can be accessed by many users or resources that traverse unprotected, open @@ -28,7 +19,7 @@ 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 -link:security-intro003.html#BNBXF[Using Deployment Descriptors for +link:#BNBXF[Using Deployment Descriptors for Declarative Security]. + Annotations, also called metadata, are used to specify information about @@ -39,13 +30,13 @@ declarative information inside XML descriptors. 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 -link:security-intro003.html#BNBXG[Using Annotations to Specify Security +link:#BNBXG[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 link:security-intro003.html#BNBXH[Using Programmatic +security, read link:#BNBXH[Using Programmatic Security]. Jakarta EE 8 includes a Security API specification that defines portable, @@ -61,20 +52,19 @@ specification. Other chapters in this Part discuss security requirements in web tier and enterprise tier applications, and the Jakarta Security. -* link:security-webtier.html#BNCAS[Chapter 51, "Getting Started Securing +* link:#BNCAS[Chapter 51, "Getting Started Securing Web Applications"] explains how to add security to web components, such as servlets. -* link:security-jakartaee.html#BNBYK[Chapter 52, "Getting Started Securing +* link:#BNBYK[Chapter 52, "Getting Started Securing Enterprise Applications"] explains how to add security to Jakarta EE components, such as enterprise beans and application clients. -* link:security-api.html#using-the-jakarta-ee-security-api[53 Using Jakarta Security] +* link:#using-the-jakarta-ee-security-api[53 Using Jakarta Security] describes the authentication and credential validation funtionality provided by Jakarta Security, and provides examples. [[BNBWL]][[a-simple-application-security-walkthrough]] -A Simple Application Security Walkthrough -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== A Simple Application Security Walkthrough The security behavior of a Jakarta EE environment may be better understood by examining what happens in a simple application with a web client, a @@ -87,8 +77,7 @@ client and using it to establish an authenticated session. [[BNBWM]][[step-1-initial-request]] -Step 1: Initial Request -^^^^^^^^^^^^^^^^^^^^^^^ +==== Step 1: Initial Request In the first step of this example, the web client requests the main application URL. This action is shown in link:#BNBWN[Figure 50-1]. @@ -96,7 +85,7 @@ application URL. This action is shown in link:#BNBWN[Figure 50-1]. [[BNBWN]] .*Figure 50-1 Initial Request* -image:img/jakartaeett_dt_039.png[ +image:jakartaeett_dt_039.png[ "Diagram of initial request from web client to web server for access to a protected resource"] @@ -105,12 +94,11 @@ 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 -link:security-intro002.html#BNBWY[Security Mechanisms]. +link:#BNBWY[Security Mechanisms]. [[BNBWO]][[step-2-initial-authentication]] -Step 2: Initial Authentication -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== 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 @@ -123,14 +111,13 @@ server sets a credential for the user. [[BNBWP]] .*Figure 50-2 Initial Authentication* -image:img/jakartaeett_dt_040.png[ +image:jakartaeett_dt_040.png[ "Diagram of initial authentication: server sends form to client, which sends authentication data to server for validation"] [[BNBWQ]][[step-3-url-authorization]] -Step 3: URL Authorization -^^^^^^^^^^^^^^^^^^^^^^^^^ +==== Step 3: URL Authorization The credential is used for future determinations of whether the user is authorized to access restricted resources it may request. The web server @@ -144,7 +131,7 @@ link:#BNBWR[Figure 50-3] shows this process. [[BNBWR]] .*Figure 50-3 URL Authorization* -image:img/jakartaeett_dt_041.png[ +image:jakartaeett_dt_041.png[ "Diagram of URL authorization"] The web server's evaluation stops with an "is authorized" outcome when @@ -154,8 +141,7 @@ the permitted roles. [[BNBWS]][[step-4-fulfilling-the-original-request]] -Step 4: Fulfilling the Original Request -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== 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 link:#BNBWT[Figure 50-4]. @@ -163,20 +149,19 @@ original URL request, as shown in link:#BNBWT[Figure 50-4]. [[BNBWT]] .*Figure 50-4 Fulfilling the Original Request* -image:img/jakartaeett_dt_042.png[ +image:jakartaeett_dt_042.png[ "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 -link:security-webtier.html#BNCAS[Chapter 51, "Getting Started Securing +link:#BNCAS[Chapter 51, "Getting Started Securing Web Applications"] for more information on protecting web applications. [[BNBWU]][[step-5-invoking-enterprise-bean-business-methods]] -Step 5: Invoking Enterprise Bean Business Methods -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== 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 @@ -187,7 +172,7 @@ one in the web server and one in the enterprise bean container. [[BNBWV]] .*Figure 50-5 Invoking an Enterprise Bean Business Method* -image:img/jakartaeett_dt_043.png[ +image:jakartaeett_dt_043.png[ "Diagram of authorization process between web component and enterprise bean"] @@ -213,8 +198,7 @@ and the web client. [[BNBWW]][[features-of-a-security-mechanism]] -Features of a Security Mechanism -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Features of a Security Mechanism A properly implemented security mechanism will provide the following functionality: @@ -234,8 +218,7 @@ Ideally, properly implemented security mechanisms will also be [[BNBWX]][[characteristics-of-application-security]] -Characteristics of Application Security -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Characteristics of Application Security Jakarta EE applications consist of components that can contain both protected and unprotected resources. Often, you need to protect diff --git a/src/main/jbake/content/security-intro002.adoc b/src/main/asciidoc/security-intro/security-intro002.adoc similarity index 91% rename from src/main/jbake/content/security-intro002.adoc rename to src/main/asciidoc/security-intro/security-intro002.adoc index a703378a..3447ae70 100644 --- a/src/main/jbake/content/security-intro002.adoc +++ b/src/main/asciidoc/security-intro/security-intro002.adoc @@ -1,15 +1,6 @@ -type=page -status=published -title=Security Mechanisms -next=security-intro003.html -prev=security-intro001.html -~~~~~~ -= Security Mechanisms - [[BNBWY]][[security-mechanisms]] -Security Mechanisms -------------------- +== Security Mechanisms The characteristics of an application should be considered when deciding the layer and type of security to be provided for applications. The @@ -18,15 +9,9 @@ that can be used to secure Jakarta EE applications. Each of these mechanisms can be used individually or with others to provide protection layers based on the specific needs of your implementation. -The following topics are addressed here: - -* link:#BNBWZ[Java SE Security Mechanisms] -* link:#BNBXA[Jakarta EE Security Mechanisms] - [[BNBWZ]][[java-se-security-mechanisms]] -Java SE Security Mechanisms -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Java SE Security Mechanisms Java SE provides support for a variety of security features and mechanisms. @@ -69,12 +54,11 @@ For more information on Java SE security, visit [[BNBXA]][[jakarta-ee-security-mechanisms]] -Jakarta EE Security Mechanisms -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== 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 -link:security-intro003.html#BNBXE[Securing Containers]). Jakarta EE security +link:#BNBXE[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 @@ -82,8 +66,7 @@ separate from the security mechanisms of the operating system. [[BNBXB]][[application-layer-security]] -Application-Layer Security -^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== Application-Layer Security In Jakarta EE, component containers are responsible for providing application-layer security, security services for a specific application @@ -119,12 +102,11 @@ transferable between application types. * Data is close to or contained within the point of vulnerability. For more information on providing security at the application layer, see -link:security-intro003.html#BNBXE[Securing Containers]. +link:#BNBXE[Securing Containers]. [[BNBXC]][[transport-layer-security]] -Transport-Layer Security -^^^^^^^^^^^^^^^^^^^^^^^^ +==== Transport-Layer Security Transport-layer security is provided by the transport mechanisms used to transmit information over the wire between clients and providers; thus, @@ -171,13 +153,12 @@ receives the message. * It is not an end-to-end solution, simply point-to-point. For more information on transport-layer security, see -link:security-intro006.html#BNBXW[Establishing a Secure Connection Using +link:#BNBXW[Establishing a Secure Connection Using SSL]. [[BNBXD]][[message-layer-security]] -Message-Layer Security -^^^^^^^^^^^^^^^^^^^^^^ +==== Message-Layer Security In message-layer security, security information is contained within the SOAP message and/or SOAP message attachment, which allows security diff --git a/src/main/jbake/content/security-intro003.adoc b/src/main/asciidoc/security-intro/security-intro003.adoc similarity index 75% rename from src/main/jbake/content/security-intro003.adoc rename to src/main/asciidoc/security-intro/security-intro003.adoc index 18e3c02b..cddd14d7 100644 --- a/src/main/jbake/content/security-intro003.adoc +++ b/src/main/asciidoc/security-intro/security-intro003.adoc @@ -1,30 +1,14 @@ -type=page -status=published -title=Securing Containers -next=security-intro003a.html -prev=security-intro002.html -~~~~~~ -= Securing Containers - [[BNBXE]][[securing-containers]] -Securing Containers -------------------- +== Securing Containers In Jakarta EE, the component containers are responsible for providing application security. A container provides two types of security: declarative and programmatic. -The following topics are addressed here: - -* link:#using-annotations-to-specify-security-information[Using Annotations to Specify Security Information] -* link:#using-deployment-descriptors-for-declarative-security[Using Deployment Descriptors for Declarative Security] -* link:#using-programmatic-security[Using Programmatic Security] - [[BNBXG]][[using-annotations-to-specify-security-information]] -Using Annotations to Specify Security Information -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Using Annotations to Specify Security Information Annotations enable a declarative style of programming and so encompass both the declarative and programmatic security concepts. Users can @@ -36,19 +20,18 @@ application deployment descriptors. Specific annotations that can be used to specify security information within an enterprise bean class file are described in -link:security-jakartaee002.html#GJGDI[Securing an Enterprise Bean Using -Declarative Security]. link:security-webtier.html#BNCAS[Chapter 51, +link:#GJGDI[Securing an Enterprise Bean Using +Declarative Security]. link:#BNCAS[Chapter 51, "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 -link:security-intro007.html#BNBYJ[Further Information about Security]. +link:#BNBYJ[Further Information about Security]. [[BNBXF]][[using-deployment-descriptors-for-declarative-security]] -Using Deployment Descriptors for Declarative Security -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Using Deployment Descriptors for Declarative Security Declarative security can express an application component's security requirements by using deployment descriptors. Because deployment @@ -84,8 +67,7 @@ which can be downloaded from [[BNBXH]][[using-programmatic-security]] -Using Programmatic Security -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Using Programmatic Security Programmatic security is embedded in an application and is used to make security decisions. Programmatic security is useful when declarative @@ -99,7 +81,7 @@ security role of the caller or remote user. Programmatic security is discussed in more detail in the following sections: -* link:security-webtier003.html#GJIIE[Using Programmatic Security with +* link:#GJIIE[Using Programmatic Security with Web Applications] -* link:security-jakartaee002.html#GJGCS[Securing an Enterprise Bean +* link:#GJGCS[Securing an Enterprise Bean Programmatically] diff --git a/src/main/jbake/content/security-intro003a.adoc b/src/main/asciidoc/security-intro/security-intro003a.adoc similarity index 93% rename from src/main/jbake/content/security-intro003a.adoc rename to src/main/asciidoc/security-intro/security-intro003a.adoc index 9d7271de..660d8afc 100644 --- a/src/main/jbake/content/security-intro003a.adoc +++ b/src/main/asciidoc/security-intro/security-intro003a.adoc @@ -1,14 +1,5 @@ -type=page -status=published -title=Using Pluggable Providers -next=security-intro004.html -prev=security-intro003.html -~~~~~~ -= Using Pluggable Providers - [[using-pluggable-providers]] -Using Pluggable Providers -------------------------- +== Using Pluggable Providers Jakarta EE includes two specifications that define SPI interfaces for pluggable security providers, JSR-196 and JSR-375. These specifications are described in more detail in the following sections: @@ -18,8 +9,7 @@ Authentication Service Provider Interface for Containers (JASPIC)] * link:#jsr-375-jakarta-ee-security-api[JSR-375 Jakarta EE Security API] [[jsr-196-java-authentication-service-provider-interface-for-containers-jaspic]] -JSR-196 Java Authentication Service Provider Interface for Containers (JASPIC) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== JSR-196 Java Authentication Service Provider Interface for Containers (JASPIC) JSR-196 defines a model for securing messages sent between a client and server in which the sender of a message "secures" it, and the receiver "validates" it. @@ -67,8 +57,7 @@ An `AuthConfigProvider` makes a `ServerAuthModule` available to the container, v series of intermediary objects, for runtime message processing. [[jsr-375-jakarta-ee-security-api]] -JSR-375 Jakarta EE Security API -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== JSR-375 Jakarta EE Security API JSR-375 defines the following authentication-related plugin SPIs: * `HttpAuthenticationMechanism` - An interface for modules that authenticate callers diff --git a/src/main/jbake/content/security-intro004.adoc b/src/main/asciidoc/security-intro/security-intro004.adoc similarity index 83% rename from src/main/jbake/content/security-intro004.adoc rename to src/main/asciidoc/security-intro/security-intro004.adoc index 342ac17c..b9867284 100644 --- a/src/main/jbake/content/security-intro004.adoc +++ b/src/main/asciidoc/security-intro/security-intro004.adoc @@ -1,15 +1,6 @@ -type=page -status=published -title=Securing GlassFish Server -next=security-intro005.html -prev=security-intro003a.html -~~~~~~ -= Securing GlassFish Server - [[BNBXI]][[securing-glassfish-server]] -Securing GlassFish Server -------------------------- +== Securing GlassFish Server This tutorial describes deployment to GlassFish Server, which provides highly secure, interoperable, and distributed component computing based @@ -18,7 +9,7 @@ security model. You can configure GlassFish Server for the following purposes. * Adding, deleting, or modifying authorized users. For more information -on this topic, see link:security-intro005.html#BNBXJ[Working with Realms, +on this topic, see link:#BNBXJ[Working with Realms, Users, Groups, and Roles]. * Configuring secure HTTP and Internet Inter-Orb Protocol (IIOP) listeners. diff --git a/src/main/jbake/content/security-intro005.adoc b/src/main/asciidoc/security-intro/security-intro005.adoc similarity index 90% rename from src/main/jbake/content/security-intro005.adoc rename to src/main/asciidoc/security-intro/security-intro005.adoc index 20614ca3..69c22a7c 100644 --- a/src/main/jbake/content/security-intro005.adoc +++ b/src/main/asciidoc/security-intro/security-intro005.adoc @@ -1,18 +1,9 @@ -type=page -status=published -title=Working with Realms, Users, Groups, and Roles -next=security-intro005a.html -prev=security-intro004.html -~~~~~~ -= Working with Realms, Users, Groups, and Roles - [[BNBXJ]][[working-with-realms-users-groups-and-roles]] -Working with Realms, Users, Groups, and Roles ---------------------------------------------- +== Working with Realms, Users, Groups, and Roles You often need to protect resources to ensure that only authorized users -have access. See link:security-intro001.html#BNBWX[Characteristics of +have access. See link:#BNBWX[Characteristics of Application Security] for an introduction to the concepts of authentication, identification, and authorization. @@ -23,7 +14,7 @@ authenticate a user, you need to follow these basic steps. 1. The application developer writes code to prompt for a user name and password. The various methods of authentication are discussed in -link:security-webtier002.html#GKBSA[Specifying Authentication +link:#GKBSA[Specifying Authentication Mechanisms]. 2. The application developer communicates how to set up security for the deployed application by use of a metadata annotation or deployment @@ -47,8 +38,7 @@ By default, group principal names are mapped to roles of the same name. [[BNBXK]][[what-are-realms-users-groups-and-roles]] -What Are Realms, Users, Groups, and Roles? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== What Are Realms, Users, Groups, and Roles? 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 @@ -61,7 +51,7 @@ 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 -link:security-webtier002.html#BNCBN[Specifying an Authentication +link:#BNCBN[Specifying an Authentication Mechanism in the Deployment Descriptor]. In some applications, authorized users are assigned to roles. In this @@ -74,7 +64,7 @@ Roles]. [[BNBXL]] .*Figure 50-6 Mapping Roles to Users and Groups* -image:img/jakartaeett_dt_044.png[ +image:jakartaeett_dt_044.png[ "Diagram of role mapping, showing creation of users and groups, definition of roles, and mapping of roles to users and groups"] @@ -83,8 +73,7 @@ groups, and roles. [[BNBXM]][[what-is-a-realm]] -What Is a Realm? -^^^^^^^^^^^^^^^^ +==== What Is a Realm? The protected resources on a server can be partitioned into a set of protection spaces, each with its own authentication scheme and/or @@ -110,7 +99,7 @@ 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 -link:security-advanced001.html#BNBYB[Working with Digital Certificates]. +link:#BNBYB[Working with Digital Certificates]. The common name field of the X.509 certificate is used as the principal name. @@ -122,8 +111,7 @@ link:#BNBXR[Managing Users and Groups in GlassFish Server]. [[BNBXN]][[what-is-a-user]] -What Is a User? -^^^^^^^^^^^^^^^ +==== What Is a User? A user is an individual or application program identity that has been defined in GlassFish Server. In a web application, a user can have @@ -141,8 +129,7 @@ security services manage users that belong to different realms. [[BNBXO]][[what-is-a-group]] -What Is a Group? -^^^^^^^^^^^^^^^^ +==== What Is a Group? A group is a set of authenticated users, classified by common traits, defined in GlassFish Server. A Jakarta EE user of the `file` realm can @@ -160,8 +147,7 @@ associated only with a specific application in GlassFish Server. [[BNBXP]][[what-is-a-role]] -What Is a Role? -^^^^^^^^^^^^^^^ +==== What Is a Role? A role is an abstract name for the permission to access a particular set of resources in an application. A role can be compared to a key that can @@ -170,8 +156,7 @@ care who you are, only that you have the right key. [[BNBXQ]][[some-other-terminology]] -Some Other Terminology -^^^^^^^^^^^^^^^^^^^^^^ +==== Some Other Terminology The following terminology is also used to describe the security requirements of the Jakarta EE platform. @@ -194,25 +179,19 @@ principal that allows its credential to be used. [[BNBXR]][[managing-users-and-groups-in-glassfish-server]] -Managing Users and Groups in GlassFish Server -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Managing Users and Groups in GlassFish Server Follow these steps for managing users before you run the tutorial examples. -The following topics are addressed here: - -* link:#BNBXS[To Add Users to GlassFish Server] - [[BNBXS]][[to-add-users-to-glassfish-server]] -To Add Users to GlassFish Server -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== To Add Users to GlassFish Server 1. Start GlassFish Server, if you haven't already done so. + Information on starting GlassFish Server is available in -link:usingexamples002.html#BNADI[Starting and Stopping GlassFish Server]. +link:#BNADI[Starting and Stopping GlassFish Server]. 2. Start the Administration Console, if you haven't already done so. + To start the Administration Console, open a web browser and specify the @@ -233,7 +212,7 @@ administrators of GlassFish Server. 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 link:security-advanced001.html#GLIFW[Adding +`certificate` realm, see link:#GLIFW[Adding Users to the Certificate Realm]. 7. On the Edit Realm page, click Manage Users. 8. On the File Users or Admin Users page, click New to add a new user @@ -258,8 +237,7 @@ without saving. [[BNBXU]][[setting-up-security-roles]] -Setting Up Security Roles -~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Setting Up Security Roles When you design an enterprise bean or web component, you should always think about the kinds of users who will access the component. For @@ -284,7 +262,7 @@ employee payroll data. The enterprise bean would be annotated as shown in the following code: -[source,oac_no_warn] +[source,java] ---- import javax.annotation.security.DeclareRoles; import javax.annotation.security.RolesAllowed; @@ -318,7 +296,7 @@ For a servlet, you can use the `@HttpConstraint` annotation within the access the servlet. For example, a servlet might be annotated as follows: -[source,oac_no_warn] +[source,java] ---- @WebServlet(name = "PayrollServlet", urlPatterns = {"/payroll"}) @ServletSecurity( @@ -328,9 +306,9 @@ public class GreetingServlet extends HttpServlet { ---- These annotations are discussed in more detail in -link:security-webtier004.html#GJRMH[Specifying Security for Basic +link:#GJRMH[Specifying Security for Basic Authentication Using Annotations] and -link:security-jakartaee002.html#GJGDI[Securing an Enterprise Bean Using +link:#GJGDI[Securing an Enterprise Bean Using Declarative Security]. After users have provided their login information and the application @@ -340,8 +318,7 @@ user, or principal. [[BNBXV]][[mapping-roles-to-users-and-groups]] -Mapping Roles to Users and Groups -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Mapping Roles to Users and Groups When you are developing a Jakarta EE application, you don't need to know what categories of users have been defined for the realm in which the @@ -368,7 +345,7 @@ specify the mapping. The following example demonstrates how to do this mapping in the `glassfish-web.xml` file, which is the file used for web applications: -[source,oac_no_warn] +[source,xml] ---- ... diff --git a/src/main/jbake/content/security-intro005a.adoc b/src/main/asciidoc/security-intro/security-intro005a.adoc similarity index 84% rename from src/main/jbake/content/security-intro005a.adoc rename to src/main/asciidoc/security-intro/security-intro005a.adoc index 18ebebdb..abdf8aee 100644 --- a/src/main/jbake/content/security-intro005a.adoc +++ b/src/main/asciidoc/security-intro/security-intro005a.adoc @@ -1,14 +1,5 @@ -type=page -status=published -title=Working with Identity Stores -next=security-intro006.html -prev=security-intro005.html -~~~~~~ -= Working with Identity Stores - [[working-with-identity-stores]] -Working with Identity Stores ----------------------------- +== Working with Identity Stores An identity store is a database or directory (store) that contains identity information about a collection of users that includes an application's callers. An identity store holds callers names, group membership information, and information sufficient @@ -37,4 +28,4 @@ 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 -link:security-api003.html#overview-of-the-identity-store-interfaces[Overview of the Identity Store Interfaces]. +link:#overview-of-the-identity-store-interfaces[Overview of the Identity Store Interfaces]. diff --git a/src/main/jbake/content/security-intro006.adoc b/src/main/asciidoc/security-intro/security-intro006.adoc similarity index 91% rename from src/main/jbake/content/security-intro006.adoc rename to src/main/asciidoc/security-intro/security-intro006.adoc index d71810e8..5dbc4f0c 100644 --- a/src/main/jbake/content/security-intro006.adoc +++ b/src/main/asciidoc/security-intro/security-intro006.adoc @@ -1,19 +1,10 @@ -type=page -status=published -title=Establishing a Secure Connection Using SSL -next=security-intro007.html -prev=security-intro005a.html -~~~~~~ -= Establishing a Secure Connection Using SSL - [[BNBXW]][[establishing-a-secure-connection-using-ssl]] -Establishing a Secure Connection Using SSL ------------------------------------------- +== Establishing a Secure Connection Using SSL Secure Sockets Layer (SSL) technology is security that is implemented at the transport layer (see -link:security-intro002.html#BNBXC[Transport-Layer Security] for more +link:#BNBXC[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 @@ -71,8 +62,7 @@ with SSL in a production environment. [[BNBXX]][[verifying-and-configuring-ssl-support]] -Verifying and Configuring SSL Support -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Verifying and Configuring SSL Support As a general rule, you must address the following issues to enable SSL for a server. @@ -89,7 +79,7 @@ For testing purposes and to verify that SSL support has been correctly installed, load the default introduction page with a URL that connects to the port defined in the server deployment descriptor: -[source,oac_no_warn] +[source,java] ---- https://localhost:8181/ ---- diff --git a/src/main/jbake/content/security-intro007.adoc b/src/main/asciidoc/security-intro/security-intro007.adoc similarity index 78% rename from src/main/jbake/content/security-intro007.adoc rename to src/main/asciidoc/security-intro/security-intro007.adoc index 4d550f6e..c48ea1c3 100644 --- a/src/main/jbake/content/security-intro007.adoc +++ b/src/main/asciidoc/security-intro/security-intro007.adoc @@ -1,15 +1,6 @@ -type=page -status=published -title=Further Information about Security -next=security-webtier.html -prev=security-intro006.html -~~~~~~ -= Further Information about Security - [[BNBYJ]][[further-information-about-security]] -Further Information about Security ----------------------------------- +== Further Information about Security For more information about security in Jakarta EE applications, see diff --git a/src/main/asciidoc/security-jakartaee/security-jakartaee.adoc b/src/main/asciidoc/security-jakartaee/security-jakartaee.adoc new file mode 100644 index 00000000..e7af83f6 --- /dev/null +++ b/src/main/asciidoc/security-jakartaee/security-jakartaee.adoc @@ -0,0 +1,13 @@ += Getting Started Securing Enterprise Applications + +[[BNBYK]][[getting-started-securing-enterprise-applications]] + +This chapter describes how to administer security for enterprise +applications. + +include::security-jakartaee001.adoc[] + +include::security-jakartaee002.adoc[] + +include::security-jakartaee003.adoc[] + diff --git a/src/main/jbake/content/security-jakartaee001.adoc b/src/main/asciidoc/security-jakartaee/security-jakartaee001.adoc similarity index 73% rename from src/main/jbake/content/security-jakartaee001.adoc rename to src/main/asciidoc/security-jakartaee/security-jakartaee001.adoc index 18aa98d3..66a40452 100644 --- a/src/main/jbake/content/security-jakartaee001.adoc +++ b/src/main/asciidoc/security-jakartaee/security-jakartaee001.adoc @@ -1,15 +1,6 @@ -type=page -status=published -title=Basic Security Tasks for Enterprise Applications -next=security-jakartaee002.html -prev=security-jakartaee.html -~~~~~~ -= Basic Security Tasks for Enterprise Applications - [[CACGIFHJ]][[basic-security-tasks-for-enterprise-applications]] -Basic Security Tasks for Enterprise Applications ------------------------------------------------- +== Basic Security Tasks for Enterprise Applications System administrators, application developers, bean providers, and deployers are responsible for administering security for enterprise diff --git a/src/main/jbake/content/security-jakartaee002.adoc b/src/main/asciidoc/security-jakartaee/security-jakartaee002.adoc similarity index 93% rename from src/main/jbake/content/security-jakartaee002.adoc rename to src/main/asciidoc/security-jakartaee/security-jakartaee002.adoc index cd5b4d27..cd89b1ea 100644 --- a/src/main/jbake/content/security-jakartaee002.adoc +++ b/src/main/asciidoc/security-jakartaee/security-jakartaee002.adoc @@ -1,15 +1,6 @@ -type=page -status=published -title=Securing Enterprise Beans -next=security-jakartaee003.html -prev=security-jakartaee001.html -~~~~~~ -= Securing Enterprise Beans - [[BNBYL]][[securing-enterprise-beans]] -Securing Enterprise Beans -------------------------- +== Securing Enterprise Beans Enterprise beans are Jakarta EE components that implement enterprise bean technology. Enterprise beans run in the enterprise bean container, a runtime environment within @@ -84,9 +75,9 @@ Programmatic security is discussed in link:#GJGCS[Securing an Enterprise Bean Programmatically]. Some of the material in this chapter assumes that you have already read -link:ejb-intro.html#GIJSZ[Chapter 35, "Enterprise Beans"], -link:ejb-gettingstarted.html#GIJRE[Chapter 36, "Getting Started with -Enterprise Beans"], and link:security-intro.html#BNBWJ[Chapter 50, +link:#GIJSZ[Chapter 35, "Enterprise Beans"], +link:#GIJRE[Chapter 36, "Getting Started with +Enterprise Beans"], and link:#BNBWJ[Chapter 50, "Introduction to Security in the Jakarta EE Platform"]. This section discusses securing a Jakarta EE application where one or more @@ -105,7 +96,7 @@ 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 link:security-webtier.html#BNCAS[Chapter 51, +`web.xml` is discussed in link:#BNCAS[Chapter 51, "Getting Started Securing Web Applications"]. The following sections describe declarative and programmatic security @@ -121,8 +112,7 @@ beans. [[GJGDI]][[securing-an-enterprise-bean-using-declarative-security]] -Securing an Enterprise Bean Using Declarative Security -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Securing an Enterprise Bean Using Declarative Security Declarative security enables the application developer to specify which users are authorized to access which methods of the enterprise beans and @@ -158,7 +148,7 @@ 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 link:security-intro005.html#BNBXV[Mapping +as described in link:#BNBXV[Mapping Roles to Users and Groups]. The following sections show how an application developer uses @@ -167,8 +157,7 @@ security view to pass along to the deployer. [[GJGCQ]][[specifying-authorized-users-by-declaring-security-roles]] -Specifying Authorized Users by Declaring Security Roles -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== Specifying Authorized Users by Declaring Security Roles This section discusses how to use annotations to specify the method permissions for the methods of a bean class. For more information on @@ -197,7 +186,7 @@ same as the parameter value. The following example code demonstrates the use of the `@DeclareRoles` annotation: + -[source,oac_no_warn] +[source,java] ---- @DeclareRoles("BusinessAdmin") public class Calculator { @@ -208,7 +197,7 @@ public class Calculator { The syntax for declaring more than one role is as shown in the following example: + -[source,oac_no_warn] +[source,java] ---- @DeclareRoles({"Administrator", "Manager", "Employee"}) ---- @@ -230,7 +219,7 @@ combined set of security roles is used by the application. The following example code demonstrates the use of the `@RolesAllowed` annotation: + -[source,oac_no_warn] +[source,java] ---- @DeclareRoles({"Administrator", "Manager", "Employee"}) public class Calculator { @@ -254,7 +243,7 @@ applies to only that method. The following example code demonstrates the use of the `@PermitAll` annotation: + -[source,oac_no_warn] +[source,java] ---- import javax.annotation.security.*; @RolesAllowed("RestrictedUsers") @@ -277,7 +266,7 @@ excluded from execution in the Jakarta EE container. The following example code demonstrates the use of the `@DenyAll` annotation: + -[source,oac_no_warn] +[source,java] ---- import javax.annotation.security.*; @RolesAllowed("Users") @@ -300,7 +289,7 @@ annotation with the `isCallerInRole` method. In this example, the `isCallerInRole("payroll")` to verify that the caller is authorized to change salary data: -[source,oac_no_warn] +[source,java] ---- @DeclareRoles("payroll") @Stateless public class PayrollBean implements Payroll { @@ -325,7 +314,7 @@ change salary data: The following example code illustrates the use of the `@RolesAllowed` annotation: -[source,oac_no_warn] +[source,java] ---- @RolesAllowed("admin") public class SomeClass { @@ -356,8 +345,7 @@ inherited by the subclass. [[BNBYU]][[specifying-an-authentication-mechanism-and-secure-connection]] -Specifying an Authentication Mechanism and Secure Connection -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== Specifying an Authentication Mechanism and Secure Connection When method permissions are specified, basic user name/password authentication will be invoked by GlassFish Server. @@ -368,8 +356,7 @@ deployment descriptor. [[GJGCS]][[securing-an-enterprise-bean-programmatically]] -Securing an Enterprise Bean Programmatically -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Securing an Enterprise Bean Programmatically Programmatic security, code that is embedded in a business method, is used to access a caller's identity programmatically and uses this @@ -428,7 +415,7 @@ returns null for an unauthenticated caller. The following code sample illustrates the use of the `getCallerPrincipal` method: + -[source,oac_no_warn] +[source,java] ---- @Stateless public class EmployeeServiceBean implements EmployeeService { @Resource SessionContext ctx; @@ -473,7 +460,7 @@ groups that exist in the operational environment. The following code sample illustrates the use of the `isCallerInRole` method: + -[source,oac_no_warn] +[source,java] ---- @Stateless public class PayrollBean implements Payroll { @Resource SessionContext ctx; @@ -498,13 +485,12 @@ 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 -link:security-jakartaee003.html#BNCAA[The converter-secure Example: Securing +link:#BNCAA[The converter-secure Example: Securing an Enterprise Bean with Programmatic Security]. [[BNBYR]][[propagating-a-security-identity-run-as]] -Propagating a Security Identity (Run-As) -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== 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 @@ -514,7 +500,7 @@ illustrates this concept. [[BNBZA]] .*Figure 52-1 Security Identity Propagation* -image:img/jakartaeett_dt_047.png[ +image:jakartaeett_dt_047.png[ "Diagram of security identity propagation from client to intermediate container to target container"] @@ -550,8 +536,7 @@ bean that might be called in turn. [[BNBZB]][[configuring-a-components-propagated-security-identity]] -Configuring a Component's Propagated Security Identity -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== Configuring a Component's Propagated Security Identity You can configure an enterprise bean's run-as, or propagated, security identity by using the `@RunAs` annotation, which defines the role of the @@ -563,7 +548,7 @@ name of a security role as its parameter. The following code demonstrates the use of the `@RunAs` annotation: -[source,oac_no_warn] +[source,java] ---- @RunAs("Admin") public class Calculator { @@ -577,8 +562,7 @@ user principal. [[BNBZC]][[trust-between-containers]] -Trust between Containers -^^^^^^^^^^^^^^^^^^^^^^^^ +==== Trust between Containers When an enterprise bean is designed so that either the original caller identity or a designated identity is used to call a target bean, the @@ -599,8 +583,7 @@ any special steps to set up a trust relationship. [[BNBZG]][[deploying-secure-enterprise-beans]] -Deploying Secure Enterprise Beans -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Deploying Secure Enterprise Beans The deployer is responsible for ensuring that an assembled application is secure after it has been deployed in the target operational diff --git a/src/main/jbake/content/security-jakartaee003.adoc b/src/main/asciidoc/security-jakartaee/security-jakartaee003.adoc similarity index 83% rename from src/main/jbake/content/security-jakartaee003.adoc rename to src/main/asciidoc/security-jakartaee/security-jakartaee003.adoc index cbca7c27..7a2bc85b 100644 --- a/src/main/jbake/content/security-jakartaee003.adoc +++ b/src/main/asciidoc/security-jakartaee/security-jakartaee003.adoc @@ -1,30 +1,13 @@ -type=page -status=published -title=Examples: Securing Enterprise Beans -next=security-api.html -prev=security-jakartaee002.html -~~~~~~ -= Examples: Securing Enterprise Beans - [[GKBSZ]][[examples-securing-enterprise-beans]] -Examples: Securing Enterprise Beans ------------------------------------ +== Examples: Securing Enterprise Beans The following examples show how to secure enterprise beans using declarative and programmatic security. -The following topics are addressed here: - -* link:#the-cart-secure-example-securing-an-enterprise-bean-with-declarative-security[The cart-secure Example: Securing an Enterprise Bean with -Declarative Security] -* link:#the-converter-secure-example-securing-an-enterprise-bean-with-programmatic-security[The converter-secure Example: Securing an Enterprise Bean -with Programmatic Security] - [[BNBZK]][[the-cart-secure-example-securing-an-enterprise-bean-with-declarative-security]] -The cart-secure Example: Securing an Enterprise Bean with Declarative Security -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== The cart-secure Example: Securing an Enterprise Bean with Declarative Security This section discusses how to configure an enterprise bean for basic user name/password authentication. When a bean that is constrained in @@ -34,13 +17,13 @@ comparing them against a database of authorized users in GlassFish Server. If the topic of authentication is new to you, see -link:security-webtier002.html#GKBSA[Specifying Authentication +link:#GKBSA[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 -link:ejb-basicexamples002.html#BNBOD[The cart Example]. +link:#BNBOD[The cart Example]. In general, the following steps are necessary to add user name/password authentication to an existing application that contains an enterprise @@ -49,13 +32,13 @@ 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. 1. Create an application like the one in -link:ejb-basicexamples002.html#BNBOD[The cart Example]. The example in +link:#BNBOD[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/`. 2. If you have not already done so, complete the steps in -link:security-webtier004.html#GJJLK[To Set Up Your System for Running the +link:#GJJLK[To Set Up Your System for Running the Security Examples] to configure your system for running the tutorial applications. 3. Modify the source code for the enterprise bean, `CartBean.java`, to @@ -68,8 +51,7 @@ cart-secure Example Using Maven]. [[BNBZL]][[annotating-the-bean]] -Annotating the Bean -^^^^^^^^^^^^^^^^^^^ +==== Annotating the Bean The source code for the original `cart` application was modified as shown in the following code snippet (modifications in bold). The @@ -78,7 +60,7 @@ resulting file can be found in the file The code snippet is as follows: -[source,oac_no_warn] +[source,java] ---- package jakarta.tutorial.cartsecure.ejb; @@ -174,15 +156,14 @@ type of authentication will be user name/password authentication. [[BNBZN]][[to-run-the-cart-secure-example-using-netbeans-ide]] -To Run the cart-secure Example Using NetBeans IDE -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== To Run the cart-secure Example Using NetBeans IDE -1. Follow the steps in link:security-webtier004.html#GJJLK[To Set Up +1. Follow the steps in link:#GJJLK[To Set Up Your System for Running the Security Examples]. 2. From the File menu, choose Open Project. 3. In the Open Project dialog box, navigate to: + -[source,oac_no_warn] +[source,java] ---- tut-install/examples/security ---- @@ -203,7 +184,7 @@ group `TutorialUser`; then click OK. If the user name and password you enter are authenticated, the output of the application client appears in the Output tab: + -[source,oac_no_warn] +[source,java] ---- ... Retrieving book title from cart: Infinite Jest @@ -220,14 +201,13 @@ reappears until you enter correct values. [[BNBZO]][[to-run-the-cart-secure-example-using-maven]] -To Run the cart-secure Example Using Maven -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== To Run the cart-secure Example Using Maven -1. Follow the steps in link:security-webtier004.html#GJJLK[To Set Up +1. Follow the steps in link:#GJJLK[To Set Up Your System for Running the Security Examples]. 2. In a terminal window, go to: + -[source,oac_no_warn] +[source,java] ---- tut-install/examples/security/cart-secure/ ---- @@ -235,7 +215,7 @@ tut-install/examples/security/cart-secure/ `cart-secure-ear/target` subdirectory, deploy it, and run it, enter the following command at the terminal window or command prompt: + -[source,oac_no_warn] +[source,java] ---- mvn install ---- @@ -246,7 +226,7 @@ group `TutorialUser`; then click OK. If the user name and password you enter are authenticated, the output of the application client appears in the Output tab: + -[source,oac_no_warn] +[source,java] ---- ... Retrieving book title from cart: Infinite Jest @@ -263,8 +243,7 @@ reappears until you enter correct values. [[BNCAA]][[the-converter-secure-example-securing-an-enterprise-bean-with-programmatic-security]] -The converter-secure Example: Securing an Enterprise Bean with Programmatic Security -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== The converter-secure Example: Securing an Enterprise Bean with Programmatic Security This example demonstrates how to use the `getCallerPrincipal` and `isCallerInRole` methods with an enterprise bean. This example starts @@ -276,13 +255,13 @@ 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 -link:ejb-gettingstarted.html#GIJRE[Chapter 36, "Getting Started with +link:#GIJRE[Chapter 36, "Getting Started with Enterprise Beans"] 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 -link:security-jakartaee002.html#securing-an-enterprise-bean-programmatically +link:#securing-an-enterprise-bean-programmatically [Securing an Enterprise Bean Programmatically]. In general, the following steps are necessary when using the @@ -295,20 +274,19 @@ application. 1. Create a simple enterprise bean application. 2. 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 link:security-webtier004.html#GJJLK[To Set Up +this, follow the steps in link:#GJJLK[To Set Up Your System for Running the Security Examples]. 3. Modify the bean to add the `getCallerPrincipal` and `isCallerInRole` methods. 4. If the application contains a web client that is a servlet, specify security for the servlet, as described in -link:security-webtier004.html#GJRMH[Specifying Security for Basic +link:#GJRMH[Specifying Security for Basic Authentication Using Annotations]. 5. Build, package, deploy, and run the application. [[BNCAB]][[modifying-converterbean]] -Modifying ConverterBean -^^^^^^^^^^^^^^^^^^^^^^^ +==== Modifying ConverterBean The source code for the original `ConverterBean` class was modified to add the `if..else` clause that tests whether the caller is in the role @@ -320,7 +298,7 @@ result as `0`. The code example can be found in The code snippet (with modifications shown in bold) is as follows: -[source,oac_no_warn] +[source,java] ---- package jakarta.tutorial.convertersecure.ejb; @@ -368,13 +346,12 @@ public class ConverterBean{ [[GKBSI]][[modifying-converterservlet]] -Modifying ConverterServlet -^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== Modifying ConverterServlet The following annotations specify security for the `converter` web client, `ConverterServlet`: -[source,oac_no_warn] +[source,java] ---- @WebServlet(urlPatterns = {"/"}) @ServletSecurity( @@ -384,15 +361,14 @@ client, `ConverterServlet`: [[BNCAD]][[to-run-the-converter-secure-example-using-netbeans-ide]] -To Run the converter-secure Example Using NetBeans IDE -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== To Run the converter-secure Example Using NetBeans IDE -1. Follow the steps in link:security-webtier004.html#GJJLK[To Set Up +1. Follow the steps in link:#GJJLK[To Set Up Your System for Running the Security Examples]. 2. From the File menu, choose Open Project. 3. In the Open Project dialog box, navigate to: + -[source,oac_no_warn] +[source,java] ---- tut-install/examples/security ---- @@ -405,20 +381,19 @@ GlassFish Server instance. [[BNCAE]][[to-run-the-converter-secure-example-using-maven]] -To Run the converter-secure Example Using Maven -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== To Run the converter-secure Example Using Maven -1. Follow the steps in link:security-webtier004.html#GJJLK[To Set Up +1. Follow the steps in link:#GJJLK[To Set Up Your System for Running the Security Examples]. 2. In a terminal window, go to: + -[source,oac_no_warn] +[source,java] ---- tut-install/examples/security/converter-secure/ ---- 3. Enter the following command: + -[source,oac_no_warn] +[source,java] ---- mvn install ---- @@ -429,12 +404,11 @@ deploys the WAR file. [[GJTDP]][[to-run-the-converter-secure-example]] -To Run the converter-secure Example -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== To Run the converter-secure Example 1. Open a web browser to the following URL: + -[source,oac_no_warn] +[source,java] ---- http://localhost:8080/converter-secure ---- diff --git a/src/main/asciidoc/security-webtier/security-webtier.adoc b/src/main/asciidoc/security-webtier/security-webtier.adoc new file mode 100644 index 00000000..5e1073d4 --- /dev/null +++ b/src/main/asciidoc/security-webtier/security-webtier.adoc @@ -0,0 +1,18 @@ += Getting Started Securing Web Applications + +[[BNCAS]][[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 +link:#BNBXE[Securing Containers]. The detail and +examples in this chapter explore these security services as they relate +to web components. + +include::security-webtier001.adoc[] + +include::security-webtier002.adoc[] + +include::security-webtier003.adoc[] + +include::security-webtier004.adoc[] + diff --git a/src/main/jbake/content/security-webtier001.adoc b/src/main/asciidoc/security-webtier/security-webtier001.adoc similarity index 76% rename from src/main/jbake/content/security-webtier001.adoc rename to src/main/asciidoc/security-webtier/security-webtier001.adoc index d866fc39..fac0bd22 100644 --- a/src/main/jbake/content/security-webtier001.adoc +++ b/src/main/asciidoc/security-webtier/security-webtier001.adoc @@ -1,19 +1,10 @@ -type=page -status=published -title=Overview of Web Application Security -next=security-webtier002.html -prev=security-webtier.html -~~~~~~ -= Overview of Web Application Security - [[BNCAT]][[overview-of-web-application-security]] -Overview of Web Application Security ------------------------------------- +== 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 -link:overview004.html#BNAAY[Distributed Multitiered Applications], the +link:#BNAAY[Distributed Multitiered Applications], the Jakarta EE platform uses a distributed multitiered application model, and web applications run in the web tier. @@ -23,7 +14,7 @@ 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 link:security-jakartaee.html#BNBYK[Chapter 52, "Getting +tier is discussed in link:#BNBYK[Chapter 52, "Getting Started Securing Enterprise Applications"]. In the Jakarta EE platform, web components provide the dynamic extension @@ -44,17 +35,17 @@ following ways. * Declarative security can be implemented using either metadata annotations or an application's deployment descriptor. See -link:security-intro001.html#BNBWK[Overview of Jakarta Security] for more +link:#BNBWK[Overview of Jakarta Security] for more information. + Declarative security for web applications is described in -link:security-webtier002.html#GKBAA[Securing Web Applications]. +link:#GKBAA[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 link:security-intro001.html#BNBWK[Overview +middle of an application. See link:#BNBWK[Overview of Jakarta Security] for more information. + Servlet 4.0 provides the `authenticate`, `login`, and `logout` methods @@ -65,7 +56,7 @@ required for web applications but may still be used to further specify security requirements beyond the basic default values. + Programmatic security is discussed in -link:security-webtier003.html#GJIIE[Using Programmatic Security with Web +link:#GJIIE[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 @@ -77,9 +68,9 @@ 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: -* link:webapp.html#BNADR[Chapter 6, "Getting Started with Web +* link:#BNADR[Chapter 6, "Getting Started with Web Applications"] -* link:jsf-intro.html#BNAPH[Chapter 7, "Jakarta Server Faces Technology"] -* link:servlets.html#BNAFD[Chapter 18, "Jakarta Servlet Technology"] -* link:security-intro.html#BNBWJ[Chapter 50, "Introduction to Security in +* link:#BNAPH[Chapter 7, "Jakarta Server Faces Technology"] +* link:#BNAFD[Chapter 18, "Jakarta Servlet Technology"] +* link:#BNBWJ[Chapter 50, "Introduction to Security in the Jakarta EE Platform"] diff --git a/src/main/jbake/content/security-webtier002.adoc b/src/main/asciidoc/security-webtier/security-webtier002.adoc similarity index 90% rename from src/main/jbake/content/security-webtier002.adoc rename to src/main/asciidoc/security-webtier/security-webtier002.adoc index 753803d1..03dc15e3 100644 --- a/src/main/jbake/content/security-webtier002.adoc +++ b/src/main/asciidoc/security-webtier/security-webtier002.adoc @@ -1,33 +1,14 @@ -type=page -status=published -title=Securing Web Applications -next=security-webtier003.html -prev=security-webtier001.html -~~~~~~ -= Securing Web Applications - [[GKBAA]][[securing-web-applications]] -Securing Web Applications -------------------------- +== Securing Web Applications Web applications are created by application developers who give, sell, or otherwise transfer the application to an application deployer for installation into a runtime environment. -The following topics are addressed here: - -* link:#overview-of-securing-web-applications[Overview of Securing Web Applications] -* link:#specifying-security-constraints[Specifying Security Constraints] -* link:#specifying-authentication-mechanisms[Specifying Authentication Mechanisms] -* link:#specifying-an-authentication-mechanism-in-the-deployment-descriptor[Specifying an Authentication Mechanism in the Deployment -Descriptor] -* link:#declaring-security-roles[Declaring Security Roles] - [[CHDBIBHI]][[overview-of-securing-web-applications]] -Overview of Securing Web Applications -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Overview of Securing Web Applications Application developers communicate how to set up security for the deployed application by using annotations or deployment descriptors. @@ -45,8 +26,7 @@ annotations cannot be used. [[BNCBK]][[specifying-security-constraints]] -Specifying Security Constraints -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Specifying Security Constraints A security constraint is used to define the access privileges to a collection of resources using their URL mapping. @@ -82,8 +62,7 @@ Connection]. [[GJJCD]][[specifying-a-web-resource-collection]] -Specifying a Web Resource Collection -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== Specifying a Web Resource Collection A web resource collection consists of the following subelements. @@ -124,8 +103,7 @@ elements, none of which names the HTTP method [[GJJCG]][[specifying-an-authorization-constraint]] -Specifying an Authorization Constraint -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== Specifying an Authorization Constraint An authorization constraint (`auth-constraint`) contains the `role-name` element. You can use as many `role-name` elements as needed here. @@ -146,7 +124,7 @@ except when default principal-to-role mapping is used. For more information about security roles, see link:#BNCAV[Declaring Security Roles]. For information on mapping security roles, see -link:security-intro005.html#BNBXV[Mapping Roles to Users and Groups]. +link:#BNBXV[Mapping Roles to Users and Groups]. For a servlet, the `@HttpConstraint` and `@HttpMethodConstraint` annotations accept a `rolesAllowed` element that specifies the @@ -154,8 +132,7 @@ authorized roles. [[BNCBM]][[specifying-a-secure-connection]] -Specifying a Secure Connection -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== Specifying a Secure Connection A user data constraint (`user-data-constraint` in the deployment descriptor) contains the `transport-guarantee` subelement. A user data @@ -229,8 +206,7 @@ easily implemented by using a filter. [[BNCBL]][[specifying-security-constraints-for-resources]] -Specifying Security Constraints for Resources -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== Specifying Security Constraints for Resources You can create security constraints for resources within your application. For example, you could allow users with the role of @@ -242,7 +218,7 @@ HTTP methods while leaving other HTTP methods unprotected. An example of a deployment descriptor that would demonstrate this functionality is the following: -[source,oac_no_warn] +[source,xml] ---- @@ -275,8 +251,7 @@ following: [[GKBSA]][[specifying-authentication-mechanisms]] -Specifying Authentication Mechanisms -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Specifying Authentication Mechanisms This section describes built-in authentication mechanisms defined by the Servlet specification. @@ -289,7 +264,7 @@ a| An alternative way to perform user authentication, including BASIC and FORM authentication, is to use the `HttpAuthenticationMechanism`, specified by Jakarta Security, and documented in -link:security-api.html#using-the-jakarta-ee-security-api[Chapter 53, "Using Jakarta Security"]. +link:#using-the-jakarta-ee-security-api[Chapter 53, "Using Jakarta Security"]. |======================================================================= @@ -309,7 +284,7 @@ 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 -link:security-intro005.html#BNBXR[Managing Users and Groups in GlassFish +link:#BNBXR[Managing Users and Groups in GlassFish Server]. The Jakarta EE platform supports the following authentication mechanisms: @@ -322,7 +297,7 @@ The Jakarta EE platform supports the following authentication mechanisms: Basic, form-based, and digest authentication are discussed in this section. Client and mutual authentication are discussed in -link:security-advanced.html#GJJWX[Chapter 54, "Jakarta EE Security: Advanced +link:#GJJWX[Chapter 54, "Jakarta EE Security: Advanced Topics"]. HTTP basic authentication and form-based authentication are not very @@ -343,8 +318,7 @@ the elements described in link:#BNCBM[Specifying a Secure Connection]. [[BNCBO]][[http-basic-authentication]] -HTTP Basic Authentication -^^^^^^^^^^^^^^^^^^^^^^^^^ +==== HTTP Basic Authentication Specifying HTTP basic authentication requires that the server request a user name and password from the web client and verify that the user name @@ -369,14 +343,13 @@ authentication. [[BNCBP]] .*Figure 51-1 HTTP Basic Authentication* -image:img/jakartaeett_dt_045.png[ +image:jakartaeett_dt_045.png[ "Diagram of four steps in HTTP basic authentication between client and server"] [[BNCBQ]][[form-based-authentication]] -Form-Based Authentication -^^^^^^^^^^^^^^^^^^^^^^^^^ +==== Form-Based Authentication Form-based authentication allows the developer to control the look and feel of the login authentication screens by customizing the login screen @@ -402,11 +375,11 @@ authentication. [[GEXFA]] .*Figure 51-2 Form-Based Authentication* -image:img/jakartaeett_dt_046.png[ +image:jakartaeett_dt_046.png[ "Diagram of four steps in form-based authentication between client and server"] -The section link:security-webtier004.html#BNCBY[The hello1-formauth +The section link:#BNCBY[The hello1-formauth Example: Form-Based Authentication with a Jakarta Server Faces Application] is an example application that uses form-based authentication. @@ -420,7 +393,7 @@ requiring the server to specify the action field of the outbound form. The following code snippet shows how the form should be coded into the HTML page: -[source,oac_no_warn] +[source,java] ----
@@ -430,8 +403,7 @@ HTML page: [[BNCBW]][[digest-authentication]] -Digest Authentication -^^^^^^^^^^^^^^^^^^^^^ +==== Digest Authentication Like basic authentication, digest authentication authenticates a user based on a user name and a password. However, unlike basic @@ -444,8 +416,7 @@ validate received authenticators by calculating the expected digest. [[BNCBN]][[specifying-an-authentication-mechanism-in-the-deployment-descriptor]] -Specifying an Authentication Mechanism in the Deployment Descriptor -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Specifying an Authentication Mechanism in the Deployment Descriptor To specify an authentication mechanism, use the `login-config` element. It can contain the following subelements. @@ -466,7 +437,7 @@ a| Another way to specify form-based authentication is to use the `authenticate`, `login`, and `logout` methods of `HttpServletRequest`, -as discussed in link:security-webtier003.html#GIRCJ[Authenticating Users +as discussed in link:#GIRCJ[Authenticating Users Programmatically]. |======================================================================= @@ -484,7 +455,7 @@ authentication mechanism, authentication of the user is not required. The following example shows how to declare form-based authentication in your deployment descriptor: -[source,oac_no_warn] +[source,xml] ---- FORM @@ -498,13 +469,13 @@ your deployment descriptor: 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 link:security-webtier004.html#BNCCA[Creating the Login Form +are shown in link:#BNCCA[Creating the Login Form and the Error Page]. The following example shows how to declare digest authentication in your deployment descriptor: -[source,oac_no_warn] +[source,xml] ---- DIGEST @@ -513,8 +484,7 @@ deployment descriptor: [[BNCAV]][[declaring-security-roles]] -Declaring Security Roles -~~~~~~~~~~~~~~~~~~~~~~~~ +=== Declaring Security Roles You can declare security role names used in web applications by using the `security-role` element of the deployment descriptor. Use this @@ -526,7 +496,7 @@ will be used in an application using the `security-role` element and specifies which of these roles is authorized to access protected resources using the `auth-constraint` element: -[source,oac_no_warn] +[source,xml] ---- diff --git a/src/main/jbake/content/security-webtier003.adoc b/src/main/asciidoc/security-webtier/security-webtier003.adoc similarity index 91% rename from src/main/jbake/content/security-webtier003.adoc rename to src/main/asciidoc/security-webtier/security-webtier003.adoc index 7fec9a36..23745c5c 100644 --- a/src/main/jbake/content/security-webtier003.adoc +++ b/src/main/asciidoc/security-webtier/security-webtier003.adoc @@ -1,38 +1,20 @@ -type=page -status=published -title=Using Programmatic Security with Web Applications -next=security-webtier004.html -prev=security-webtier002.html -~~~~~~ -= Using Programmatic Security with Web Applications - [[GJIIE]][[using-programmatic-security-with-web-applications]] -Using Programmatic Security with Web Applications -------------------------------------------------- +== Using Programmatic Security with Web Applications Programmatic security is used by security-aware applications when declarative security alone is not sufficient to express the security model of the application. -The following topics are addressed here: - -* link:#authenticating-users-programmatically[Authenticating Users Programmatically] -* link:#checking-caller-identity-programmatically[Checking Caller Identity Programmatically] -* link:#testing-access-to-a-resource-programmatically[Testing Access to a Resource Programmatically] -* link:#example-code-for-programmatic-security[Example Code for Programmatic Security] -* link:#declaring-and-linking-role-references[Declaring and Linking Role References] - [[GIRCJ]][[authenticating-users-programmatically]] -Authenticating Users Programmatically -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Authenticating Users Programmatically You can use the `SecurityContext` and `HttpServletRequest` interfaces to authenticate users for a web application programmatically. [[security-context]] -==== SecurityContext +== SecurityContext The `SecurityContext` interface, as specified in the Jakarta EE Security API specification, defines the following method to programmatically trigger the authentication process: @@ -50,7 +32,7 @@ as if `HttpServletRequest.authenticate()` were called. [[httpservletrequest]] -==== HttpServletRequest +== HttpServletRequest The `HttpServletRequest` interface defines the following methods that enable you to authenticate users for a web application programmatically. @@ -67,7 +49,7 @@ request. The following example code shows how to use the `login` and `logout` methods: -[source,oac_no_warn] +[source,java] ---- package test; @@ -125,7 +107,7 @@ public class TutorialServlet extends HttpServlet { The following example code shows how to use the `authenticate` method: -[source,oac_no_warn] +[source,java] ---- package com.example.test; @@ -151,8 +133,7 @@ public class TestServlet extends HttpServlet { [[BNCBA]][[checking-caller-identity-programmatically]] -Checking Caller Identity Programmatically -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Checking Caller Identity Programmatically In general, the container enforces security management in a manner that is transparent to the web component. Use the security APIs @@ -215,8 +196,7 @@ information obtained using these APIs. [[testing-access-to-a-resource-programmatically]] -Testing Access to a Resource Programmatically -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Testing Access to a Resource Programmatically The `SecurityContext` interface, as specified in the Jakarta Security API specification, defines the following method for programmatically testing @@ -237,14 +217,14 @@ access to resources in a different application. For example, consider the following Servlet definition: -[source,oac_no_warn] +[source,java] ---- @WebServlet("/protectedServlet") @ServletSecurity(@HttpConstraint(rolesAllowed = "foo")) public class ProtectedServlet extends HttpServlet { ... } ---- And the following call to `hasAccessToWebResource()`: -[source,oac_no_warn] +[source,java] ---- securityContext.hasAccessToWebResource("/protectedServlet", GET) ---- @@ -254,8 +234,7 @@ the caller is in role "foo". [[GJJLQ]][[example-code-for-programmatic-security]] -Example Code for Programmatic Security -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Example Code for Programmatic Security The following code demonstrates the use of programmatic security for the purposes of programmatic login. This servlet does the following. @@ -268,7 +247,7 @@ purposes of programmatic login. This servlet does the following. 5. It prints out the information again to demonstrate the effect of the `logout` method. -[source,oac_no_warn] +[source,java] ---- package enterprise.programmatic_login; @@ -336,8 +315,7 @@ public class LoginServlet extends HttpServlet { [[BNCBB]][[declaring-and-linking-role-references]] -Declaring and Linking Role References -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Declaring and Linking Role References A security role reference is a mapping between the name of a role that is called from a web component using `isUserInRole(String role)` and the @@ -362,7 +340,7 @@ of the call. For example, to map the security role reference `cust` to the security role with role name `bankCustomer`, the elements would look like this: -[source,oac_no_warn] +[source,xml] ---- ... @@ -381,7 +359,7 @@ The `role-link` element in the `security-role-ref` element must match a `role-name` defined in the `security-role` element of the same `web.xml` deployment descriptor, as shown here: -[source,oac_no_warn] +[source,xml] ---- bankCustomer diff --git a/src/main/jbake/content/security-webtier004.adoc b/src/main/asciidoc/security-webtier/security-webtier004.adoc similarity index 81% rename from src/main/jbake/content/security-webtier004.adoc rename to src/main/asciidoc/security-webtier/security-webtier004.adoc index 33b19704..28cac5ad 100644 --- a/src/main/jbake/content/security-webtier004.adoc +++ b/src/main/asciidoc/security-webtier/security-webtier004.adoc @@ -1,33 +1,13 @@ -type=page -status=published -title=Examples: Securing Web Applications -next=security-jakartaee.html -prev=security-webtier003.html -~~~~~~ -= Examples: Securing Web Applications - - [[BNCBX]][[examples-securing-web-applications]] -Examples: Securing Web Applications ------------------------------------ +== Examples: Securing Web Applications Some basic setup is required before any of the example applications will run correctly. -The following topics are addressed here: - -* link:#overview-of-examples-of-securing-web-applications[Overview of Examples of Securing Web Applications] -* link:#to-set-up-your-system-for-running-the-security-examples[To Set Up Your System for Running the Security Examples] -* link:#the-hello2-basicauth-example-basic-authentication-with-a-servlet[The hello2-basicauth Example: Basic Authentication with a -Servlet] -* link:#the-hello1-formauth-example-form-based-authentication-with-a-javaserver-faces-application[The hello1-formauth Example: Form-Based Authentication -with a Jakarta Server Faces Application] - [[CHDEBCHG]][[overview-of-examples-of-securing-web-applications]] -Overview of Examples of Securing Web Applications -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Overview of Examples of Securing Web Applications The examples use annotations, programmatic security, and/or declarative security to demonstrate adding security to existing web applications. @@ -35,47 +15,43 @@ security to demonstrate adding security to existing web applications. Here are some other locations where you will find examples of securing various types of applications: -* link:security-jakartaee003.html#BNBZK[The cart-secure Example: Securing an +* link:#BNBZK[The cart-secure Example: Securing an Enterprise Bean with Declarative Security] -* link:security-jakartaee003.html#BNCAA[The converter-secure Example: +* link:#BNCAA[The converter-secure Example: Securing an Enterprise Bean with Programmatic Security] * Java EE 8 GlassFish samples: `https://javaee.github.io/glassfish-samples/` [[GJJLK]][[to-set-up-your-system-for-running-the-security-examples]] -To Set Up Your System for Running the Security Examples -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== To Set Up Your System for Running the Security Examples 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. -1. Make sure that GlassFish Server has been started (see -link:usingexamples002.html#BNADI[Starting and Stopping GlassFish -Server]). -2. Add an authorized user to GlassFish Server. For the examples in this -chapter and in link:security-jakartaee.html#BNBYK[Chapter 52, "Getting +. Make sure that GlassFish Server has been started (see link:#BNADI[Starting and Stopping GlassFish Server]). +. Add an authorized user to GlassFish Server. For the examples in this +chapter and in link:#BNBYK[Chapter 52, "Getting Started Securing Enterprise Applications"], add a user to the `file` realm of GlassFish Server, and assign the user to the group `TutorialUser`. -1. From the Administration Console, expand the Configurations node, +.. From the Administration Console, expand the Configurations node, then expand the server-config node. -2. Expand the Security node. -3. Expand the Realms node. -4. Select the File node. -5. On the Edit Realm page, click Manage Users. -6. On the File Users page, click New. -7. In the User ID field, enter a user ID. -8. In the Group List field, enter `TutorialUser`. -9. In the New Password and Confirm New Password fields, enter a -password. -10. Click OK. +.. Expand the Security node. +.. Expand the Realms node. +.. Select the File node. +.. On the Edit Realm page, click Manage Users. +.. On the File Users page, click New. +.. In the User ID field, enter a user ID. +.. In the Group List field, enter `TutorialUser`. +.. In the New Password and Confirm New Password fields, enter a password. +.. Click OK. + Be sure to write down the user name and password for the user you create so that you can use it for testing the example applications. Authentication is case sensitive for both the user name and password, so write down the user name and password exactly. This topic is discussed -more in link:security-intro005.html#BNBXR[Managing Users and Groups in +more in link:#BNBXR[Managing Users and Groups in GlassFish Server]. + [width="100%",cols="100%",] @@ -93,8 +69,7 @@ the console. [[BNCCK]][[the-hello2-basicauth-example-basic-authentication-with-a-servlet]] -The hello2-basicauth Example: Basic Authentication with a Servlet -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== The hello2-basicauth Example: Basic Authentication with a Servlet This example explains how to use basic authentication with a servlet. With basic authentication of a servlet, the web browser presents a @@ -105,7 +80,7 @@ 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 -link:webapp.html#BNADR[Chapter 6, "Getting Started with Web +link:#BNADR[Chapter 6, "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 @@ -115,7 +90,7 @@ application. This application can be found in the 1. Follow the steps in link:#GJJLK[To Set Up Your System for Running the Security Examples]. 2. Create a web module for the servlet example, `hello2`, as described -in link:webapp.html#BNADR[Chapter 6, "Getting Started with Web +in link:#BNADR[Chapter 6, "Getting Started with Web Applications"]. 3. Add the appropriate security annotations to the servlet. The security annotations are described in link:#GJRMH[Specifying Security @@ -129,8 +104,7 @@ link:#GJQZF[To Run the hello2-basicauth Example]. [[GJRMH]][[specifying-security-for-basic-authentication-using-annotations]] -Specifying Security for Basic Authentication Using Annotations -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== Specifying Security for Basic Authentication Using Annotations The default authentication mechanism used by GlassFish Server is basic authentication. With basic authentication, GlassFish Server spawns a @@ -164,7 +138,7 @@ roles. For the `hello2-basicauth` application, the `GreetingServlet` has the following annotations: -[source,oac_no_warn] +[source,java] ---- @WebServlet(name = "GreetingServlet", urlPatterns = {"/greeting"}) @ServletSecurity( @@ -185,15 +159,14 @@ for which you cannot use the `@ServletSecurity` annotation. [[GJQYS]][[to-build-package-and-deploy-the-hello2-basicauth-example-using-netbeans-ide]] -To Build, Package, and Deploy the hello2-basicauth Example Using NetBeans IDE -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== To Build, Package, and Deploy the hello2-basicauth Example Using NetBeans IDE 1. Follow the steps in link:#GJJLK[To Set Up Your System for Running the Security Examples]. 2. From the File menu, choose Open Project. 3. In the Open Project dialog box, navigate to: + -[source,oac_no_warn] +[source,java] ---- tut-install/examples/security ---- @@ -207,20 +180,19 @@ GlassFish Server instance. [[GJQZH]][[to-build-package-and-deploy-the-hello2-basicauth-example-using-maven]] -To Build, Package, and Deploy the hello2-basicauth Example Using Maven -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== To Build, Package, and Deploy the hello2-basicauth Example Using Maven 1. Follow the steps in link:#GJJLK[To Set Up Your System for Running the Security Examples]. 2. In a terminal window, go to: + -[source,oac_no_warn] +[source,java] ---- tut-install/examples/security/hello2-basicauth/ ---- 3. Enter the following command: + -[source,oac_no_warn] +[source,java] ---- mvn install ---- @@ -231,12 +203,11 @@ deploys the WAR file. [[GJQZF]][[to-run-the-hello2-basicauth-example]] -To Run the hello2-basicauth Example -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== To Run the hello2-basicauth Example 1. In a web browser, enter the following URL: + -[source,oac_no_warn] +[source,java] ---- https://localhost:8181/hello2-basicauth/greeting ---- @@ -276,8 +247,7 @@ The application responds by saying "Hello" to the name you entered. [[BNCBY]][[the-hello1-formauth-example-form-based-authentication-with-a-javaserver-faces-application]] -The hello1-formauth Example: Form-Based Authentication with a Jakarta Server Faces Application -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== The hello1-formauth Example: Form-Based Authentication with a Jakarta Server Faces Application This example explains how to use form-based authentication with a Jakarta Server Faces application. With form-based authentication, you can @@ -288,7 +258,7 @@ 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 Server -Faces application shown in link:webapp003.html#BNADX[A Web Module That +Faces application shown in link:#BNADX[A Web Module That Uses Jakarta Server Faces Technology: The hello1 Example]. In general, the steps necessary for adding form-based authentication to @@ -306,8 +276,7 @@ This application can be found in the [[BNCCA]][[creating-the-login-form-and-the-error-page]] -Creating the Login Form and the Error Page -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== 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, @@ -324,7 +293,7 @@ and password information between `` tags in your login page. The content of an HTML page or servlet for a login page should be coded as follows: -[source,oac_no_warn] +[source,html] ----
@@ -336,7 +305,7 @@ 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`. Here is the code for this page: -[source,oac_no_warn] +[source,html] ---- @@ -374,7 +343,7 @@ 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: -[source,oac_no_warn] +[source,html] ---- @@ -394,8 +363,7 @@ again. Here is the code for this page: [[BNCCB]][[specifying-security-for-the-form-based-authentication-example]] -Specifying Security for the Form-Based Authentication Example -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== Specifying Security for the Form-Based Authentication Example This example takes a very simple servlet-based web application and adds form-based security. To specify form-based instead of basic @@ -406,7 +374,7 @@ 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`: -[source,oac_no_warn] +[source,xml] ---- Constraint1 @@ -438,15 +406,14 @@ deployment descriptor for this example, which can be found in [[GJRBA]][[to-build-package-and-deploy-the-hello1-formauth-example-using-netbeans-ide]] -To Build, Package, and Deploy the hello1-formauth Example Using NetBeans IDE -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== To Build, Package, and Deploy the hello1-formauth Example Using NetBeans IDE 1. Follow the steps in link:#GJJLK[To Set Up Your System for Running the Security Examples]. 2. From the File menu, choose Open Project. 3. In the Open Project dialog box, navigate to: + -[source,oac_no_warn] +[source,java] ---- tut-install/examples/security ---- @@ -460,21 +427,20 @@ GlassFish Server instance, then opens it in a browser. [[GJRAZ]][[to-build-package-and-deploy-the-hello1-formauth-example-using-maven-and-the-asadmin-command]] -To Build, Package, and Deploy the hello1-formauth Example Using Maven and the asadmin Command -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== To Build, Package, and Deploy the hello1-formauth Example Using Maven and the asadmin Command 1. Follow the steps in link:#GJJLK[To Set Up Your System for Running the Security Examples]. 2. In a terminal window, go to: + -[source,oac_no_warn] +[source,java] ---- tut-install/examples/security/hello1-formauth/ ---- 3. Enter the following command at the terminal window or command prompt: + -[source,oac_no_warn] +[source,java] ---- mvn install ---- @@ -485,14 +451,13 @@ deploys the WAR file to GlassFish Server. [[GJRAL]][[to-run-the-hello1-formauth-example]] -To Run the hello1-formauth Example -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== To Run the hello1-formauth Example To run the web client for `hello1-formauth`, follow these steps. 1. Open a web browser to the following URL: + -[source,oac_no_warn] +[source,java] ---- http://localhost:8080/hello1-formauth/ ---- diff --git a/src/main/asciidoc/servlets/servlets.adoc b/src/main/asciidoc/servlets/servlets.adoc new file mode 100644 index 00000000..397dce36 --- /dev/null +++ b/src/main/asciidoc/servlets/servlets.adoc @@ -0,0 +1,48 @@ += Jakarta Servlet Technology + + +[[BNAFD]][[java-servlet-technology]] + +Jakarta Servlet technology provides dynamic, user-oriented content in web +applications using a request-response programming model. + +include::servlets001.adoc[] + +include::servlets002.adoc[] + +include::servlets003.adoc[] + +include::servlets004.adoc[] + +include::servlets005.adoc[] + +include::servlets006.adoc[] + +include::servlets007.adoc[] + +include::servlets008.adoc[] + +include::servlets009.adoc[] + +include::servlets010.adoc[] + +include::servlets011.adoc[] + +include::servlets012.adoc[] + +include::servlets013.adoc[] + +include::servlets014a.adoc[] + +include::servlets014.adoc[] + +include::servlets014b.adoc[] + +include::servlets015.adoc[] + +include::servlets016.adoc[] + +include::servlets017.adoc[] + +include::servlets018.adoc[] + diff --git a/src/main/jbake/content/servlets001.adoc b/src/main/asciidoc/servlets/servlets001.adoc similarity index 82% rename from src/main/jbake/content/servlets001.adoc rename to src/main/asciidoc/servlets/servlets001.adoc index bd901636..f95ec77c 100644 --- a/src/main/jbake/content/servlets001.adoc +++ b/src/main/asciidoc/servlets/servlets001.adoc @@ -1,16 +1,6 @@ -type=page -status=published -title=What Is a Servlet? -next=servlets002.html -prev=servlets.html -~~~~~~ -What Is a Servlet? -================== - [[BNAFE]][[what-is-a-servlet]] -What Is a Servlet? ------------------- +== 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 diff --git a/src/main/jbake/content/servlets002.adoc b/src/main/asciidoc/servlets/servlets002.adoc similarity index 79% rename from src/main/jbake/content/servlets002.adoc rename to src/main/asciidoc/servlets/servlets002.adoc index 6711540c..7b1812da 100644 --- a/src/main/jbake/content/servlets002.adoc +++ b/src/main/asciidoc/servlets/servlets002.adoc @@ -1,39 +1,24 @@ -type=page -status=published -title=Servlet Lifecycle -next=servlets003.html -prev=servlets001.html -~~~~~~ -= Servlet Lifecycle - - [[BNAFI]][[servlet-lifecycle]] -Servlet Lifecycle ------------------ +== Servlet Lifecycle 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. -1. If an instance of the servlet does not exist, the web container: -1. Loads the servlet class -2. Creates an instance of the servlet class -3. Initializes the servlet instance by calling the `init` method -(initialization is covered in link:servlets004.html#BNAFU[Creating and -Initializing a Servlet]) -2. The container invokes the `service` method, passing request and -response objects. Service methods are discussed in -link:servlets005.html#BNAFV[Writing Service Methods]. +. 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 link:#BNAFU[Creating and Initializing a Servlet]) +. The container invokes the `service` method, passing request and response objects. Service methods are discussed in link:#BNAFV[Writing Service Methods]. If it needs to remove the servlet, the container finalizes the servlet by calling the servlet's `destroy` method. For more information, see -link:servlets010.html#BNAGS[Finalizing a Servlet]. +link:#BNAGS[Finalizing a Servlet]. [[BNAFJ]][[handling-servlet-lifecycle-events]] -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. @@ -42,8 +27,7 @@ class. [[BNAFK]][[defining-the-listener-class]] -Defining the Listener Class -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== Defining the Listener Class You define a listener class as an implementation of a listener interface. link:#BNAFL[Table 18-1] lists the events that can be @@ -91,7 +75,7 @@ various operations on the particular web application context. Classes annotated with `@WebListener` must implement one of the following interfaces: -[source,oac_no_warn] +[source,java] ---- javax.servlet.ServletContextListener javax.servlet.ServletContextAttributeListener @@ -104,7 +88,7 @@ javax.servlet..http.HttpSessionAttributeListener For example, the following code snippet defines a listener that implements two of these interfaces: -[source,oac_no_warn] +[source,java] ---- import javax.servlet.ServletContextAttributeListener; import javax.servlet.ServletContextListener; @@ -118,14 +102,13 @@ public class SimpleServletListener implements ServletContextListener, [[BNAFN]][[handling-servlet-errors]] -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: -[source,oac_no_warn] +[source,java] ---- A Servlet Exception Has Occurred ---- diff --git a/src/main/jbake/content/servlets003.adoc b/src/main/asciidoc/servlets/servlets003.adoc similarity index 85% rename from src/main/jbake/content/servlets003.adoc rename to src/main/asciidoc/servlets/servlets003.adoc index 60e82723..42561fbc 100644 --- a/src/main/jbake/content/servlets003.adoc +++ b/src/main/asciidoc/servlets/servlets003.adoc @@ -1,16 +1,6 @@ -type=page -status=published -title=Sharing Information -next=servlets004.html -prev=servlets002.html -~~~~~~ -= Sharing Information - - [[BNAFO]][[sharing-information]] -Sharing Information -------------------- +== 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. @@ -20,12 +10,11 @@ accomplish their tasks. Web components can do so by doing the following. * 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 link:servlets007.html#BNAGI[Invoking Other Web Resources]. +in link:#BNAGI[Invoking Other Web Resources]. [[BNAFP]][[using-scope-objects]] -Using Scope Objects -~~~~~~~~~~~~~~~~~~~ +=== Using Scope Objects Collaborating web components share information by means of objects that are maintained as attributes of four scope objects. You access these @@ -41,11 +30,11 @@ objects. |======================================================================= |*Scope Object* |*Class* |*Accessible From* |Web context |`javax.servlet.ServletContext` |Web components within a -web context. See link:servlets008.html#BNAGL[Accessing the Web Context]. +web context. See link:#BNAGL[Accessing the Web Context]. |Session |`javax.servlet.http.HttpSession` |Web components handling a request that belongs to the session. See -link:servlets009.html#BNAGM[Maintaining Client State]. +link:#BNAGM[Maintaining Client State]. |Request |Subtype of `javax.servlet.ServletRequest` |Web components handling the request. @@ -57,8 +46,7 @@ object. [[BNAFS]][[controlling-concurrent-access-to-shared-resources]] -Controlling Concurrent Access to Shared Resources -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Controlling Concurrent Access to Shared Resources In a multithreaded server, shared resources can be accessed concurrently. In addition to scope object attributes, shared resources diff --git a/src/main/jbake/content/servlets004.adoc b/src/main/asciidoc/servlets/servlets004.adoc similarity index 85% rename from src/main/jbake/content/servlets004.adoc rename to src/main/asciidoc/servlets/servlets004.adoc index e9267b14..46c7f152 100644 --- a/src/main/jbake/content/servlets004.adoc +++ b/src/main/asciidoc/servlets/servlets004.adoc @@ -1,16 +1,6 @@ -type=page -status=published -title=Creating and Initializing a Servlet -next=servlets005.html -prev=servlets003.html -~~~~~~ -Creating and Initializing a Servlet -=================================== - [[BNAFU]][[creating-and-initializing-a-servlet]] -Creating and Initializing a Servlet ------------------------------------ +== Creating and Initializing a Servlet Use the `@WebServlet` annotation to define a servlet component in a web application. This annotation is specified on a class and contains @@ -26,7 +16,7 @@ Classes annotated with `@WebServlet` must extend the `javax.servlet.http.HttpServlet` class. For example, the following code snippet defines a servlet with the URL pattern `/report`: -[source,oac_no_warn] +[source,java] ---- import javax.servlet.annotation.WebServlet; import javax.servlet.http.HttpServlet; diff --git a/src/main/jbake/content/servlets005.adoc b/src/main/asciidoc/servlets/servlets005.adoc similarity index 91% rename from src/main/jbake/content/servlets005.adoc rename to src/main/asciidoc/servlets/servlets005.adoc index df09b8f6..5eae373b 100644 --- a/src/main/jbake/content/servlets005.adoc +++ b/src/main/asciidoc/servlets/servlets005.adoc @@ -1,16 +1,6 @@ -type=page -status=published -title=Writing Service Methods -next=servlets006.html -prev=servlets004.html -~~~~~~ -Writing Service Methods -======================= - [[BNAFV]][[writing-service-methods]] -Writing Service Methods ------------------------ +== Writing Service Methods The service provided by a servlet is implemented in the `service` method of a `GenericServlet`, in the `do`Method methods (where Method can take @@ -36,8 +26,7 @@ describe how to get information from requests and generate responses. [[BNAFW]][[getting-information-from-requests]] -Getting Information from Requests -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Getting Information from Requests A request contains data passed between a client and the servlet. All requests implement the `ServletRequest` interface. This interface @@ -61,7 +50,7 @@ HTTP servlets are passed an HTTP request object, `HttpServletRequest`, which contains the request URL, HTTP headers, query string, and so on. An HTTP request URL contains the following parts: -[source,oac_no_warn] +[source,java] ---- http://[host]:[port][request-path]?[query-string] ---- @@ -92,8 +81,7 @@ method is submitted. [[BNAFZ]][[constructing-responses]] -Constructing Responses -~~~~~~~~~~~~~~~~~~~~~~ +=== Constructing Responses A response contains data passed between a server and the client. All responses implement the `ServletResponse` interface. This interface @@ -119,7 +107,7 @@ with more time to set appropriate status codes and headers or forward to another web resource. The method must be called before any content is written or before the response is committed. * Set localization information, such as locale and character encoding. -See link:webi18n.html#BNAXU[Chapter 22, "Internationalizing and +See link:#BNAXU[Chapter 22, "Internationalizing and Localizing Web Applications"] for details. HTTP response objects, `javax.servlet.http.HttpServletResponse`, have @@ -129,5 +117,5 @@ fields representing HTTP headers, such as the following. 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 link:servlets009.html#BNAGR[Session +tracking a user's session (see link:#BNAGR[Session Tracking]). diff --git a/src/main/jbake/content/servlets006.adoc b/src/main/asciidoc/servlets/servlets006.adoc similarity index 70% rename from src/main/jbake/content/servlets006.adoc rename to src/main/asciidoc/servlets/servlets006.adoc index 87e4c198..8f57e350 100644 --- a/src/main/jbake/content/servlets006.adoc +++ b/src/main/asciidoc/servlets/servlets006.adoc @@ -1,16 +1,6 @@ -type=page -status=published -title=Filtering Requests and Responses -next=servlets007.html -prev=servlets005.html -~~~~~~ -Filtering Requests and Responses -================================ - [[BNAGB]][[filtering-requests-and-responses]] -Filtering Requests and Responses --------------------------------- +== Filtering Requests and Responses A filter is an object that can transform the header and content (or both) of a request or response. Filters differ from web components in @@ -24,10 +14,8 @@ The main tasks that a filter can perform are as follows. * Query the request and act accordingly. * Block the request-and-response pair from passing any further. -* Modify the request headers and data. You do this by providing a -customized version of the request. -* Modify the response headers and data. You do this by providing a -customized version of the response. +* Modify the request headers and data. You do this by providing a customized version of the request. +* Modify the response headers and data. You do this by providing a customized version of the response. * Interact with external resources. Applications of filters include authentication, logging, image @@ -41,8 +29,7 @@ when a web container loads the component. [[BNAGC]][[programming-filters]] -Programming Filters -~~~~~~~~~~~~~~~~~~~ +=== Programming Filters The filtering API is defined by the `Filter`, `FilterChain`, and `FilterConfig` interfaces in the `javax.servlet` package. You define a @@ -65,7 +52,7 @@ attribute of the `@WebFilter` annotation. The `initParams` attribute contains a `@WebInitParam` annotation. The following code snippet defines a filter, specifying an initialization parameter: -[source,oac_no_warn] +[source,java] ---- import javax.servlet.Filter; import javax.servlet.annotation.WebFilter; @@ -84,20 +71,9 @@ is passed request, response, and filter chain objects. This method can perform the following actions. * Examine the request headers. -* Customize the request object if the filter wishes to modify request -headers or data. -* Customize the response object if the filter wishes to modify response -headers or data. -* Invoke the next entity in the filter chain. If the current filter is -the last filter in the chain that ends with the target web component or -static resource, the next entity is the resource at the end of the -chain; otherwise, it is the next filter that was configured in the WAR. -The filter invokes the next entity by calling the `doFilter` method on -the chain object, passing in the request and response it was called with -or the wrapped versions it may have created. Alternatively, the filter -can choose to block the request by not making the call to invoke the -next entity. In the latter case, the filter is responsible for filling -out the response. +* Customize the request object if the filter wishes to modify request headers or data. +* Customize the response object if the filter wishes to modify response headers or data. +* Invoke the next entity in the filter chain. If the current filter is the last filter in the chain that ends with the target web component or static resource, the next entity is the resource at the end of the chain; otherwise, it is the next filter that was configured in the WAR. The filter invokes the next entity by calling the `doFilter` method on the chain object, passing in the request and response it was called with or the wrapped versions it may have created. Alternatively, the filter can choose to block the request by not making the call to invoke the next entity. In the latter case, the filter is responsible for filling out the response. * Examine response headers after invoking the next filter in the chain. * Throw an exception to indicate an error in processing. @@ -109,8 +85,7 @@ filter, you retrieve them from the `FilterConfig` object passed to [[BNAGD]][[programming-customized-requests-and-responses]] -Programming Customized Requests and Responses -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Programming Customized Requests and Responses There are many ways for a filter to modify a request or a response. For example, a filter can add an attribute to the request or can insert data @@ -135,8 +110,7 @@ extends either `ServletResponseWrapper` or `HttpServletResponseWrapper`. [[BNAGF]][[specifying-filter-mappings]] -Specifying Filter Mappings -~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Specifying Filter Mappings A web container uses filter mappings to decide how to apply filters to web resources. A filter mapping matches a filter to a web component by @@ -158,7 +132,7 @@ to servlets S1 and S2. [[BNAGH]] .*Figure 18-1 Filter-to-Servlet Mapping* -image:img/jakartaeett_dt_018.png[ +image:jakartaeett_dt_018.png[ "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."] @@ -178,42 +152,33 @@ F1's `doFilter` method. [[GJSLC]][[to-specify-filter-mappings-using-netbeans-ide]] -To Specify Filter Mappings Using NetBeans IDE -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -1. Expand the application's project node in the Project tab. -2. Expand the Web Pages and WEB-INF nodes under the project node. -3. Double-click `web.xml`. -4. Click Filters at the top of the editor window. -5. Expand the Servlet Filters node in the editor window. -6. Click Add Filter Element to map the filter to a web resource by name -or by URL pattern. -7. In the Add Servlet Filter dialog box, enter the name of the filter -in the Filter Name field. -8. Click Browse to locate the servlet class to which the filter -applies. +==== To Specify Filter Mappings Using NetBeans IDE + +. Expand the application's project node in the Project tab. +. Expand the Web Pages and WEB-INF nodes under the project node. +. Double-click `web.xml`. +. Click Filters at the top of the editor window. +. Expand the Servlet Filters node in the editor window. +. Click Add Filter Element to map the filter to a web resource by name or by URL pattern. +. In the Add Servlet Filter dialog box, enter the name of the filter in the Filter Name field. +. Click Browse to locate the servlet class to which the filter applies. + -You can include wildcard characters so that you can apply the filter to -more than one servlet. -9. Click OK. -10. To constrain how the filter is applied to requests, follow these -steps. -1. Expand the Filter Mappings node. -2. Select the filter from the list of filters. -3. Click Add. -4. In the Add Filter Mapping dialog box, select one of the following -dispatcher types: -* 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 -link:servlets007.html#BNAGK[Transferring Control to Another Web -Component]) -* INCLUDE: Only when the request is being processed by a component that -has been included (see link:servlets007.html#BNAGJ[Including Other -Resources in the Response]) -* ERROR: Only when the request is being processed with the error page -mechanism (see link:servlets002.html#BNAFN[Handling Servlet Errors]) +-- +You can include wildcard characters so that you can apply the filter to more than one servlet. +-- +. Click OK. +. To constrain how the filter is applied to requests, follow these steps: + -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. +-- +.. Expand the Filter Mappings node. +.. Select the filter from the list of filters. +.. Click Add. +.. In the Add Filter Mapping dialog box, select one of the following dispatcher types: +... 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 link:#BNAGK[Transferring Control to Another Web Component]) +... INCLUDE: Only when the request is being processed by a component that has been included (see link:#BNAGJ[Including Other Resources in the Response]) +... ERROR: Only when the request is being processed with the error page mechanism (see link:#BNAFN[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/jbake/content/servlets007.adoc b/src/main/asciidoc/servlets/servlets007.adoc similarity index 87% rename from src/main/jbake/content/servlets007.adoc rename to src/main/asciidoc/servlets/servlets007.adoc index dc7f2894..a3093c20 100644 --- a/src/main/jbake/content/servlets007.adoc +++ b/src/main/asciidoc/servlets/servlets007.adoc @@ -1,16 +1,6 @@ -type=page -status=published -title=Invoking Other Web Resources -next=servlets008.html -prev=servlets006.html -~~~~~~ -Invoking Other Web Resources -============================ - [[BNAGI]][[invoking-other-web-resources]] -Invoking Other Web Resources ----------------------------- +== Invoking Other Web Resources Web components can invoke other web resources both indirectly and directly. A web component indirectly invokes another web resource by @@ -33,15 +23,14 @@ null. Your servlet should be prepared to deal with this condition. [[BNAGJ]][[including-other-resources-in-the-response]] -Including Other Resources in the Response -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Including Other Resources in the Response It is often useful to include another web resource, such as banner content or copyright information, in the response returned from a web component. To include another resource, invoke the `include` method of a `RequestDispatcher` object: -[source,oac_no_warn] +[source,java] ---- include(request, response); ---- @@ -60,8 +49,7 @@ affects the headers of the response. [[BNAGK]][[transferring-control-to-another-web-component]] -Transferring Control to Another Web Component -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Transferring Control to Another Web Component In some applications, you might want to have one web component do preliminary processing of a request and have another component generate @@ -74,7 +62,7 @@ method of a `RequestDispatcher`. When a request is forwarded, the request URL is set to the path of the forwarded page. The original URI and its constituent parts are saved as the following request attributes: -[source,oac_no_warn] +[source,java] ---- javax.servlet.forward.request_uri javax.servlet.forward.context_path diff --git a/src/main/jbake/content/servlets008.adoc b/src/main/asciidoc/servlets/servlets008.adoc similarity index 75% rename from src/main/jbake/content/servlets008.adoc rename to src/main/asciidoc/servlets/servlets008.adoc index 07852cf2..2fabdcf4 100644 --- a/src/main/jbake/content/servlets008.adoc +++ b/src/main/asciidoc/servlets/servlets008.adoc @@ -1,16 +1,6 @@ -type=page -status=published -title=Accessing the Web Context -next=servlets009.html -prev=servlets007.html -~~~~~~ -Accessing the Web Context -========================= - [[BNAGL]][[accessing-the-web-context]] -Accessing the Web Context -------------------------- +== Accessing the Web Context The context in which web components execute is an object that implements the `ServletContext` interface. You retrieve the web context by using diff --git a/src/main/jbake/content/servlets009.adoc b/src/main/asciidoc/servlets/servlets009.adoc similarity index 87% rename from src/main/jbake/content/servlets009.adoc rename to src/main/asciidoc/servlets/servlets009.adoc index eecd8e89..2847acfb 100644 --- a/src/main/jbake/content/servlets009.adoc +++ b/src/main/asciidoc/servlets/servlets009.adoc @@ -1,16 +1,6 @@ -type=page -status=published -title=Maintaining Client State -next=servlets010.html -prev=servlets008.html -~~~~~~ -Maintaining Client State -======================== - [[BNAGM]][[maintaining-client-state]] -Maintaining Client State ------------------------- +== Maintaining Client State Many applications require that a series of requests from a client be associated with one another. For example, a web application can save the @@ -22,8 +12,7 @@ several mechanisms for implementing sessions. [[BNAGN]][[accessing-a-session]] -Accessing a Session -~~~~~~~~~~~~~~~~~~~ +=== Accessing a Session Sessions are represented by an `HttpSession` object. You access a session by calling the `getSession` method of a request object. This @@ -32,15 +21,14 @@ the request does not have a session, this method creates one. [[BNAGO]][[associating-objects-with-a-session]] -Associating Objects with a Session -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Associating Objects with a Session 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 (link:servlets002.html#BNAFJ[Handling +objects of servlet lifecycle events (link:#BNAFJ[Handling Servlet Lifecycle Events]). You can also notify objects of certain events related to their association with a session, such as the following. @@ -56,8 +44,7 @@ storage. To receive this notification, your object must implement the [[BNAGQ]][[session-management]] -Session Management -~~~~~~~~~~~~~~~~~~ +=== Session Management Because an HTTP client has no way to signal that it no longer needs a session, each session has an associated timeout so that its resources @@ -73,8 +60,7 @@ and remove any session data. [[sthref100]][[to-set-the-timeout-period-using-netbeans-ide]] -To Set the Timeout Period Using NetBeans IDE -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== To Set the Timeout Period Using NetBeans IDE To set the timeout period in the deployment descriptor using NetBeans IDE, follow these steps. @@ -92,8 +78,7 @@ must pass before the session times out. [[BNAGR]][[session-tracking]] -Session Tracking -~~~~~~~~~~~~~~~~ +=== Session Tracking To associate a session with a user, a web container can use several methods, all of which involve passing an identifier between the client diff --git a/src/main/jbake/content/servlets010.adoc b/src/main/asciidoc/servlets/servlets010.adoc similarity index 90% rename from src/main/jbake/content/servlets010.adoc rename to src/main/asciidoc/servlets/servlets010.adoc index 29cc06e1..6f073066 100644 --- a/src/main/jbake/content/servlets010.adoc +++ b/src/main/asciidoc/servlets/servlets010.adoc @@ -1,16 +1,6 @@ -type=page -status=published -title=Finalizing a Servlet -next=servlets011.html -prev=servlets009.html -~~~~~~ -Finalizing a Servlet -==================== - [[BNAGS]][[finalizing-a-servlet]] -Finalizing a Servlet --------------------- +== Finalizing a Servlet The web container may determine that a servlet should be removed from service (for example, when a container wants to reclaim memory resources @@ -39,8 +29,7 @@ and, if necessary, stop working, clean up, and return. [[BNAGT]][[tracking-service-requests]] -Tracking Service Requests -~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Tracking Service Requests To track service requests: @@ -50,7 +39,7 @@ service methods that are running. The field should have synchronized access methods to increment, decrement, and return its value: + -[source,oac_no_warn] +[source,java] ---- public class ShutdownExample extends HttpServlet { private int serviceCounter = 0; @@ -75,7 +64,7 @@ should override the `service` method. The new method should call `super.service` to preserve the functionality of the original `service` method: + -[source,oac_no_warn] +[source,java] ---- protected void service(HttpServletRequest req, HttpServletResponse resp) @@ -91,8 +80,7 @@ protected void service(HttpServletRequest req, [[BNAGU]][[notifying-methods-to-shut-down]] -Notifying Methods to Shut Down -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Notifying Methods to Shut Down To ensure a clean shutdown, your `destroy` method should not release any shared resources until all the service requests have completed: @@ -103,7 +91,7 @@ shared resources until all the service requests have completed: For this notification, another field is required. The field should have the usual access methods: + -[source,oac_no_warn] +[source,java] ---- public class ShutdownExample extends HttpServlet { private boolean shuttingDown; @@ -121,7 +109,7 @@ public class ShutdownExample extends HttpServlet { Here is an example of the `destroy` method using these fields to provide a clean shutdown: + -[source,oac_no_warn] +[source,java] ---- public void destroy() { /* Check to see whether there are still service methods /* @@ -142,15 +130,14 @@ public void destroy() { [[BNAGV]][[creating-polite-long-running-methods]] -Creating Polite Long-Running Methods -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Creating Polite Long-Running Methods The final step in providing a clean shutdown is to make any long-running methods behave politely. Methods that might run for a long time should check the value of the field that notifies them of shutdowns and should interrupt their work, if necessary: -[source,oac_no_warn] +[source,java] ---- public void doPost(...) { ... diff --git a/src/main/jbake/content/servlets011.adoc b/src/main/asciidoc/servlets/servlets011.adoc similarity index 89% rename from src/main/jbake/content/servlets011.adoc rename to src/main/asciidoc/servlets/servlets011.adoc index 524e23e5..0c9817ae 100644 --- a/src/main/jbake/content/servlets011.adoc +++ b/src/main/asciidoc/servlets/servlets011.adoc @@ -1,16 +1,6 @@ -type=page -status=published -title=Uploading Files with Jakarta Servlet Technology -next=servlets012.html -prev=servlets010.html -~~~~~~ -Uploading Files with Jakarta Servlet Technology -=============================================== - [[BABFGCHB]][[uploading-files-with-java-servlet-technology]] -Uploading Files with Jakarta Servlet Technology ------------------------------------------------ +== Uploading Files with Jakarta Servlet Technology Supporting file uploads is a very basic and common requirement for many web applications. In prior versions of the Servlet specification, @@ -31,8 +21,7 @@ a given `multipart/form-data` request by calling the [[sthref101]][[the-multipartconfig-annotation]] -The @MultipartConfig Annotation -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== The @MultipartConfig Annotation The `@MultipartConfig` annotation supports the following optional attributes. @@ -56,7 +45,7 @@ size is unlimited. For, example, the `@MultipartConfig` annotation could be constructed as follows: -[source,oac_no_warn] +[source,java] ---- @MultipartConfig(location="/tmp", fileSizeThreshold=1024*1024, maxFileSize=1024*1024*5, maxRequestSize=1024*1024*5*5) @@ -67,7 +56,7 @@ attributes in your file upload servlet, you could add the following as a child element of the servlet configuration element in the `web.xml` file: -[source,oac_no_warn] +[source,xml] ---- /tmp @@ -79,8 +68,7 @@ file: [[sthref102]][[the-getparts-and-getpart-methods]] -The getParts and getPart Methods -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== The getParts and getPart Methods The Servlet specification supports two additional `HttpServletRequest` methods: diff --git a/src/main/jbake/content/servlets012.adoc b/src/main/asciidoc/servlets/servlets012.adoc similarity index 95% rename from src/main/jbake/content/servlets012.adoc rename to src/main/asciidoc/servlets/servlets012.adoc index 1645dd75..335ddb52 100644 --- a/src/main/jbake/content/servlets012.adoc +++ b/src/main/asciidoc/servlets/servlets012.adoc @@ -1,16 +1,6 @@ -type=page -status=published -title=Asynchronous Processing -next=servlets013.html -prev=servlets011.html -~~~~~~ -= Asynchronous Processing - - [[BEIGCFDF]][[asynchronous-processing]] -Asynchronous Processing ------------------------ +== Asynchronous Processing Web containers in application servers normally use a server thread per client request. Under heavy load conditions, containers need a large @@ -39,8 +29,7 @@ with the request immediately to the container. [[sthref103]][[asynchronous-processing-in-servlets]] -Asynchronous Processing in Servlets -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Asynchronous Processing in Servlets Jakarta EE provides asynchronous processing support for servlets and filters. If a servlet or a filter reaches a potentially blocking @@ -54,7 +43,7 @@ to another servlet. To enable asynchronous processing on a servlet, set the parameter `asyncSupported` to `true` on the `@WebServlet` annotation as follows: -[source,oac_no_warn] +[source,java] ---- @WebServlet(urlPatterns={"/asyncservlet"}, asyncSupported=true) public class AsyncServlet extends HttpServlet { ... } @@ -65,7 +54,7 @@ you need to perform asynchronous processing inside service methods. To obtain an instance of `AsyncContext`, call the `startAsync()` method on the request object of your service method; for example: -[source,oac_no_warn] +[source,java] ---- public void doGet(HttpServletRequest req, HttpServletResponse resp) { ... @@ -130,8 +119,7 @@ the blocking operation completes. [[sthref105]][[waiting-for-a-resource]] -Waiting for a Resource -~~~~~~~~~~~~~~~~~~~~~~ +=== Waiting for a Resource This section demonstrates how to use the functionality provided by the `AsyncContext` class for the following use case: @@ -145,7 +133,7 @@ can be slow at times, so this may be a blocking operation. The following code shows a basic servlet that does not use asynchronous processing: -[source,oac_no_warn] +[source,java] ---- @WebServlet(urlPatterns={"/syncservlet"}) public class SyncServlet extends HttpServlet { @@ -168,7 +156,7 @@ public class SyncServlet extends HttpServlet { The following code shows the same servlet using asynchronous processing: -[source,oac_no_warn] +[source,java] ---- @WebServlet(urlPatterns={"/asyncservlet"}, asyncSupported=true) public class AsyncServlet extends HttpServlet { diff --git a/src/main/jbake/content/servlets013.adoc b/src/main/asciidoc/servlets/servlets013.adoc similarity index 91% rename from src/main/jbake/content/servlets013.adoc rename to src/main/asciidoc/servlets/servlets013.adoc index 9cbdeeb3..29d71bab 100644 --- a/src/main/jbake/content/servlets013.adoc +++ b/src/main/asciidoc/servlets/servlets013.adoc @@ -1,22 +1,12 @@ -type=page -status=published -title=Nonblocking I/O -next=servlets014.html -prev=servlets012.html -~~~~~~ -= Nonblocking I/O - - [[BEIHICDH]][[nonblocking-io]] -Nonblocking I/O ---------------- +== Nonblocking I/O 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. -link:servlets012.html#BEIGCFDF[Asynchronous Processing] provides a +link:#BEIGCFDF[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 @@ -36,7 +26,7 @@ how to use nonblocking I/O to process requests and write responses inside service methods. 1. Put the request in asynchronous mode as described in -link:servlets012.html#BEIGCFDF[Asynchronous Processing]. +link:#BEIGCFDF[Asynchronous Processing]. 2. Obtain an input stream and/or an output stream from the request and response objects in the service method. 3. Assign a read listener to the input stream and/or a write listener @@ -44,7 +34,7 @@ to the output stream. 4. Process the request and the response inside the listener's callback methods. -link:#BEIFDICJ[Table 18-4] and link:#BEIFIIIH[Table 18-5] describe the +link:#BEIFIIIH[Table 18-5] describe the methods available in the servlet input and output streams for nonblocking I/O support. link:#BEIFGJCG[Table 18-6] describes the interfaces for read listeners and write listeners. @@ -117,16 +107,15 @@ error. [[sthref109]][[reading-a-large-http-post-request-using-nonblocking-io]] -Reading a Large HTTP POST Request Using Nonblocking I/O -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== 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 link:servlets012.html#BEIGCFDF[Asynchronous Processing]) and +described in link:#BEIGCFDF[Asynchronous Processing]) and using the nonblocking I/O functionality from link:#BEIFDICJ[Table 18-4] and link:#BEIFGJCG[Table 18-6]. -[source,oac_no_warn] +[source,java] ---- @WebServlet(urlPatterns={"/asyncioservlet"}, asyncSupported=true) public class AsyncIOServlet extends HttpServlet { diff --git a/src/main/jbake/content/servlets014.adoc b/src/main/asciidoc/servlets/servlets014.adoc similarity index 90% rename from src/main/jbake/content/servlets014.adoc rename to src/main/asciidoc/servlets/servlets014.adoc index 5e270751..337f4e38 100644 --- a/src/main/jbake/content/servlets014.adoc +++ b/src/main/asciidoc/servlets/servlets014.adoc @@ -1,16 +1,6 @@ -type=page -status=published -title=Protocol Upgrade Processing -next=servlets014a.html -prev=servlets013.html -~~~~~~ -= Protocol Upgrade Processing - - [[BEIJHCDJ]][[protocol-upgrade-processing]] -Protocol Upgrade Processing ---------------------------- +== Protocol Upgrade Processing In HTTP/1.1, clients can request to switch to a different protocol on the current connection by using the `Upgrade` header field. If the @@ -22,7 +12,7 @@ using the new protocol. For example, a client can make an HTTP request to switch to the XYZP protocol as follows: -[source,oac_no_warn] +[source,java] ---- GET /xyzpresource HTTP/1.1 Host: localhost:8080 @@ -36,7 +26,7 @@ The client can specify parameters for the new protocol using HTTP headers. The server can accept the request and generate a response as follows: -[source,oac_no_warn] +[source,java] ---- HTTP/1.1 101 Switching Protocols Upgrade: XYZP @@ -84,14 +74,14 @@ the new protocol. `ServletInputStream getInputStream()` The `getInputStream` method provides access to the input stream of the -connection. You can use link:servlets013.html#BEIHICDH[Nonblocking I/O] +connection. You can use link:#BEIHICDH[Nonblocking I/O] with the returned stream to implement the new protocol. |`WebConnection` a| `ServletOutputStream getOutputStream()` The `getOutputStream` method provides access to the output stream of the -connection. You can use link:servlets013.html#BEIHICDH[Nonblocking I/O] +connection. You can use link:#BEIHICDH[Nonblocking I/O] with the returned stream to implement the new protocol. |======================================================================= @@ -100,7 +90,7 @@ with the returned stream to implement the new protocol. The following code demonstrates how to accept an HTTP protocol upgrade request from a client: -[source,oac_no_warn] +[source,java] ---- @WebServlet(urlPatterns={"/xyzpresource"}) public class XYZPUpgradeServlet extends HttpServlet { @@ -125,7 +115,7 @@ public class XYZPUpgradeServlet extends HttpServlet { The `XYZPUpgradeHandler` class handles the connection: -[source,oac_no_warn] +[source,java] ---- public class XYZPUpgradeHandler implements HttpUpgradeHandler { @Override diff --git a/src/main/jbake/content/servlets014a.adoc b/src/main/asciidoc/servlets/servlets014a.adoc similarity index 90% rename from src/main/jbake/content/servlets014a.adoc rename to src/main/asciidoc/servlets/servlets014a.adoc index 153d6f2f..4da9c801 100644 --- a/src/main/jbake/content/servlets014a.adoc +++ b/src/main/asciidoc/servlets/servlets014a.adoc @@ -1,15 +1,5 @@ -type=page -status=published -title=Server Push -next=servlets014b.html -prev=servlets014.html -~~~~~~ -= Server Push - - [[server-push]] -Server Push ------------ +== Server Push Server push is the ability of the server to anticipate what will be needed by the client in advance of the client's request. It lets the server diff --git a/src/main/jbake/content/servlets014b.adoc b/src/main/asciidoc/servlets/servlets014b.adoc similarity index 92% rename from src/main/jbake/content/servlets014b.adoc rename to src/main/asciidoc/servlets/servlets014b.adoc index 86fdf633..338809f3 100644 --- a/src/main/jbake/content/servlets014b.adoc +++ b/src/main/asciidoc/servlets/servlets014b.adoc @@ -1,15 +1,5 @@ -type=page -status=published -title=HTTP Trailer -next=servlets015.html -prev=servlets014a.html -~~~~~~ -= HTTP Trailer - - [[http-trailer]] -HTTP Trailer ------------- +== HTTP Trailer HTTP trailer is a collection of a special type of HTTP headers that comes after the response body. The trailer response header allows the sender to diff --git a/src/main/jbake/content/servlets015.adoc b/src/main/asciidoc/servlets/servlets015.adoc similarity index 72% rename from src/main/jbake/content/servlets015.adoc rename to src/main/asciidoc/servlets/servlets015.adoc index 82f47543..14d6b538 100644 --- a/src/main/jbake/content/servlets015.adoc +++ b/src/main/asciidoc/servlets/servlets015.adoc @@ -1,16 +1,6 @@ -type=page -status=published -title=The mood Example Application -next=servlets016.html -prev=servlets014b.html -~~~~~~ -= The mood Example Application - - [[GKCPG]][[the-mood-example-application]] -The mood Example Application ----------------------------- +== The mood Example Application The `mood` example application, located in the tut-install`/examples/web/servlet/mood/` directory, is a simple example @@ -19,15 +9,9 @@ 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. -The following topics are addressed here: - -* link:#CHDEBFCB[Components of the mood Example Application] -* link:#GKCOJ[Running the mood Example] - [[CHDEBFCB]][[components-of-the-mood-example-application]] -Components of the mood Example Application -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Components of the mood Example Application The `mood` example application is comprised of three components: `mood.web.MoodServlet`, `mood.web.TimeOfDayFilter`, and @@ -37,7 +21,7 @@ The `mood` example application is comprised of three components: Duke's mood in a graphic, based on the time of day. The `@WebServlet` annotation specifies the URL pattern: -[source,oac_no_warn] +[source,java] ---- @WebServlet("/report") public class MoodServlet extends HttpServlet { @@ -47,7 +31,7 @@ public class MoodServlet extends HttpServlet { `TimeOfDayFilter` sets an initialization parameter indicating that Duke is awake: -[source,oac_no_warn] +[source,java] ---- @WebFilter(filterName = "TimeOfDayFilter", urlPatterns = {"/*"}, @@ -65,29 +49,22 @@ entries appear in the server log. [[GKCOJ]][[running-the-mood-example]] -Running the mood Example -~~~~~~~~~~~~~~~~~~~~~~~~ +=== Running the mood Example You can use either NetBeans IDE or Maven to build, package, deploy, and run the `mood` example. -The following topics are addressed here: - -* link:#GKCOB[To Run the mood Example Using NetBeans IDE] -* link:#GKCPJ[To Run the mood Example Using Maven] - [[GKCOB]][[to-run-the-mood-example-using-netbeans-ide]] -To Run the mood Example Using NetBeans IDE -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== To Run the mood Example Using NetBeans IDE 1. Make sure that GlassFish Server has been started (see -link:usingexamples002.html#BNADI[Starting and Stopping GlassFish +link:#BNADI[Starting and Stopping GlassFish Server]). 2. From the File menu, choose Open Project. 3. In the Open Project dialog box, navigate to: + -[source,oac_no_warn] +[source,java] ---- tut-install/examples/web/servlet ---- @@ -97,7 +74,7 @@ tut-install/examples/web/servlet Build. 7. In a web browser, enter the following URL: + -[source,oac_no_warn] +[source,java] ---- http://localhost:8080/mood/report ---- @@ -109,27 +86,26 @@ string describing Duke's mood, and an illustrative graphic. [[GKCPJ]][[to-run-the-mood-example-using-maven]] -To Run the mood Example Using Maven -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== To Run the mood Example Using Maven 1. Make sure that GlassFish Server has been started (see -link:usingexamples002.html#BNADI[Starting and Stopping GlassFish +link:#BNADI[Starting and Stopping GlassFish Server]). 2. In a terminal window, go to: + -[source,oac_no_warn] +[source,java] ---- tut-install/examples/web/servlet/mood/ ---- 3. Enter the following command to deploy the application: + -[source,oac_no_warn] +[source,java] ---- mvn install ---- 4. In a web browser, enter the following URL: + -[source,oac_no_warn] +[source,java] ---- http://localhost:8080/mood/report ---- diff --git a/src/main/jbake/content/servlets016.adoc b/src/main/asciidoc/servlets/servlets016.adoc similarity index 86% rename from src/main/jbake/content/servlets016.adoc rename to src/main/asciidoc/servlets/servlets016.adoc index e2a24df0..28fd70a4 100644 --- a/src/main/jbake/content/servlets016.adoc +++ b/src/main/asciidoc/servlets/servlets016.adoc @@ -1,16 +1,6 @@ -type=page -status=published -title=The fileupload Example Application -next=servlets017.html -prev=servlets015.html -~~~~~~ -The fileupload Example Application -================================== - [[BABDGFJJ]][[the-fileupload-example-application]] -The fileupload Example Application ----------------------------------- +== The fileupload Example Application The `fileupload` example, located in the tut-install`/examples/web/servlet/fileupload/` directory, illustrates @@ -47,15 +37,9 @@ data that results from the download or use of content. |======================================================================= -The following topics are addressed here: - -* link:#CHDFGBGI[Architecture of the fileupload Example Application] -* link:#CHDIHJCI[Running the fileupload Example] - [[CHDFGBGI]][[architecture-of-the-fileupload-example-application]] -Architecture of the fileupload Example Application -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Architecture of the fileupload Example Application The `fileupload` example application consists of a single servlet and an HTML form that makes a file upload request to the servlet. @@ -80,7 +64,7 @@ in the specified destination. The HTML form in `index.html` is as follows: -[source,oac_no_warn] +[source,html] ---- @@ -118,7 +102,7 @@ This is what submitted data from the `fileupload` form looks like, after selecting `sample.txt` as the file that will be uploaded to the `tmp` directory on the local file system: -[source,oac_no_warn] +[source,xml] ---- POST /fileupload/upload HTTP/1.1 Host: localhost:8080 @@ -139,7 +123,7 @@ Content-Disposition: form-data; name="upload" The servlet `FileUploadServlet.java` begins as follows: -[source,oac_no_warn] +[source,java] ---- @WebServlet(name = "FileUploadServlet", urlPatterns = {"/upload"}) @MultipartConfig @@ -162,7 +146,7 @@ section of the method catches and handles some of the most common reasons why a file would not be found. The `processRequest` and `getFileName` methods look like this: -[source,oac_no_warn] +[source,java] ---- protected void processRequest(HttpServletRequest request, HttpServletResponse response) @@ -228,32 +212,22 @@ private String getFileName(final Part part) { [[CHDIHJCI]][[running-the-fileupload-example]] -Running the fileupload Example -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Running the fileupload Example You can use either NetBeans IDE or Maven to build, package, deploy, and run the `fileupload` example. -The following topics are addressed here: - -* link:#CHDGDJCI[To Build, Package, and Deploy the fileupload Example -Using NetBeans IDE] -* link:#CHDCFADG[To Build, Package, and Deploy the fileupload Example -Using Maven] -* link:#CHDDDAAJ[To Run the fileupload Example] - [[CHDGDJCI]][[to-build-package-and-deploy-the-fileupload-example-using-netbeans-ide]] -To Build, Package, and Deploy the fileupload Example Using NetBeans IDE -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== To Build, Package, and Deploy the fileupload Example Using NetBeans IDE 1. Make sure that GlassFish Server has been started (see -link:usingexamples002.html#BNADI[Starting and Stopping GlassFish +link:#BNADI[Starting and Stopping GlassFish Server]). 2. From the File menu, choose Open Project. 3. In the Open Project dialog box, navigate to: + -[source,oac_no_warn] +[source,java] ---- tut-install/examples/web/servlet ---- @@ -264,33 +238,31 @@ Build. [[CHDCFADG]][[to-build-package-and-deploy-the-fileupload-example-using-maven]] -To Build, Package, and Deploy the fileupload Example Using Maven -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== To Build, Package, and Deploy the fileupload Example Using Maven 1. Make sure that GlassFish Server has been started (see -link:usingexamples002.html#BNADI[Starting and Stopping GlassFish +link:#BNADI[Starting and Stopping GlassFish Server]). 2. In a terminal window, go to: + -[source,oac_no_warn] +[source,java] ---- tut-install/examples/web/servlet/fileupload/ ---- 3. Enter the following command to deploy the application: + -[source,oac_no_warn] +[source,java] ---- mvn install ---- [[CHDDDAAJ]][[to-run-the-fileupload-example]] -To Run the fileupload Example -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== To Run the fileupload Example 1. In a web browser, enter the following URL: + -[source,oac_no_warn] +[source,java] ---- http://localhost:8080/fileupload/ ---- diff --git a/src/main/jbake/content/servlets017.adoc b/src/main/asciidoc/servlets/servlets017.adoc similarity index 83% rename from src/main/jbake/content/servlets017.adoc rename to src/main/asciidoc/servlets/servlets017.adoc index d00c1307..2c204ac4 100644 --- a/src/main/jbake/content/servlets017.adoc +++ b/src/main/asciidoc/servlets/servlets017.adoc @@ -1,16 +1,6 @@ -type=page -status=published -title=The dukeetf Example Application -next=servlets018.html -prev=servlets016.html -~~~~~~ -The dukeetf Example Application -=============================== - [[BEIFAIFF]][[the-dukeetf-example-application]] -The dukeetf Example Application -------------------------------- +== The dukeetf Example Application The `dukeetf` example application, located in the tut-install`/examples/web/dukeetf/` directory, demonstrates how to use @@ -18,15 +8,9 @@ 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). -The following topics are addressed here: - -* link:#CHDBBEDA[Architecture of the dukeetf Example Application] -* link:#CHDHBBBI[Running the dukeetf Example Application] - [[CHDBBEDA]][[architecture-of-the-dukeetf-example-application]] -Architecture of the dukeetf Example Application -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Architecture of the dukeetf Example Application The `dukeetf` example application consists of a servlet, an enterprise bean, and an HTML page. @@ -53,12 +37,11 @@ the connection open until new data becomes available. [[sthref111]][[the-servlet]] -The Servlet -^^^^^^^^^^^ +==== The Servlet The `DukeETFServlet` class uses asynchronous processing: -[source,oac_no_warn] +[source,java] ---- @WebServlet(urlPatterns={"/dukeetf"}, asyncSupported=true) public class DukeETFServlet extends HttpServlet { @@ -72,7 +55,7 @@ provides the price and volume updates. The `send` method gets called once per second by the `PriceVolumeBean` to send updates and close the connection: -[source,oac_no_warn] +[source,java] ---- @Override public void init(ServletConfig config) { @@ -108,7 +91,7 @@ writing a response or when there is an error. Finally, the service method adds the request to the request queue created in the `init` method. The service method is the following: -[source,oac_no_warn] +[source,java] ---- @Override public void doGet(HttpServletRequest request, @@ -136,14 +119,13 @@ public void doGet(HttpServletRequest request, [[sthref112]][[the-enterprise-bean]] -The Enterprise Bean -^^^^^^^^^^^^^^^^^^^ +==== The Enterprise Bean The `PriceVolumeBean` class is an enterprise bean that uses the timer service from the container to update the price and volume information and call the servlet's `send` method once every second: -[source,oac_no_warn] +[source,java] ---- @Startup @Singleton @@ -177,19 +159,18 @@ public class PriceVolumeBean { } ---- -See link:ejb-basicexamples005.html#BNBOY[Using the Timer Service] in -link:ejb-basicexamples.html#GIJRB[Chapter 37, "Running the Enterprise +See link:#BNBOY[Using the Timer Service] in +link:#GIJRB[Chapter 37, "Running the Enterprise Bean Examples"] for more information on the timer service. [[sthref113]][[the-html-page]] -The HTML Page -^^^^^^^^^^^^^ +==== The HTML Page The HTML page consists of a table and some JavaScript code. The table contains two fields referenced from JavaScript code: -[source,oac_no_warn] +[source,html] ---- ... @@ -213,7 +194,7 @@ callback method. When the server provides a response, the callback method updates the fields in the table and makes a new request. The JavaScript code is the following: -[source,oac_no_warn] +[source,java] ---- var ajaxRequest; function updatePage() { @@ -237,37 +218,29 @@ The `XMLHttpRequest` API is supported by most modern browsers, and it is widely used in Ajax web client development (Asynchronous JavaScript and XML). -See link:websocket011.html#BABGCEHE[The dukeetf2 Example Application] in -link:websocket.html#GKJIQ5[Chapter 19, "Jakarta WebSocket"] for an +See link:#BABGCEHE[The dukeetf2 Example Application] in +link:#GKJIQ5[Chapter 19, "Jakarta WebSocket"] for an equivalent version of this example implemented using a WebSocket endpoint. [[CHDHBBBI]][[running-the-dukeetf-example-application]] -Running the dukeetf Example Application -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Running the dukeetf Example Application This section describes how to run the `dukeetf` example application using NetBeans IDE and from the command line. -The following topics are addressed here: - -* link:#CHDCGCJD[To Run the dukeetf Example Application Using NetBeans -IDE] -* link:#CHDHHAFG[To Run the dukeetf Example Application Using Maven] - [[CHDCGCJD]][[to-run-the-dukeetf-example-application-using-netbeans-ide]] -To Run the dukeetf Example Application Using NetBeans IDE -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== To Run the dukeetf Example Application Using NetBeans IDE 1. Make sure that GlassFish Server has been started (see -link:usingexamples002.html#BNADI[Starting and Stopping GlassFish +link:#BNADI[Starting and Stopping GlassFish Server]). 2. From the File menu, choose Open Project. 3. In the Open Project dialog box, navigate to: + -[source,oac_no_warn] +[source,java] ---- tut-install/examples/web/servlet ---- @@ -280,7 +253,7 @@ This command builds and packages the application into a WAR file (`dukeetf.war`) located in the `target` directory, deploys it to the server, and launches a web browser window with the following URL: + -[source,oac_no_warn] +[source,java] ---- http://localhost:8080/dukeetf/ ---- @@ -290,27 +263,26 @@ price and volume updates simultaneously. [[CHDHHAFG]][[to-run-the-dukeetf-example-application-using-maven]] -To Run the dukeetf Example Application Using Maven -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== To Run the dukeetf Example Application Using Maven 1. Make sure that GlassFish Server has been started (see -link:usingexamples002.html#BNADI[Starting and Stopping GlassFish +link:#BNADI[Starting and Stopping GlassFish Server]). 2. In a terminal window, go to: + -[source,oac_no_warn] +[source,java] ---- tut-install/examples/web/servlet/dukeetf/ ---- 3. Enter the following command to deploy the application: + -[source,oac_no_warn] +[source,java] ---- mvn install ---- 4. Open a web browser window and type the following address: + -[source,oac_no_warn] +[source,java] ---- http://localhost:8080/dukeetf/ ---- diff --git a/src/main/asciidoc/servlets/servlets018.adoc b/src/main/asciidoc/servlets/servlets018.adoc new file mode 100644 index 00000000..93dd3272 --- /dev/null +++ b/src/main/asciidoc/servlets/servlets018.adoc @@ -0,0 +1,6 @@ +[[BNAGW]][[further-information-about-java-servlet-technology]] + +== Further Information about Jakarta Servlet Technology + +For more information on Jakarta Servlet technology, see the Jakarta Servlet +4.0 specification at `https://jakarta.ee/specifications/servlet/4.0`. diff --git a/src/main/jbake/content/title.adoc b/src/main/asciidoc/title.adoc similarity index 81% rename from src/main/jbake/content/title.adoc rename to src/main/asciidoc/title.adoc index 1166ea61..de31a3da 100644 --- a/src/main/jbake/content/title.adoc +++ b/src/main/asciidoc/title.adoc @@ -1,24 +1,11 @@ -type=page -status=published -title=The Jakarta EE 8 Tutorial -next=preface.html -prev=toc.html -~~~~~~ - -[[java-platform-enterprise-edition]] -Jakarta EE ---------------------------- - -The Jakarta EE Tutorial - Release 8 Contributed 2018, 2019 -[[sthref1]] - ''''' +[[sthref1]] + The Jakarta EE 8 Tutorial diff --git a/src/main/asciidoc/transactions/transactions.adoc b/src/main/asciidoc/transactions/transactions.adoc new file mode 100644 index 00000000..4d392225 --- /dev/null +++ b/src/main/asciidoc/transactions/transactions.adoc @@ -0,0 +1,25 @@ += Transactions + +[[BNCIH]][[transactions]] + +This chapter describes types of transactions and how they are managed in +different applications. + +include::transactions001.adoc[] + +include::transactions002.adoc[] + +include::transactions003.adoc[] + +include::transactions004.adoc[] + +include::transactions005.adoc[] + +include::transactions006.adoc[] + +include::transactions007.adoc[] + +include::transactions008.adoc[] + +include::transactions009.adoc[] + diff --git a/src/main/jbake/content/transactions001.adoc b/src/main/asciidoc/transactions/transactions001.adoc similarity index 77% rename from src/main/jbake/content/transactions001.adoc rename to src/main/asciidoc/transactions/transactions001.adoc index 1101591e..fc3e9d57 100644 --- a/src/main/jbake/content/transactions001.adoc +++ b/src/main/asciidoc/transactions/transactions001.adoc @@ -1,16 +1,6 @@ -type=page -status=published -title=Overview of Transactions -next=transactions002.html -prev=transactions.html -~~~~~~ -Overview of Transactions -======================== - [[A1024277]][[overview-of-transactions]] -Overview of Transactions ------------------------- +== Overview of Transactions A typical enterprise application accesses and stores information in one or more databases. Because this information is critical for business diff --git a/src/main/jbake/content/transactions002.adoc b/src/main/asciidoc/transactions/transactions002.adoc similarity index 82% rename from src/main/jbake/content/transactions002.adoc rename to src/main/asciidoc/transactions/transactions002.adoc index 2d73df33..932808a8 100644 --- a/src/main/jbake/content/transactions002.adoc +++ b/src/main/asciidoc/transactions/transactions002.adoc @@ -1,16 +1,6 @@ -type=page -status=published -title=Transactions in Jakarta EE Applications -next=transactions003.html -prev=transactions001.html -~~~~~~ -Transactions in Jakarta EE Applications -======================================= - [[GIJRG]][[transactions-in-jakarta-ee-applications]] -Transactions in Jakarta EE Applications ---------------------------------------- +== Transactions in Jakarta EE Applications In a Jakarta EE application, a transaction is a series of actions that must all complete successfully, or else all the changes in each action are diff --git a/src/main/jbake/content/transactions003.adoc b/src/main/asciidoc/transactions/transactions003.adoc similarity index 86% rename from src/main/jbake/content/transactions003.adoc rename to src/main/asciidoc/transactions/transactions003.adoc index 2ab7e31b..1ab0e0e7 100644 --- a/src/main/jbake/content/transactions003.adoc +++ b/src/main/asciidoc/transactions/transactions003.adoc @@ -1,23 +1,13 @@ -type=page -status=published -title=What Is a Transaction? -next=transactions004.html -prev=transactions002.html -~~~~~~ -What Is a Transaction? -====================== - [[BNCII]][[what-is-a-transaction]] -What Is a Transaction? ----------------------- +== What Is a Transaction? To emulate a business transaction, a program may need to perform several steps. A financial program, for example, might transfer funds from a checking account to a savings account by using the steps listed in the following pseudocode: -[source,oac_no_warn] +[source,java] ---- begin transaction debit checking account diff --git a/src/main/jbake/content/transactions004.adoc b/src/main/asciidoc/transactions/transactions004.adoc similarity index 91% rename from src/main/jbake/content/transactions004.adoc rename to src/main/asciidoc/transactions/transactions004.adoc index 37ddc62c..1a0d8157 100644 --- a/src/main/jbake/content/transactions004.adoc +++ b/src/main/asciidoc/transactions/transactions004.adoc @@ -1,16 +1,6 @@ -type=page -status=published -title=Container-Managed Transactions -next=transactions005.html -prev=transactions003.html -~~~~~~ -= Container-Managed Transactions - - [[BNCIJ]][[container-managed-transactions]] -Container-Managed Transactions ------------------------------- +== Container-Managed Transactions In an enterprise bean with container-managed transaction demarcation, the enterprise bean container sets the boundaries of the transactions. You can use @@ -46,8 +36,7 @@ must not use the `javax.transaction.UserTransaction` interface. [[BNCIK]][[transaction-attributes]] -Transaction Attributes -~~~~~~~~~~~~~~~~~~~~~~ +=== Transaction Attributes A transaction attribute controls the scope of a transaction. link:#BNCIL[Figure 54-1] illustrates why controlling the scope is @@ -60,7 +49,7 @@ attribute of `method-B`. [[BNCIL]] .*Figure 54-1 Transaction Scope* -image:img/jakartaeett_dt_050.png[ +image:jakartaeett_dt_050.png[ "A diagram showing a transaction between two beans."] A transaction attribute can have one of the following values: @@ -74,8 +63,7 @@ A transaction attribute can have one of the following values: [[BNCIM]][[required-attribute]] -Required Attribute -^^^^^^^^^^^^^^^^^^ +==== Required Attribute If the client is running within a transaction and invokes the enterprise bean's method, the method executes within the client's transaction. If @@ -90,8 +78,7 @@ attributes are declarative, you can easily change them later. [[BNCIN]][[requiresnew-attribute]] -RequiresNew Attribute -^^^^^^^^^^^^^^^^^^^^^ +==== RequiresNew Attribute If the client is running within a transaction and invokes the enterprise bean's method, the container takes the following steps: @@ -109,8 +96,7 @@ the method always runs within a new transaction. [[BNCIO]][[mandatory-attribute]] -Mandatory Attribute -^^^^^^^^^^^^^^^^^^^ +==== Mandatory Attribute If the client is running within a transaction and invokes the enterprise bean's method, the method executes within the client's transaction. If @@ -122,8 +108,7 @@ the transaction of the client. [[BNCIP]][[notsupported-attribute]] -NotSupported Attribute -^^^^^^^^^^^^^^^^^^^^^^ +==== NotSupported Attribute If the client is running within a transaction and invokes the enterprise bean's method, the container suspends the client's transaction before @@ -139,8 +124,7 @@ improve performance. [[BNCIQ]][[supports-attribute]] -Supports Attribute -^^^^^^^^^^^^^^^^^^ +==== Supports Attribute If the client is running within a transaction and invokes the enterprise bean's method, the method executes within the client's transaction. If @@ -152,8 +136,7 @@ use the `Supports` attribute with caution. [[BNCIR]][[never-attribute]] -Never Attribute -^^^^^^^^^^^^^^^ +==== Never Attribute If the client is running within a transaction and invokes the enterprise bean's method, the container throws a `RemoteException`. If the client @@ -162,8 +145,7 @@ transaction before running the method. [[BNCIS]][[summary-of-transaction-attributes]] -Summary of Transaction Attributes -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== Summary of Transaction Attributes link:#BNCIT[Table 54-1] summarizes the effects of the transaction attributes. Both the `T1` and the `T2` transactions are controlled by @@ -216,8 +198,7 @@ Transaction [[BNCIU]][[setting-transaction-attributes]] -Setting Transaction Attributes -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== Setting Transaction Attributes Transaction attributes are specified by decorating the enterprise bean class or method with a `javax.ejb.TransactionAttribute` annotation and @@ -254,7 +235,7 @@ section. The following code snippet demonstrates how to use the `@TransactionAttribute` annotation: -[source,oac_no_warn] +[source,java] ---- @TransactionAttribute(NOT_SUPPORTED) @Stateful @@ -283,8 +264,7 @@ transaction or start a new transaction. Calls to `thirdMethod` or [[BNCIV]][[rolling-back-a-container-managed-transaction]] -Rolling Back a Container-Managed Transaction -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Rolling Back a Container-Managed Transaction There are two ways to roll back a container-managed transaction. First, if a system exception is thrown, the container will automatically roll @@ -296,8 +276,7 @@ to `setRollbackOnly`. [[BNCIW]][[synchronizing-a-session-beans-instance-variables]] -Synchronizing a Session Bean's Instance Variables -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Synchronizing a Session Bean's Instance Variables The `SessionSynchronization` interface, which is optional, allows stateful session bean instances to receive transaction synchronization @@ -323,8 +302,7 @@ back. [[BNCIX]][[methods-not-allowed-in-container-managed-transactions]] -Methods Not Allowed in Container-Managed Transactions -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Methods Not Allowed in Container-Managed Transactions You should not invoke any method that might interfere with the transaction boundaries set by the container. The following methods are diff --git a/src/main/jbake/content/transactions005.adoc b/src/main/asciidoc/transactions/transactions005.adoc similarity index 88% rename from src/main/jbake/content/transactions005.adoc rename to src/main/asciidoc/transactions/transactions005.adoc index 2b807a68..2a16c64a 100644 --- a/src/main/jbake/content/transactions005.adoc +++ b/src/main/asciidoc/transactions/transactions005.adoc @@ -1,16 +1,6 @@ -type=page -status=published -title=Bean-Managed Transactions -next=transactions006.html -prev=transactions004.html -~~~~~~ -Bean-Managed Transactions -========================= - [[BNCIY]][[bean-managed-transactions]] -Bean-Managed Transactions -------------------------- +== Bean-Managed Transactions In bean-managed transaction demarcation, the code in the session or message-driven bean explicitly marks the boundaries of the transaction. @@ -25,7 +15,7 @@ you can obtain with application-managed transactions. By checking various conditions, the pseudocode decides whether to start or stop certain transactions within the business method: -[source,oac_no_warn] +[source,java] ---- begin transaction ... @@ -50,8 +40,7 @@ types of transactions. [[BNCIZ]][[jta-transactions]] -Jakarta Transactions -~~~~~~~~~~~~~~~~~~~~ +=== Jakarta Transactions Jakarta Transactions allows you to demarcate transactions in a manner that is independent of the transaction manager @@ -73,8 +62,7 @@ To demarcate a Jakarta transaction, you invoke the `begin`, `commit`, and [[BNCJA]][[returning-without-committing]] -Returning without Committing -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Returning without Committing In a stateless session bean with bean-managed transactions, a business method must commit or roll back a transaction before returning. However, @@ -93,8 +81,7 @@ not retained. [[BNCJB]][[methods-not-allowed-in-bean-managed-transactions]] -Methods Not Allowed in Bean-Managed Transactions -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Methods Not Allowed in Bean-Managed Transactions Do not invoke the `getRollbackOnly` and `setRollbackOnly` methods of the `EJBContext` interface in bean-managed transactions. These methods diff --git a/src/main/jbake/content/transactions006.adoc b/src/main/asciidoc/transactions/transactions006.adoc similarity index 71% rename from src/main/jbake/content/transactions006.adoc rename to src/main/asciidoc/transactions/transactions006.adoc index 30af1959..ba35b4a6 100644 --- a/src/main/jbake/content/transactions006.adoc +++ b/src/main/asciidoc/transactions/transactions006.adoc @@ -1,28 +1,17 @@ -type=page -status=published -title=Transaction Timeouts -next=transactions007.html -prev=transactions005.html -~~~~~~ -Transaction Timeouts -==================== - [[BNCJC]][[transaction-timeouts]] -Transaction Timeouts --------------------- +== Transaction Timeouts For container-managed transactions, you can use the Administration Console to configure the transaction timeout interval. See -link:usingexamples003.html#BNADJ[Starting the Administration Console]. +link:#BNADJ[Starting the Administration Console]. For enterprise beans with bean-managed Jakarta transactions, you invoke the `setTransactionTimeout` method of the `UserTransaction` interface. [[sthref237]][[to-set-a-transaction-timeout]] -To Set a Transaction Timeout -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== To Set a Transaction Timeout 1. In the Administration Console, expand the Configurations node, then expand the server-config node and select Transaction Service. diff --git a/src/main/jbake/content/transactions007.adoc b/src/main/asciidoc/transactions/transactions007.adoc similarity index 83% rename from src/main/jbake/content/transactions007.adoc rename to src/main/asciidoc/transactions/transactions007.adoc index 5988f7d6..b0d931e6 100644 --- a/src/main/jbake/content/transactions007.adoc +++ b/src/main/asciidoc/transactions/transactions007.adoc @@ -1,16 +1,6 @@ -type=page -status=published -title=Updating Multiple Databases -next=transactions008.html -prev=transactions006.html -~~~~~~ -Updating Multiple Databases -=========================== - [[BNCJD]][[updating-multiple-databases]] -Updating Multiple Databases ---------------------------- +== Updating Multiple Databases The Jakarta EE transaction manager controls all enterprise bean transactions except for bean-managed JDBC transactions. The Jakarta EE @@ -36,13 +26,13 @@ in the same transaction. [[BNCJE]] .*Figure 54-2 Updating Multiple Databases* -image:img/jakartaeett_dt_051.png[ +image:jakartaeett_dt_051.png[ "A diagram showing Bean-A updating databases X and Y, and Bean-B updating database Z."] [[BNCJF]] .*Figure 54-3 Updating Multiple Databases Across Jakarta EE Servers* -image:img/jakartaeett_dt_052.png[ +image:jakartaeett_dt_052.png[ "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/jbake/content/transactions008.adoc b/src/main/asciidoc/transactions/transactions008.adoc similarity index 54% rename from src/main/jbake/content/transactions008.adoc rename to src/main/asciidoc/transactions/transactions008.adoc index 169e61ee..4e35cf64 100644 --- a/src/main/jbake/content/transactions008.adoc +++ b/src/main/asciidoc/transactions/transactions008.adoc @@ -1,22 +1,12 @@ -type=page -status=published -title=Transactions in Web Components -next=transactions009.html -prev=transactions007.html -~~~~~~ -Transactions in Web Components -============================== - [[BNCJG]][[transactions-in-web-components]] -Transactions in Web Components ------------------------------- +== Transactions in Web Components You can demarcate a transaction in a web component by using either the `java.sql.Connection` or the `javax.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 -link:transactions005.html#BNCIZ[Jakarta Transactions]. +link:#BNCIZ[Jakarta Transactions]. diff --git a/src/main/asciidoc/transactions/transactions009.adoc b/src/main/asciidoc/transactions/transactions009.adoc new file mode 100644 index 00000000..b0346340 --- /dev/null +++ b/src/main/asciidoc/transactions/transactions009.adoc @@ -0,0 +1,8 @@ +[[GKCMI]][[further-information-about-transactions]] + +== Further Information about Transactions + +For more information about transactions, see the Jakarta Transactions +1.3 specification at `https://jakarta.ee/specifications/transactions/1.3/`. + + diff --git a/src/main/asciidoc/usingexamples/usingexamples.adoc b/src/main/asciidoc/usingexamples/usingexamples.adoc new file mode 100644 index 00000000..6d04c241 --- /dev/null +++ b/src/main/asciidoc/usingexamples/usingexamples.adoc @@ -0,0 +1,29 @@ += Using the Tutorial Examples + + +[[GFIUD]][[using-the-tutorial-examples]] + +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/javaee/glassfish-samples/tree/master/ws/javaee8 + +include::usingexamples001.adoc[] + +include::usingexamples002.adoc[] + +include::usingexamples003.adoc[] + +include::usingexamples004.adoc[] + +include::usingexamples005.adoc[] + +include::usingexamples006.adoc[] + +include::usingexamples007.adoc[] + +include::usingexamples008.adoc[] + +include::usingexamples009.adoc[] + diff --git a/src/main/jbake/content/usingexamples001.adoc b/src/main/asciidoc/usingexamples/usingexamples001.adoc similarity index 84% rename from src/main/jbake/content/usingexamples001.adoc rename to src/main/asciidoc/usingexamples/usingexamples001.adoc index bdc0452b..e8da4fd1 100644 --- a/src/main/jbake/content/usingexamples001.adoc +++ b/src/main/asciidoc/usingexamples/usingexamples001.adoc @@ -1,16 +1,6 @@ -type=page -status=published -title=Required Software -next=usingexamples002.html -prev=usingexamples.html -~~~~~~ -= Required Software - - [[GEXAJ]][[required-software]] -Required Software ------------------ +== Required Software The following software is required to run the examples: @@ -23,8 +13,7 @@ The following software is required to run the examples: [[GEXAE]][[java-platform-standard-edition]] -Java Platform, Standard Edition -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Java Platform, Standard Edition To build, deploy, and run the examples, you need a copy of the Java Platform, Standard Edition Development Kit (JDK). You must use JDK 7 @@ -34,8 +23,7 @@ software from [[GEXAB]][[jakarta-ee-8-software-development-kit]] -Jakarta EE 8 Software Development Kit -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Jakarta EE 8 Software Development Kit GlassFish Server 5.1 is targeted as the build and runtime environment for the tutorial examples. To build, deploy, and run @@ -46,8 +34,7 @@ NetBeans IDE. You can download GlassFish Server from [[GEXBC]][[sdk-installation-tips]] -GlassFish Server Installation Tips -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== GlassFish Server Installation Tips GlassFish Server is installed from a ZIP file. It sets the default administration user name as `admin` with no required password. @@ -64,7 +51,7 @@ After you install GlassFish Server, add the following directories to your `PATH` to avoid having to specify the full path when you use commands: -[source,oac_no_warn] +[source,java] ---- as-install-parent/bin as-install/bin @@ -72,8 +59,7 @@ as-install/bin [[GEXBA]][[jakarta-ee-8-tutorial-component]] -Jakarta EE 8 Tutorial Component -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Jakarta EE 8 Tutorial Component The tutorial component, including the documentation and example source, is contained in GlassFish Server. @@ -81,14 +67,13 @@ is contained in GlassFish Server. //// Updates to the Jakarta EE Tutorial are published periodically. For details on obtaining these updates, see -link:usingexamples008.html#GIQWR[Getting the Latest Updates to the +link:#GIQWR[Getting the Latest Updates to the Tutorial]. //// [[GEXAZ]][[netbeans-ide]] -NetBeans IDE -~~~~~~~~~~~~ +=== NetBeans IDE The NetBeans integrated development environment (IDE) is a free, open-source IDE for developing Java applications, including enterprise @@ -102,8 +87,7 @@ the Jakarta EE bundle. [[GJSEQ]][[to-install-netbeans-ide-without-glassfish-server]] -To Install NetBeans IDE without GlassFish Server -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== To Install NetBeans IDE without GlassFish Server When you install NetBeans IDE, do not install the version of GlassFish Server that comes with NetBeans IDE. To skip the installation of @@ -119,8 +103,7 @@ install it. [[GIQZL]][[to-add-glassfish-server-as-a-server-using-netbeans-ide]] -To Add GlassFish Server as a Server Using NetBeans IDE -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== To Add GlassFish Server as a Server Using NetBeans IDE To run the tutorial examples in NetBeans IDE, you must add your GlassFish Server as a server in NetBeans IDE. Follow these instructions @@ -136,8 +119,7 @@ and click Next. [[GEXAA]][[apache-maven]] -Apache Maven -~~~~~~~~~~~~ +=== Apache Maven Maven is a Java technology-based build tool developed by the Apache Software Foundation and is used to build, package, and deploy the diff --git a/src/main/jbake/content/usingexamples002.adoc b/src/main/asciidoc/usingexamples/usingexamples002.adoc similarity index 71% rename from src/main/jbake/content/usingexamples002.adoc rename to src/main/asciidoc/usingexamples/usingexamples002.adoc index 1a7bae50..4b5c6838 100644 --- a/src/main/jbake/content/usingexamples002.adoc +++ b/src/main/asciidoc/usingexamples/usingexamples002.adoc @@ -1,24 +1,13 @@ -type=page -status=published -title=Starting and Stopping GlassFish Server -next=usingexamples003.html -prev=usingexamples001.html -~~~~~~ -Starting and Stopping GlassFish Server -====================================== - [[BNADI]][[starting-and-stopping-glassfish-server]] -Starting and Stopping GlassFish Server --------------------------------------- +== Starting and Stopping GlassFish Server You can start and stop GlassFish Server using either NetBeans IDE or the command line. [[CHDCACDI]][[to-start-glassfish-server-using-netbeans-ide]] -To Start GlassFish Server Using NetBeans IDE -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== To Start GlassFish Server Using NetBeans IDE 1. Click the Services tab. 2. Expand Servers. @@ -26,21 +15,19 @@ To Start GlassFish Server Using NetBeans IDE [[sthref14]][[to-stop-glassfish-server-using-netbeans-ide]] -To Stop GlassFish Server Using NetBeans IDE -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== To Stop GlassFish Server Using NetBeans IDE To stop GlassFish Server using NetBeans IDE, right-click the GlassFish Server instance and select Stop. [[CHDBDDAF]][[to-start-glassfish-server-using-the-command-line]] -To Start GlassFish Server Using the Command Line -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== To Start GlassFish Server Using the Command Line To start GlassFish Server from the command line, open a terminal window or command prompt and execute the following: -[source,oac_no_warn] +[source,java] ---- asadmin start-domain --verbose ---- @@ -66,13 +53,12 @@ domain-dir`/logs/server.log`. [[sthref15]][[to-stop-glassfish-server-using-the-command-line]] -To Stop GlassFish Server Using the Command Line -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== To Stop GlassFish Server Using the Command Line To stop GlassFish Server, open a terminal window or command prompt and execute: -[source,oac_no_warn] +[source,java] ---- asadmin stop-domain domain1 ---- diff --git a/src/main/jbake/content/usingexamples003.adoc b/src/main/asciidoc/usingexamples/usingexamples003.adoc similarity index 67% rename from src/main/jbake/content/usingexamples003.adoc rename to src/main/asciidoc/usingexamples/usingexamples003.adoc index 6d835a3c..3cb18b0f 100644 --- a/src/main/jbake/content/usingexamples003.adoc +++ b/src/main/asciidoc/usingexamples/usingexamples003.adoc @@ -1,16 +1,6 @@ -type=page -status=published -title=Starting the Administration Console -next=usingexamples004.html -prev=usingexamples002.html -~~~~~~ -Starting the Administration Console -=================================== - [[BNADJ]][[starting-the-administration-console]] -Starting the Administration Console ------------------------------------ +== Starting the Administration Console To administer GlassFish Server and manage users, resources, and Jakarta EE applications, use the Administration Console tool. GlassFish Server must @@ -19,8 +9,7 @@ Administration Console, open a browser at `http://localhost:4848/`. [[GJKST]][[to-start-the-administration-console-using-netbeans-ide]] -To Start the Administration Console Using NetBeans IDE -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== To Start the Administration Console Using NetBeans IDE 1. Click the Services tab. 2. Expand Servers. diff --git a/src/main/jbake/content/usingexamples004.adoc b/src/main/asciidoc/usingexamples/usingexamples004.adoc similarity index 74% rename from src/main/jbake/content/usingexamples004.adoc rename to src/main/asciidoc/usingexamples/usingexamples004.adoc index 11a0d380..f56058f2 100644 --- a/src/main/jbake/content/usingexamples004.adoc +++ b/src/main/asciidoc/usingexamples/usingexamples004.adoc @@ -1,23 +1,13 @@ -type=page -status=published -title=Starting and Stopping Apache Derby -next=usingexamples005.html -prev=usingexamples003.html -~~~~~~ -= Starting and Stopping Apache Derby - - [[BNADK]][[starting-and-stopping-the-java-db-server]] -Starting and Stopping Apache Derby ----------------------------------- +== Starting and Stopping Apache Derby GlassFish Server includes Apache Derby. To start Derby from the command line, open a terminal window or command prompt, change to the `_as-install_/bin` directory, and execute: -[source,oac_no_warn] +[source,java] ---- asadmin start-database ---- @@ -25,7 +15,7 @@ asadmin start-database To stop Derby from the command line, open a terminal window or command prompt, change to the `_as-install_/bin` directory, and execute: -[source,oac_no_warn] +[source,java] ---- asadmin stop-database ---- @@ -35,8 +25,7 @@ the Release Notes that are located in the `_as-install_/javadb/` directory. [[GJSFS]][[to-start-the-database-server-using-netbeans-ide]] -To Start Derby Using NetBeans IDE -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== To Start Derby Using NetBeans IDE When you start GlassFish Server using NetBeans IDE, the database server starts automatically. If you ever need to start the server manually, diff --git a/src/main/jbake/content/usingexamples005.adoc b/src/main/asciidoc/usingexamples/usingexamples005.adoc similarity index 58% rename from src/main/jbake/content/usingexamples005.adoc rename to src/main/asciidoc/usingexamples/usingexamples005.adoc index e79398ec..c84c823e 100644 --- a/src/main/jbake/content/usingexamples005.adoc +++ b/src/main/asciidoc/usingexamples/usingexamples005.adoc @@ -1,16 +1,6 @@ -type=page -status=published -title=Building the Examples -next=usingexamples006.html -prev=usingexamples004.html -~~~~~~ -Building the Examples -===================== - [[BNAAN]][[building-the-examples]] -Building the Examples ---------------------- +== Building the Examples The tutorial examples are distributed with a configuration file for either NetBeans IDE or Maven. Either NetBeans IDE or Maven may be used diff --git a/src/main/jbake/content/usingexamples006.adoc b/src/main/asciidoc/usingexamples/usingexamples006.adoc similarity index 81% rename from src/main/jbake/content/usingexamples006.adoc rename to src/main/asciidoc/usingexamples/usingexamples006.adoc index 9778c093..018669b3 100644 --- a/src/main/jbake/content/usingexamples006.adoc +++ b/src/main/asciidoc/usingexamples/usingexamples006.adoc @@ -1,16 +1,6 @@ -type=page -status=published -title=Tutorial Example Directory Structure -next=usingexamples007.html -prev=usingexamples005.html -~~~~~~ -Tutorial Example Directory Structure -==================================== - [[GEXAP]][[tutorial-example-directory-structure]] -Tutorial Example Directory Structure ------------------------------------- +== Tutorial Example Directory Structure To facilitate iterative development and keep application source files separate from compiled files, the tutorial examples use the Maven diff --git a/src/main/jbake/content/usingexamples007.adoc b/src/main/asciidoc/usingexamples/usingexamples007.adoc similarity index 64% rename from src/main/jbake/content/usingexamples007.adoc rename to src/main/asciidoc/usingexamples/usingexamples007.adoc index 1df5efa9..e734632d 100644 --- a/src/main/jbake/content/usingexamples007.adoc +++ b/src/main/asciidoc/usingexamples/usingexamples007.adoc @@ -1,16 +1,6 @@ -type=page -status=published -title=Jakarta EE Maven Archetypes in the Tutorial -next=usingexamples009.html -prev=usingexamples006.html -~~~~~~ -= Jakarta EE Maven Archetypes in the Tutorial - - [[CIHBHEFF]][[jakarta-ee-maven-archetypes-in-the-tutorial]] -Jakarta EE Maven Archetypes in the Tutorial -------------------------------------------- +== Jakarta EE Maven Archetypes in the Tutorial Some of the chapters have instructions on how to build an example application using Maven archetypes. Archetypes are templates for @@ -19,8 +9,7 @@ Maven archetypes for generating Jakarta EE projects. [[CHDJGCCA]][[installing-the-tutorial-archetypes]] -Installing the Tutorial Archetypes -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Installing the Tutorial Archetypes You must install the included Maven archetypes into your local Maven repository before you can create new projects based on the archetypes. @@ -28,13 +17,12 @@ You can install the archetypes using NetBeans IDE or Maven. [[sthref16]][[installing-the-tutorial-archetypes-using-netbeans-ide]] -Installing the Tutorial Archetypes Using NetBeans IDE -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== Installing the Tutorial Archetypes Using NetBeans IDE 1. From the *File* menu, choose *Open Project*. 2. In the Open Project dialog box, navigate to: + -[source,oac_no_warn] +[source,java] ---- tut-install/examples ---- @@ -45,18 +33,17 @@ tut-install/examples [[sthref17]][[installing-the-tutorial-archetypes-using-maven]] -Installing the Tutorial Archetypes Using Maven -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== Installing the Tutorial Archetypes Using Maven 1. In a terminal window, go to: + -[source,oac_no_warn] +[source,java] ---- tut-install/examples/archetypes/ ---- 2. Enter the following command: + -[source,oac_no_warn] +[source,java] ---- mvn install ---- diff --git a/src/main/jbake/content/usingexamples008.adoc b/src/main/asciidoc/usingexamples/usingexamples008.adoc similarity index 70% rename from src/main/jbake/content/usingexamples008.adoc rename to src/main/asciidoc/usingexamples/usingexamples008.adoc index 51558400..b7da57f8 100644 --- a/src/main/jbake/content/usingexamples008.adoc +++ b/src/main/asciidoc/usingexamples/usingexamples008.adoc @@ -1,24 +1,13 @@ -type=page -status=published -title=Getting the Latest Updates to the Tutorial -next=usingexamples009.html -prev=usingexamples007.html -~~~~~~ -= Getting the Latest Updates to the Tutorial - - [[GIQWR]][[getting-the-latest-updates-to-the-tutorial]] -Getting the Latest Updates to the Tutorial ------------------------------------------- +== Getting the Latest Updates to the Tutorial Check for any updates to the tutorial by using the Update Tool included with the Jakarta EE SDK. [[GIQYK]][[to-update-the-tutorial-using-netbeans-ide]] -To Update the Tutorial Using NetBeans IDE -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== To Update the Tutorial Using NetBeans IDE 1. Open the *Services* tab in NetBeans IDE and expand *Servers*. 2. Right-click the GlassFish Server instance and select *View Domain @@ -32,13 +21,12 @@ Tutorial* (`jakartaee-tutorial`) and click *Install*. [[sthref18]][[to-update-the-tutorial-using-the-command-line]] -To Update the Tutorial Using the Command Line -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== To Update the Tutorial Using the Command Line 1. Open a terminal window and enter the following command to display the Update Tool: + -[source,oac_no_warn] +[source,java] ---- updatetool ---- diff --git a/src/main/jbake/content/usingexamples009.adoc b/src/main/asciidoc/usingexamples/usingexamples009.adoc similarity index 82% rename from src/main/jbake/content/usingexamples009.adoc rename to src/main/asciidoc/usingexamples/usingexamples009.adoc index 32581e58..3ae254b2 100644 --- a/src/main/jbake/content/usingexamples009.adoc +++ b/src/main/asciidoc/usingexamples/usingexamples009.adoc @@ -1,24 +1,13 @@ -type=page -status=published -title=Debugging Jakarta EE Applications -next=partplatform.html -prev=usingexamples007.html -~~~~~~ -= Debugging Jakarta EE Applications - - [[BNADL]][[debugging-jakarta-ee-applications]] -Debugging Jakarta EE Applications ---------------------------------- +== Debugging Jakarta EE Applications This section explains how to determine what is causing an error in your application deployment or execution. [[BNADM]][[using-the-server-log]] -Using the Server Log -~~~~~~~~~~~~~~~~~~~~ +=== Using the Server Log One way to debug applications is to look at the server log in domain-dir`/logs/server.log`. The log contains output from GlassFish @@ -40,8 +29,7 @@ viewer. [[GJSGH]][[to-use-the-administration-console-log-viewer]] -To Use the Administration Console Log Viewer -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== To Use the Administration Console Log Viewer 1. Select the *GlassFish Server* node. 2. Click *View Log Files*. @@ -54,8 +42,7 @@ c. Click Search at the top of the log viewer. [[BNADN]][[using-a-debugger]] -Using a Debugger -~~~~~~~~~~~~~~~~ +=== Using a Debugger GlassFish Server supports the Java Platform Debugger Architecture (JPDA). With JPDA, you can configure GlassFish Server to communicate @@ -63,15 +50,14 @@ debugging information using a socket. [[GJQWL]][[to-debug-an-application-using-a-debugger]] -To Debug an Application Using a Debugger -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== To Debug an Application Using a Debugger 1. Follow these steps to enable debugging in GlassFish Server using the Administration Console: a. Expand the *Configurations* node, then expand the *server-config* node. b. Select the *JVM Settings* node. The default debug options are set to: + -[source,oac_no_warn] +[source,java] ---- -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=9009 ---- diff --git a/src/main/asciidoc/webapp/webapp.adoc b/src/main/asciidoc/webapp/webapp.adoc new file mode 100644 index 00000000..34bb755c --- /dev/null +++ b/src/main/asciidoc/webapp/webapp.adoc @@ -0,0 +1,19 @@ += Getting Started with Web Applications + +[[BNADR]][[getting-started-with-web-applications]] + +This chapter introduces web applications, which typically use JavaServer +Faces technology and/or Java Servlet technology. + +include::webapp001.adoc[] + +include::webapp002.adoc[] + +include::webapp003.adoc[] + +include::webapp004.adoc[] + +include::webapp005.adoc[] + +include::webapp006.adoc[] + diff --git a/src/main/jbake/content/webapp001.adoc b/src/main/asciidoc/webapp/webapp001.adoc similarity index 86% rename from src/main/jbake/content/webapp001.adoc rename to src/main/asciidoc/webapp/webapp001.adoc index f3d51d9b..a13c1c52 100644 --- a/src/main/jbake/content/webapp001.adoc +++ b/src/main/asciidoc/webapp/webapp001.adoc @@ -1,16 +1,6 @@ -type=page -status=published -title=Web Applications -next=webapp002.html -prev=webapp.html -~~~~~~ -Web Applications -================ - [[GEYSJ]][[web-applications]] -Web Applications ----------------- +== Web Applications A web application is a dynamic extension of a web or application server. Web applications are of the following types: @@ -19,16 +9,16 @@ Web applications are of the following types: 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 link:jsf-intro.html#BNAPH[Chapter 7, "Jakarta Server Faces -Technology,"] through link:servlets.html#BNAFD[Chapter 18, "Jakarta Servlet +covered in link:#BNAPH[Chapter 7, "Jakarta Server Faces +Technology,"] through link:#BNAFD[Chapter 18, "Jakarta Servlet Technology."] * 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 -link:jaxws.html#BNAYL[Chapter 31, "Building Web Services with JAX-WS,"] -and link:jaxrs.html#GIEPU[Chapter 32, "Building RESTful Web Services with -Jakarta RESTful Web Services,"] in link:partwebsvcs.html#BNAYK[Part III, "Web Services."] +link:#BNAYL[Chapter 31, "Building Web Services with JAX-WS,"] +and link:#GIEPU[Chapter 32, "Building RESTful Web Services with +Jakarta RESTful Web Services,"] in link:#BNAYK[Part III, "Web Services."] In the Jakarta EE platform, web components provide the dynamic extension capabilities for a web server. Web components can be Jakarta servlets, web @@ -48,7 +38,7 @@ HTTP response and returns it to the client. [[BNADS]] .*Figure 6-1 Jakarta Web Application Request Handling* -image:img/jakartaeett_dt_013.png[ +image:jakartaeett_dt_013.png[ "Diagram of web application request handling. Clients and servlets communicate using HttpServletRequest and HttpServletResponse."] diff --git a/src/main/jbake/content/webapp002.adoc b/src/main/asciidoc/webapp/webapp002.adoc similarity index 89% rename from src/main/jbake/content/webapp002.adoc rename to src/main/asciidoc/webapp/webapp002.adoc index 3cc4e711..281fa8da 100644 --- a/src/main/jbake/content/webapp002.adoc +++ b/src/main/asciidoc/webapp/webapp002.adoc @@ -1,16 +1,6 @@ -type=page -status=published -title=Web Application Lifecycle -next=webapp003.html -prev=webapp001.html -~~~~~~ -Web Application Lifecycle -========================= - [[BNADU]][[web-application-lifecycle]] -Web Application Lifecycle -------------------------- +== 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 diff --git a/src/main/jbake/content/webapp003.adoc b/src/main/asciidoc/webapp/webapp003.adoc similarity index 82% rename from src/main/jbake/content/webapp003.adoc rename to src/main/asciidoc/webapp/webapp003.adoc index 4525a8e2..ef34065f 100644 --- a/src/main/jbake/content/webapp003.adoc +++ b/src/main/asciidoc/webapp/webapp003.adoc @@ -1,16 +1,6 @@ -type=page -status=published -title=A Web Module That Uses Jakarta Server Faces Technology: The hello1 Example -next=webapp004.html -prev=webapp002.html -~~~~~~ -= A Web Module That Uses Jakarta Server Faces Technology: The hello1 Example - - [[BNADX]][[a-web-module-that-uses-javaserver-faces-technology-the-hello1-example]] -A Web Module That Uses Jakarta Server Faces Technology: The hello1 Example --------------------------------------------------------------------------- +== A Web Module That Uses Jakarta Server Faces Technology: The hello1 Example The `hello1` application is a web module that uses Jakarta Server Faces technology to display a greeting and response. You can use a text editor @@ -19,25 +9,16 @@ to view the application files, or you can use NetBeans IDE. The source code for this application is in the `_tut-install_/examples/web/jsf/hello1/` directory. -The following topics are addressed here: - -* link:#to-view-the-hello1-web-module-using-netbeans-ide[To View the hello1 Web Module Using NetBeans IDE] -* link:#packaging-and-deploying-the-hello1-web-module[Packaging and Deploying the hello1 Web Module] -* link:#viewing-deployed-web-modules[Viewing Deployed Web Modules] -* link:#running-the-deployed-hello1-web-module[Running the Deployed hello1 Web Module] -* link:#undeploying-the-hello1-web-module[Undeploying the hello1 Web Module] - [[GJWTV]][[to-view-the-hello1-web-module-using-netbeans-ide]] -To View the hello1 Web Module Using NetBeans IDE -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== To View the hello1 Web Module Using NetBeans IDE To view the `hello1` web module using NetBeans IDE: 1. From the File menu, choose Open Project. 2. In the Open Project dialog box, navigate to: + -[source,oac_no_warn] +[source,xml] ---- tut-install/examples/web/jsf ---- @@ -50,7 +31,7 @@ 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,oac_no_warn] +[source,xml] ---- @@ -108,7 +89,7 @@ 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,oac_no_warn] +[source,xml] ---- @@ -140,7 +121,7 @@ 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,oac_no_warn] +[source,java] ---- package jakarta.tutorial.hello1; @@ -170,7 +151,7 @@ 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 link:cdi-adv008.html#GKHQC[Using Stereotypes in CDI +later in link:#GKHQC[Using Stereotypes in CDI Applications]. Some examples will use `@Model` where it is appropriate. 8. Under the Web Pages node, expand the WEB-INF node and double-click the `web.xml` file to view it. @@ -181,7 +162,7 @@ when you use NetBeans IDE to create an application. * A context parameter specifying the project stage: + -[source,oac_no_warn] +[source,xml] ---- javax.faces.PROJECT_STAGE @@ -196,7 +177,7 @@ 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,oac_no_warn] +[source,xml] ---- Faces Servlet @@ -211,7 +192,7 @@ context parameters that an application can use. * A `welcome-file-list` element specifying the location of the landing page: + -[source,oac_no_warn] +[source,xml] ---- index.xhtml @@ -220,8 +201,7 @@ page: [[GLQLK]][[introduction-to-scopes]] -Introduction to Scopes -^^^^^^^^^^^^^^^^^^^^^^ +==== Introduction to Scopes In the `Hello.java` class, the annotations `javax.inject.Named` and `javax.enterprise.context.RequestScoped` identify the class as a managed @@ -243,12 +223,11 @@ use session scope. all users' interactions with a web application. For more information on scopes in Jakarta Server Faces technology, see -link:jsf-configure002.html#GIRCR[Using Managed Bean Scopes]. +link:#GIRCR[Using Managed Bean Scopes]. [[BNADZ]][[packaging-and-deploying-the-hello1-web-module]] -Packaging and Deploying the hello1 Web Module -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== 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 @@ -268,18 +247,17 @@ packaging and deploying. [[GJRGN]][[to-build-and-package-the-hello1-web-module-using-netbeans-ide]] -To Build and Package the hello1 Web Module Using NetBeans IDE -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== To Build and Package the hello1 Web Module Using NetBeans IDE To build and package the `hello1` web module using NetBeans IDE: 1. Start GlassFish Server as described in -link:usingexamples002.html#CHDCACDI[To Start GlassFish Server Using +link:#CHDCACDI[To Start GlassFish Server Using NetBeans IDE], if you have not already done so. 2. From the File menu, choose Open Project. 3. In the Open Project dialog box, navigate to: + -[source,oac_no_warn] +[source,xml] ---- tut-install/examples/web/jsf ---- @@ -290,23 +268,22 @@ Build. This command deploys the project to the server. [[GJRKN]][[to-build-and-package-the-hello1-web-module-using-maven]] -To Build and Package the hello1 Web Module Using Maven -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== To Build and Package the hello1 Web Module Using Maven To build and package the `hello1` web module using Maven: 1. Start GlassFish Server as described in -link:usingexamples002.html#CHDBDDAF[To Start GlassFish Server Using the +link:#CHDBDDAF[To Start GlassFish Server Using the Command Line], if you have not already done so. 2. In a terminal window, go to: + -[source,oac_no_warn] +[source,xml] ---- tut-install/examples/web/jsf/hello1/ ---- 3. Enter the following command: + -[source,oac_no_warn] +[source,xml] ---- mvn install ---- @@ -317,8 +294,7 @@ project to the server. [[BNAEI]][[viewing-deployed-web-modules]] -Viewing Deployed Web Modules -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== 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 @@ -326,8 +302,7 @@ NetBeans IDE to view deployed modules. [[GJSGR]][[to-view-deployed-web-modules-using-the-administration-console]] -To View Deployed Web Modules Using the Administration Console -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== To View Deployed Web Modules Using the Administration Console To view deployed web modules using the Administration Console: @@ -338,20 +313,18 @@ The deployed web modules appear in the Deployed Applications table. [[GJSEW]][[to-view-deployed-web-modules-using-the-asadmin-command]] -To View Deployed Web Modules Using the asadmin Command -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== To View Deployed Web Modules Using the asadmin Command Enter the following command: -[source,oac_no_warn] +[source,xml] ---- asadmin list-applications ---- [[sthref24]][[to-view-deployed-web-modules-using-netbeans-ide]] -To View Deployed Web Modules Using NetBeans IDE -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== To View Deployed Web Modules Using NetBeans IDE To view deployed web modules using NetBeans IDE: @@ -361,8 +334,7 @@ GlassFish Server node. [[BCEBEGED]][[running-the-deployed-hello1-web-module]] -Running the Deployed hello1 Web Module -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== 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 @@ -374,7 +346,7 @@ To run the deployed `hello1` web module: 1. Open a web browser. 2. Enter the following URL: + -[source,oac_no_warn] +[source,xml] ---- http://localhost:8080/hello1/ ---- @@ -385,8 +357,7 @@ again. [[BNAEM]][[dynamic-reloading-of-deployed-modules]] -Dynamic Reloading of Deployed Modules -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== 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 @@ -407,16 +378,14 @@ In GlassFish Server, dynamic reloading is enabled by default. [[BNAEN]][[undeploying-the-hello1-web-module]] -Undeploying the hello1 Web Module -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Undeploying the hello1 Web Module You can undeploy web modules and other types of enterprise applications by using either NetBeans IDE or Maven. [[GJSEJ]][[to-undeploy-the-hello1-web-module-using-netbeans-ide]] -To Undeploy the hello1 Web Module Using NetBeans IDE -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== To Undeploy the hello1 Web Module Using NetBeans IDE To undeploy the `hello1` web module using NetBeans IDE: @@ -429,27 +398,26 @@ Projects tab, right-click the project, and select Clean. [[GJSHH]][[to-undeploy-the-hello1-web-module-using-maven]] -To Undeploy the hello1 Web Module Using Maven -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== To Undeploy the hello1 Web Module Using Maven To undeploy the `hello1` web module using Maven: 1. In a terminal window, go to: + -[source,oac_no_warn] +[source,xml] ---- tut-install/examples/web/jsf/hello1/ ---- 2. Enter the following command: + -[source,oac_no_warn] +[source,xml] ---- mvn cargo:undeploy ---- 3. To delete the class files and other build artifacts, enter the following command: + -[source,oac_no_warn] +[source,xml] ---- mvn clean ---- diff --git a/src/main/jbake/content/webapp004.adoc b/src/main/asciidoc/webapp/webapp004.adoc similarity index 80% rename from src/main/jbake/content/webapp004.adoc rename to src/main/asciidoc/webapp/webapp004.adoc index 75e29da0..e7b7c59d 100644 --- a/src/main/jbake/content/webapp004.adoc +++ b/src/main/asciidoc/webapp/webapp004.adoc @@ -1,16 +1,6 @@ -type=page -status=published -title=A Web Module That Uses Jakarta Servlet Technology: The hello2 Example -next=webapp005.html -prev=webapp003.html -~~~~~~ -A Web Module That Uses Jakarta Servlet Technology: The hello2 Example -===================================================================== - [[BNAEO]][[a-web-module-that-uses-java-servlet-technology-the-hello2-example]] -A Web Module That Uses Jakarta Servlet Technology: The hello2 Example ---------------------------------------------------------------------- +== 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 @@ -19,16 +9,9 @@ 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. -The following topics are addressed here: - -* link:#mapping-urls-to-web-components[Mapping URLs to Web Components] -* link:#examining-the-hello2-web-module[Examining the hello2 Web Module] -* link:#running-the-hello2-example[Running the hello2 Example] - [[BNAEP]][[mapping-urls-to-web-components]] -Mapping URLs to Web Components -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== 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 @@ -36,7 +19,7 @@ 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: -[source,oac_no_warn] +[source,java] ---- http://host:port/context-root[/url-pattern] ---- @@ -46,7 +29,7 @@ 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,oac_no_warn] +[source,java] ---- @WebServlet("/greeting") public class GreetingServlet extends HttpServlet { @@ -57,7 +40,7 @@ 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: -[source,oac_no_warn] +[source,java] ---- http://localhost:8080/hello2/greeting ---- @@ -67,8 +50,7 @@ the URL pattern. [[GJWWG]][[examining-the-hello2-web-module]] -Examining the hello2 Web Module -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Examining the hello2 Web Module The `hello2` application behaves almost identically to the `hello1` application, but it is implemented using Jakarta Servlet technology instead @@ -77,15 +59,14 @@ application files, or you can use NetBeans IDE. [[GJWWA]][[to-view-the-hello2-web-module-using-netbeans-ide]] -To View the hello2 Web Module Using NetBeans IDE -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== To View the hello2 Web Module Using NetBeans IDE To view the `hello2` web module using NetBeans IDE: 1. From the File menu, choose Open Project. 2. In the Open Project dialog box, navigate to: + -[source,oac_no_warn] +[source,java] ---- tut-install/examples/web/servlet ---- @@ -100,7 +81,7 @@ 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,oac_no_warn] +[source,java] ---- @WebServlet("/greeting") public class GreetingServlet extends HttpServlet { @@ -150,7 +131,7 @@ response. The following excerpt begins with the `@WebServlet` annotation, which specifies the URL pattern relative to the context root: + -[source,oac_no_warn] +[source,java] ---- @WebServlet("/response") public class ResponseServlet extends HttpServlet { @@ -173,31 +154,24 @@ public class ResponseServlet extends HttpServlet { [[GKBLH]][[running-the-hello2-example]] -Running the hello2 Example -~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Running the hello2 Example You can use either NetBeans IDE or Maven to build, package, deploy, and run the `hello2` example. -The following topics are addressed here: - -* link:#GJSED[To Run the hello2 Example Using NetBeans IDE] -* link:#GJSHX[To Run the hello2 Example Using Maven] - [[GJSED]][[to-run-the-hello2-example-using-netbeans-ide]] -To Run the hello2 Example Using NetBeans IDE -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== To Run the hello2 Example Using NetBeans IDE To run the `hello2` example using NetBeans IDE: 1. Start GlassFish Server as described in -link:usingexamples002.html#CHDCACDI[To Start GlassFish Server Using +link:#CHDCACDI[To Start GlassFish Server Using NetBeans IDE], if you have not already done so. 2. From the File menu, choose Open Project. 3. In the Open Project dialog box, navigate to: + -[source,oac_no_warn] +[source,java] ---- tut-install/examples/web/servlet ---- @@ -207,7 +181,7 @@ tut-install/examples/web/servlet Build to package and deploy the project. 7. In a web browser, open the following URL: + -[source,oac_no_warn] +[source,java] ---- http://localhost:8080/hello2/greeting ---- @@ -220,23 +194,22 @@ greeting, not on a separate page. [[GJSHX]][[to-run-the-hello2-example-using-maven]] -To Run the hello2 Example Using Maven -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== To Run the hello2 Example Using Maven To run the `hello2` example using Maven: 1. Start GlassFish Server as described in -link:usingexamples002.html#CHDBDDAF[To Start GlassFish Server Using the +link:#CHDBDDAF[To Start GlassFish Server Using the Command Line], if you have not already done so. 2. In a terminal window, go to: + -[source,oac_no_warn] +[source,java] ---- tut-install/examples/web/servlet/hello2/ ---- 3. Enter the following command: + -[source,oac_no_warn] +[source,java] ---- mvn install ---- @@ -245,7 +218,7 @@ This target builds the WAR file, copies it to the `_tut-install_/examples/web/hello2/target/` directory, and deploys it. 4. In a web browser, open the following URL: + -[source,oac_no_warn] +[source,java] ---- http://localhost:8080/hello2/greeting ---- diff --git a/src/main/jbake/content/webapp005.adoc b/src/main/asciidoc/webapp/webapp005.adoc similarity index 88% rename from src/main/jbake/content/webapp005.adoc rename to src/main/asciidoc/webapp/webapp005.adoc index 94ef8528..6035da5e 100644 --- a/src/main/jbake/content/webapp005.adoc +++ b/src/main/asciidoc/webapp/webapp005.adoc @@ -1,16 +1,6 @@ -type=page -status=published -title=Configuring Web Applications -next=webapp006.html -prev=webapp004.html -~~~~~~ -= Configuring Web Applications - - [[CHDHGJIA]][[configuring-web-applications]] -Configuring Web Applications ----------------------------- +== Configuring Web Applications This section describes the following tasks involved with configuring web applications: @@ -22,20 +12,18 @@ applications: [[BNAES]][[setting-context-parameters]] -Setting Context Parameters -~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== 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 link:servlets004.html#BNAFU[Creating and +initialization parameters, see link:#BNAFU[Creating and Initializing a Servlet]. [[GJSFJ]][[to-add-a-context-parameter-using-netbeans-ide]] -To Add a Context Parameter Using NetBeans IDE -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== 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. @@ -60,8 +48,7 @@ context object. [[GKIHH]][[to-create-a-web.xml-file-using-netbeans-ide]] -To Create a web.xml File Using NetBeans IDE -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== To Create a web.xml File Using NetBeans IDE To create a `web.xml` file using NetBeans IDE: @@ -75,8 +62,7 @@ A basic `web.xml` file appears in `web/WEB-INF/`. [[BNAER]][[declaring-welcome-files]] -Declaring Welcome Files -~~~~~~~~~~~~~~~~~~~~~~~ +=== 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 @@ -102,7 +88,7 @@ listing. You specify welcome files in the `web.xml` file. The welcome file specification for the `hello1` example looks like this: -[source,oac_no_warn] +[source,java] ---- index.xhtml @@ -118,8 +104,7 @@ pattern `/greeting`. [[GKBKW]][[mapping-errors-to-error-screens]] -Mapping Errors to Error Screens -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== 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 @@ -134,8 +119,7 @@ error page to open. This error page can be the same for any number of [[BNAET]][[to-set-up-error-mapping-using-netbeans-ide]] -To Set Up Error Mapping Using NetBeans IDE -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== 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. @@ -165,8 +149,7 @@ throwable errors and exceptions, enter `java.lang.Throwable`. [[BNAEU]][[declaring-resource-references]] -Declaring Resource References -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== 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 @@ -188,13 +171,13 @@ link:#BNAEV[Table 6-1]. This section explains how to use a couple of the annotations supported by a web container to inject resources. -link:persistence-basicexamples.html#GIJST[Chapter 41, "Running the +link:#GIJST[Chapter 41, "Running the Persistence Examples"], explains how web applications use annotations supported by Jakarta Persistence. -link:security-webtier.html#BNCAS[Chapter 51, "Getting Started Securing +link:#BNCAS[Chapter 51, "Getting Started Securing Web Applications"], explains how to use annotations to specify information about securing web applications. See -link:resources.html#BNCJH[Chapter 55, "Resource Adapters and Contracts"], +link:#BNCJH[Chapter 55, "Resource Adapters and Contracts"], for more information on resources. [[sthref25]][[BNAEV]] @@ -227,8 +210,7 @@ for more information on resources. [[BNAEW]][[declaring-a-reference-to-a-resource]] -Declaring a Reference to a Resource -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== 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. @@ -243,7 +225,7 @@ 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,oac_no_warn] +[source,java] ---- @Resource javax.sql.DataSource catalogDS; public getProductsByCategory() { @@ -262,7 +244,7 @@ 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,oac_no_warn] +[source,java] ---- @Resources ({ @Resource(name="myDB" type=javax.sql.DataSource.class), @@ -277,14 +259,13 @@ 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. -link:persistence-basicexamples.html#GIJST[Chapter 41, "Running the +link:#GIJST[Chapter 41, "Running the Persistence Examples"] describes these annotations and the use of the Jakarta Persistence in web applications. [[BNAEX]][[declaring-a-reference-to-a-web-service]] -Declaring a Reference to a Web Service -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== 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 @@ -292,7 +273,7 @@ declare a reference to a web service. `WebServiceRef` uses the `wsdlLocation` element to specify the URI of the deployed service's WSDL file: -[source,oac_no_warn] +[source,java] ---- ... import javax.xml.ws.WebServiceRef; diff --git a/src/main/jbake/content/webapp006.adoc b/src/main/asciidoc/webapp/webapp006.adoc similarity index 52% rename from src/main/jbake/content/webapp006.adoc rename to src/main/asciidoc/webapp/webapp006.adoc index 5f7ccd24..fed336f7 100644 --- a/src/main/jbake/content/webapp006.adoc +++ b/src/main/asciidoc/webapp/webapp006.adoc @@ -1,16 +1,6 @@ -type=page -status=published -title=Further Information about Web Applications -next=jsf-intro.html -prev=webapp005.html -~~~~~~ -= Further Information about Web Applications - - [[BNAFC]][[further-information-about-web-applications]] -Further Information about Web Applications ------------------------------------------- +== Further Information about Web Applications For more information on web applications, see diff --git a/src/main/jbake/content/webi18n.adoc b/src/main/asciidoc/webi18n/webi18n.adoc similarity index 56% rename from src/main/jbake/content/webi18n.adoc rename to src/main/asciidoc/webi18n/webi18n.adoc index 971cc217..74c45352 100644 --- a/src/main/jbake/content/webi18n.adoc +++ b/src/main/asciidoc/webi18n/webi18n.adoc @@ -1,18 +1,8 @@ -type=page -status=published -title=Internationalizing and Localizing Web Applications -next=webi18n001.html -prev=jsonb004.html -~~~~~~ = Internationalizing and Localizing Web Applications [[BNAXU]][[internationalizing-and-localizing-web-applications]] -22 Internationalizing and Localizing Web Applications ------------------------------------------------------ - - 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 @@ -22,9 +12,11 @@ and date and currency formats. Although all client user interfaces should be internationalized and localized, it is particularly important for web applications because of the global nature of the web. -The following topics are addressed here: +include::webi18n001.adoc[] + +include::webi18n002.adoc[] + +include::webi18n003.adoc[] + +include::webi18n004.adoc[] -* link:webi18n001.html#BNAXV[Java Platform Localization Classes] -* link:webi18n002.html#BNAXW[Providing Localized Messages and Labels] -* link:webi18n003.html#BNAYA[Date and Number Formatting] -* link:webi18n004.html#BNAYB[Character Sets and Encodings] diff --git a/src/main/jbake/content/webi18n001.adoc b/src/main/asciidoc/webi18n/webi18n001.adoc similarity index 82% rename from src/main/jbake/content/webi18n001.adoc rename to src/main/asciidoc/webi18n/webi18n001.adoc index 9efe59b8..278b2f85 100644 --- a/src/main/jbake/content/webi18n001.adoc +++ b/src/main/asciidoc/webi18n/webi18n001.adoc @@ -1,16 +1,6 @@ -type=page -status=published -title=Java Platform Localization Classes -next=webi18n002.html -prev=webi18n.html -~~~~~~ -Java Platform Localization Classes -================================== - [[BNAXV]][[java-platform-localization-classes]] -Java Platform Localization Classes ----------------------------------- +== Java Platform Localization Classes In the Java platform, java.util.Locale (`http://docs.oracle.com/javase/8/docs/api/java/util/Locale.html`) @@ -30,7 +20,7 @@ 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 -link:dukes-bookstore.html#GLNVI[Chapter 60, "Duke's Bookstore Case Study +link:#GLNVI[Chapter 60, "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 diff --git a/src/main/jbake/content/webi18n002.adoc b/src/main/asciidoc/webi18n/webi18n002.adoc similarity index 87% rename from src/main/jbake/content/webi18n002.adoc rename to src/main/asciidoc/webi18n/webi18n002.adoc index e5f15d80..2bf9412c 100644 --- a/src/main/jbake/content/webi18n002.adoc +++ b/src/main/asciidoc/webi18n/webi18n002.adoc @@ -1,16 +1,6 @@ -type=page -status=published -title=Providing Localized Messages and Labels -next=webi18n003.html -prev=webi18n001.html -~~~~~~ -Providing Localized Messages and Labels -======================================= - [[BNAXW]][[providing-localized-messages-and-labels]] -Providing Localized Messages and Labels ---------------------------------------- +== Providing Localized Messages and Labels Messages and labels should be tailored according to the conventions of a user's language and region. There are two approaches to providing @@ -31,7 +21,7 @@ the corresponding key. The Duke's Bookstore application follows the second approach. Here are a few lines from the default resource bundle `messages`.`properties`: -[source,oac_no_warn] +[source,xml] ---- TitleShoppingCart=Shopping Cart TitleReceipt=Receipt @@ -44,8 +34,7 @@ What=What We\'re Reading [[GKUIA]][[establishing-the-locale]] -Establishing the Locale -~~~~~~~~~~~~~~~~~~~~~~~ +=== Establishing the Locale To get the correct strings for a given user, a web application either retrieves the locale (set by a browser language preference) from the @@ -60,7 +49,7 @@ default locale and also registers other supported locales. This element in Duke's Bookstore registers English as the default locale and indicates that German, French, and Spanish are supported locales. -[source,oac_no_warn] +[source,xml] ---- en @@ -73,7 +62,7 @@ indicates that German, French, and Spanish are supported locales. The `LocaleBean` in the Duke's Bookstore application uses the `getLocale` method to retrieve the locale. -[source,oac_no_warn] +[source,xml] ---- public class LocaleBean { @@ -87,13 +76,12 @@ public class LocaleBean { [[BNAXY]][[setting-the-resource-bundle]] -Setting the Resource Bundle -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Setting the Resource Bundle The resource bundle is set with the `resource-bundle` element in the configuration file. The setting for Duke's Bookstore looks like this: -[source,oac_no_warn] +[source,xml] ---- @@ -105,11 +93,11 @@ configuration file. 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 link:servlets009.html#BNAGO[Associating Objects with a +attribute (see link:#BNAGO[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,oac_no_warn] +[source,java] ---- public String toString(Locale locale) { ResourceBundle res = @@ -123,7 +111,7 @@ Alternatively, an application could use the `f:loadBundle` tag to set the resource bundle. This tag loads the correct resource bundle according to the locale stored in `FacesContext`. -[source,oac_no_warn] +[source,xml] ---- @@ -135,17 +123,16 @@ registered using the `resource-bundle` element of the configuration file. For more information on using this element, see -link:jsf-configure006.html#BNAXB[Registering Application Messages]. +link:#BNAXB[Registering Application Messages]. [[GKUFC]][[retrieving-localized-messages]] -Retrieving Localized Messages -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Retrieving Localized Messages A web component written in the Java programming language retrieves the resource bundle from the session: -[source,oac_no_warn] +[source,xml] ---- ResourceBundle messages = (ResourceBundle)session.getAttribute("messages"); ---- @@ -153,7 +140,7 @@ ResourceBundle messages = (ResourceBundle)session.getAttribute("messages"); Then it looks up the string associated with the key `person.lastName` as follows: -[source,oac_no_warn] +[source,java] ---- messages.getString("person.lastName"); ---- @@ -165,7 +152,7 @@ being registered on the component. The following example shows a input component if the validator registered on the component fails to validate the value the user enters into the component. -[source,oac_no_warn] +[source,xml] ---- @@ -176,7 +163,7 @@ validate the value the user enters into the component. ---- For more information on using the `message` or `messages` tags, see -link:jsf-page002.html#BNASO[Displaying Error Messages with the h:message +link:#BNASO[Displaying Error Messages with the h:message and h:messages Tags]. Messages that are not queued on a component and are therefore not loaded @@ -196,7 +183,7 @@ bundle, referred to by the `var` attribute. Here is an example from `bookcashier.xhtml` in Duke's Bookstore: -[source,oac_no_warn] +[source,xml] ---- ---- diff --git a/src/main/jbake/content/webi18n003.adoc b/src/main/asciidoc/webi18n/webi18n003.adoc similarity index 69% rename from src/main/jbake/content/webi18n003.adoc rename to src/main/asciidoc/webi18n/webi18n003.adoc index 3c981c59..0d3b1525 100644 --- a/src/main/jbake/content/webi18n003.adoc +++ b/src/main/asciidoc/webi18n/webi18n003.adoc @@ -1,16 +1,6 @@ -type=page -status=published -title=Date and Number Formatting -next=webi18n004.html -prev=webi18n002.html -~~~~~~ -Date and Number Formatting -========================== - [[BNAYA]][[date-and-number-formatting]] -Date and Number Formatting --------------------------- +== Date and Number Formatting Java programs use the `DateFormat.getDateInstance(int,` `locale)` method to parse and format dates in a locale-sensitive manner. Java programs @@ -22,7 +12,7 @@ An application can use date/time and number converters to format dates and numbers in a locale-sensitive manner. For example, a shipping date could be converted as follows: -[source,oac_no_warn] +[source,xml] ---- @@ -30,6 +20,6 @@ could be converted as follows: ---- For information on Jakarta Server Faces converters, see -link:jsf-page-core001.html#BNAST[Using the Standard Converters]. +link:#BNAST[Using the Standard Converters]. diff --git a/src/main/jbake/content/webi18n004.adoc b/src/main/asciidoc/webi18n/webi18n004.adoc similarity index 86% rename from src/main/jbake/content/webi18n004.adoc rename to src/main/asciidoc/webi18n/webi18n004.adoc index 677e862b..81f0c09c 100644 --- a/src/main/jbake/content/webi18n004.adoc +++ b/src/main/asciidoc/webi18n/webi18n004.adoc @@ -1,28 +1,12 @@ -type=page -status=published -title=Character Sets and Encodings -next=partbeanvalidation.html -prev=webi18n003.html -~~~~~~ -Character Sets and Encodings -============================ - [[BNAYB]][[character-sets-and-encodings]] -Character Sets and Encodings ----------------------------- +== Character Sets and Encodings The following sections describe character sets and character encodings. -The following topics are addressed here: - -* link:#BNAYC[Character Sets] -* link:#BNAYD[Character Encoding] - [[BNAYC]][[character-sets]] -Character Sets -~~~~~~~~~~~~~~ +=== Character Sets A character set is a set of textual and graphic symbols, each of which is mapped to a set of nonnegative integers. @@ -40,15 +24,14 @@ character's 16-bit representation in hexadecimal. For example, the Spanish version of a message file could use Unicode for non-ASCII characters, as follows: -[source,oac_no_warn] +[source,java] ---- admin.nav.main=P\u00e1gina principal de administraci\u00f3n ---- [[BNAYD]][[character-encoding]] -Character Encoding -~~~~~~~~~~~~~~~~~~ +=== Character Encoding A character encoding maps a character set to units of a specific width and defines byte serialization and ordering rules. Many character sets diff --git a/src/main/asciidoc/webservices-intro/webservices-intro.adoc b/src/main/asciidoc/webservices-intro/webservices-intro.adoc new file mode 100644 index 00000000..398e5e81 --- /dev/null +++ b/src/main/asciidoc/webservices-intro/webservices-intro.adoc @@ -0,0 +1,14 @@ += Introduction to Web Services + +[[GIJTI]][[introduction-to-web-services]] + +This part of the tutorial discusses Jakarta EE 8 web services technologies. +These technologies include Java API for XML Web Services (JAX-WS) and +Jakarta RESTful Web Services. + +include::webservices-intro001.adoc[] + +include::webservices-intro002.adoc[] + +include::webservices-intro003.adoc[] + diff --git a/src/main/jbake/content/webservices-intro001.adoc b/src/main/asciidoc/webservices-intro/webservices-intro001.adoc similarity index 76% rename from src/main/jbake/content/webservices-intro001.adoc rename to src/main/asciidoc/webservices-intro/webservices-intro001.adoc index bc56c6c0..dcba50a0 100644 --- a/src/main/jbake/content/webservices-intro001.adoc +++ b/src/main/asciidoc/webservices-intro/webservices-intro001.adoc @@ -1,16 +1,6 @@ -type=page -status=published -title=What Are Web Services? -next=webservices-intro002.html -prev=webservices-intro.html -~~~~~~ -What Are Web Services? -====================== - [[GIJVH]][[what-are-web-services]] -What Are Web Services? ----------------------- +== 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 diff --git a/src/main/jbake/content/webservices-intro002.adoc b/src/main/asciidoc/webservices-intro/webservices-intro002.adoc similarity index 91% rename from src/main/jbake/content/webservices-intro002.adoc rename to src/main/asciidoc/webservices-intro/webservices-intro002.adoc index ca25e9c9..e5152beb 100644 --- a/src/main/jbake/content/webservices-intro002.adoc +++ b/src/main/asciidoc/webservices-intro/webservices-intro002.adoc @@ -1,16 +1,6 @@ -type=page -status=published -title=Types of Web Services -next=webservices-intro003.html -prev=webservices-intro001.html -~~~~~~ -= Types of Web Services - - [[GIQSX]][[types-of-web-services]] -Types of Web Services ---------------------- +== 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 @@ -22,18 +12,12 @@ 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. -The following topics are addressed here: - -* link:#GKCDG["Big" Web Services] -* link:#GKCAW[RESTful Web Services] - [[GKCDG]][[big-web-services]] -"Big" Web Services -~~~~~~~~~~~~~~~~~~ +=== "Big" Web Services JAX-WS provides the functionality for "big" web services, -which are described in link:jaxws.html#BNAYL[Chapter 31, "Building Web +which are described in link:#BNAYL[Chapter 31, "Building Web Services with JAX-WS"]. 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 @@ -66,8 +50,7 @@ leveraged out of the box. [[GKCAW]][[restful-web-services]] -RESTful Web Services -~~~~~~~~~~~~~~~~~~~~ +=== 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 @@ -122,7 +105,7 @@ 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 link:jaxrs.html#GIEPU[Chapter 32, +RESTful web services are discussed in link:#GIEPU[Chapter 32, "Building RESTful Web Services with Jakarta RESTful Web Services"]. 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/jbake/content/webservices-intro003.adoc b/src/main/asciidoc/webservices-intro/webservices-intro003.adoc similarity index 81% rename from src/main/jbake/content/webservices-intro003.adoc rename to src/main/asciidoc/webservices-intro/webservices-intro003.adoc index 3f1e90c1..16e4dfea 100644 --- a/src/main/jbake/content/webservices-intro003.adoc +++ b/src/main/asciidoc/webservices-intro/webservices-intro003.adoc @@ -1,16 +1,6 @@ -type=page -status=published -title=Deciding Which Type of Web Service to Use -next=jaxws.html -prev=webservices-intro002.html -~~~~~~ -Deciding Which Type of Web Service to Use -========================================= - [[GJBJI]][[deciding-which-type-of-web-service-to-use]] -Deciding Which Type of Web Service to Use ------------------------------------------ +== 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 diff --git a/src/main/asciidoc/websocket/websocket.adoc b/src/main/asciidoc/websocket/websocket.adoc new file mode 100644 index 00000000..cca75a64 --- /dev/null +++ b/src/main/asciidoc/websocket/websocket.adoc @@ -0,0 +1,35 @@ += Jakarta WebSocket + +[[GKJIQ5]][[java-api-for-websocket]] + +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. + +include::websocket001.adoc[] + +include::websocket002.adoc[] + +include::websocket003.adoc[] + +include::websocket004.adoc[] + +include::websocket005.adoc[] + +include::websocket006.adoc[] + +include::websocket007.adoc[] + +include::websocket008.adoc[] + +include::websocket009.adoc[] + +include::websocket010.adoc[] + +include::websocket011.adoc[] + +include::websocket012.adoc[] + +include::websocket013.adoc[] + diff --git a/src/main/jbake/content/websocket001.adoc b/src/main/asciidoc/websocket/websocket001.adoc similarity index 92% rename from src/main/jbake/content/websocket001.adoc rename to src/main/asciidoc/websocket/websocket001.adoc index b5b640c1..b380c105 100644 --- a/src/main/jbake/content/websocket001.adoc +++ b/src/main/asciidoc/websocket/websocket001.adoc @@ -1,16 +1,6 @@ -type=page -status=published -title=Introduction to WebSocket -next=websocket002.html -prev=websocket.html -~~~~~~ -Introduction to WebSocket -========================= - [[BABDABHF]][[introduction-to-websocket]] -Introduction to WebSocket -------------------------- +== Introduction to WebSocket In the traditional request-response model used in HTTP, the client requests resources, and the server provides responses. The exchange is @@ -40,7 +30,7 @@ HTTP-based infrastructure: web servers interpret it as an HTTP connection upgrade request. An example handshake from a client looks like this: -[source,oac_no_warn] +[source,java] ---- GET /path/to/websocket/endpoint HTTP/1.1 Host: localhost @@ -54,7 +44,7 @@ Sec-WebSocket-Version: 13 An example handshake from the server in response to the client looks like this: -[source,oac_no_warn] +[source,java] ---- HTTP/1.1 101 Switching Protocols Upgrade: websocket @@ -77,7 +67,7 @@ a ping frame). Ping and pong frames may also contain application data. WebSocket endpoints are represented by URIs that have the following form: -[source,oac_no_warn] +[source,java] ---- ws://host:port/path?query wss://host:port/path?query diff --git a/src/main/jbake/content/websocket002.adoc b/src/main/asciidoc/websocket/websocket002.adoc similarity index 85% rename from src/main/jbake/content/websocket002.adoc rename to src/main/asciidoc/websocket/websocket002.adoc index c04d8f2a..b110471c 100644 --- a/src/main/jbake/content/websocket002.adoc +++ b/src/main/asciidoc/websocket/websocket002.adoc @@ -1,16 +1,6 @@ -type=page -status=published -title=Creating WebSocket Applications in the Jakarta EE Platform -next=websocket003.html -prev=websocket001.html -~~~~~~ -Creating WebSocket Applications in the Jakarta EE Platform -========================================================== - [[BABEAEFC]][[creating-websocket-applications-in-the-jakarta-ee-platform]] -Creating WebSocket Applications in the Jakarta EE Platform ----------------------------------------------------------- +== Creating WebSocket Applications in the Jakarta EE Platform The Jakarta EE platform includes Jakarta WebSocket, which enables you to create, configure, and deploy WebSocket endpoints @@ -51,8 +41,7 @@ a programmatic endpoint, but it focuses on annotated endpoints. [[sthref114]][[creating-and-deploying-a-websocket-endpoint]] -Creating and Deploying a WebSocket Endpoint -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Creating and Deploying a WebSocket Endpoint The process for creating and deploying a WebSocket endpoint: diff --git a/src/main/jbake/content/websocket003.adoc b/src/main/asciidoc/websocket/websocket003.adoc similarity index 86% rename from src/main/jbake/content/websocket003.adoc rename to src/main/asciidoc/websocket/websocket003.adoc index e019f890..444640c9 100644 --- a/src/main/jbake/content/websocket003.adoc +++ b/src/main/asciidoc/websocket/websocket003.adoc @@ -1,21 +1,11 @@ -type=page -status=published -title=Programmatic Endpoints -next=websocket004.html -prev=websocket002.html -~~~~~~ -Programmatic Endpoints -====================== - [[BABGJEIG]][[programmatic-endpoints]] -Programmatic Endpoints ----------------------- +== Programmatic Endpoints The following example shows how to create an endpoint by extending the `Endpoint` class: -[source,oac_no_warn] +[source,java] ---- public class EchoEndpoint extends Endpoint { @Override @@ -50,7 +40,7 @@ receives a text message. To deploy this programmatic endpoint, use the following code in your Jakarta EE application: -[source,oac_no_warn] +[source,java] ---- ServerEndpointConfig.Builder.create(EchoEndpoint.class, "/echo").build(); ---- diff --git a/src/main/jbake/content/websocket004.adoc b/src/main/asciidoc/websocket/websocket004.adoc similarity index 83% rename from src/main/jbake/content/websocket004.adoc rename to src/main/asciidoc/websocket/websocket004.adoc index ac053ece..760d47ea 100644 --- a/src/main/jbake/content/websocket004.adoc +++ b/src/main/asciidoc/websocket/websocket004.adoc @@ -1,22 +1,12 @@ -type=page -status=published -title=Annotated Endpoints -next=websocket005.html -prev=websocket003.html -~~~~~~ -= Annotated Endpoints - - [[BABFEBGA]][[annotated-endpoints]] -Annotated Endpoints -------------------- +== Annotated Endpoints The following example shows how to create the same endpoint from -link:websocket003.html#BABGJEIG[Programmatic Endpoints] using annotations +link:#BABGJEIG[Programmatic Endpoints] using annotations instead: -[source,oac_no_warn] +[source,java] ---- @ServerEndpoint("/echo") public class EchoEndpoint { @@ -50,7 +40,7 @@ parameters are allowed in each case. |======================================== |*Annotation* |*Event* |*Example* |`OnOpen` |Connection opened a| -[source,oac_no_warn] +[source,java] ---- @OnOpen public void open(Session session, @@ -58,7 +48,7 @@ public void open(Session session, ---- |`OnMessage` |Message received a| -[source,oac_no_warn] +[source,java] ---- @OnMessage public void message(Session session, @@ -66,7 +56,7 @@ public void message(Session session, ---- |`OnError` |Connection error a| -[source,oac_no_warn] +[source,java] ---- @OnError public void error(Session session, @@ -74,7 +64,7 @@ public void error(Session session, ---- |`OnClose` |Connection closed a| -[source,oac_no_warn] +[source,java] ---- @OnClose public void close(Session session, diff --git a/src/main/jbake/content/websocket005.adoc b/src/main/asciidoc/websocket/websocket005.adoc similarity index 84% rename from src/main/jbake/content/websocket005.adoc rename to src/main/asciidoc/websocket/websocket005.adoc index f620c474..19000400 100644 --- a/src/main/jbake/content/websocket005.adoc +++ b/src/main/asciidoc/websocket/websocket005.adoc @@ -1,16 +1,6 @@ -type=page -status=published -title=Sending and Receiving Messages -next=websocket006.html -prev=websocket004.html -~~~~~~ -Sending and Receiving Messages -============================== - [[BABFCGBJ]][[sending-and-receiving-messages]] -Sending and Receiving Messages ------------------------------- +== Sending and Receiving Messages WebSocket endpoints can send and receive text and binary messages. In addition, they can also send ping frames and receive pong frames. This @@ -18,15 +8,9 @@ section describes how to use the `Session` and `RemoteEndpoint` interfaces to send messages to the connected peer and how to use the `OnMessage` annotation to receive messages from it. -The following topics are addressed here: - -* link:#CIHEHFCB[Sending Messages] -* link:#CIHIDFHD[Receiving Messages] - [[CIHEHFCB]][[sending-messages]] -Sending Messages -~~~~~~~~~~~~~~~~ +=== Sending Messages Follow these steps to send messages in an endpoint. @@ -34,7 +18,7 @@ Follow these steps to send messages in an endpoint. + The `Session` object is available as a parameter in the annotated lifecycle methods of the endpoint, like those in -link:websocket004.html#BABDGEJH[Table 19-1]. When your message is a +link:#BABDGEJH[Table 19-1]. 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 @@ -67,14 +51,13 @@ Send a ping frame to the peer. + Send a pong frame to the peer. -The example in link:websocket004.html#BABFEBGA[Annotated Endpoints] +The example in link:#BABFEBGA[Annotated Endpoints] demonstrates how to use this procedure to reply to every incoming text message. [[BABIFBCG]][[sending-messages-to-all-peers-connected-to-an-endpoint]] -Sending Messages to All Peers Connected to an Endpoint -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== Sending Messages to All Peers Connected to an Endpoint Each instance of an endpoint class is associated with one and only one connection and peer; however, there are cases in which an endpoint @@ -84,7 +67,7 @@ the `getOpenSessions` method for this purpose. The following example demonstrates how to use this method to forward incoming text messages to all connected peers: -[source,oac_no_warn] +[source,java] ---- @ServerEndpoint("/echoall") public class EchoAllEndpoint { @@ -102,8 +85,7 @@ public class EchoAllEndpoint { [[CIHIDFHD]][[receiving-messages]] -Receiving Messages -~~~~~~~~~~~~~~~~~~ +=== Receiving Messages The `OnMessage` annotation designates methods that handle incoming messages. You can have at most three methods annotated with `@OnMessage` @@ -111,7 +93,7 @@ in an endpoint, one for each message type: text, binary, and pong. The following example demonstrates how to designate methods to receive all three types of messages: -[source,oac_no_warn] +[source,java] ---- @ServerEndpoint("/receive") public class ReceiveEndpoint { diff --git a/src/main/jbake/content/websocket006.adoc b/src/main/asciidoc/websocket/websocket006.adoc similarity index 83% rename from src/main/jbake/content/websocket006.adoc rename to src/main/asciidoc/websocket/websocket006.adoc index db2424e5..d1e9ffd6 100644 --- a/src/main/jbake/content/websocket006.adoc +++ b/src/main/asciidoc/websocket/websocket006.adoc @@ -1,16 +1,6 @@ -type=page -status=published -title=Maintaining Client State -next=websocket007.html -prev=websocket005.html -~~~~~~ -Maintaining Client State -======================== - [[BABGJCAD]][[maintaining-client-state]] -Maintaining Client State ------------------------- +== Maintaining Client State Because the container creates an instance of the endpoint class for every connection, you can define and use instance variables to store @@ -19,7 +9,7 @@ method provides a modifiable map to store user properties. For example, the following endpoint replies to incoming text messages with the contents of the previous message from each client: -[source,oac_no_warn] +[source,java] ---- @ServerEndpoint("/delayedecho") public class DelayedEchoEndpoint { diff --git a/src/main/jbake/content/websocket007.adoc b/src/main/asciidoc/websocket/websocket007.adoc similarity index 87% rename from src/main/jbake/content/websocket007.adoc rename to src/main/asciidoc/websocket/websocket007.adoc index d421cd33..fae79870 100644 --- a/src/main/jbake/content/websocket007.adoc +++ b/src/main/asciidoc/websocket/websocket007.adoc @@ -1,16 +1,6 @@ -type=page -status=published -title=Using Encoders and Decoders -next=websocket008.html -prev=websocket006.html -~~~~~~ -Using Encoders and Decoders -=========================== - [[BABGADFG]][[using-encoders-and-decoders]] -Using Encoders and Decoders ---------------------------- +== Using Encoders and Decoders Jakarta WebSocket provides support for converting between WebSocket messages and custom Java types using encoders and decoders. An @@ -24,17 +14,9 @@ This mechanism simplifies WebSocket applications, because it decouples the business logic from the serialization and deserialization of objects. -The following topics are addressed here: - -* link:#CIHBIGBI[Implementing Encoders to Convert Java Objects into -WebSocket Messages] -* link:#CIHGDJFG[Implementing Decoders to Convert WebSocket Messages -into Java Objects] - [[CIHBIGBI]][[implementing-encoders-to-convert-java-objects-into-websocket-messages]] -Implementing Encoders to Convert Java Objects into WebSocket Messages -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Implementing Encoders to Convert Java Objects into WebSocket Messages The procedure to implement and use encoders in endpoints follows. @@ -56,7 +38,7 @@ you want to send as text messages, implement the `Encoder.Text` and `Encoder.Text` interfaces as follows: -[source,oac_no_warn] +[source,java] ---- public class MessageATextEncoder implements Encoder.Text { @Override @@ -74,7 +56,7 @@ public class MessageATextEncoder implements Encoder.Text { Implement `Encoder.Text` similarly. Then, add the `encoders` parameter to the `ServerEndpoint` annotation as follows: -[source,oac_no_warn] +[source,java] ---- @ServerEndpoint( value = "/myendpoint", @@ -86,7 +68,7 @@ public class EncEndpoint { ... } Now, you can send `MessageA` and `MessageB` objects as WebSocket messages using the `sendObject` method as follows: -[source,oac_no_warn] +[source,java] ---- MessageA msgA = new MessageA(...); MessageB msgB = new MessageB(...); @@ -102,8 +84,7 @@ instance at any given time. [[CIHGDJFG]][[implementing-decoders-to-convert-websocket-messages-into-java-objects]] -Implementing Decoders to Convert WebSocket Messages into Java Objects -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Implementing Decoders to Convert WebSocket Messages into Java Objects The procedure to implement and use decoders in endpoints follows. @@ -138,7 +119,7 @@ extend a common class (`Message`). Because you can only define one decoder for text messages, implement a decoder for the `Message` class as follows: -[source,oac_no_warn] +[source,java] ---- public class MessageTextDecoder implements Decoder.Text { @Override @@ -165,7 +146,7 @@ public class MessageTextDecoder implements Decoder.Text { Then, add the `decoder` parameter to the `ServerEndpoint` annotation as follows: -[source,oac_no_warn] +[source,java] ---- @ServerEndpoint( value = "/myendpoint", @@ -178,7 +159,7 @@ public class EncDecEndpoint { ... } Now, define a method in the endpoint class that receives `MessageA` and `MessageB` objects as follows: -[source,oac_no_warn] +[source,java] ---- @OnMessage public void message(Session session, Message msg) { diff --git a/src/main/jbake/content/websocket008.adoc b/src/main/asciidoc/websocket/websocket008.adoc similarity index 85% rename from src/main/jbake/content/websocket008.adoc rename to src/main/asciidoc/websocket/websocket008.adoc index 8e656a4f..da29e42d 100644 --- a/src/main/jbake/content/websocket008.adoc +++ b/src/main/asciidoc/websocket/websocket008.adoc @@ -1,22 +1,12 @@ -type=page -status=published -title=Path Parameters -next=websocket009.html -prev=websocket007.html -~~~~~~ -Path Parameters -=============== - [[BABEJIJI]][[path-parameters]] -Path Parameters ---------------- +== Path Parameters The `ServerEndpoint` annotation enables you to use URI templates to specify parts of an endpoint deployment URI as application parameters. For example, consider this endpoint: -[source,oac_no_warn] +[source,java] ---- @ServerEndpoint("/chatrooms/{room-name}") public class ChatEndpoint { @@ -28,7 +18,7 @@ If the endpoint is deployed inside a web application called `chatapp` at a local Jakarta EE server in port 8080, clients can connect to the endpoint using any of the following URIs: -[source,oac_no_warn] +[source,java] ---- http://localhost:8080/chatapp/chatrooms/currentnews http://localhost:8080/chatapp/chatrooms/music @@ -41,7 +31,7 @@ annotated with `@OnOpen`, `@OnMessage`, and `@OnClose`. In this example, the endpoint uses the parameter in the `@OnOpen` method to determine which chat room the client wants to join: -[source,oac_no_warn] +[source,java] ---- @ServerEndpoint("/chatrooms/{room-name}") public class ChatEndpoint { diff --git a/src/main/jbake/content/websocket009.adoc b/src/main/asciidoc/websocket/websocket009.adoc similarity index 72% rename from src/main/jbake/content/websocket009.adoc rename to src/main/asciidoc/websocket/websocket009.adoc index 1e8c3c94..a084fa88 100644 --- a/src/main/jbake/content/websocket009.adoc +++ b/src/main/asciidoc/websocket/websocket009.adoc @@ -1,21 +1,11 @@ -type=page -status=published -title=Handling Errors -next=websocket010.html -prev=websocket008.html -~~~~~~ -= Handling Errors - - [[BABDEJHB]][[handling-errors]] -Handling Errors ---------------- +== Handling Errors To designate a method that handles errors in an annotated WebSocket endpoint, decorate it with `@OnError`: -[source,oac_no_warn] +[source,java] ---- @ServerEndpoint("/testendpoint") public class TestEndpoint { diff --git a/src/main/jbake/content/websocket010.adoc b/src/main/asciidoc/websocket/websocket010.adoc similarity index 86% rename from src/main/jbake/content/websocket010.adoc rename to src/main/asciidoc/websocket/websocket010.adoc index af80ee0c..c3022670 100644 --- a/src/main/jbake/content/websocket010.adoc +++ b/src/main/asciidoc/websocket/websocket010.adoc @@ -1,16 +1,6 @@ -type=page -status=published -title=Specifying an Endpoint Configurator Class -next=websocket011.html -prev=websocket009.html -~~~~~~ -Specifying an Endpoint Configurator Class -========================================= - [[BABJAIGH]][[specifying-an-endpoint-configurator-class]] -Specifying an Endpoint Configurator Class ------------------------------------------ +== Specifying an Endpoint Configurator Class Jakarta WebSocket enables you to configure how the container creates server endpoint instances. You can provide custom endpoint @@ -31,7 +21,7 @@ the `configurator` parameter of the `ServerEndpoint` annotation. For example, the following configurator class makes the handshake request object available to endpoint instances: -[source,oac_no_warn] +[source,java] ---- public class CustomConfigurator extends ServerEndpointConfig.Configurator { @@ -50,7 +40,7 @@ The following endpoint class configures endpoint instances with the custom configurator, which enables them to access the handshake request object: -[source,oac_no_warn] +[source,java] ---- @ServerEndpoint( value = "/myendpoint", diff --git a/src/main/jbake/content/websocket011.adoc b/src/main/asciidoc/websocket/websocket011.adoc similarity index 80% rename from src/main/jbake/content/websocket011.adoc rename to src/main/asciidoc/websocket/websocket011.adoc index fb56f44d..32c51a65 100644 --- a/src/main/jbake/content/websocket011.adoc +++ b/src/main/asciidoc/websocket/websocket011.adoc @@ -1,16 +1,6 @@ -type=page -status=published -title=The dukeetf2 Example Application -next=websocket012.html -prev=websocket010.html -~~~~~~ -The dukeetf2 Example Application -================================ - [[BABGCEHE]][[the-dukeetf2-example-application]] -The dukeetf2 Example Application --------------------------------- +== The dukeetf2 Example Application The `dukeetf2` example application, located in the tut-install`/examples/web/websocket/dukeetf2/` directory, demonstrates @@ -18,15 +8,9 @@ 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). -The following topics are addressed here: - -* link:#CIHJHJCD[Architecture of the dukeetf2 Sample Application] -* link:#CIHHBAIC[Running the dukeetf2 Example Application] - [[CIHJHJCD]][[architecture-of-the-dukeetf2-sample-application]] -Architecture of the dukeetf2 Sample Application -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Architecture of the dukeetf2 Sample Application The `dukeetf2` example application consists of a WebSocket endpoint, an enterprise bean, and an HTML page. @@ -41,14 +25,13 @@ information without reloading the page. [[sthref116]][[the-endpoint]] -The Endpoint -^^^^^^^^^^^^ +==== The Endpoint The WebSocket endpoint is implemented in the `ETFEndpoint` class, which stores all connected sessions in a queue and provides a method that the enterprise bean calls when there is new information available to send: -[source,oac_no_warn] +[source,java] ---- @ServerEndpoint("/dukeetf") public class ETFEndpoint { @@ -76,7 +59,7 @@ public class ETFEndpoint { The lifecycle methods of the endpoint add and remove sessions to and from the queue: -[source,oac_no_warn] +[source,java] ---- @ServerEndpoint("/dukeetf") public class ETFEndpoint { @@ -107,13 +90,12 @@ public class ETFEndpoint { [[sthref117]][[the-enterprise-bean]] -The Enterprise Bean -^^^^^^^^^^^^^^^^^^^ +==== The Enterprise Bean The enterprise bean uses the timer service to generate new price and volume information every second: -[source,oac_no_warn] +[source,java] ---- @Startup @Singleton @@ -144,20 +126,19 @@ public class PriceVolumeBean { ---- The enterprise bean calls the `send` method of the `ETFEndpoint` class -in the timeout method. See link:ejb-basicexamples005.html#BNBOY[Using the -Timer Service] in link:ejb-basicexamples.html#GIJRB[Chapter 37, "Running +in the timeout method. See link:#BNBOY[Using the +Timer Service] in link:#GIJRB[Chapter 37, "Running the Enterprise Bean Examples"] for more information on the timer service. [[CIHHIEFH]][[the-html-page]] -The HTML Page -^^^^^^^^^^^^^ +==== The HTML Page The HTML page consists of a table and some JavaScript code. The table contains two fields referenced from JavaScript code: -[source,oac_no_warn] +[source,html] ---- @@ -179,7 +160,7 @@ The JavaScript code uses the WebSocket API to connect to the server endpoint and to designate a callback method for incoming messages. The callback method updates the page with the new information. -[source,oac_no_warn] +[source,java] ---- var wsocket; function connect() { @@ -199,30 +180,22 @@ used in HTML5 web client development. [[CIHHBAIC]][[running-the-dukeetf2-example-application]] -Running the dukeetf2 Example Application -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Running the dukeetf2 Example Application This section describes how to run the `dukeetf2` example application using NetBeans IDE and from the command line. -The following topics are addressed here: - -* link:#CIHEBIAH[To Run the dukeetf2 Example Application Using NetBeans -IDE] -* link:#CIHDJCGJ[To Run the dukeetf2 Example Application Using Maven] - [[CIHEBIAH]][[to-run-the-dukeetf2-example-application-using-netbeans-ide]] -To Run the dukeetf2 Example Application Using NetBeans IDE -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== To Run the dukeetf2 Example Application Using NetBeans IDE 1. Make sure that GlassFish Server has been started (see -link:usingexamples002.html#BNADI[Starting and Stopping GlassFish +link:#BNADI[Starting and Stopping GlassFish Server]). 2. From the File menu, choose Open Project. 3. In the Open Project dialog box, navigate to: + -[source,oac_no_warn] +[source,java] ---- tut-install/examples/web/websocket ---- @@ -235,7 +208,7 @@ This command builds and packages the application into a WAR file (`dukeetf2.war`) located in the `target/` directory, deploys it to the server, and launches a web browser window with the following URL: + -[source,oac_no_warn] +[source,java] ---- http://localhost:8080/dukeetf2/ ---- @@ -245,27 +218,26 @@ both pages get price and volume updates simultaneously. [[CIHDJCGJ]][[to-run-the-dukeetf2-example-application-using-maven]] -To Run the dukeetf2 Example Application Using Maven -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== To Run the dukeetf2 Example Application Using Maven 1. Make sure that GlassFish Server has been started (see -link:usingexamples002.html#BNADI[Starting and Stopping GlassFish +link:#BNADI[Starting and Stopping GlassFish Server]). 2. In a terminal window, go to: + -[source,oac_no_warn] +[source,java] ---- tut-install/examples/web/websocket/dukeetf2/ ---- 3. Enter the following command to deploy the application: + -[source,oac_no_warn] +[source,java] ---- mvn install ---- 4. Open a web browser window and enter the following URL: + -[source,oac_no_warn] +[source,java] ---- http://localhost:8080/dukeetf2/ ---- diff --git a/src/main/jbake/content/websocket012.adoc b/src/main/asciidoc/websocket/websocket012.adoc similarity index 85% rename from src/main/jbake/content/websocket012.adoc rename to src/main/asciidoc/websocket/websocket012.adoc index 002c2891..14cd223f 100644 --- a/src/main/jbake/content/websocket012.adoc +++ b/src/main/asciidoc/websocket/websocket012.adoc @@ -1,16 +1,6 @@ -type=page -status=published -title=The websocketbot Example Application -next=websocket013.html -prev=websocket011.html -~~~~~~ -The websocketbot Example Application -==================================== - [[BABCDBBC]][[the-websocketbot-example-application]] -The websocketbot Example Application ------------------------------------- +== The websocketbot Example Application The `websocketbot` example application, located in the tut-install`/examples/web/websocket/websocketbot/` directory, @@ -19,15 +9,9 @@ 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. -The following topics are addressed here: - -* link:#CIHICIDE[Architecture of the websocketbot Example Application] -* link:#CIHHJHDB[Running the websocketbot Example Application] - [[CIHICIDE]][[architecture-of-the-websocketbot-example-application]] -Architecture of the websocketbot Example Application -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Architecture of the websocketbot Example Application The `websocketbot` example application consists of the following elements: @@ -46,20 +30,19 @@ text messages as JSON data * link:#CIHHFICG[The Message Decoder] – A class (`MessageDecoder`) the parses WebSocket text messages as JSON data and decodes them into `JoinMessage` or `ChatMessage` objects -* link:websocket011.html#CIHHIEFH[The HTML Page] – An HTML page +* link:#CIHHIEFH[The HTML Page] – An HTML page (`index.html`) that uses JavaScript code to implement the client for the chat room [[CIHDAEHF]][[the-cdi-bean]] -The CDI Bean -^^^^^^^^^^^^ +==== The CDI Bean The CDI bean (`BotBean`) is a Java class that contains the `respond` method. This method compares the incoming chat message with a set of predefined questions and returns a chat response. -[source,oac_no_warn] +[source,java] ---- @Named public class BotBean { @@ -69,8 +52,7 @@ public class BotBean { [[CIHJJJHG]][[the-websocket-endpoint]] -The WebSocket Endpoint -^^^^^^^^^^^^^^^^^^^^^^ +==== The WebSocket Endpoint The WebSocket endpoint (`BotEndpoint`) is an annotated endpoint that performs the following functions: @@ -85,7 +67,7 @@ decoders using the `ServerEndpoint` annotation. The endpoint obtains an instance of the `BotBean` class and a managed executor service resource through dependency injection: -[source,oac_no_warn] +[source,java] ---- @ServerEndpoint( value = "/websocketbot", @@ -115,7 +97,7 @@ decoder converts incoming text messages into `JoinMessage` or `ChatMessage` objects, which inherit from the `Message` class. The `message` method receives a `Message` object as a parameter: -[source,oac_no_warn] +[source,java] ---- @OnMessage public void message(Session session, Message msg) { @@ -160,7 +142,7 @@ 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 -link:websocket005.html#BABIFBCG[Sending Messages to All Peers Connected +link:#BABIFBCG[Sending Messages to All Peers Connected to an Endpoint]. Asynchronous Processing and Concurrency Considerations @@ -184,21 +166,20 @@ 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 link:concurrency-utilities.html#GKJIQ8[Chapter 59, "Concurrency +Refer to link:#GKJIQ8[Chapter 59, "Concurrency Utilities for Jakarta EE"] for more information on the managed executor service and Concurrency Utilities for Jakarta EE. [[CIHFDGHG]][[the-application-messages]] -The Application Messages -^^^^^^^^^^^^^^^^^^^^^^^^ +==== The Application Messages The classes that represent application messages (`Message`, `ChatMessage`, `InfoMessage`, `JoinMessage`, and `UsersMessage`) contain only properties and getter and setter methods. For example, the `ChatMessage` class looks like this: -[source,oac_no_warn] +[source,java] ---- public class ChatMessage extends Message { private String name; @@ -210,14 +191,13 @@ public class ChatMessage extends Message { [[CIHGHHBD]][[the-encoder-classes]] -The Encoder Classes -^^^^^^^^^^^^^^^^^^^ +==== The Encoder Classes The encoder classes convert application message objects into JSON text using the Java API for JSON Processing. For example, the `ChatMessageEncoder` class is implemented as follows: -[source,oac_no_warn] +[source,java] ---- /* Encode a ChatMessage as JSON. * For example, (new ChatMessage("Peter","Duke","How are you?")) @@ -236,19 +216,18 @@ public class ChatMessageEncoder implements Encoder.Text { } ---- -See link:jsonp.html#GLRBB[Chapter 20], link:jsonp.html#GLRBB[JSON +See link:#GLRBB[JSON Processing] for more information on the Java API for JSON Processing. [[CIHHFICG]][[the-message-decoder]] -The Message Decoder -^^^^^^^^^^^^^^^^^^^ +==== The Message Decoder The message decoder (`MessageDecoder`) class converts WebSocket text messages into application messages by parsing JSON text. It is implemented as follows: -[source,oac_no_warn] +[source,java] ---- /* Decode a JSON message into a JoinMessage or a ChatMessage. * For example, the incoming message @@ -296,8 +275,7 @@ public class MessageDecoder implements Decoder.Text { [[CIHGDBGF]][[the-html-page]] -The HTML Page -^^^^^^^^^^^^^ +==== The HTML Page The HTML page (`index.html`) contains a field for the user name. After the user types a name and clicks Join, three text areas are available: @@ -312,32 +290,22 @@ client development with HTML5. [[CIHHJHDB]][[running-the-websocketbot-example-application]] -Running the websocketbot Example Application -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +=== Running the websocketbot Example Application This section describes how to run the `websocketbot` example application using NetBeans IDE and from the command line. -The following topics are addressed here: - -* link:#CIHFDDGE[To Run the websocketbot Example Application Using -NetBeans IDE] -* link:#CIHEDEHB[To Run the websocketbot Example Application Using -Maven] -* link:#BABDDAAG[To Test the websocketbot Example Application] - [[CIHFDDGE]][[to-run-the-websocketbot-example-application-using-netbeans-ide]] -To Run the websocketbot Example Application Using NetBeans IDE -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== To Run the websocketbot Example Application Using NetBeans IDE 1. Make sure that GlassFish Server has been started (see -link:usingexamples002.html#BNADI[Starting and Stopping GlassFish +link:#BNADI[Starting and Stopping GlassFish Server]). 2. From the File menu, choose Open Project. 3. In the Open Project dialog box, navigate to: + -[source,oac_no_warn] +[source,java] ---- tut-install/examples/web/websocket ---- @@ -350,7 +318,7 @@ This command builds and packages the application into a WAR file, `websocketbot.war`, located in the `target/` directory; deploys it to the server; and launches a web browser window with the following URL: + -[source,oac_no_warn] +[source,java] ---- http://localhost:8080/websocketbot/ ---- @@ -360,27 +328,26 @@ more information. [[CIHEDEHB]][[to-run-the-websocketbot-example-application-using-maven]] -To Run the websocketbot Example Application Using Maven -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== To Run the websocketbot Example Application Using Maven 1. Make sure that GlassFish Server has been started (see -link:usingexamples002.html#BNADI[Starting and Stopping GlassFish +link:#BNADI[Starting and Stopping GlassFish Server]). 2. In a terminal window, go to: + -[source,oac_no_warn] +[source,java] ---- tut-install/examples/web/websocket/websocketbot/ ---- 3. Enter the following command to deploy the application: + -[source,oac_no_warn] +[source,java] ---- mvn install ---- 4. Open a web browser window and type the following address: + -[source,oac_no_warn] +[source,java] ---- http://localhost:8080/websocketbot/ ---- @@ -390,8 +357,7 @@ more information. [[BABDDAAG]][[to-test-the-websocketbot-example-application]] -To Test the websocketbot Example Application -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +==== To Test the websocketbot Example Application 1. On the main page, type your name on the first text field and press the Enter key. @@ -402,7 +368,7 @@ text area on the left is the chat room. type the messages in bold and press enter to obtain responses similar to the following: + -[source,oac_no_warn] +[source,java] ---- [--Peter has joined the chat--] Duke: @Peter Hi there!! diff --git a/src/main/asciidoc/websocket/websocket013.adoc b/src/main/asciidoc/websocket/websocket013.adoc new file mode 100644 index 00000000..e4403cca --- /dev/null +++ b/src/main/asciidoc/websocket/websocket013.adoc @@ -0,0 +1,9 @@ +[[BABDFIFD]][[further-information-about-websocket]] + +== Further Information about WebSocket + +For more information on WebSocket in Jakarta EE, see the Jakarta WebSocket specification: + +`https://jakarta.ee/specifications/websocket/1.1/` + + diff --git a/src/main/jbake/assets/CONTRIBUTING.md b/src/main/jbake/assets/CONTRIBUTING.md deleted file mode 100644 index 64e41037..00000000 --- a/src/main/jbake/assets/CONTRIBUTING.md +++ /dev/null @@ -1,49 +0,0 @@ -# Contributing to Eclipse Jakarta EE Platform - -Thanks for your interest in this project. - -## Project description - -The Eclipse Jakarta EE Platform project produces the Jakarta EE -platform specification, which is an umbrella specification that -aggregates all other Jakarta EE specifications. - -* [https://projects.eclipse.org/projects/ee4j.jakartaee-platform](https://projects.eclipse.org/projects/ee4j.jakartaee-platform) - -## 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 Contributor Agreement - -Before your contribution can be accepted by the project team contributors must -electronically sign the Eclipse Contributor Agreement (ECA). - -* [http://www.eclipse.org/legal/ECA.php](http://www.eclipse.org/legal/ECA.php) - -Commits that are provided by non-committers must have a Signed-off-by field in -the footer indicating that the author is aware of the terms by which the -contribution has been provided to the project. The non-committer must -additionally have an Eclipse Foundation account and must have a signed Eclipse -Contributor Agreement (ECA) on file. - -For more information, please see the Eclipse Committer Handbook: -[https://www.eclipse.org/projects/handbook/#resources-commit](https://www.eclipse.org/projects/handbook/#resources-commit) - -## 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) diff --git a/src/main/jbake/assets/LICENSE.md b/src/main/jbake/assets/LICENSE.md deleted file mode 100644 index f046098c..00000000 --- a/src/main/jbake/assets/LICENSE.md +++ /dev/null @@ -1,277 +0,0 @@ -# Eclipse Public License - v 2.0 - - THE ACCOMPANYING PROGRAM IS PROVIDED UNDER THE TERMS OF THIS ECLIPSE - PUBLIC LICENSE ("AGREEMENT"). ANY USE, REPRODUCTION OR DISTRIBUTION - OF THE PROGRAM CONSTITUTES RECIPIENT'S ACCEPTANCE OF THIS AGREEMENT. - - 1. DEFINITIONS - - "Contribution" means: - - a) in the case of the initial Contributor, the initial content - Distributed under this Agreement, and - - b) in the case of each subsequent Contributor: - i) changes to the Program, and - ii) additions to the Program; - where such changes and/or additions to the Program originate from - and are Distributed by that particular Contributor. A Contribution - "originates" from a Contributor if it was added to the Program by - such Contributor itself or anyone acting on such Contributor's behalf. - Contributions do not include changes or additions to the Program that - are not Modified Works. - - "Contributor" means any person or entity that Distributes the Program. - - "Licensed Patents" mean patent claims licensable by a Contributor which - are necessarily infringed by the use or sale of its Contribution alone - or when combined with the Program. - - "Program" means the Contributions Distributed in accordance with this - Agreement. - - "Recipient" means anyone who receives the Program under this Agreement - or any Secondary License (as applicable), including Contributors. - - "Derivative Works" shall mean any work, whether in Source Code or other - form, that is based on (or derived from) the Program and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. - - "Modified Works" shall mean any work in Source Code or other form that - results from an addition to, deletion from, or modification of the - contents of the Program, including, for purposes of clarity any new file - in Source Code form that contains any contents of the Program. Modified - Works shall not include works that contain only declarations, - interfaces, types, classes, structures, or files of the Program solely - in each case in order to link to, bind by name, or subclass the Program - or Modified Works thereof. - - "Distribute" means the acts of a) distributing or b) making available - in any manner that enables the transfer of a copy. - - "Source Code" means the form of a Program preferred for making - modifications, including but not limited to software source code, - documentation source, and configuration files. - - "Secondary License" means either the GNU General Public License, - Version 2.0, or any later versions of that license, including any - exceptions or additional permissions as identified by the initial - Contributor. - - 2. GRANT OF RIGHTS - - a) Subject to the terms of this Agreement, each Contributor hereby - grants Recipient a non-exclusive, worldwide, royalty-free copyright - license to reproduce, prepare Derivative Works of, publicly display, - publicly perform, Distribute and sublicense the Contribution of such - Contributor, if any, and such Derivative Works. - - b) Subject to the terms of this Agreement, each Contributor hereby - grants Recipient a non-exclusive, worldwide, royalty-free patent - license under Licensed Patents to make, use, sell, offer to sell, - import and otherwise transfer the Contribution of such Contributor, - if any, in Source Code or other form. This patent license shall - apply to the combination of the Contribution and the Program if, at - the time the Contribution is added by the Contributor, such addition - of the Contribution causes such combination to be covered by the - Licensed Patents. The patent license shall not apply to any other - combinations which include the Contribution. No hardware per se is - licensed hereunder. - - c) Recipient understands that although each Contributor grants the - licenses to its Contributions set forth herein, no assurances are - provided by any Contributor that the Program does not infringe the - patent or other intellectual property rights of any other entity. - Each Contributor disclaims any liability to Recipient for claims - brought by any other entity based on infringement of intellectual - property rights or otherwise. As a condition to exercising the - rights and licenses granted hereunder, each Recipient hereby - assumes sole responsibility to secure any other intellectual - property rights needed, if any. For example, if a third party - patent license is required to allow Recipient to Distribute the - Program, it is Recipient's responsibility to acquire that license - before distributing the Program. - - d) Each Contributor represents that to its knowledge it has - sufficient copyright rights in its Contribution, if any, to grant - the copyright license set forth in this Agreement. - - e) Notwithstanding the terms of any Secondary License, no - Contributor makes additional grants to any Recipient (other than - those set forth in this Agreement) as a result of such Recipient's - receipt of the Program under the terms of a Secondary License - (if permitted under the terms of Section 3). - - 3. REQUIREMENTS - - 3.1 If a Contributor Distributes the Program in any form, then: - - a) the Program must also be made available as Source Code, in - accordance with section 3.2, and the Contributor must accompany - the Program with a statement that the Source Code for the Program - is available under this Agreement, and informs Recipients how to - obtain it in a reasonable manner on or through a medium customarily - used for software exchange; and - - b) the Contributor may Distribute the Program under a license - different than this Agreement, provided that such license: - i) effectively disclaims on behalf of all other Contributors all - warranties and conditions, express and implied, including - warranties or conditions of title and non-infringement, and - implied warranties or conditions of merchantability and fitness - for a particular purpose; - - ii) effectively excludes on behalf of all other Contributors all - liability for damages, including direct, indirect, special, - incidental and consequential damages, such as lost profits; - - iii) does not attempt to limit or alter the recipients' rights - in the Source Code under section 3.2; and - - iv) requires any subsequent distribution of the Program by any - party to be under a license that satisfies the requirements - of this section 3. - - 3.2 When the Program is Distributed as Source Code: - - a) it must be made available under this Agreement, or if the - Program (i) is combined with other material in a separate file or - files made available under a Secondary License, and (ii) the initial - Contributor attached to the Source Code the notice described in - Exhibit A of this Agreement, then the Program may be made available - under the terms of such Secondary Licenses, and - - b) a copy of this Agreement must be included with each copy of - the Program. - - 3.3 Contributors may not remove or alter any copyright, patent, - trademark, attribution notices, disclaimers of warranty, or limitations - of liability ("notices") contained within the Program from any copy of - the Program which they Distribute, provided that Contributors may add - their own appropriate notices. - - 4. COMMERCIAL DISTRIBUTION - - Commercial distributors of software may accept certain responsibilities - with respect to end users, business partners and the like. While this - license is intended to facilitate the commercial use of the Program, - the Contributor who includes the Program in a commercial product - offering should do so in a manner which does not create potential - liability for other Contributors. Therefore, if a Contributor includes - the Program in a commercial product offering, such Contributor - ("Commercial Contributor") hereby agrees to defend and indemnify every - other Contributor ("Indemnified Contributor") against any losses, - damages and costs (collectively "Losses") arising from claims, lawsuits - and other legal actions brought by a third party against the Indemnified - Contributor to the extent caused by the acts or omissions of such - Commercial Contributor in connection with its distribution of the Program - in a commercial product offering. The obligations in this section do not - apply to any claims or Losses relating to any actual or alleged - intellectual property infringement. In order to qualify, an Indemnified - Contributor must: a) promptly notify the Commercial Contributor in - writing of such claim, and b) allow the Commercial Contributor to control, - and cooperate with the Commercial Contributor in, the defense and any - related settlement negotiations. The Indemnified Contributor may - participate in any such claim at its own expense. - - For example, a Contributor might include the Program in a commercial - product offering, Product X. That Contributor is then a Commercial - Contributor. If that Commercial Contributor then makes performance - claims, or offers warranties related to Product X, those performance - claims and warranties are such Commercial Contributor's responsibility - alone. Under this section, the Commercial Contributor would have to - defend claims against the other Contributors related to those performance - claims and warranties, and if a court requires any other Contributor to - pay any damages as a result, the Commercial Contributor must pay - those damages. - - 5. NO WARRANTY - - EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, AND TO THE EXTENT - PERMITTED BY APPLICABLE LAW, THE PROGRAM IS PROVIDED ON AN "AS IS" - BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR - IMPLIED INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR CONDITIONS OF - TITLE, NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR - PURPOSE. Each Recipient is solely responsible for determining the - appropriateness of using and distributing the Program and assumes all - risks associated with its exercise of rights under this Agreement, - including but not limited to the risks and costs of program errors, - compliance with applicable laws, damage to or loss of data, programs - or equipment, and unavailability or interruption of operations. - - 6. DISCLAIMER OF LIABILITY - - EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, AND TO THE EXTENT - PERMITTED BY APPLICABLE LAW, NEITHER RECIPIENT NOR ANY CONTRIBUTORS - SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, - EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT LIMITATION LOST - PROFITS), 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 OR DISTRIBUTION OF THE PROGRAM OR THE - EXERCISE OF ANY RIGHTS GRANTED HEREUNDER, EVEN IF ADVISED OF THE - POSSIBILITY OF SUCH DAMAGES. - - 7. GENERAL - - If any provision of this Agreement is invalid or unenforceable under - applicable law, it shall not affect the validity or enforceability of - the remainder of the terms of this Agreement, and without further - action by the parties hereto, such provision shall be reformed to the - minimum extent necessary to make such provision valid and enforceable. - - If Recipient institutes patent litigation against any entity - (including a cross-claim or counterclaim in a lawsuit) alleging that the - Program itself (excluding combinations of the Program with other software - or hardware) infringes such Recipient's patent(s), then such Recipient's - rights granted under Section 2(b) shall terminate as of the date such - litigation is filed. - - All Recipient's rights under this Agreement shall terminate if it - fails to comply with any of the material terms or conditions of this - Agreement and does not cure such failure in a reasonable period of - time after becoming aware of such noncompliance. If all Recipient's - rights under this Agreement terminate, Recipient agrees to cease use - and distribution of the Program as soon as reasonably practicable. - However, Recipient's obligations under this Agreement and any licenses - granted by Recipient relating to the Program shall continue and survive. - - Everyone is permitted to copy and distribute copies of this Agreement, - but in order to avoid inconsistency the Agreement is copyrighted and - may only be modified in the following manner. The Agreement Steward - reserves the right to publish new versions (including revisions) of - this Agreement from time to time. No one other than the Agreement - Steward has the right to modify this Agreement. The Eclipse Foundation - is the initial Agreement Steward. The Eclipse Foundation may assign the - responsibility to serve as the Agreement Steward to a suitable separate - entity. Each new version of the Agreement will be given a distinguishing - version number. The Program (including Contributions) may always be - Distributed subject to the version of the Agreement under which it was - received. In addition, after a new version of the Agreement is published, - Contributor may elect to Distribute the Program (including its - Contributions) under the new version. - - Except as expressly stated in Sections 2(a) and 2(b) above, Recipient - receives no rights or licenses to the intellectual property of any - Contributor under this Agreement, whether expressly, by implication, - estoppel or otherwise. All rights in the Program not expressly granted - under this Agreement are reserved. Nothing in this Agreement is intended - to be enforceable by any entity that is not a Contributor or Recipient. - No third-party beneficiary rights are created under this Agreement. - - Exhibit A - Form of Secondary Licenses Notice - - "This Source Code may also be made available under the following - Secondary Licenses when the conditions for such availability set forth - in the Eclipse Public License, v. 2.0 are satisfied: {name license(s), - version(s), and exceptions or additional permissions here}." - - Simply including a copy of this Agreement, including this Exhibit A - is not sufficient to license the Source Code under Secondary Licenses. - - If it is not possible or desirable to put the notice in a particular - file, then You may include the notice in a location (such as a LICENSE - file in a relevant directory) where a recipient would be likely to - look for such a notice. - - You may add additional accurate notices of copyright ownership. \ No newline at end of file diff --git a/src/main/jbake/assets/README.md b/src/main/jbake/assets/README.md deleted file mode 100644 index cb973256..00000000 --- a/src/main/jbake/assets/README.md +++ /dev/null @@ -1,42 +0,0 @@ -# About this Project - -The {{site.title}} Project is the official site for the -_Jakarta Platform, Enterprise Edition (Jakarta EE) Tutorial_. -The {{site.title}} teaches and demonstrates the Jakarta EE features that -are used to develop enterprise applications. - -[View the Jakarta EE Tutorial](toc.html) - -The latest build of the {{site.title}} is automatically published to -this site as HTML via a Jenkins job that watches for changes to the -master branch of the repository. The tutorial is authored in -[AsciiDoc](http://asciidoc.org/). AsciiDoc is similar to markdown but -is particularly suited for user documentation. If you are interested in -forking the tutorial source files or building the tutorials locally, -then see the [repository](https://github.com/eclipse-ee4j/jakartaee-tutorial). - -# Related Projects - -* [eclipse-ee4j/jakartaee-tutorial-examples](https://github.com/eclipse-ee4j/jakartaee-tutorial-examples): -this repository contains the example code that is used in the {{site.title}}. - -* [Your First Cup: An Introduction to the Jakarta EE Platform](https://eclipse-ee4j.github.io/jakartaee-firstcup/): -an introductory tutorial suitable for beginners. - -* [eclipse-ee4j/firstcup-examples](https://github.com/eclipse-ee4j/jakartaee-firstcup-examples): -this repository contains the example code that is used in the Your -First Cup tutorial. - -# How To Contribute -The easiest way to contribute is by opening an -[issue](https://github.com/eclipse-ee4j/jakartaee-tutorial/issues) -that contains feedback and review comments. - -The {{site.title}} is 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) -* [Pull Request Acceptance Workflow](pr_doc_workflow) -* [License](LICENSE) diff --git a/src/main/jbake/assets/_config.yml b/src/main/jbake/assets/_config.yml deleted file mode 100644 index 58d41679..00000000 --- a/src/main/jbake/assets/_config.yml +++ /dev/null @@ -1,17 +0,0 @@ -remote_theme: jakartaee/jekyll-theme-jakarta-ee - -title: [Jakarta EE Tutorial] -description: [Jakarta EE Tutorial Project] - -# sidebar links url -links: - source: https://github.com/eclipse-ee4j/jakartaee-tutorial - download: https://github.com/eclipse-ee4j/jakartaee-tutorial/releases - mailinglist: https://accounts.eclipse.org/mailing-list/jakartaee-platform-dev - #javadocs: - docs: toc.html - #faq: - -include: - - LICENSE.md - - CONTRIBUTING.md diff --git a/src/main/jbake/assets/css/style.css b/src/main/jbake/assets/css/style.css deleted file mode 100644 index ae901110..00000000 --- a/src/main/jbake/assets/css/style.css +++ /dev/null @@ -1,312 +0,0 @@ -/* CSS */ -/*! normalize.css v3.0.2 | MIT License | git.io/normalize */ -/** 1. Set default font family to sans-serif. 2. Prevent iOS text size adjust after orientation change, without disabling user zoom. */ -html { font-family: sans-serif; /* 1 */ -ms-text-size-adjust: 100%; /* 2 */ -webkit-text-size-adjust: 100%; /* 2 */ } - -/* HTML5 display definitions ========================================================================== */ -/** Correct `block` display not defined for any HTML5 element in IE 8/9. Correct `block` display not defined for `details` or `summary` in IE 10/11 and Firefox. Correct `block` display not defined for `main` in IE 11. */ -article, aside, details, figcaption, figure, footer, header, hgroup, main, menu, nav, section, summary { display: block; } - -/** 1. Correct `inline-block` display not defined in IE 8/9. 2. Normalize vertical alignment of `progress` in Chrome, Firefox, and Opera. */ -audio, canvas, progress, video { display: inline-block; /* 1 */ vertical-align: baseline; /* 2 */ } - -/** Prevent modern browsers from displaying `audio` without controls. Remove excess height in iOS 5 devices. */ -audio:not([controls]) { display: none; height: 0; } - -/** Address `[hidden]` styling not present in IE 8/9/10. Hide the `template` element in IE 8/9/11, Safari, and Firefox < 22. */ -[hidden], template { display: none; } - -/* Links ========================================================================== */ -/** Remove the gray background color from active links in IE 10. */ -a { background-color: transparent; } - -/** Improve readability when focused and also mouse hovered in all browsers. */ -a:active, a:hover { outline: 0; } - -/* Text-level semantics ========================================================================== */ -/** Address styling not present in IE 8/9/10/11, Safari, and Chrome. */ -abbr[title] { border-bottom: 1px dotted; } - -/** Address style set to `bolder` in Firefox 4+, Safari, and Chrome. */ -b, strong { font-weight: bold; } - -/** Address styling not present in Safari and Chrome. */ -dfn { font-style: italic; } - -/** Address variable `h1` font-size and margin within `section` and `article` contexts in Firefox 4+, Safari, and Chrome. */ -h1 { font-size: 2em; margin: 0.67em 0; } - -/** Address styling not present in IE 8/9. */ -mark { background: #ff0; color: #000; } - -/** Address inconsistent and variable font size in all browsers. */ -small { font-size: 80%; } - -/** Prevent `sub` and `sup` affecting `line-height` in all browsers. */ -sub, sup { font-size: 75%; line-height: 0; position: relative; vertical-align: baseline; } - -sup { top: -0.5em; } - -sub { bottom: -0.25em; } - -/* Embedded content ========================================================================== */ -/** Remove border when inside `a` element in IE 8/9/10. */ -img { border: 0; } - -/** Correct overflow not hidden in IE 9/10/11. */ -svg:not(:root) { overflow: hidden; } - -/* Grouping content ========================================================================== */ -/** Address margin not present in IE 8/9 and Safari. */ -figure { margin: 1em 40px; } - -/** Address differences between Firefox and other browsers. */ -hr { box-sizing: content-box; height: 0; } - -/** Contain overflow in all browsers. */ -pre { overflow: auto; } - -/** Address odd `em`-unit font size rendering in all browsers. */ -code, kbd, pre, samp { font-family: monospace, monospace; font-size: 1em; } - -/* Forms ========================================================================== */ -/** Known limitation: by default, Chrome and Safari on OS X allow very limited styling of `select`, unless a `border` property is set. */ -/** 1. Correct color not being inherited. Known issue: affects color of disabled elements. 2. Correct font properties not being inherited. 3. Address margins set differently in Firefox 4+, Safari, and Chrome. */ -button, input, optgroup, select, textarea { color: inherit; /* 1 */ font: inherit; /* 2 */ margin: 0; /* 3 */ } - -/** Address `overflow` set to `hidden` in IE 8/9/10/11. */ -button { overflow: visible; } - -/** Address inconsistent `text-transform` inheritance for `button` and `select`. All other form control elements do not inherit `text-transform` values. Correct `button` style inheritance in Firefox, IE 8/9/10/11, and Opera. Correct `select` style inheritance in Firefox. */ -button, select { text-transform: none; } - -/** 1. Avoid the WebKit bug in Android 4.0.* where (2) destroys native `audio` and `video` controls. 2. Correct inability to style clickable `input` types in iOS. 3. Improve usability and consistency of cursor style between image-type `input` and others. */ -button, html input[type="button"], input[type="reset"], input[type="submit"] { -webkit-appearance: button; /* 2 */ cursor: pointer; /* 3 */ } - -/** Re-set default cursor for disabled elements. */ -button[disabled], html input[disabled] { cursor: default; } - -/** Remove inner padding and border in Firefox 4+. */ -button::-moz-focus-inner, input::-moz-focus-inner { border: 0; padding: 0; } - -/** Address Firefox 4+ setting `line-height` on `input` using `!important` in the UA stylesheet. */ -input { line-height: normal; } - -/** It's recommended that you don't attempt to style these elements. Firefox's implementation doesn't respect box-sizing, padding, or width. 1. Address box sizing set to `content-box` in IE 8/9/10. 2. Remove excess padding in IE 8/9/10. */ -input[type="checkbox"], input[type="radio"] { box-sizing: border-box; /* 1 */ padding: 0; /* 2 */ } - -/** Fix the cursor style for Chrome's increment/decrement buttons. For certain `font-size` values of the `input`, it causes the cursor style of the decrement button to change from `default` to `text`. */ -input[type="number"]::-webkit-inner-spin-button, input[type="number"]::-webkit-outer-spin-button { height: auto; } - -/** 1. Address `appearance` set to `searchfield` in Safari and Chrome. 2. Address `box-sizing` set to `border-box` in Safari and Chrome (include `-moz` to future-proof). */ -input[type="search"] { -webkit-appearance: textfield; /* 1 */ /* 2 */ box-sizing: content-box; } - -/** Remove inner padding and search cancel button in Safari and Chrome on OS X. Safari (but not Chrome) clips the cancel button when the search input has padding (and `textfield` appearance). */ -input[type="search"]::-webkit-search-cancel-button, input[type="search"]::-webkit-search-decoration { -webkit-appearance: none; } - -/** Define consistent border, margin, and padding. */ -fieldset { border: 1px solid #c0c0c0; margin: 0 2px; padding: 0.35em 0.625em 0.75em; } - -/** 1. Correct `color` not being inherited in IE 8/9/10/11. 2. Remove padding so people aren't caught out if they zero out fieldsets. */ -legend { border: 0; /* 1 */ padding: 0; /* 2 */ } - -/** Remove default vertical scrollbar in IE 8/9/10/11. */ -textarea { overflow: auto; } - -/** Don't inherit the `font-weight` (applied by a rule above). NOTE: the default cannot safely be changed in Chrome and Safari on OS X. */ -optgroup { font-weight: bold; } - -/* Tables ========================================================================== */ -/** Remove most spacing between table cells. */ -table { border-collapse: collapse; border-spacing: 0; } - -td, th { padding: 0; } - -/* LAYOUT STYLES */ - -p { margin-top: 0; } - -code, pre { margin-bottom: 30px; font-family: Monaco, "Bitstream Vera Sans Mono", "Lucida Console", Terminal, monospace; font-size: 13px; color: #222; } - -code { padding: 0 3px; background-color: #f2f8fc; border: solid 1px #dbe7f3; } - -pre { padding: 20px; overflow: auto; text-shadow: none; background: #fff; border: solid 1px #f2f2f2; } - -pre code { padding: 0; color: #2879d0; background-color: #fff; border: none; } - -ul, ol, dl { margin-bottom: 20px; } - -/* COMMON STYLES */ - -td.halign-right { text-align: right; } - -td.halign-center { text-align: center; } - -form { padding: 20px; background: #f2f2f2; } - -h2 { - font-size: 2em; - line-height: 1.2em; - font-weight: 200; - letter-spacing: 0; -} - -h3 { - font-size: 1.4em; - line-height: 1.2em; - font-weight: normal; - letter-spacing: 0; -} - -.sect1 { - margin-left: 4%; - margin-right: 4%; - font: 13px/20px Arial, Helvetica, sans-serif -} - -a:link { - text-decoration: none; - color: #09569d; -} - -#preamble hr{ - margin-left: 0%; - margin-right: 0%; -} - -#preamble .sectionbody table { - font-weight: 200; - margin-left: 4%; - margin-right: 4%; -} - -hr { - margin-bottom: 12px; -} - -table.tableblock.frame-all.grid-all.spread { - font-size: 12px; -} - -code { - font-size:.9em; - border: 1px solid #eaeaea; - background-color: #f6f6f6; - border-radius: 3px; - padding: 1px; - padding-left:2px; - padding-right:2px; -} - -pre.prettyprint.highlight { - border: 1px solid #eaeaea; - background-color: #f6f6f6; - border-radius: 4px; - padding: 8px; - padding-top:4px; - padding-bottom:4px; -} - -.language-oac_no_warn { - font-size:.9em; - color:#222; - background-color: transparent; -} - -#doc-title { - margin-left: 4%; -} - -#top-nav { - margin-left: 4%; - font-size: 12px; -} - -#bottom-nav { - margin-left: 4%; - font-size: 12px; -} - -.vector-font { - color:grey; - font-size: 20px; -} - -#copyright { - padding-top: 10px; - padding-bottom: 4px; - display: table; - margin:0 auto; - color: grey; - font-size: 12px; -} - -.beta {color: #FF0000} - -/* GENERAL ELEMENT TYPE STYLES */ - -/* #Media Queries -================================================== */ -/* Smaller than standard 960 (devices and browsers) */ -/* Tablet Portrait size to standard 960 (devices and browsers) */ -@media only screen and (min-width: 768px) and (max-width: 959px) { .inner { width: 740px; } - header h1, header h2 { width: 340px; } - header h1 { font-size: 60px; } - header h2 { font-size: 30px; } -} -/* All Mobile Sizes (devices and browser) */ -@media only screen and (max-width: 767px) { .inner { width: 93%; } - header { padding: 20px 0; } - header .inner { position: relative; } - header h1, header h2 { width: 100%; } - header h1 { font-size: 48px; } - header h2 { font-size: 24px; } - header a.button { position: relative; display: inline-block; width: auto; height: auto; padding: 5px 10px; margin-top: 15px; font-size: 13px; line-height: 1; color: #2879d0; text-align: center; background-color: #9ddcff; background-image: none; border-radius: 5px; -moz-border-radius: 5px; -webkit-border-radius: 5px; } - header a.button small { display: inline; font-size: 13px; } -} -/* Mobile Landscape Size to Tablet Portrait (devices and browsers) */ -/* Mobile Portrait Size to Mobile Landscape Size (devices and browsers) */ - -header h1 { padding-top: 14px; font-size: 2em; font-weight: 200; line-height: 1.4; color: #FFFFFF; letter-spacing: 0px; border-bottom: 0px; } - -header h2 { font-size: 1.2em; margin-top: 0; margin-bottom: 0; font-weight: 200; line-height: .8; color: #ec7D11; letter-spacing: 0; } - -header a.button { background: transparent url(../images/logo.png) 0 0 no-repeat; padding-left: 32px; } - -header a:hover { text-decoration: none; } - -/* Admonition (Note) block */ -.admonitionblock > table { - border: 0; - background: none; - width: 100%; - table-layout: auto; - margin-bottom: 10.5px; -} -.admonitionblock > table td.icon { - text-align: center; - width: 60px; -} -.admonitionblock > table td.icon img { - max-width: none; -} -.admonitionblock > table td.icon .title { - text-transform: uppercase; -} -.admonitionblock > table td.content { - padding-left: 1em; - padding-right: 1em; - border-left: 3px solid #ddd; -} -.admonitionblock > table td.content > :last-child > :last-child { - margin-bottom: 0; -} -.admonitionblock td.icon [class^="fa icon-"]:before { - font-size: 2.5em; - text-shadow: 1px 1px 2px rgba(0, 0, 0, 0.5); - cursor: default; -} -.admonitionblock td.icon .icon-note:before { - content: "\f05a"; - color: #5bc0de; -} \ No newline at end of file diff --git a/src/main/jbake/assets/pr_doc_workflow.md b/src/main/jbake/assets/pr_doc_workflow.md deleted file mode 100644 index a36ba3a2..00000000 --- a/src/main/jbake/assets/pr_doc_workflow.md +++ /dev/null @@ -1,56 +0,0 @@ -# Documentation Pull Request Acceptance Workflow - -## One Time Setup -* [Fork](https://help.github.com/articles/fork-a-repo/) the -[tutorial](https://github.com/eclipse-ee4j/jakartaee-tutorial/) repository. -* [Clone](https://help.github.com/articles/cloning-a-repository/) -your forked repository. -``` -$ git clone https://github.com/YOUR-USERNAME/jakartaee-tutorial.git -``` -* [Configure](https://help.github.com/articles/configuring-a-remote-for-a-fork/) -the remote for your fork. -``` -$ git remote add upstream https://github.com/eclipse-ee4j/jakartaee-tutorial.git -$ git remote -v -origin https://github.com/YOUR-USERNAME/jakartaee-tutorial.git (fetch) -origin https://github.com/YOUR-USERNAME/jakartaee-tutorial.git (push) -upstream https://github.com/eclipse-ee4j/jakartaee-tutorial.git (fetch) -upstream https://github.com/eclipse-ee4j/jakartaee-tutorial.git (push) -``` -## Raising a Pull Request -* Sync the master of your fork with upstream master. -``` -$ git fetch upstream -$ git checkout master -$ git merge upstream/master -$ git push origin master # push local master to github fork. -``` -* Create a local topic branch in your fork from your master. -``` -$ git checkout -b doc_update -``` -* Do the development in your branch. -* Commit all the changes. -``` -$ git add src/main/jbake/content/my.adoc -$ git commit -m "my commit message" -``` -* Push your changes in a remote branch of your fork. -``` -$ git push origin doc_update -``` -* Before raising a Pull Request, please raise an -[issue](https://github.com/eclipse-ee4j/jakartaee-tutorial/issues) -if it doesn't exist. We would like every Pull Request to be associated -with an issue. Submit the Pull Request referring to the issue number. -* Raise a [Pull Request](https://github.com/eclipse-ee4j/jakartaee-tutorial/pulls). -* Make sure you put a proper 'title' for the Pull Request. The title of -the Pull Request would become the commit message. Instead of giving -'title' like "Iss xxxx" or "Fixes #xxxxx", consider giving a proper one -line 'title' for the Pull Request like "Fixes xxx : " -* In the Pull Request description (body), please mention "Fixes #xxxxx" -in order to link the Pull Request with the Issue you are fixing. -* If you have signed the [ECA](https://www.eclipse.org/legal/ECA.php), -one of the project team members will review your Pull Request. diff --git a/src/main/jbake/content/batch-processing.adoc b/src/main/jbake/content/batch-processing.adoc deleted file mode 100644 index 67f07977..00000000 --- a/src/main/jbake/content/batch-processing.adoc +++ /dev/null @@ -1,39 +0,0 @@ -type=page -status=published -title=Batch Processing -next=batch-processing001.html -prev=interceptors003.html -~~~~~~ -Batch Processing -================ - -[[GKJIQ6]][[batch-processing]] - -59 Batch Processing -------------------- - - -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. The batch framework is composed of a job specification -language based on XML, a Java API, and a batch runtime. - -The following topics are addressed here: - -* link:batch-processing001.html#BCGJDEEH[Introduction to Batch -Processing] -* link:batch-processing002.html#BCGGIBHA[Batch Processing in Jakarta EE] -* link:batch-processing003.html#BCGHBJIG[Simple Use Case] -* link:batch-processing004.html#BCGDDBBG[Using the Job Specification -Language] -* link:batch-processing005.html#BCGHDHGH[Creating Batch Artifacts] -* link:batch-processing006.html#BCGCAHCB[Submitting Jobs to the Batch -Runtime] -* link:batch-processing007.html#BCGBBGJI[Packaging Batch Applications] -* link:batch-processing008.html#BCGJHEHJ[The webserverlog Example -Application] -* link:batch-processing009.html#BCGFCACD[The phonebilling Example -Application] -* link:batch-processing010.html#BCGHCHAJ[Further Information about Batch -Processing] diff --git a/src/main/jbake/content/batch-processing010.adoc b/src/main/jbake/content/batch-processing010.adoc deleted file mode 100644 index 37ea5126..00000000 --- a/src/main/jbake/content/batch-processing010.adoc +++ /dev/null @@ -1,19 +0,0 @@ -type=page -status=published -title=Further Information about Batch Processing -next=concurrency-utilities.html -prev=batch-processing009.html -~~~~~~ -Further Information about Batch Processing -========================================== - -[[BCGHCHAJ]][[further-information-about-batch-processing]] - -Further Information about Batch Processing ------------------------------------------- - -For more information on batch processing in Jakarta EE, see Jakarta Batch: - -`https://jakarta.ee/specifications/batch/1.0/` - - diff --git a/src/main/jbake/content/bean-validation-advanced.adoc b/src/main/jbake/content/bean-validation-advanced.adoc deleted file mode 100644 index 481662c6..00000000 --- a/src/main/jbake/content/bean-validation-advanced.adoc +++ /dev/null @@ -1,28 +0,0 @@ -type=page -status=published -title=Bean Validation: Advanced Topics -next=bean-validation-advanced001.html -prev=bean-validation005.html -~~~~~~ -Bean Validation: Advanced Topics -================================ - -[[GKAHP]][[bean-validation-advanced-topics]] - -24 Bean Validation: Advanced Topics ------------------------------------ - - -This chapter describes how to create custom constraints, custom -validator messages, and constraint groups using the Java API for -JavaBeans Validation (Bean Validation). - -The following topics are addressed here: - -* link:bean-validation-advanced001.html#GKFGX[Creating Custom -Constraints] -* link:bean-validation-advanced002.html#GKAHI[Customizing Validator -Messages] -* link:bean-validation-advanced003.html#GKAGV[Grouping Constraints] -* link:bean-validation-advanced004.html#CIHGJBGI[Using Method Constraints -in Type Hierarchies] diff --git a/src/main/jbake/content/bean-validation.adoc b/src/main/jbake/content/bean-validation.adoc deleted file mode 100644 index fb04ac60..00000000 --- a/src/main/jbake/content/bean-validation.adoc +++ /dev/null @@ -1,27 +0,0 @@ -type=page -status=published -title=Introduction to Jakarta Bean Validation -next=bean-validation001.html -prev=partbeanvalidation.html -~~~~~~ -= Introduction to Jakarta Bean Validation - - -[[CHDGJIIA]][[introduction-to-bean-validation]] - -23 Introduction to Jakarta Bean Validation ------------------------------------------- - - -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. - -The following topics are addressed here: - -* link:bean-validation001.html#A1101988[Overview of Jakarta Bean Validation] -* link:bean-validation002.html#GIRCZ[Using Jakarta Bean Validation Constraints] -* link:bean-validation003.html#GKCRG[Validating Null and Empty Strings] -* link:bean-validation004.html#CACJIBEJ[Validating Constructors and -Methods] -* link:bean-validation005.html#CACDECFE[Further Information about Jakarta Bean -Validation] diff --git a/src/main/jbake/content/bean-validation005.adoc b/src/main/jbake/content/bean-validation005.adoc deleted file mode 100644 index e269439f..00000000 --- a/src/main/jbake/content/bean-validation005.adoc +++ /dev/null @@ -1,22 +0,0 @@ -type=page -status=published -title=Further Information about Jakarta Bean Validation -next=bean-validation-advanced.html -prev=bean-validation004.html -~~~~~~ -Further Information about Jakarta Bean Validation -================================================= - -[[CACDECFE]][[further-information-about-bean-validation]] - -Further Information about Jakarta Bean Validation -------------------------------------------------- - -For more information on Jakarta Bean Validation, see - -* Jakarta Bean Validation 2.0 Specification: -+ -`https://jakarta.ee/specifications/bean-validation/2.0/` -* Bean Validation Specification website: -+ -`http://beanvalidation.org/` diff --git a/src/main/jbake/content/cdi-adv-examples.adoc b/src/main/jbake/content/cdi-adv-examples.adoc deleted file mode 100644 index 289325ea..00000000 --- a/src/main/jbake/content/cdi-adv-examples.adoc +++ /dev/null @@ -1,32 +0,0 @@ -type=page -status=published -title=Running the Advanced Contexts and Dependency Injection Examples -next=cdi-adv-examples001.html -prev=cdi-bootstrap-se8002.html -~~~~~~ -= Running the Advanced Contexts and Dependency Injection Examples - - -[[GKHRE]][[running-the-advanced-contexts-and-dependency-injection-examples]] - -29 Running the Advanced Contexts and Dependency Injection Examples ------------------------------------------------------------------- - - -This chapter describes in detail how to build and run several advanced -examples that use CDI. - -The following topics are addressed here: - -* link:cdi-adv-examples001.html#A1251406[Building and Running the CDI -Advanced Examples] -* link:cdi-adv-examples002.html#GKHPU[The encoder Example: Using -Alternatives] -* link:cdi-adv-examples003.html#GKHPY[The producermethods Example: Using -a Producer Method to Choose a Bean Implementation] -* link:cdi-adv-examples004.html#GKHRG[The producerfields Example: Using -Producer Fields to Generate Resources] -* link:cdi-adv-examples005.html#GKHPA[The billpayment Example: Using -Events and Interceptors] -* link:cdi-adv-examples006.html#GKPAX[The decorators Example: Decorating -a Bean] diff --git a/src/main/jbake/content/cdi-adv-examples001.adoc b/src/main/jbake/content/cdi-adv-examples001.adoc deleted file mode 100644 index 98e29682..00000000 --- a/src/main/jbake/content/cdi-adv-examples001.adoc +++ /dev/null @@ -1,37 +0,0 @@ -type=page -status=published -title=Building and Running the CDI Advanced Examples -next=cdi-adv-examples002.html -prev=cdi-adv-examples.html -~~~~~~ -= Building and Running the CDI Advanced Examples - - -[[A1251406]][[building-and-running-the-cdi-advanced-examples]] - -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. - -1. Use NetBeans IDE or the Maven tool to compile, package, and deploy -the example. -2. Run the example in a web browser. - -See link:usingexamples.html#GFIUD[Chapter 2, "Using the Tutorial -Examples"], for basic information on installing, building, and running -the examples. - -The following topics are addressed here: - -* link:cdi-adv-examples002.html#GKHPU[The encoder Example: Using -Alternatives] -* link:cdi-adv-examples003.html#GKHPY[The producermethods Example: Using -a Producer Method to Choose a Bean Implementation] -* link:cdi-adv-examples004.html#GKHRG[The producerfields Example: Using -Producer Fields to Generate Resources] -* link:cdi-adv-examples005.html#GKHPA[The billpayment Example: Using -Events and Interceptors] -* link:cdi-adv-examples006.html#GKPAX[The decorators Example: Decorating -a Bean] diff --git a/src/main/jbake/content/cdi-adv.adoc b/src/main/jbake/content/cdi-adv.adoc deleted file mode 100644 index 42cb8591..00000000 --- a/src/main/jbake/content/cdi-adv.adoc +++ /dev/null @@ -1,35 +0,0 @@ -type=page -status=published -title=Jakarta Contexts and Dependency Injection: Advanced Topics -next=cdi-adv001.html -prev=cdi-basicexamples003.html -~~~~~~ -= Jakarta Contexts and Dependency Injection: Advanced Topics - - -[[GJEHI]][[contexts-and-dependency-injection-for-jakarta-ee-advanced-topics]] - -27 Jakarta Contexts and Dependency Injection: Advanced Topics -------------------------------------------------------------- - - -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 link:cdi-basic002.html#GIWHL[Overview -of CDI]. - -The following topics are addressed here: - -* link:cdi-adv001.html#CACDCFDE[Packaging CDI Applications] -* link:cdi-adv002.html#GJSDF[Using Alternatives in CDI Applications] -* link:cdi-adv003.html#GKGKV[Using Producer Methods, Producer Fields, and -Disposer Methods in CDI Applications] -* link:cdi-adv004.html#CJGHGDBA[Using Predefined Beans in CDI -Applications] -* link:cdi-adv005.html#GKHIC[Using Events in CDI Applications] -* link:cdi-adv006.html#GKHJX[Using Interceptors in CDI Applications] -* link:cdi-adv007.html#GKHQF[Using Decorators in CDI Applications] -* link:cdi-adv008.html#GKHQC[Using Stereotypes in CDI Applications] -* link:cdi-adv009.html#using-the-built-in-annotation-literals[Using the Built-In Annotation Literals] -* link:cdi-adv010.html#using-the-configurators-interfaces[Using the Configurators Interfaces] diff --git a/src/main/jbake/content/cdi-basic.adoc b/src/main/jbake/content/cdi-basic.adoc deleted file mode 100644 index 9ac1e9e3..00000000 --- a/src/main/jbake/content/cdi-basic.adoc +++ /dev/null @@ -1,39 +0,0 @@ -type=page -status=published -title=Introduction to Jakarta Contexts and Dependency Injection -next=cdi-basic001.html -prev=partcdi.html -~~~~~~ -= Introduction to Jakarta Contexts and Dependency Injection - - -[[GIWHB]][[introduction-to-contexts-and-dependency-injection-for-jakarta-ee]] - -25 Introduction to Jakarta Contexts and Dependency Injection ------------------------------------------------------------- - - -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. - -The following topics are addressed here: - -* link:cdi-basic001.html#BABJDJGA[Getting Started] -* link:cdi-basic002.html#GIWHL[Overview of CDI] -* link:cdi-basic003.html#GJEBJ[About Beans] -* link:cdi-basic004.html#GJFZI[About CDI Managed Beans] -* link:cdi-basic005.html#GIZKS[Beans as Injectable Objects] -* link:cdi-basic006.html#GJBCK[Using Qualifiers] -* link:cdi-basic007.html#GJBAN[Injecting Beans] -* link:cdi-basic008.html#GJBBK[Using Scopes] -* link:cdi-basic009.html#GJBAK[Giving Beans EL Names] -* link:cdi-basic010.html#GJBBP[Adding Setter and Getter Methods] -* link:cdi-basic011.html#GJBBU[Using a Managed Bean in a Facelets Page] -* link:cdi-basic012.html#GJDID[Injecting Objects by Using Producer -Methods] -* link:cdi-basic013.html#GJBNZ[Configuring a CDI Application] -* link:cdi-basic014.html#BABJFEAI[Using the @PostConstruct and -@PreDestroy Annotations with CDI Managed Bean Classes] -* link:cdi-basic015.html#GIWEL[Further Information about CDI] diff --git a/src/main/jbake/content/cdi-basicexamples.adoc b/src/main/jbake/content/cdi-basicexamples.adoc deleted file mode 100644 index 9b9d5a57..00000000 --- a/src/main/jbake/content/cdi-basicexamples.adoc +++ /dev/null @@ -1,24 +0,0 @@ -type=page -status=published -title=Running the Basic Contexts and Dependency Injection Examples -next=cdi-basicexamples001.html -prev=cdi-basic015.html -~~~~~~ -= Running the Basic Contexts and Dependency Injection Examples - - -[[GJBLS]][[running-the-basic-contexts-and-dependency-injection-examples]] - -26 Running the Basic Contexts and Dependency Injection Examples ---------------------------------------------------------------- - - -This chapter describes in detail how to build and run simple examples -that use CDI. - -The following topics are addressed here: - -* link:cdi-basicexamples001.html#A1250045[Building and Running the CDI -Samples] -* link:cdi-basicexamples002.html#GJBJU[The simplegreeting CDI Example] -* link:cdi-basicexamples003.html#GJCXV[The guessnumber-cdi CDI Example] diff --git a/src/main/jbake/content/cdi-basicexamples001.adoc b/src/main/jbake/content/cdi-basicexamples001.adoc deleted file mode 100644 index 6ff336e7..00000000 --- a/src/main/jbake/content/cdi-basicexamples001.adoc +++ /dev/null @@ -1,31 +0,0 @@ -type=page -status=published -title=Building and Running the CDI Samples -next=cdi-basicexamples002.html -prev=cdi-basicexamples.html -~~~~~~ -= Building and Running the CDI Samples - - -[[A1250045]][[building-and-running-the-cdi-samples]] - -Building and Running the CDI Samples ------------------------------------- - -The examples are in the `_tut-install_/examples/cdi/` directory. - -To build and run the examples, you will do the following: - -1. Use NetBeans IDE or the Maven tool to compile and package the -example. -2. Use NetBeans IDE or the Maven tool to deploy the example. -3. Run the example in a web browser. - -See link:usingexamples.html#GFIUD[Chapter 2, "Using the Tutorial -Examples"], for basic information on installing, building, and running -the examples. - -The following topics are addressed here: - -* link:cdi-basicexamples002.html#GJBJU[The simplegreeting CDI Example] -* link:cdi-basicexamples003.html#GJCXV[The guessnumber-cdi CDI Example] diff --git a/src/main/jbake/content/concurrency-utilities.adoc b/src/main/jbake/content/concurrency-utilities.adoc deleted file mode 100644 index c259c3e4..00000000 --- a/src/main/jbake/content/concurrency-utilities.adoc +++ /dev/null @@ -1,31 +0,0 @@ -type=page -status=published -title=Jakarta Concurrency -next=concurrency-utilities001.html -prev=batch-processing010.html -~~~~~~ -= Jakarta Concurrency - - -[[GKJIQ8]][[concurrency-utilities-for-jakarta-ee]] - -60 Jakarta Concurrency ---------------------------------------- - - -This chapter describes Jakarta Concurrency spec. - -This chapter covers the following topics: - -* link:concurrency-utilities001.html#CIHDFGGG[Concurrency Basics] -* link:concurrency-utilities002.html#CIHFBCFH[Main Components of the -Concurrency Utilities] -* link:concurrency-utilities003.html#CIHIDBDG[Concurrency and -Transactions] -* link:concurrency-utilities004.html#CIHCACAA[Concurrency and Security] -* link:concurrency-utilities005.html#CIHCGGEG[The jobs Concurrency -Example] -* link:concurrency-utilities006.html#CIHBFEAE[The taskcreator Concurrency -Example] -* link:concurrency-utilities007.html#CHDBIHAA[Further Information about -Jakarta Concurrency] diff --git a/src/main/jbake/content/connectorexample.adoc b/src/main/jbake/content/connectorexample.adoc deleted file mode 100644 index 49dcd2ba..00000000 --- a/src/main/jbake/content/connectorexample.adoc +++ /dev/null @@ -1,25 +0,0 @@ -type=page -status=published -title=The Resource Adapter Examples -next=connectorexample001.html -prev=resources005.html -~~~~~~ -The Resource Adapter Examples -============================= - -[[GLODB]][[the-resource-adapter-examples]] - -57 The Resource Adapter Examples --------------------------------- - - -This chapter describes two examples that demonstrate how to use resource -adapters in Jakarta EE applications and how to implement simple resource -adapters. - -The following topics are addressed here: - -* link:connectorexample001.html#A1253757[Overview of the Resource Adapter -Examples] -* link:connectorexample002.html#CHDFHAID[The trading Example] -* link:connectorexample003.html#CHDJEADB[The traffic Example] diff --git a/src/main/jbake/content/dukes-bookstore.adoc b/src/main/jbake/content/dukes-bookstore.adoc deleted file mode 100644 index 54f1b7a0..00000000 --- a/src/main/jbake/content/dukes-bookstore.adoc +++ /dev/null @@ -1,29 +0,0 @@ -type=page -status=published -title=Duke's Bookstore Case Study Example -next=dukes-bookstore001.html -prev=partcasestudies.html -~~~~~~ -Duke's Bookstore Case Study Example -=================================== - -[[GLNVI]][[dukes-bookstore-case-study-example]] - -61 Duke's Bookstore Case Study Example --------------------------------------- - - -The Duke's Bookstore example is a simple e-commerce application that -illustrates some of the more advanced features of Jakarta Server 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. - -The following topics are addressed here: - -* link:dukes-bookstore001.html#GLOAW[Design and Architecture of Duke's -Bookstore] -* link:dukes-bookstore002.html#GLQFD[The Duke's Bookstore Interface] -* link:dukes-bookstore003.html#GLPPQ[Running the Duke's Bookstore Case -Study Application] diff --git a/src/main/jbake/content/dukes-forest.adoc b/src/main/jbake/content/dukes-forest.adoc deleted file mode 100644 index 9b1b50f1..00000000 --- a/src/main/jbake/content/dukes-forest.adoc +++ /dev/null @@ -1,28 +0,0 @@ -type=page -status=published -title=Duke's Forest Case Study Example -next=dukes-forest001.html -prev=dukes-tutoring004.html -~~~~~~ -Duke's Forest Case Study Example -================================ - -[[GLNPW]][[dukes-forest-case-study-example]] - -63 Duke's Forest Case Study Example ------------------------------------ - - -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. - -The following topics are addressed here: - -* link:dukes-forest001.html#A1256074[Overview of the Duke's Forest Case -Study Example] -* link:dukes-forest002.html#GLNRJ[Design and Architecture of Duke's -Forest] -* link:dukes-forest003.html#GLNQP[Building and Deploying the Duke's -Forest Case Study Application] -* link:dukes-forest004.html#GLNSX[Running the Duke's Forest Application] diff --git a/src/main/jbake/content/dukes-tutoring.adoc b/src/main/jbake/content/dukes-tutoring.adoc deleted file mode 100644 index e13ebdd8..00000000 --- a/src/main/jbake/content/dukes-tutoring.adoc +++ /dev/null @@ -1,29 +0,0 @@ -type=page -status=published -title=Duke's Tutoring Case Study Example -next=dukes-tutoring001.html -prev=dukes-bookstore003.html -~~~~~~ -Duke's Tutoring Case Study Example -================================== - -[[GKAEE]][[dukes-tutoring-case-study-example]] - -62 Duke's Tutoring Case Study Example -------------------------------------- - - -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. -Administrators can maintain the tutoring center system. - -The following topics are addressed here: - -* link:dukes-tutoring001.html#GKAEI[Design and Architecture of Duke's -Tutoring] -* link:dukes-tutoring002.html#GKAFH[Main Interface] -* link:dukes-tutoring003.html#GKAFW[Administration Interface] -* link:dukes-tutoring004.html#GKJNN[Running the Duke's Tutoring Case -Study Application] diff --git a/src/main/jbake/content/ejb-async.adoc b/src/main/jbake/content/ejb-async.adoc deleted file mode 100644 index a82e0aaa..00000000 --- a/src/main/jbake/content/ejb-async.adoc +++ /dev/null @@ -1,21 +0,0 @@ -type=page -status=published -title=Using Asynchronous Method Invocation in Session Beans -next=ejb-async001.html -prev=ejb-embedded003.html -~~~~~~ -Using Asynchronous Method Invocation in Session Beans -===================================================== - -[[GKIDZ]][[using-asynchronous-method-invocation-in-session-beans]] -39 Using Asynchronous Method Invocation in Session Beans --------------------------------------------------------- - - -This chapter discusses how to implement asynchronous business methods in -session beans and call them from enterprise bean clients. - -The following topics are addressed here: - -* link:ejb-async001.html#GKKQG[Asynchronous Method Invocation] -* link:ejb-async002.html#GKIEZ[The async Example Application] diff --git a/src/main/jbake/content/ejb-basicexamples.adoc b/src/main/jbake/content/ejb-basicexamples.adoc deleted file mode 100644 index 27782714..00000000 --- a/src/main/jbake/content/ejb-basicexamples.adoc +++ /dev/null @@ -1,30 +0,0 @@ -type=page -status=published -title=Running the Enterprise Bean Examples -next=ejb-basicexamples001.html -prev=ejb-gettingstarted003.html -~~~~~~ -Running the Enterprise Bean Examples -==================================== - -[[GIJRB]][[running-the-enterprise-bean-examples]] - -37 Running the Enterprise Bean Examples ---------------------------------------- - - -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. - -The following topics are addressed here: - -* link:ejb-basicexamples001.html#A1250776[Overview of the Jakarta Enterprise Beans Examples] -* link:ejb-basicexamples002.html#BNBOD[The cart Example] -* link:ejb-basicexamples003.html#GIPVI[A Singleton Session Bean Example: -counter] -* link:ejb-basicexamples004.html#BNBOR[A Web Service Example: -helloservice] -* link:ejb-basicexamples005.html#BNBOY[Using the Timer Service] -* link:ejb-basicexamples006.html#BNBPJ[Handling Exceptions] diff --git a/src/main/jbake/content/ejb-embedded.adoc b/src/main/jbake/content/ejb-embedded.adoc deleted file mode 100644 index 76ec3958..00000000 --- a/src/main/jbake/content/ejb-embedded.adoc +++ /dev/null @@ -1,26 +0,0 @@ -type=page -status=published -title=Using the Embedded Enterprise Bean Container -next=ejb-embedded001.html -prev=ejb-basicexamples006.html -~~~~~~ -Using the Embedded Enterprise Bean Container -============================================ - -[[GKCQZ]][[using-the-embedded-enterprise-bean-container]] - -38 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. - -The following topics are addressed here: - -* link:ejb-embedded001.html#GKFAE[Overview of the Embedded Enterprise -Bean Container] -* link:ejb-embedded002.html#GKCRR[Developing Embeddable Enterprise Bean -Applications] -* link:ejb-embedded003.html#GKCPV[The standalone Example Application] diff --git a/src/main/jbake/content/ejb-gettingstarted.adoc b/src/main/jbake/content/ejb-gettingstarted.adoc deleted file mode 100644 index 5dbc701c..00000000 --- a/src/main/jbake/content/ejb-gettingstarted.adoc +++ /dev/null @@ -1,29 +0,0 @@ -type=page -status=published -title=Getting Started with Enterprise Beans -next=ejb-gettingstarted001.html -prev=ejb-intro008.html -~~~~~~ -Getting Started with Enterprise Beans -===================================== - -[[GIJRE]][[getting-started-with-enterprise-beans]] - -36 Getting Started with Enterprise Beans ----------------------------------------- - - -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. - -The following topics are addressed here: - -* link:ejb-gettingstarted001.html#A1249349[Starting With Enterprise -Beans] -* link:ejb-gettingstarted002.html#GIPSS[Creating the Enterprise Bean] -* link:ejb-gettingstarted003.html#GIPTI[Modifying the Jakarta EE -Application] diff --git a/src/main/jbake/content/ejb-gettingstarted001.adoc b/src/main/jbake/content/ejb-gettingstarted001.adoc deleted file mode 100644 index e95810bf..00000000 --- a/src/main/jbake/content/ejb-gettingstarted001.adoc +++ /dev/null @@ -1,34 +0,0 @@ -type=page -status=published -title=Starting With Enterprise Beans -next=ejb-gettingstarted002.html -prev=ejb-gettingstarted.html -~~~~~~ -Starting With Enterprise Beans -============================== - -[[A1249349]][[starting-with-enterprise-beans]] - -Starting With Enterprise Beans ------------------------------- - -Here's an overview of the steps you'll follow: - -1. Create the enterprise bean: `ConverterBean`. -2. Create the web client. -3. Deploy `converter` onto the server. -4. Using a browser, run the web client. - -Before proceeding, make sure that you've done the following: - -* Read link:overview.html#BNAAW[Chapter 1, "Overview"] -* Become familiar with enterprise beans (see -link:ejb-intro.html#GIJSZ[Chapter 35, "Enterprise Beans"]) -* Started the server (see link:usingexamples002.html#BNADI[Starting and -Stopping GlassFish Server]) - -The following topics are addressed here: - -* link:ejb-gettingstarted002.html#GIPSS[Creating the Enterprise Bean] -* link:ejb-gettingstarted003.html#GIPTI[Modifying the Jakarta EE -Application] diff --git a/src/main/jbake/content/ejb-intro.adoc b/src/main/jbake/content/ejb-intro.adoc deleted file mode 100644 index 5904460c..00000000 --- a/src/main/jbake/content/ejb-intro.adoc +++ /dev/null @@ -1,35 +0,0 @@ -type=page -status=published -title=Enterprise Beans -next=ejb-intro001.html -prev=partentbeans.html -~~~~~~ -Enterprise Beans -================ - -[[GIJSZ]][[enterprise-beans]] - -35 Enterprise Beans -------------------- - - -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 -link:overview005.html#BNABQ[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. - -The following topics are addressed here: - -* link:ejb-intro001.html#GIPMB[What Is an Enterprise Bean?] -* link:ejb-intro002.html#GIPJG[What Is a Session Bean?] -* link:ejb-intro003.html#GIPKO[What Is a Message-Driven Bean?] -* link:ejb-intro004.html#GIPJF[Accessing Enterprise Beans] -* link:ejb-intro005.html#GIPIO[The Contents of an Enterprise Bean] -* link:ejb-intro006.html#GIPKS[Naming Conventions for Enterprise Beans] -* link:ejb-intro007.html#GIPLJ[The Lifecycles of Enterprise Beans] -* link:ejb-intro008.html#GIPLG[Further Information about Enterprise -Beans] diff --git a/src/main/jbake/content/ejb-intro008.adoc b/src/main/jbake/content/ejb-intro008.adoc deleted file mode 100644 index 649d8f35..00000000 --- a/src/main/jbake/content/ejb-intro008.adoc +++ /dev/null @@ -1,19 +0,0 @@ -type=page -status=published -title=Further Information about Enterprise Beans -next=ejb-gettingstarted.html -prev=ejb-intro007.html -~~~~~~ -=Further Information about Enterprise Beans - -[[GIPLG]][[further-information-about-enterprise-beans]] - -Further Information about Enterprise Beans ------------------------------------------- - -For more information on Jakarta Enterprise Beans technology, see the Jakarta Enterprise Beans 3.2 specification: -+ -`https://jakarta.ee/specifications/enterprise-beans/3.2/` - - - diff --git a/src/main/jbake/content/interceptors.adoc b/src/main/jbake/content/interceptors.adoc deleted file mode 100644 index 59d65cde..00000000 --- a/src/main/jbake/content/interceptors.adoc +++ /dev/null @@ -1,24 +0,0 @@ -type=page -status=published -title=Using Jakarta EE Interceptors -next=interceptors001.html -prev=connectorexample003.html -~~~~~~ -Using Jakarta EE Interceptors -========================== - -[[GKEED]][[using-jakarta-ee-interceptors]] - -58 Using Jakarta EE Interceptors --------------------------------- - - -This chapter discusses how to create interceptor classes and methods -that interpose on method invocations or lifecycle events on a target -class. - -The following topics are addressed here: - -* link:interceptors001.html#GKIGQ[Overview of Interceptors] -* link:interceptors002.html#GKEDM[Using Interceptors] -* link:interceptors003.html#GKECI[The interceptor Example Application] diff --git a/src/main/jbake/content/jaxrs-advanced.adoc b/src/main/jbake/content/jaxrs-advanced.adoc deleted file mode 100644 index 1b5b05d1..00000000 --- a/src/main/jbake/content/jaxrs-advanced.adoc +++ /dev/null @@ -1,39 +0,0 @@ -type=page -status=published -title=Jakarta REST: Advanced Topics and an Example -next=jaxrs-advanced001.html -prev=jaxrs-client003.html -~~~~~~ -Jakarta REST: Advanced Topics and an Example -============================================ - -[[GJJXE]][[jax-rs-advanced-topics-and-an-example]] - -34 Jakarta REST: Advanced Topics and an Example ------------------------------------------------ - - -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 link:jaxrs.html#GIEPU[Chapter 32, "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. - -The following topics are addressed here: - -* link:jaxrs-advanced001.html#GKKRB[Annotations for Field and Bean -Properties of Resource Classes] -* link:jaxrs-advanced002.html#BABCJEDF[Validating Resource Data with Bean -Validation] -* link:jaxrs-advanced003.html#GKNAV[Subresources and Runtime Resource -Resolution] -* link:jaxrs-advanced004.html#GKNCY[Integrating Jakarta REST with Jakarta Enterprise Beans -Technology and CDI] -* link:jaxrs-advanced005.html#GKQDA[Conditional HTTP Requests] -* link:jaxrs-advanced006.html#GKQBQ[Runtime Content Negotiation] -* link:jaxrs-advanced007.html#GKKNJ[Using Jakarta REST with Jakarta XML Binding] -* link:jaxrs-advanced008.html#GKOIB[The customer Example Application] diff --git a/src/main/jbake/content/jaxrs-client.adoc b/src/main/jbake/content/jaxrs-client.adoc deleted file mode 100644 index 4f90fb88..00000000 --- a/src/main/jbake/content/jaxrs-client.adoc +++ /dev/null @@ -1,27 +0,0 @@ -type=page -status=published -title=Accessing REST Resources with the Jakarta REST Client API -next=jaxrs-client001.html -prev=jaxrs004.html -~~~~~~ -Accessing REST Resources with the Jakarta REST Client API -========================================================= - -[[BABEIGIH]][[accessing-rest-resources-with-the-jax-rs-client-api]] - -33 Accessing REST Resources with the Jakarta REST Client API ------------------------------------------------------------- - - -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. - -The following topics are addressed here: - -* link:jaxrs-client001.html#BABBIHEJ[Overview of the Client API] -* link:jaxrs-client002.html#BABJCIJC[Using the Client API in the Jakarta REST -Example Applications] -* link:jaxrs-client003.html#BABCDDGH[Advanced Features of the Client API] diff --git a/src/main/jbake/content/jaxrs.adoc b/src/main/jbake/content/jaxrs.adoc deleted file mode 100644 index 43a57818..00000000 --- a/src/main/jbake/content/jaxrs.adoc +++ /dev/null @@ -1,27 +0,0 @@ -type=page -status=published -title=Building RESTful Web Services with Jakarta REST -next=jaxrs001.html -prev=jaxws005.html -~~~~~~ -= Building RESTful Web Services with Jakarta REST - - -[[GIEPU]][[building-restful-web-services-with-jax-rs]] - -32 Building RESTful Web Services with Jakarta REST --------------------------------------------------- - - -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. - -The following topics are addressed here: - -* link:jaxrs001.html#GIJQY[What Are RESTful Web Services?] -* link:jaxrs002.html#GILIK[Creating a RESTful Root Resource Class] -* link:jaxrs003.html#GIPZZ[Example Applications for Jakarta REST] -* link:jaxrs004.html#GILIZ[Further Information about Jakarta REST] diff --git a/src/main/jbake/content/jaxws.adoc b/src/main/jbake/content/jaxws.adoc deleted file mode 100644 index 9e8fa86b..00000000 --- a/src/main/jbake/content/jaxws.adoc +++ /dev/null @@ -1,28 +0,0 @@ -type=page -status=published -title=Building Web Services with JAX-WS -next=jaxws001.html -prev=webservices-intro003.html -~~~~~~ -Building Web Services with JAX-WS -================================= - -[[BNAYL]][[building-web-services-with-jax-ws]] - -31 Building Web Services with JAX-WS ------------------------------------- - - -This chapter describes Java API for XML Web Services (JAX-WS), a -technology for building web services and clients that communicate using -XML. JAX-WS allows developers to write message-oriented as well as -Remote Procedure Call–oriented (RPC-oriented) web services. - -The following topics are addressed here: - -* link:jaxws001.html#A1250966[Overview of Java API for XML Web Services] -* link:jaxws002.html#BNAYN[Creating a Simple Web Service and Clients with -JAX-WS] -* link:jaxws003.html#BNAZC[Types Supported by JAX-WS] -* link:jaxws004.html#BNAZD[Web Services Interoperability and JAX-WS] -* link:jaxws005.html#BNAZE[Further Information about JAX-WS] diff --git a/src/main/jbake/content/jms-concepts.adoc b/src/main/jbake/content/jms-concepts.adoc deleted file mode 100644 index 7678816f..00000000 --- a/src/main/jbake/content/jms-concepts.adoc +++ /dev/null @@ -1,30 +0,0 @@ -type=page -status=published -title=Jakarta Messaging Concepts -next=jms-concepts001.html -prev=partmessaging.html -~~~~~~ -= Jakarta Messaging Concepts -:description: Jakarta Messaging allows applications to create, send, and receive messages. -:keywords: messaging, glassfish - -[[BNCDQ]][[java-message-service-concepts]] - -48 Jakarta Messaging Concepts ------------------------------ - - -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. - -The following topics are addressed here: - -* link:jms-concepts001.html#BNCDR[Jakarta Messaging Overview] -* link:jms-concepts002.html#BNCDX[Basic Jakarta Messaging Concepts] -* link:jms-concepts003.html#BNCEH[Jakarta Messaging Programming Model] -* link:jms-concepts004.html#BNCFU[Using Advanced Jakarta Messaging Features] -* link:jms-concepts005.html#BNCGL[Using Jakarta Messaging in Jakarta EE -Applications] -* link:jms-concepts006.html#BNCGU[Further Information about Jakarta Messaging] diff --git a/src/main/jbake/content/jms-concepts006.adoc b/src/main/jbake/content/jms-concepts006.adoc deleted file mode 100644 index 2f2f76fc..00000000 --- a/src/main/jbake/content/jms-concepts006.adoc +++ /dev/null @@ -1,23 +0,0 @@ -type=page -status=published -title=Further Information about Jakarta Messaging -next=jms-examples.html -prev=jms-concepts005.html -~~~~~~ -Further Information about Jakarta Messaging -=========================================== - -[[BNCGU]][[further-information-about-jms]] - -Further Information about Jakarta Messaging -------------------------------------------- - -For more information about Jakarta Messaging, see - -* Jakarta Messaging website: -+ -`https://projects.eclipse.org/projects/ee4j.jms` - -* Jakarta Messaging specification, version 2.0, available from: - -`https://jakarta.ee/specifications/messaging/2.0/` diff --git a/src/main/jbake/content/jms-examples.adoc b/src/main/jbake/content/jms-examples.adoc deleted file mode 100644 index 642e1909..00000000 --- a/src/main/jbake/content/jms-examples.adoc +++ /dev/null @@ -1,37 +0,0 @@ -type=page -status=published -title=Jakarta Messaging Examples -next=jms-examples001.html -prev=jms-concepts006.html -~~~~~~ -Jakarta Messaging Examples -========================== - -[[BNCGV]][[java-message-service-examples]] - -49 Jakarta Messaging Examples ------------------------------ - - -This chapter provides examples that show how to use Jakarta Messaging in -various kinds of Jakarta EE applications. - -The following topics are addressed here: - -* link:jms-examples001.html#A1251921[Building and Running Jakarta Messaging -Service Examples] -* link:jms-examples002.html#BABEFBHJ[Overview of the Jakarta Messaging Examples] -* link:jms-examples003.html#BNCFA[Writing Simple Jakarta Messaging Applications] -* link:jms-examples004.html#GIWFH[Writing More Advanced Jakarta Messaging Applications] -* link:jms-examples005.html#BABGEFHC[Writing High Performance and -Scalable Jakarta Messaging Applications] -* link:jms-examples006.html#BABBABFC[Sending and Receiving Messages Using -a Simple Web Application] -* link:jms-examples007.html#BNBPK[Receiving Messages Asynchronously Using -a Message-Driven Bean] -* link:jms-examples008.html#BNCGW[Sending Messages from a Session Bean to -an MDB] -* link:jms-examples009.html#BNCHF[Using an Entity to Join Messages from -Two MDBs] -* link:jms-examples010.html#BABDFDJC[Using NetBeans IDE to Create Jakarta Messaging -Resources] diff --git a/src/main/jbake/content/jsf-advanced-cc.adoc b/src/main/jbake/content/jsf-advanced-cc.adoc deleted file mode 100644 index 8d06bf04..00000000 --- a/src/main/jbake/content/jsf-advanced-cc.adoc +++ /dev/null @@ -1,28 +0,0 @@ -type=page -status=published -title=Composite Components: Advanced Topics and an Example -next=jsf-advanced-cc001.html -prev=jsf-ajax012.html -~~~~~~ -Composite Components: Advanced Topics and an Example -==================================================== - -[[GKHXA]][[composite-components-advanced-topics-and-an-example]] - -14 Composite Components: Advanced Topics and an Example -------------------------------------------------------- - - -This chapter describes the advanced features of composite components in -Jakarta Server Faces technology. - -The following topics are addressed here: - -* link:jsf-advanced-cc001.html#GKHWV[Attributes of a Composite Component] -* link:jsf-advanced-cc002.html#GKHUO[Invoking a Managed Bean] -* link:jsf-advanced-cc003.html#GKHWO[Validating Composite Component -Values] -* link:jsf-advanced-cc004.html#GKHVN[The compositecomponentexample -Example Application] - - diff --git a/src/main/jbake/content/jsf-ajax.adoc b/src/main/jbake/content/jsf-ajax.adoc deleted file mode 100644 index fec694f2..00000000 --- a/src/main/jbake/content/jsf-ajax.adoc +++ /dev/null @@ -1,41 +0,0 @@ -type=page -status=published -title=Using Ajax with Jakarta Server Faces Technology -next=jsf-ajax001.html -prev=jsf-develop003.html -~~~~~~ -Using Ajax with Jakarta Server Faces Technology -=============================================== - -[[GKIOW]][[using-ajax-with-javaserver-faces-technology]] - -13 Using Ajax with Jakarta Server Faces Technology --------------------------------------------------- - - -This chapter describes using Ajax functionality in Jakarta Server 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. In the Jakarta EE platform, Jakarta Server Faces technology provides -built-in support for Ajax. - -The following topics are addressed here: - -* link:jsf-ajax001.html#GKIGR[Overview of Ajax] -* link:jsf-ajax002.html#GKINL[Using Ajax Functionality with Jakarta Server -Faces Technology] -* link:jsf-ajax003.html#GKABR[Using Ajax with Facelets] -* link:jsf-ajax004.html#GKACE[Sending an Ajax Request] -* link:jsf-ajax005.html#GKDDF[Monitoring Events on the Client] -* link:jsf-ajax006.html#GKDCB[Handling Errors] -* link:jsf-ajax007.html#GKDBR[Receiving an Ajax Response] -* link:jsf-ajax008.html#GKUAR[Ajax Request Lifecycle] -* link:jsf-ajax009.html#GKHYH[Grouping of Components] -* link:jsf-ajax010.html#GKAAM[Loading JavaScript as a Resource] -* link:jsf-ajax011.html#GKOKB[The ajaxguessnumber Example Application] -* link:jsf-ajax012.html#GKSDK[Further Information about Ajax in -Jakarta Server Faces Technology] - - diff --git a/src/main/jbake/content/jsf-ajax012.adoc b/src/main/jbake/content/jsf-ajax012.adoc deleted file mode 100644 index 0a5c8f16..00000000 --- a/src/main/jbake/content/jsf-ajax012.adoc +++ /dev/null @@ -1,21 +0,0 @@ -type=page -status=published -title=Further Information about Ajax in Jakarta Server Faces Technology -next=jsf-advanced-cc.html -prev=jsf-ajax011.html -~~~~~~ -= Further Information about Ajax in Jakarta Server Faces Technology - - -[[GKSDK]][[further-information-about-ajax-in-javaserver-faces-technology]] - -Further Information about Ajax in Jakarta Server Faces Technology ------------------------------------------------------------------ - -For more information on Ajax in Jakarta Server Faces Technology, see - -* Jakarta Server Faces project website: -+ -`https://javaserverfaces.github.io/users.html` -* link:../javaserver-faces-2-2/jsdocs/symbols/jsf.ajax.html[Jakarta Server -Faces JavaScript Library APIs] diff --git a/src/main/jbake/content/jsf-configure.adoc b/src/main/jbake/content/jsf-configure.adoc deleted file mode 100644 index 5260bc4d..00000000 --- a/src/main/jbake/content/jsf-configure.adoc +++ /dev/null @@ -1,40 +0,0 @@ -type=page -status=published -title=Configuring Jakarta Server Faces Applications -next=jsf-configure001.html -prev=jsf-custom014.html -~~~~~~ -Configuring Jakarta Server Faces Applications -============================================= - -[[BNAWO]][[configuring-javaserver-faces-applications]] - -16 Configuring Jakarta Server Faces Applications ------------------------------------------------- - - -This chapter describes additional configuration tasks required when you -create large and complex applications. - -The following topics are addressed here: - -* link:jsf-configure001.html#A1352824[Introduction to Configuring -Jakarta Server Faces Applications] -* link:jsf-configure002.html#GIRCH[Using Annotations to Configure Managed -Beans] -* link:jsf-configure003.html#BNAWP[Application Configuration Resource -File] -* link:jsf-configure004.html#CHDGFCJF[Using Faces Flows] -* link:jsf-configure005.html#BNAWQ[Configuring Managed Beans] -* link:jsf-configure006.html#BNAXB[Registering Application Messages] -* link:jsf-configure007.html#GIREB[Using Default Validators] -* link:jsf-configure008.html#BNAXD[Registering a Custom Validator] -* link:jsf-configure009.html#BNAXE[Registering a Custom Converter] -* link:jsf-configure010.html#BNAXF[Configuring Navigation Rules] -* link:jsf-configure011.html#BNAXH[Registering a Custom Renderer with a -Render Kit] -* link:jsf-configure012.html#BNAXI[Registering a Custom Component] -* link:jsf-configure013.html#BNAXJ[Basic Requirements of a Jakarta Server -Faces Application] - - diff --git a/src/main/jbake/content/jsf-custom.adoc b/src/main/jbake/content/jsf-custom.adoc deleted file mode 100644 index 51dfe7e1..00000000 --- a/src/main/jbake/content/jsf-custom.adoc +++ /dev/null @@ -1,42 +0,0 @@ -type=page -status=published -title=Creating Custom UI Components and Other Custom Objects -next=jsf-custom001.html -prev=jsf-advanced-cc004.html -~~~~~~ -Creating Custom UI Components and Other Custom Objects -====================================================== - -[[BNAVG]][[creating-custom-ui-components-and-other-custom-objects]] - -15 Creating Custom UI Components and Other Custom Objects ---------------------------------------------------------- - - -This chapter describes creating custom components for applications that -have additional functionality not provided by standard Jakarta Server Faces -components. - -The following topics are addressed here: - -* link:jsf-custom001.html#A1350198[Introduction to Creating Custom -Components] -* link:jsf-custom002.html#BNAVH[Determining Whether You Need a Custom -Component or Renderer] -* link:jsf-custom003.html#GLPCB[Understanding the Image Map Example] -* link:jsf-custom004.html#BNAVT[Steps for Creating a Custom Component] -* link:jsf-custom005.html#BNAVU[Creating Custom Component Classes] -* link:jsf-custom006.html#BNAWA[Delegating Rendering to a Renderer] -* link:jsf-custom007.html#BNAUT[Implementing an Event Listener] -* link:jsf-custom008.html#BNAWD[Handling Events for Custom Components] -* link:jsf-custom009.html#BNAWN[Defining the Custom Component Tag in a -Tag Library Descriptor] -* link:jsf-custom010.html#BNATT[Using a Custom Component] -* link:jsf-custom011.html#BNAUS[Creating and Using a Custom Converter] -* link:jsf-custom012.html#BNAUW[Creating and Using a Custom Validator] -* link:jsf-custom013.html#BNATG[Binding Component Values and Instances to -Managed Bean Properties] -* link:jsf-custom014.html#BNATM[Binding Converters, Listeners, and -Validators to Managed Bean Properties] - - diff --git a/src/main/jbake/content/jsf-custom004.adoc b/src/main/jbake/content/jsf-custom004.adoc deleted file mode 100644 index bc25d784..00000000 --- a/src/main/jbake/content/jsf-custom004.adoc +++ /dev/null @@ -1,44 +0,0 @@ -type=page -status=published -title=Steps for Creating a Custom Component -next=jsf-custom005.html -prev=jsf-custom003.html -~~~~~~ -Steps for Creating a Custom Component -===================================== - -[[BNAVT]][[steps-for-creating-a-custom-component]] - -Steps for Creating a Custom Component -------------------------------------- - -You can apply the following steps while developing your own custom -component. - -1. Create a custom component class that does the following: -1. Overrides the `getFamily` method to return the component family, -which is used to look up renderers that can render the component -2. Includes the rendering code or delegates it to a renderer (explained -in Step link:#CDECBJAE[2]) -3. Enables component attributes to accept expressions -4. Queues an event on the component if the component generates events -5. Saves and restores the component state -2. [[CDECBJAE]] -+ -Delegate rendering to a renderer if your component does not handle the -rendering. To do this: -1. Create a custom renderer class by extending -`javax.faces.render.Renderer`. -2. Register the renderer to a render kit. -3. Register the component. -4. Create an event handler if your component generates events. -5. Create a tag library descriptor (TLD) that defines the custom tag. - -See link:jsf-configure012.html#BNAXI[Registering a Custom Component] and -link:jsf-configure011.html#BNAXH[Registering a Custom Renderer with a -Render Kit] for information on registering the custom component and the -renderer. The section link:jsf-custom010.html#BNATT[Using a Custom -Component] discusses how to use the custom component in a Jakarta Server -Faces page. - - diff --git a/src/main/jbake/content/jsf-develop.adoc b/src/main/jbake/content/jsf-develop.adoc deleted file mode 100644 index b5fcede9..00000000 --- a/src/main/jbake/content/jsf-develop.adoc +++ /dev/null @@ -1,28 +0,0 @@ -type=page -status=published -title=Developing with Jakarta Server Faces Technology -next=jsf-develop001.html -prev=jsf-page-core004.html -~~~~~~ -Developing with Jakarta Server Faces Technology -=========================================== - -[[BNATX]][[developing-with-javaserver-faces-technology]] - -12 Developing with Jakarta Server Faces Technology ----------------------------------------------- - - -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 Server Faces application. This chapter also introduces the Bean -Validation feature. - -The following topics are addressed here: - -* link:jsf-develop001.html#BNAQM[Managed Beans in Jakarta Server Faces -Technology] -* link:jsf-develop002.html#BNATY[Writing Bean Properties] -* link:jsf-develop003.html#BNAVB[Writing Managed Bean Methods] - - diff --git a/src/main/jbake/content/jsf-el.adoc b/src/main/jbake/content/jsf-el.adoc deleted file mode 100644 index e1596e1a..00000000 --- a/src/main/jbake/content/jsf-el.adoc +++ /dev/null @@ -1,37 +0,0 @@ -type=page -status=published -title=Expression Language -next=jsf-el001.html -prev=jsf-facelets009.html -~~~~~~ -Expression Language -=================== - -[[GJDDD]][[expression-language]] - -9 Expression Language ---------------------- - - -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 Server Faces technology, Jakarta Server Pages technology, and -Dependency Injection for Jakarta EE (CDI). The EL can also be -used in stand-alone environments. This chapter only covers the use of -the EL in Jakarta EE containers. - -The following topics are addressed here: - -* link:jsf-el001.html#BNAHQ[Overview of the EL] -* link:jsf-el002.html#BNAHR[Immediate and Deferred Evaluation Syntax] -* link:jsf-el003.html#BNAHU[Value and Method Expressions] -* link:jsf-el004.html#CIHGABHD[Operations on Collection Objects] -* link:jsf-el005.html#BNAIK[Operators] -* link:jsf-el006.html#BNAIL[Reserved Words] -* link:jsf-el007.html#BNAIM[Examples of EL Expressions] -* link:jsf-el008.html#CIHGBBHA[Further Information about the Expression -Language] - - diff --git a/src/main/jbake/content/jsf-el008.adoc b/src/main/jbake/content/jsf-el008.adoc deleted file mode 100644 index 6078d4b9..00000000 --- a/src/main/jbake/content/jsf-el008.adoc +++ /dev/null @@ -1,22 +0,0 @@ -type=page -status=published -title=Further Information about the Expression Language -next=jsf-page.html -prev=jsf-el007.html -~~~~~~ -= Further Information about the Expression Language - - -[[CIHGBBHA]][[further-information-about-the-expression-language]] - -Further Information about the Expression Language -------------------------------------------------- - -For more information about the EL, see - -* The Expression Language 3.0 specification: -+ -`http://www.jcp.org/en/jsr/detail?id=341` -* The EL specification website: -+ -`https://github.com/javaee/el-spec` diff --git a/src/main/jbake/content/jsf-facelets.adoc b/src/main/jbake/content/jsf-facelets.adoc deleted file mode 100644 index ac71b14c..00000000 --- a/src/main/jbake/content/jsf-facelets.adoc +++ /dev/null @@ -1,39 +0,0 @@ -type=page -status=published -title=Introduction to Facelets -next=jsf-facelets001.html -prev=jsf-intro009.html -~~~~~~ -Introduction to Facelets -======================== - -[[GIEPX]][[introduction-to-facelets]] - -8 Introduction to Facelets --------------------------- - - -The term Facelets refers to the view declaration language for Jakarta Server -Faces technology. Facelets is a part of the Jakarta Server Faces -specification and also the preferred presentation technology for -building Jakarta Server Faces technology–based applications. Jakarta Server -Pages technology, previously used as the presentation technology -for Jakarta Server Faces, does not support all the new features available in -Jakarta Server Faces in the Jakarta EE platform. Jakarta Server Pages technology is considered -to be a deprecated presentation technology for Jakarta Server Faces. - -The following topics are addressed here: - -* link:jsf-facelets001.html#GIJTU[What Is Facelets?] -* link:jsf-facelets002.html#GIPRR[The Lifecycle of a Facelets -Application] -* link:jsf-facelets003.html#GIPOB[Developing a Simple Facelets -Application: The guessnumber-jsf Example Application] -* link:jsf-facelets004.html#GIQXP[Using Facelets Templates] -* link:jsf-facelets005.html#GIQZR[Composite Components] -* link:jsf-facelets006.html#GIRGM[Web Resources] -* link:jsf-facelets007.html#BABHGBJI[Relocatable Resources] -* link:jsf-facelets008.html#BABHAHDF[Resource Library Contracts] -* link:jsf-facelets009.html#BABGECCJ[HTML5-Friendly Markup] - - diff --git a/src/main/jbake/content/jsf-intro.adoc b/src/main/jbake/content/jsf-intro.adoc deleted file mode 100644 index d32f59c6..00000000 --- a/src/main/jbake/content/jsf-intro.adoc +++ /dev/null @@ -1,34 +0,0 @@ -type=page -status=published -title=Jakarta Server Faces Technology -next=jsf-intro001.html -prev=webapp006.html -~~~~~~ -Jakarta Server Faces Technology -=============================== - -[[BNAPH]][[javaserver-faces-technology]] - -7 Jakarta Server Faces Technology ---------------------------------- - - -Jakarta Server Faces technology is a server-side component framework for -building Java technology–based web applications. - -The following topics are addressed here: - -* link:jsf-intro001.html#A1073698[Introduction to Jakarta Server Faces -Technology] -* link:jsf-intro002.html#BNAPK[What Is a Jakarta Server Faces Application?] -* link:jsf-intro003.html#BNAPJ[Jakarta Server Faces Technology Benefits] -* link:jsf-intro004.html#GJAAM[A Simple Jakarta Server Faces Application] -* link:jsf-intro005.html#BNAQD[User Interface Component Model] -* link:jsf-intro006.html#BNAQL[Navigation Model] -* link:jsf-intro007.html#BNAQQ[The Lifecycle of a Jakarta Server Faces -Application] -* link:jsf-intro008.html#GKNOJ[Partial Processing and Partial Rendering] -* link:jsf-intro009.html#BNAQY[Further Information about Jakarta Server Faces -Technology] - - diff --git a/src/main/jbake/content/jsf-ws.adoc b/src/main/jbake/content/jsf-ws.adoc deleted file mode 100644 index 0eb75511..00000000 --- a/src/main/jbake/content/jsf-ws.adoc +++ /dev/null @@ -1,23 +0,0 @@ -type=page -status=published -title=Using WebSockets with Jakarta Server Faces Technology -next=jsf-ws001.html -prev=jsf-configure013.html -~~~~~~ -= Using WebSockets with Jakarta Server Faces Technology - - -[[using-websockets-with-javaserver-faces-technology]] -17 Using WebSockets with Jakarta Server Faces Technology --------------------------------------------------------- -This chapter describes using WebSockets in Jakarta Server Faces web applications. - -The following topics are addressed here: - -* link:jsf-ws001.html#about-websockets-in-jsf[About WebSockets in JSF] -* link:jsf-ws002.html#configuring-websockets[Configuring WebSockets] -* link:jsf-ws003.html#using-the-fwebsocket-tag[Using the f:websocket Tag] -* link:jsf-ws004.html#websocket-scopes-and-users[WebSocket Scopes and Users] -* link:jsf-ws005.html#conditionally-connecting-websockets[Conditionally Connecting WebSockets] -* link:jsf-ws006.html#websocket-security-considerations[WebSocket Security Considerations] -* link:jsf-ws007.html#using-ajax-with-websockets[Using Ajax With WebSockets] diff --git a/src/main/jbake/content/jsonb.adoc b/src/main/jbake/content/jsonb.adoc deleted file mode 100644 index d3584032..00000000 --- a/src/main/jbake/content/jsonb.adoc +++ /dev/null @@ -1,27 +0,0 @@ -type=page -status=published -title=JSON Binding -next=jsonb001.html -prev=jsonp008.html -~~~~~~ -= JSON Binding - -[[json-binding]] -21 JSON Binding ---------------- - -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 -link:jsonp001.html#introduction-to-json[Introduction to JSON]. - -The link:https://jakarta.ee/specifications/json-binding/[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. -You can learn more about Yasson at https://projects.eclipse.org/projects/ee4j.yasson. - -The following topics are addressed here: - -* link:jsonb001.html#json-binding-in-the-jakarta-ee-platform[JSON Binding in the Jakarta EE Platform] -* link:jsonb002.html#overview-of-the-json-binding-api[Overview of the JSON Binding API] -* link:jsonb003.html#running-the-jsonbbasics-example-application[Running the jsonbbasics Example Application] -* link:jsonb004.html#further-information-about-the-java-api-for-json-binding[Further Information about Jakarta JSON Binding] diff --git a/src/main/jbake/content/jsonb003.adoc b/src/main/jbake/content/jsonb003.adoc deleted file mode 100644 index 013f80f0..00000000 --- a/src/main/jbake/content/jsonb003.adoc +++ /dev/null @@ -1,84 +0,0 @@ -type=page -status=published -title=JSON Binding -next=jsonb004.html -prev=jsonb002.html -~~~~~~ -= Running the jsonbbasics Example Application - -[[running-the-jsonbbasics-example-application]] -Running the jsonbbasics Example Application -------------------------------------------- - -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 following topics are addressed here: - -* link:#components-of-the-jsonbbasics-example-application[Components of the jsonbbasics Example Application] -* link:#running-the-jsonbbasics-example-application[Running the jsonbbasics Example Application] - - - -[[components-of-the-jsonbbasics-example-application]] -Components of the jsonbbasics Example Application -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The `jsonbbasics` example application contains the following files. - -* Two JavaServer Faces pages. - -** The `index.xhtml` page contains a form to collect data that is used to -create a `Person` object. - -** The `jsongenerated.xhtml` page contains a text area that displays the data -in JSON format. - -* The `jsonbBean.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 contains code that -uses the JSON Binding API. - - - -[[running-the-jsonbbasics-example-application]] -Running the jsonbbasics Example Application -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This section describes how to run the `jsonbbasics` example application -from the command line using Maven. - - -To run the jsonbbasics example application using Maven: - - -1. Make sure that GlassFish Server has been started (see -link:usingexamples002.html#BNADI[Starting and Stopping GlassFish -Server]). -2. In a terminal window, go to: -+ -[source,oac_no_warn] ----- -tut-install/examples/web/jsonb/jsonbbasics ----- -3. Enter the following command to deploy the application: -+ -[source,oac_no_warn] ----- -mvn install ----- -4. Open a web browser window and enter the following address: -+ -[source,oac_no_warn] ----- -http://localhost:8080/jsonbbasics/ ----- -5. Enter data on form and click Serialize to JSON to submit -the form. The following page shows the JSON format of the object data. -6. Click Deserialize JSON. The index page displays and contains the fields populated from -the object data. diff --git a/src/main/jbake/content/jsonp.adoc b/src/main/jbake/content/jsonp.adoc deleted file mode 100644 index ad648892..00000000 --- a/src/main/jbake/content/jsonp.adoc +++ /dev/null @@ -1,30 +0,0 @@ -type=page -status=published -title=JSON Processing -next=jsonp001.html -prev=websocket013.html -~~~~~~ -= JSON Processing - - -[[json-processing]] -20 JSON Processing ------------------- - - -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. - -The following topics are addressed here: - -* link:jsonp001.html#introduction-to-json[Introduction to JSON] -* link:jsonp002.html#json-processing-in-the-jakarta-ee-platform[JSON Processing in the Jakarta EE Platform] -* link:jsonp003.html#using-the-object-model-api[Using the Object Model API] -* link:jsonp004.html#using-the-streaming-api[Using the Streaming API] -* link:jsonp005.html#json-in-jakarta-ee-restful-web-services[JSON in Jakarta EE RESTful Web Services] -* link:jsonp006.html#the-jsonpmodel-example-application[The jsonpmodel Example Application] -* link:jsonp007.html#the-jsonpstreaming-example-application[The jsonpstreaming Example Application] -* link:jsonp008.html#further-information-about-the-java-api-for-json-processing[Further Information about Jakarta JSON Processing] diff --git a/src/main/jbake/content/jsonp008.adoc b/src/main/jbake/content/jsonp008.adoc deleted file mode 100644 index 65b15de9..00000000 --- a/src/main/jbake/content/jsonp008.adoc +++ /dev/null @@ -1,18 +0,0 @@ -type=page -status=published -title=Further Information about the Jakarta JSON Processing -next=jsonb.html -prev=jsonp007.html -~~~~~~ -= Further Information about the Java API for JSON Processing - - -[[further-information-about-the-java-api-for-json-processing]] -Further Information about the Jakarta JSON Processing ----------------------------------------------------------- - -For more information on JSON processing in Jakarta EE, see the Jakarta JSON Processing specification: - -`https://jakarta.ee/specifications/jsonp/1.1` - - diff --git a/src/main/jbake/content/overview.adoc b/src/main/jbake/content/overview.adoc deleted file mode 100644 index f392793f..00000000 --- a/src/main/jbake/content/overview.adoc +++ /dev/null @@ -1,35 +0,0 @@ -type=page -status=published -title=Overview -next=overview001.html -prev=partintro.html -~~~~~~ -Overview -======== - -[[BNAAW]][[overview]] - -1 Overview ----------- - - -This chapter introduces you to Jakarta EE enterprise application -development. Here you will review development basics, learn about the -Jakarta EE architecture and APIs, become acquainted with important terms -and concepts, and find out how to approach Jakarta EE application -programming, assembly, and deployment. - -The following topics are addressed here: - -* link:overview001.html#A1046550[Introduction to Jakarta EE] -* link:overview002.html#GIQVH[Jakarta EE 8 Platform Highlights] -* link:overview003.html#BNAAX[Jakarta EE Application Model] -* link:overview004.html#BNAAY[Distributed Multitiered Applications] -* link:overview005.html#BNABO[Jakarta EE Containers] -* link:overview006.html#BNABS[Web Services Support] -* link:overview007.html#BNABX[Jakarta EE Application Assembly and -Deployment] -* link:overview008.html#BNACJ[Jakarta EE 8 APIs] -* link:overview009.html#GIRDR[Jakarta EE 8 APIs in the Java Platform, -Standard Edition 8] -* link:overview010.html#BNADF[GlassFish Server Tools] diff --git a/src/main/jbake/content/overview002.adoc b/src/main/jbake/content/overview002.adoc deleted file mode 100644 index d61ea80f..00000000 --- a/src/main/jbake/content/overview002.adoc +++ /dev/null @@ -1,36 +0,0 @@ -type=page -status=published -title=Jakarta EE 8 Platform Highlights -next=overview003.html -prev=overview001.html -~~~~~~ -= Jakarta EE 8 Platform Highlights - - -[[GIQVH]][[jakarta-ee-8-platform-highlights]] - -Jakarta EE 8 Platform Highlights --------------------------------- - -The key goals of the Jakarta EE 8 platform are to modernize the infrastructure for enterprise Java for the cloud and microservices environments, emphasize HTML5 and HTTP/2 support, enhance ease of development through new Contexts and Dependency Injection features, and further enhance security and reliability of the platform. - -The Jakarta EE 8 platform includes the following new features: - -* New technologies, including the following: - -** link:overview008.html#java-api-for-json-binding[Jakarta JSON Binding] -** link:overview008.html#jakarta-ee-security-api[Jakarta Security] - -* New object model improvements for JSON Processing (see -link:overview008.html#java-api-for-json-processing[Jakarta JSON Processing] for details), including support for the following: - -** JSON Pointer -** JSON Patch -** JSON Merge Patch - -* New features for RESTful web services (see link:overview008.html#java-api-for-restful-web-services[Jakarta RESTful Web Services] for details) -* New features for servlets (see -link:overview008.html#java-servlet-technology[Jakarta Servlet Technology] for details) -* New features for Jakarta Server Faces components (see link:overview008.html#javaserver-faces-technology[Jakarta Server Faces Technology] for details) -* New Contexts and Dependency Injection features (see link:overview008.html#contexts-and-dependency-injection-for-jakarta-ee[Jakarta Contexts and Dependency Injection] for details) -* New JavaBean validation features (see link:overview008.html#bean-validation[Bean Validation] for details) diff --git a/src/main/jbake/content/packaging.adoc b/src/main/jbake/content/packaging.adoc deleted file mode 100644 index 742c053a..00000000 --- a/src/main/jbake/content/packaging.adoc +++ /dev/null @@ -1,29 +0,0 @@ -type=page -status=published -title=Packaging -next=packaging001.html -prev=injection003.html -~~~~~~ -Packaging -========= - -[[GKJIQ4]][[packaging]] - -5 Packaging ------------ - - -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. - -The following topics are addressed here: - -* link:packaging001.html#BCGDJDFB[Packaging Applications] -* link:packaging002.html#BCGECBIJ[Packaging Enterprise Beans] -* link:packaging003.html#BCGHAHGD[Packaging Web Archives] -* link:packaging004.html#BCGDHBHJ[Packaging Resource Adapter Archives] - - diff --git a/src/main/jbake/content/partbeanvalidation.adoc b/src/main/jbake/content/partbeanvalidation.adoc deleted file mode 100644 index c795a9a3..00000000 --- a/src/main/jbake/content/partbeanvalidation.adoc +++ /dev/null @@ -1,22 +0,0 @@ -type=page -status=published -title=Bean Validation -next=bean-validation.html -prev=webi18n004.html -~~~~~~ -Bean Validation -=============== - -[[sthref1322]][[JEETT001301]] - -[[part-iv-bean-validation]] -Part IV Bean Validation ------------------------ - -Part IV explores Jakarta Bean Validation. -This part contains the following chapters: - -* link:bean-validation.html#CHDGJIIA[Chapter 23, "Introduction to Bean -Validation"] -* link:bean-validation-advanced.html#GKAHP[Chapter 24, "Bean Validation: -Advanced Topics"] diff --git a/src/main/jbake/content/partcasestudies.adoc b/src/main/jbake/content/partcasestudies.adoc deleted file mode 100644 index c2eafd40..00000000 --- a/src/main/jbake/content/partcasestudies.adoc +++ /dev/null @@ -1,24 +0,0 @@ -type=page -status=published -title=Case Studies -next=dukes-bookstore.html -prev=concurrency-utilities007.html -~~~~~~ -Case Studies -============ - -[[GKGJW]][[JEETT00135]] - -[[part-xii-case-studies]] -Part XII Case Studies ---------------------- - -Part XII presents case studies that use a variety of Jakarta EE -technologies. This part contains the following chapters: - -* link:dukes-bookstore.html#GLNVI[Chapter 61, "Duke's Bookstore Case -Study Example"] -* link:dukes-tutoring.html#GKAEE[Chapter 62, "Duke's Tutoring Case Study -Example"] -* link:dukes-forest.html#GLNPW[Chapter 63, "Duke's Forest Case Study -Example"] diff --git a/src/main/jbake/content/partcdi.adoc b/src/main/jbake/content/partcdi.adoc deleted file mode 100644 index 202b4b00..00000000 --- a/src/main/jbake/content/partcdi.adoc +++ /dev/null @@ -1,25 +0,0 @@ -type=page -status=published -title=Jakarta EE Contexts and Dependency Injection -next=cdi-basic.html -prev=bean-validation-advanced004.html -~~~~~~ -Jakarta EE Contexts and Dependency Injection -============================================ - -[[GJBNR]][[JEETT00131]] - -[[part-v-contexts-and-dependency-injection-for-jakarta-ee]] -Part V Jakarta EE Contexts and Dependency Injection ---------------------------------------------------- - -Part V explores Jakarta EE Contexts and Dependency Injection (CDI). -This part contains the following chapters: - -* link:cdi-basic.html#GIWHB[Chapter 25, "Introduction to Jakarta EE Contexts and Dependency Injection"] -* link:cdi-basicexamples.html#GJBLS[Chapter 26, "Running the Basic -Contexts and Dependency Injection Examples"] -* link:cdi-adv.html#GJEHI[Chapter 27, "Jakarta EE Contexts and Dependency Injection: Advanced Topics"] -* link:cdi-bootstrap-se8.html#bootstrapping-a-cdi-container-in-java-se[Chapter 28, "Bootstrapping a CDI Container in Java SE"] -* link:cdi-adv-examples.html#GKHRE[Chapter 29, "Running the Advanced -Contexts and Dependency Injection Examples"] diff --git a/src/main/jbake/content/partentbeans.adoc b/src/main/jbake/content/partentbeans.adoc deleted file mode 100644 index 214627a2..00000000 --- a/src/main/jbake/content/partentbeans.adoc +++ /dev/null @@ -1,27 +0,0 @@ -type=page -status=published -title=Enterprise Beans -next=ejb-intro.html -prev=jaxrs-advanced008.html -~~~~~~ -Enterprise Beans -================ - -[[BNBLR]][[JEETT00130]] - -[[part-vii-enterprise-beans]] -Part VII Enterprise Beans -------------------------- - -Part VII explores Jakarta Enterprise Beans components. This part contains -the following chapters: - -* link:ejb-intro.html#GIJSZ[Chapter 35, "Enterprise Beans"] -* link:ejb-gettingstarted.html#GIJRE[Chapter 36, "Getting Started with -Enterprise Beans"] -* link:ejb-basicexamples.html#GIJRB[Chapter 37, "Running the Enterprise -Bean Examples"] -* link:ejb-embedded.html#GKCQZ[Chapter 38, "Using the Embedded Enterprise -Bean Container"] -* link:ejb-async.html#GKIDZ[Chapter 39, "Using Asynchronous Method -Invocation in Session Beans"] diff --git a/src/main/jbake/content/partintro.adoc b/src/main/jbake/content/partintro.adoc deleted file mode 100644 index eda994e7..00000000 --- a/src/main/jbake/content/partintro.adoc +++ /dev/null @@ -1,22 +0,0 @@ -type=page -status=published -title=Introduction -next=overview.html -prev=preface.html -~~~~~~ -Introduction -============ - -[[GFIRP]][[JEETT00127]] - -[[part-i-introduction]] -Part I Introduction -------------------- - -Part I introduces the platform, the tutorial, and the examples. This -part contains the following chapters: - -* link:overview.html#BNAAW[Chapter 1, "Overview"] -* link:usingexamples.html#GFIUD[Chapter 2, "Using the Tutorial Examples"] - - diff --git a/src/main/jbake/content/partmessaging.adoc b/src/main/jbake/content/partmessaging.adoc deleted file mode 100644 index 372bf6f2..00000000 --- a/src/main/jbake/content/partmessaging.adoc +++ /dev/null @@ -1,21 +0,0 @@ -type=page -status=published -title=Messaging -next=jms-concepts.html -prev=persistence-cache002.html -~~~~~~ -Messaging -========= - -[[GFIRP3]][[JEETT1712]] - -[[part-ix-messaging]] -Part IX Messaging ------------------ - -Part IX introduces messaging. This part contains the following chapters: - -* link:jms-concepts.html#BNCDQ[Chapter 48, "Jakarta Messaging -Concepts"] -* link:jms-examples.html#BNCGV[Chapter 49, "Jakarta Messaging -Examples"] diff --git a/src/main/jbake/content/partpersist.adoc b/src/main/jbake/content/partpersist.adoc deleted file mode 100644 index 827b3c18..00000000 --- a/src/main/jbake/content/partpersist.adoc +++ /dev/null @@ -1,33 +0,0 @@ -type=page -status=published -title=Persistence -next=persistence-intro.html -prev=ejb-async002.html -~~~~~~ -Persistence -=========== - -[[BNBPY]][[JEETT00132]] - -[[part-viii-persistence]] -Part VIII Persistence ---------------------- - -Part VIII explores Jakartaa Persistence. This part contains the -following chapters: - -* link:persistence-intro.html#BNBPZ[Chapter 40, "Introduction to Jakarta Persistence"] -* link:persistence-basicexamples.html#GIJST[Chapter 41, "Running the -Persistence Examples"] -* link:persistence-querylanguage.html#BNBTG[Chapter 42, "The Jakarta -Persistence Query Language"] -* link:persistence-criteria.html#GJITV[Chapter 43, "Using the Criteria -API to Create Queries"] -* link:persistence-string-queries.html#GKJIQ[Chapter 44, "Creating and -Using String-Based Criteria Queries"] -* link:persistence-locking.html#GKJJF[Chapter 45, "Controlling Concurrent -Access to Entity Data with Locking"] -* link:persistence-entitygraphs.html#BABIJIAC[Chapter 46, "Creating Fetch -Plans with Entity Graphs"] -* link:persistence-cache.html#GKJIA[Chapter 47, "Using a Second-Level -Cache with Jakarta Persistence Applications"] diff --git a/src/main/jbake/content/partplatform.adoc b/src/main/jbake/content/partplatform.adoc deleted file mode 100644 index 33fd7c82..00000000 --- a/src/main/jbake/content/partplatform.adoc +++ /dev/null @@ -1,23 +0,0 @@ -type=page -status=published -title=Platform Basics -next=resource-creation.html -prev=usingexamples009.html -~~~~~~ -Platform Basics -=============== - -[[GFIRP2]][[JEETT1358]] - -[[part-ii-platform-basics]] -Part II Platform Basics ------------------------ - -Part II introduces platform basics. This part contains the following -chapters: - -* link:resource-creation.html#GKJIQ2[Chapter 3, "Resource Creation"] -* link:injection.html#GKJIQ3[Chapter 4, "Injection"] -* link:packaging.html#GKJIQ4[Chapter 5, "Packaging"] - - diff --git a/src/main/jbake/content/partsecurity.adoc b/src/main/jbake/content/partsecurity.adoc deleted file mode 100644 index 8d8ff204..00000000 --- a/src/main/jbake/content/partsecurity.adoc +++ /dev/null @@ -1,26 +0,0 @@ -type=page -status=published -title=Security -next=security-intro.html -prev=jms-examples010.html -~~~~~~ -= Security - -[[GIJRP]][[JEETT00133]] - -[[part-x-security]] -Part X Security ---------------- - -Part X explores security concepts and examples. This part contains the -following chapters: - -* link:security-intro.html#BNBWJ[Chapter 50, "Introduction to Security in -the Jakarta EE Platform"] -* link:security-webtier.html#BNCAS[Chapter 51, "Getting Started Securing -Web Applications"] -* link:security-jakartaee.html#BNBYK[Chapter 52, "Getting Started Securing -Enterprise Applications"] -* link:security-api.html#using-the-jakarta-ee-security-api[Chapter 53, "Using Jakarta Security"] -* link:security-advanced.html#GJJWX[Chapter 54, "Jakarta Security: -Advanced Topics"] diff --git a/src/main/jbake/content/partsupporttechs.adoc b/src/main/jbake/content/partsupporttechs.adoc deleted file mode 100644 index ff1aed7d..00000000 --- a/src/main/jbake/content/partsupporttechs.adoc +++ /dev/null @@ -1,26 +0,0 @@ -type=page -status=published -title=Jakarta EE Supporting Technologies -next=transactions.html -prev=security-advanced008.html -~~~~~~ -Jakarta EE Supporting Technologies -================================== - -[[GIJUE]][[JEETT00134]] - -[[part-xi-jakarta-ee-supporting-technologies]] -Part XI Jakarta EE Supporting Technologies ------------------------------------------- - -Part XI explores several technologies that support the Jakarta EE platform. -This part contains the following chapters: - -* link:transactions.html#BNCIH[Chapter 55, "Transactions"] -* link:resources.html#BNCJH[Chapter 56, "Resource Adapters and -Contracts"] -* link:connectorexample.html#GLODB[Chapter 57, "The Resource Adapter -Examples"] -* link:interceptors.html#GKEED[Chapter 58, "Using Jakarta Interceptors"] -* link:batch-processing.html#GKJIQ6[Chapter 59, "Batch Processing"] -* link:concurrency-utilities.html#GKJIQ8[Chapter 60, "Jakarta Concurrency"] diff --git a/src/main/jbake/content/partwebsvcs.adoc b/src/main/jbake/content/partwebsvcs.adoc deleted file mode 100644 index 1295f07e..00000000 --- a/src/main/jbake/content/partwebsvcs.adoc +++ /dev/null @@ -1,27 +0,0 @@ -type=page -status=published -title=Web Services -next=webservices-intro.html -prev=cdi-adv-examples006.html -~~~~~~ -Web Services -============ - -[[BNAYK]][[JEETT00129]] - -[[part-vi-web-services]] -Part VI Web Services --------------------- - -Part VI explores web services. This part contains the following -chapters: - -* link:webservices-intro.html#GIJTI[Chapter 30, "Introduction to Web -Services"] -* link:jaxws.html#BNAYL[Chapter 31, "Building Web Services with Jakarta RESTful Web Services"] -* link:jaxrs.html#GIEPU[Chapter 32, "Building RESTful Web Services with -Jakarta RESTful Web Services"] -* link:jaxrs-client.html#BABEIGIH[Chapter 33, "Accessing REST Resources -with the Jakarta RESTful Web Services Client API"] -* link:jaxrs-advanced.html#GJJXE[Chapter 34, "Jakarta RESTful Web Services: Advanced Topics and -an Example"] diff --git a/src/main/jbake/content/partwebtier.adoc b/src/main/jbake/content/partwebtier.adoc deleted file mode 100644 index bb3d1594..00000000 --- a/src/main/jbake/content/partwebtier.adoc +++ /dev/null @@ -1,44 +0,0 @@ -type=page -status=published -title=The Web Tier -next=webapp.html -prev=packaging004.html -~~~~~~ -The Web Tier -============ - -[[BNADP]][[JEETT00128]] - -[[part-iii-the-web-tier]] -Part III The Web Tier ---------------------- - -Part III explores the technologies in the web tier. This part contains -the following chapters: - -* link:webapp.html#BNADR[Chapter 6, "Getting Started with Web -Applications"] -* link:jsf-intro.html#BNAPH[Chapter 7, "Jakarta Server Faces Technology"] -* link:jsf-facelets.html#GIEPX[Chapter 8, "Introduction to Facelets"] -* link:jsf-el.html#GJDDD[Chapter 9, "Expression Language"] -* link:jsf-page.html#BNAQZ[Chapter 10, "Using Jakarta Server Faces Technology -in Web Pages"] -* link:jsf-page-core.html#GJCUT[Chapter 11, "Using Converters, Listeners, -and Validators"] -* link:jsf-develop.html#BNATX[Chapter 12, "Developing with Jakarta Server -Faces Technology"] -* link:jsf-ajax.html#GKIOW[Chapter 13, "Using Ajax with Jakarta Server Faces -Technology"] -* link:jsf-advanced-cc.html#GKHXA[Chapter 14, "Composite Components: -Advanced Topics and an Example"] -* link:jsf-custom.html#BNAVG[Chapter 15, "Creating Custom UI Components -and Other Custom Objects"] -* link:jsf-configure.html#BNAWO[Chapter 16, "Configuring Jakarta Server Faces -Applications"] -* link:jsf-ws.html#using-websockets-with-javaserver-faces-technology[Chapter 17, "Using WebSockets with Jakarta Server Faces Technology"] -* link:servlets.html#BNAFD[Chapter 18, "Jakarta Servlet Technology"] -* link:websocket.html#GKJIQ5[Chapter 19, "Jakarta WebSocket"] -* link:jsonp.html#GLRBB[Chapter 20, "JSON Processing"] -* link:jsonb.html#json-binding[Chapter 21, "JSON Binding"] -* link:webi18n.html#BNAXU[Chapter 22, "Internationalizing and Localizing -Web Applications"] diff --git a/src/main/jbake/content/persistence-basicexamples.adoc b/src/main/jbake/content/persistence-basicexamples.adoc deleted file mode 100644 index 6c5df7f9..00000000 --- a/src/main/jbake/content/persistence-basicexamples.adoc +++ /dev/null @@ -1,26 +0,0 @@ -type=page -status=published -title=Running the Persistence Examples -next=persistence-basicexamples001.html -prev=persistence-intro007.html -~~~~~~ -Running the Persistence Examples -================================ - -[[GIJST]][[running-the-persistence-examples]] - -41 Running the Persistence Examples ------------------------------------ - - -This chapter explains how to use Jakarta Persistence. The material -here focuses on the source code and settings of three examples. - -The following topics are addressed here: - -* link:persistence-basicexamples001.html#A1023268[Overview of the -Persistence Examples] -* link:persistence-basicexamples002.html#GIQST[The order Application] -* link:persistence-basicexamples003.html#GIQSQ[The roster Application] -* link:persistence-basicexamples004.html#GKANQ[The address-book -Application] diff --git a/src/main/jbake/content/persistence-cache.adoc b/src/main/jbake/content/persistence-cache.adoc deleted file mode 100644 index d1dcb449..00000000 --- a/src/main/jbake/content/persistence-cache.adoc +++ /dev/null @@ -1,25 +0,0 @@ -type=page -status=published -title=Using a Second-Level Cache with Jakarta Persistence Applications -next=persistence-cache001.html -prev=persistence-entitygraphs004.html -~~~~~~ -Using a Second-Level Cache with Jakarta Persistence Applications -================================================================ - -[[GKJIA]][[using-a-second-level-cache-with-java-persistence-api-applications]] - -47 Using a Second-Level Cache with Jakarta Persistence Applications -------------------------------------------------------------------- - - -This chapter explains how to modify the second-level cache mode settings -to improve the performance of applications that use the Jakarta Persistence -API. - -The following topics are addressed here: - -* link:persistence-cache001.html#GKJIO[Overview of the Second-Level -Cache] -* link:persistence-cache002.html#GKJJJ[Specifying the Cache Mode Settings -to Improve Performance] diff --git a/src/main/jbake/content/persistence-criteria.adoc b/src/main/jbake/content/persistence-criteria.adoc deleted file mode 100644 index d9465713..00000000 --- a/src/main/jbake/content/persistence-criteria.adoc +++ /dev/null @@ -1,28 +0,0 @@ -type=page -status=published -title=Using the Criteria API to Create Queries -next=persistence-criteria001.html -prev=persistence-querylanguage006.html -~~~~~~ -Using the Criteria API to Create Queries -======================================== - -[[GJITV]][[using-the-criteria-api-to-create-queries]] - -43 Using the Criteria API to Create Queries -------------------------------------------- - - -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. - -The following topics are addressed here: - -* link:persistence-criteria001.html#GJRIJ[Overview of the Criteria and -Metamodel APIs] -* link:persistence-criteria002.html#GJIUP[Using the Metamodel API to -Model Entity Classes] -* link:persistence-criteria003.html#GJIVM[Using the Criteria API and -Metamodel API to Create Basic Typesafe Queries] diff --git a/src/main/jbake/content/persistence-entitygraphs.adoc b/src/main/jbake/content/persistence-entitygraphs.adoc deleted file mode 100644 index ec3c5d77..00000000 --- a/src/main/jbake/content/persistence-entitygraphs.adoc +++ /dev/null @@ -1,27 +0,0 @@ -type=page -status=published -title=Creating Fetch Plans with Entity Graphs -next=persistence-entitygraphs001.html -prev=persistence-locking002.html -~~~~~~ -Creating Fetch Plans with Entity Graphs -======================================= - -[[BABIJIAC]][[creating-fetch-plans-with-entity-graphs]] - -46 Creating Fetch Plans with Entity Graphs ------------------------------------------- - - -This chapter explains how to use entity graphs to create fetch plans for -Jakarta Persistence operations and queries. - -The following topics are addressed here: - -* link:persistence-entitygraphs001.html#A1153411[Overview of Using Fetch -Plans and Entity Graphs] -* link:persistence-entitygraphs002.html#BABCJBCG[Entity Graph Basics] -* link:persistence-entitygraphs003.html#BABFIGEI[Using Named Entity -Graphs] -* link:persistence-entitygraphs004.html#BABGJDAJ[Using Entity Graphs in -Query Operations] diff --git a/src/main/jbake/content/persistence-intro.adoc b/src/main/jbake/content/persistence-intro.adoc deleted file mode 100644 index 2d25e8c0..00000000 --- a/src/main/jbake/content/persistence-intro.adoc +++ /dev/null @@ -1,28 +0,0 @@ -type=page -status=published -title=Introduction to Jakarta Persistence -next=persistence-intro001.html -prev=partpersist.html -~~~~~~ -Introduction to Jakarta Persistence -=================================== - -[[BNBPZ]][[introduction-to-the-java-persistence-api]] - -40 Introduction to Jakarta Persistence --------------------------------------- - - -This chapter provides a description of Jakarta Persistence. - -The following topics are addressed here: - -* link:persistence-intro001.html#A1019685[Overview of the Jakarta -Persistence] -* link:persistence-intro002.html#BNBQA[Entities] -* link:persistence-intro003.html#BNBQN[Entity Inheritance] -* link:persistence-intro004.html#BNBQW[Managing Entities] -* link:persistence-intro005.html#GJISE[Querying Entities] -* link:persistence-intro006.html#CHDBEGIC[Database Schema Creation] -* link:persistence-intro007.html#GKCLC[Further Information about -Persistence] diff --git a/src/main/jbake/content/persistence-locking.adoc b/src/main/jbake/content/persistence-locking.adoc deleted file mode 100644 index b35f1b27..00000000 --- a/src/main/jbake/content/persistence-locking.adoc +++ /dev/null @@ -1,24 +0,0 @@ -type=page -status=published -title=Controlling Concurrent Access to Entity Data with Locking -next=persistence-locking001.html -prev=persistence-string-queries003.html -~~~~~~ -Controlling Concurrent Access to Entity Data with Locking -========================================================= - -[[GKJJF]][[controlling-concurrent-access-to-entity-data-with-locking]] - -45 Controlling Concurrent Access to Entity Data with Locking ------------------------------------------------------------- - - -This chapter details how to handle concurrent access to entity data, and -the locking strategies available to Jakarta Persistence application -developers. - -The following topics are addressed here: - -* link:persistence-locking001.html#GKJHZ[Overview of Entity Locking and -Concurrency] -* link:persistence-locking002.html#GKJIU[Lock Modes] diff --git a/src/main/jbake/content/persistence-querylanguage.adoc b/src/main/jbake/content/persistence-querylanguage.adoc deleted file mode 100644 index 41e3332b..00000000 --- a/src/main/jbake/content/persistence-querylanguage.adoc +++ /dev/null @@ -1,33 +0,0 @@ -type=page -status=published -title=The Jakarta Persistence Query Language -next=persistence-querylanguage001.html -prev=persistence-basicexamples004.html -~~~~~~ -The Jakarta Persistence Query Language -====================================== - -[[BNBTG]][[the-java-persistence-query-language]] - -42 The Jakarta Persistence Query Language ------------------------------------------ - - -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. - -The following topics are addressed here: - -* link:persistence-querylanguage001.html#A1073303[Overview of the Jakarta -Persistence Query Language] -* link:persistence-querylanguage002.html#BNBTH[Query Language -Terminology] -* link:persistence-querylanguage003.html#BNBRG[Creating Queries Using the -Jakarta Persistence Query Language] -* link:persistence-querylanguage004.html#BNBTI[Simplified Query Language -Syntax] -* link:persistence-querylanguage005.html#BNBTL[Example Queries] -* link:persistence-querylanguage006.html#BNBUF[Full Query Language -Syntax] diff --git a/src/main/jbake/content/persistence-string-queries.adoc b/src/main/jbake/content/persistence-string-queries.adoc deleted file mode 100644 index b5563090..00000000 --- a/src/main/jbake/content/persistence-string-queries.adoc +++ /dev/null @@ -1,26 +0,0 @@ -type=page -status=published -title=Creating and Using String-Based Criteria Queries -next=persistence-string-queries001.html -prev=persistence-criteria003.html -~~~~~~ -Creating and Using String-Based Criteria Queries -================================================ - -[[GKJIQ]][[creating-and-using-string-based-criteria-queries]] - -44 Creating and Using String-Based Criteria Queries ---------------------------------------------------- - - -This chapter describes how to create weakly typed string-based Criteria -API queries. - -The following topics are addressed here: - -* link:persistence-string-queries001.html#GKJIV[Overview of String-Based -Criteria API Queries] -* link:persistence-string-queries002.html#GKJBQ[Creating String-Based -Queries] -* link:persistence-string-queries003.html#GKJDB[Executing String-Based -Queries] diff --git a/src/main/jbake/content/resources.adoc b/src/main/jbake/content/resources.adoc deleted file mode 100644 index 2d5e538a..00000000 --- a/src/main/jbake/content/resources.adoc +++ /dev/null @@ -1,27 +0,0 @@ -type=page -status=published -title=Resource Adapters and Contracts -next=resources001.html -prev=transactions009.html -~~~~~~ -Resource Adapters and Contracts -=============================== - -[[BNCJH]][[resource-adapters-and-contracts]] - -56 Resource Adapters and Contracts ----------------------------------- - - -This chapter examines resource adapters and explains how communications -between Jakarta EE servers and EIS systems are mediated by them. - -The following topics are addressed here: - -* link:resources001.html#GIPGL[What Is a Resource Adapter?] -* link:resources002.html#GIRDD[Metadata Annotations] -* link:resources003.html#GIPJU[Common Client Interface] -* link:resources004.html#CHDJFIGB[Using Resource Adapters with Contexts -and Dependency Injection for Jakarta EE (CDI)] -* link:resources005.html#BNCJW[Further Information about Resource -Adapters] diff --git a/src/main/jbake/content/security-advanced.adoc b/src/main/jbake/content/security-advanced.adoc deleted file mode 100644 index ae64010b..00000000 --- a/src/main/jbake/content/security-advanced.adoc +++ /dev/null @@ -1,31 +0,0 @@ -type=page -status=published -title=Jakarta EE Security: Advanced Topics -next=security-advanced001.html -prev=security-api005.html -~~~~~~ -= Jakarta EE Security: Advanced Topics - -[[GJJWX]][[jakarta-ee-security-advanced-topics]] - -54 Jakarta EE Security: Advanced Topics ---------------------------------------- - - -This chapter provides advanced information on securing Jakarta EE -applications. - -The following topics are addressed here: - -* link:security-advanced001.html#BNBYB[Working with Digital Certificates] -* link:security-advanced002.html#GLIEN[Authentication Mechanisms] -* link:security-advanced003.html#BABEJJDE[Using the JDBC Realm for User -Authentication] -* link:security-advanced004.html#BABGEJJJ[Securing HTTP Resources] -* link:security-advanced005.html#GLIGC[Securing Application Clients] -* link:security-advanced006.html#GLIFD[Securing Enterprise Information -Systems Applications] -* link:security-advanced007.html#GKHRL[Configuring Security Using -Deployment Descriptors] -* link:security-advanced008.html#BABBGBBF[Further Information about -Advanced Security Topics] diff --git a/src/main/jbake/content/security-api.adoc b/src/main/jbake/content/security-api.adoc deleted file mode 100644 index c1d495aa..00000000 --- a/src/main/jbake/content/security-api.adoc +++ /dev/null @@ -1,27 +0,0 @@ -type=page -status=published -title=Using Jakarta Security -next=security-api001.html -prev=security-jakartaee003.html -~~~~~~ -= Using Jakarta Security - - - -[[using-the-jakarta-ee-security-api]] -53 Using Jakarta Security -------------------------- - - -This chapter describes the authentication and credential validation -functionality provided by Jakarta Security. The API also -defines a SecurityContext access point for programmatic security. - - -The following topics are addressed here: - -* link:security-api001.html#about-the-jakarta-ee-security-api[About Jakarta Security] -* link:security-api002.html#overview-of-the-http-auth-mech-int[Overview of the HTTP Authentication Mechanism Interface] -* link:security-api003.html#overview-of-the-identity-store-interfaces[Overview of the Identity Store Interfaces] -* link:security-api004.html#running-the-built-in-database-identity-store-example[Running the Built-In Database Identity Store Example] -* link:security-api005.html#running-the-custom-identity-store-example[Running the Custom Identity Store Example] diff --git a/src/main/jbake/content/security-intro.adoc b/src/main/jbake/content/security-intro.adoc deleted file mode 100644 index 7b72a4d9..00000000 --- a/src/main/jbake/content/security-intro.adoc +++ /dev/null @@ -1,40 +0,0 @@ -type=page -status=published -title=Introduction to Security in the Jakarta EE Platform -next=security-intro001.html -prev=partsecurity.html -~~~~~~ -= Introduction to Security in the Jakarta EE Platform - - -[[BNBWJ]][[introduction-to-security-in-the-jakarta-ee-platform]] - -50 Introduction to Security in the Jakarta EE Platform ------------------------------------------------------- - - -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 8 specification. - -[width="100%",cols="100%",] -|======================================================================= -a| -*Note:* - -The SDK may include additional material demonstrating key features of Jakarta Security. Please check the latest SDK release notes for additional details. - -|======================================================================= - - -The following topics are addressed here: - -* link:security-intro001.html#BNBWK[Overview of Jakarta Security] -* link:security-intro002.html#BNBWY[Security Mechanisms] -* link:security-intro003.html#BNBXE[Securing Containers] -* link:security-intro004.html#BNBXI[Securing GlassFish Server] -* link:security-intro005.html#BNBXJ[Working with Realms, Users, Groups, -and Roles] -* link:security-intro006.html#BNBXW[Establishing a Secure Connection -Using SSL] -* link:security-intro007.html#BNBYJ[Further Information about Security] diff --git a/src/main/jbake/content/security-jakartaee.adoc b/src/main/jbake/content/security-jakartaee.adoc deleted file mode 100644 index 29750608..00000000 --- a/src/main/jbake/content/security-jakartaee.adoc +++ /dev/null @@ -1,23 +0,0 @@ -type=page -status=published -title=Getting Started Securing Enterprise Applications -next=security-jakartaee001.html -prev=security-webtier004.html -~~~~~~ -= Getting Started Securing Enterprise Applications - -[[BNBYK]][[getting-started-securing-enterprise-applications]] - -52 Getting Started Securing Enterprise Applications ---------------------------------------------------- - - -This chapter describes how to administer security for enterprise -applications. - -The following topics are addressed here: - -* link:security-jakartaee001.html#CACGIFHJ[Basic Security Tasks for -Enterprise Applications] -* link:security-jakartaee002.html#BNBYL[Securing Enterprise Beans] -* link:security-jakartaee003.html#GKBSZ[Examples: Securing Enterprise Beans] diff --git a/src/main/jbake/content/security-webtier.adoc b/src/main/jbake/content/security-webtier.adoc deleted file mode 100644 index ac251fee..00000000 --- a/src/main/jbake/content/security-webtier.adoc +++ /dev/null @@ -1,30 +0,0 @@ -type=page -status=published -title=Getting Started Securing Web Applications -next=security-webtier001.html -prev=security-intro007.html -~~~~~~ -Getting Started Securing Web Applications -========================================= - -[[BNCAS]][[getting-started-securing-web-applications]] - -51 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 -link:security-intro003.html#BNBXE[Securing Containers]. The detail and -examples in this chapter explore these security services as they relate -to web components. - -The following topics are addressed here: - -* link:security-webtier001.html#BNCAT[Overview of Web Application -Security] -* link:security-webtier002.html#GKBAA[Securing Web Applications] -* link:security-webtier003.html#GJIIE[Using Programmatic Security with -Web Applications] -* link:security-webtier004.html#BNCBX[Examples: Securing Web -Applications] diff --git a/src/main/jbake/content/servlets.adoc b/src/main/jbake/content/servlets.adoc deleted file mode 100644 index af3a8678..00000000 --- a/src/main/jbake/content/servlets.adoc +++ /dev/null @@ -1,42 +0,0 @@ -type=page -status=published -title=Jakarta Servlet Technology -next=servlets001.html -prev=jsf-ws007.html -~~~~~~ -= Jakarta Servlet Technology - - -[[BNAFD]][[java-servlet-technology]] - -18 Jakarta Servlet Technology ------------------------------ - - -Jakarta Servlet technology provides dynamic, user-oriented content in web -applications using a request-response programming model. - -The following topics are addressed here: - -* link:servlets001.html#BNAFE[What Is a Servlet?] -* link:servlets002.html#BNAFI[Servlet Lifecycle] -* link:servlets003.html#BNAFO[Sharing Information] -* link:servlets004.html#BNAFU[Creating and Initializing a Servlet] -* link:servlets005.html#BNAFV[Writing Service Methods] -* link:servlets006.html#BNAGB[Filtering Requests and Responses] -* link:servlets007.html#BNAGI[Invoking Other Web Resources] -* link:servlets008.html#BNAGL[Accessing the Web Context] -* link:servlets009.html#BNAGM[Maintaining Client State] -* link:servlets010.html#BNAGS[Finalizing a Servlet] -* link:servlets011.html#BABFGCHB[Uploading Files with Jakarta Servlet -Technology] -* link:servlets012.html#BEIGCFDF[Asynchronous Processing] -* link:servlets013.html#BEIHICDH[Nonblocking I/O] -* link:servlets014.html#BEIJHCDJ[Protocol Upgrade Processing] -* link:servlets014a.html#server-push[Server Push] -* link:servlets014b.html#http-trailer[HTTP Trailer] -* link:servlets015.html#GKCPG[The mood Example Application] -* link:servlets016.html#BABDGFJJ[The fileupload Example Application] -* link:servlets017.html#BEIFAIFF[The dukeetf Example Application] -* link:servlets018.html#BNAGW[Further Information about Jakarta Servlet -Technology] diff --git a/src/main/jbake/content/servlets018.adoc b/src/main/jbake/content/servlets018.adoc deleted file mode 100644 index ac2b1a54..00000000 --- a/src/main/jbake/content/servlets018.adoc +++ /dev/null @@ -1,16 +0,0 @@ -type=page -status=published -title=Further Information about Jakarta Servlet Technology -next=websocket.html -prev=servlets017.html -~~~~~~ -= Further Information about Jakarta Servlet Technology - - -[[BNAGW]][[further-information-about-java-servlet-technology]] - -Further Information about Jakarta Servlet Technology ----------------------------------------------------- - -For more information on Jakarta Servlet technology, see the Jakarta Servlet -4.0 specification at `https://jakarta.ee/specifications/servlet/4.0`. diff --git a/src/main/jbake/content/transactions.adoc b/src/main/jbake/content/transactions.adoc deleted file mode 100644 index b612b7b9..00000000 --- a/src/main/jbake/content/transactions.adoc +++ /dev/null @@ -1,29 +0,0 @@ -type=page -status=published -title=Transactions -next=transactions001.html -prev=partsupporttechs.html -~~~~~~ -Transactions -============ - -[[BNCIH]][[transactions]] - -55 Transactions ---------------- - - -This chapter describes types of transactions and how they are managed in -different applications. - -The following topics are addressed here: - -* link:transactions001.html#A1024277[Overview of Transactions] -* link:transactions002.html#GIJRG[Transactions in Jakarta EE Applications] -* link:transactions003.html#BNCII[What Is a Transaction?] -* link:transactions004.html#BNCIJ[Container-Managed Transactions] -* link:transactions005.html#BNCIY[Bean-Managed Transactions] -* link:transactions006.html#BNCJC[Transaction Timeouts] -* link:transactions007.html#BNCJD[Updating Multiple Databases] -* link:transactions008.html#BNCJG[Transactions in Web Components] -* link:transactions009.html#GKCMI[Further Information about Transactions] diff --git a/src/main/jbake/content/transactions009.adoc b/src/main/jbake/content/transactions009.adoc deleted file mode 100644 index 13d09b00..00000000 --- a/src/main/jbake/content/transactions009.adoc +++ /dev/null @@ -1,18 +0,0 @@ -type=page -status=published -title=Further Information about Transactions -next=resources.html -prev=transactions008.html -~~~~~~ -Further Information about Transactions -====================================== - -[[GKCMI]][[further-information-about-transactions]] - -Further Information about Transactions --------------------------------------- - -For more information about transactions, see the Jakarta Transactions -1.3 specification at `https://jakarta.ee/specifications/transactions/1.3/`. - - diff --git a/src/main/jbake/content/usingexamples.adoc b/src/main/jbake/content/usingexamples.adoc deleted file mode 100644 index af66f17b..00000000 --- a/src/main/jbake/content/usingexamples.adoc +++ /dev/null @@ -1,33 +0,0 @@ -type=page -status=published -title=Using the Tutorial Examples -next=usingexamples001.html -prev=overview010.html -~~~~~~ -= Using the Tutorial Examples - - -[[GFIUD]][[using-the-tutorial-examples]] - -2 Using the Tutorial Examples ------------------------------ - - -This chapter tells you everything you need to know to install, build, -and run the tutorial examples. - -The following topics are addressed here: - -* link:usingexamples001.html#GEXAJ[Required Software] -* link:usingexamples002.html#BNADI[Starting and Stopping GlassFish -Server] -* link:usingexamples003.html#BNADJ[Starting the Administration Console] -* link:usingexamples004.html#BNADK[Starting and Stopping Apache Derby] -* link:usingexamples005.html#BNAAN[Building the Examples] -* link:usingexamples006.html#GEXAP[Tutorial Example Directory Structure] -* link:usingexamples007.html#CIHBHEFF[Jakarta EE Maven Archetypes in the -Tutorial] -* link:usingexamples009.html#BNADL[Debugging Jakarta EE Applications] - -For additional samples, see the GlassFish samples at -https://github.com/javaee/glassfish-samples/tree/master/ws/javaee8 diff --git a/src/main/jbake/content/webapp.adoc b/src/main/jbake/content/webapp.adoc deleted file mode 100644 index a9ba180a..00000000 --- a/src/main/jbake/content/webapp.adoc +++ /dev/null @@ -1,30 +0,0 @@ -type=page -status=published -title=Getting Started with Web Applications -next=webapp001.html -prev=partwebtier.html -~~~~~~ -Getting Started with Web Applications -===================================== - -[[BNADR]][[getting-started-with-web-applications]] - -6 Getting Started with Web Applications ---------------------------------------- - - -This chapter introduces web applications, which typically use JavaServer -Faces technology and/or Java Servlet technology. - -The following topics are addressed here: - -* link:webapp001.html#GEYSJ[Web Applications] -* link:webapp002.html#BNADU[Web Application Lifecycle] -* link:webapp003.html#BNADX[A Web Module That Uses Jakarta Server Faces -Technology: The hello1 Example] -* link:webapp004.html#BNAEO[A Web Module That Uses Jakarta Servlet -Technology: The hello2 Example] -* link:webapp005.html#CHDHGJIA[Configuring Web Applications] -* link:webapp006.html#BNAFC[Further Information about Web Applications] - - diff --git a/src/main/jbake/content/webservices-intro.adoc b/src/main/jbake/content/webservices-intro.adoc deleted file mode 100644 index 0405f9d2..00000000 --- a/src/main/jbake/content/webservices-intro.adoc +++ /dev/null @@ -1,25 +0,0 @@ -type=page -status=published -title=Introduction to Web Services -next=webservices-intro001.html -prev=partwebsvcs.html -~~~~~~ -Introduction to Web Services -============================ - -[[GIJTI]][[introduction-to-web-services]] - -30 Introduction to Web Services -------------------------------- - - -This part of the tutorial discusses Jakarta EE 8 web services technologies. -These technologies include Java API for XML Web Services (JAX-WS) and -Jakarta RESTful Web Services. - -The following topics are addressed here: - -* link:webservices-intro001.html#GIJVH[What Are Web Services?] -* link:webservices-intro002.html#GIQSX[Types of Web Services] -* link:webservices-intro003.html#GJBJI[Deciding Which Type of Web Service -to Use] diff --git a/src/main/jbake/content/websocket.adoc b/src/main/jbake/content/websocket.adoc deleted file mode 100644 index 289ef20f..00000000 --- a/src/main/jbake/content/websocket.adoc +++ /dev/null @@ -1,37 +0,0 @@ -type=page -status=published -title=Jakarta WebSocket -next=websocket001.html -prev=servlets018.html -~~~~~~ -= Jakarta WebSocket - - -[[GKJIQ5]][[java-api-for-websocket]] - -19 Jakarta WebSocket --------------------- - - -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. - -The following topics are addressed here: - -* link:websocket001.html#BABDABHF[Introduction to WebSocket] -* link:websocket002.html#BABEAEFC[Creating WebSocket Applications in the -Jakarta EE Platform] -* link:websocket003.html#BABGJEIG[Programmatic Endpoints] -* link:websocket004.html#BABFEBGA[Annotated Endpoints] -* link:websocket005.html#BABFCGBJ[Sending and Receiving Messages] -* link:websocket006.html#BABGJCAD[Maintaining Client State] -* link:websocket007.html#BABGADFG[Using Encoders and Decoders] -* link:websocket008.html#BABEJIJI[Path Parameters] -* link:websocket009.html#BABDEJHB[Handling Errors] -* link:websocket010.html#BABJAIGH[Specifying an Endpoint Configurator -Class] -* link:websocket011.html#BABGCEHE[The dukeetf2 Example Application] -* link:websocket012.html#BABCDBBC[The websocketbot Example Application] -* link:websocket013.html#BABDFIFD[Further Information about WebSocket] diff --git a/src/main/jbake/content/websocket013.adoc b/src/main/jbake/content/websocket013.adoc deleted file mode 100644 index dbb0d170..00000000 --- a/src/main/jbake/content/websocket013.adoc +++ /dev/null @@ -1,19 +0,0 @@ -type=page -status=published -title=Further Information about WebSocket -next=jsonp.html -prev=websocket012.html -~~~~~~ -Further Information about WebSocket -=================================== - -[[BABDFIFD]][[further-information-about-websocket]] - -Further Information about WebSocket ------------------------------------ - -For more information on WebSocket in Jakarta EE, see the Jakarta WebSocket specification: - -`https://jakarta.ee/specifications/websocket/1.1/` - - diff --git a/src/main/jbake/jbake.properties b/src/main/jbake/jbake.properties deleted file mode 100644 index 546d09c7..00000000 --- a/src/main/jbake/jbake.properties +++ /dev/null @@ -1,7 +0,0 @@ -site.host=http://jbake.org -render.tags=false -render.sitemap=false -render.archive=false -render.feed=false -asciidoctor.option.safe=0 -asciidoctor.attributes.export=true diff --git a/src/main/jbake/templates/footer.ftl b/src/main/jbake/templates/footer.ftl deleted file mode 100644 index 6f2b09ea..00000000 --- a/src/main/jbake/templates/footer.ftl +++ /dev/null @@ -1,46 +0,0 @@ -<#-- a footer template fragment included in the page template --> -
- - - - - - - - - <#if content.prev??> - - - - <#if content.next??> - - - - - -
- - - Previous - - - - - Next - - - - - Contents - -
- - - Eclipse Foundation Logo  - Copyright © 2019, Oracle and/or its affiliates. All rights reserved. - - -

${config.status!}

- - - diff --git a/src/main/jbake/templates/header.ftl b/src/main/jbake/templates/header.ftl deleted file mode 100644 index 82ebb365..00000000 --- a/src/main/jbake/templates/header.ftl +++ /dev/null @@ -1,55 +0,0 @@ - -<#-- a header template fragment included in the page template --> - - - - <#if (content.title)??><#escape x as x?xml>${content.title}</#escape></#if> - - - - - - - - - -
- ${content.title}
-

${config.status!}

-
-
- - - - - - - - - <#if content.prev??> - - - - <#if content.next??> - - - - - -
- - - Previous - - - - - Next - - - - - Contents - -
- diff --git a/src/main/jbake/templates/menu.ftl b/src/main/jbake/templates/menu.ftl deleted file mode 100644 index 888c03dc..00000000 --- a/src/main/jbake/templates/menu.ftl +++ /dev/null @@ -1 +0,0 @@ -<#-- a menu bar template fragment included in the page template --> \ No newline at end of file diff --git a/src/main/jbake/templates/page.ftl b/src/main/jbake/templates/page.ftl deleted file mode 100644 index eca51db3..00000000 --- a/src/main/jbake/templates/page.ftl +++ /dev/null @@ -1,8 +0,0 @@ -<#-- a top level page layout template --> - -<#include "header.ftl"> -<#include "menu.ftl"> - -${content.body} - -<#include "footer.ftl"> \ No newline at end of file diff --git a/src/theme/jakartaee-theme.yml b/src/theme/jakartaee-theme.yml deleted file mode 100644 index 6092a2f5..00000000 --- a/src/theme/jakartaee-theme.yml +++ /dev/null @@ -1,299 +0,0 @@ -# -# Following is the asciidoctor-pdf default theme [1], with small -# customizations, mostly for header and footer, marked "EE". -# -# [1] https://github.com/asciidoctor/asciidoctor-pdf/blob/master/data/themes/default-theme.yml -# -font: - catalog: - # Noto Serif supports Latin, Latin-1 Supplement, Latin Extended-A, Greek, Cyrillic, Vietnamese & an assortment of symbols - Noto Serif: - normal: notoserif-regular-subset.ttf - bold: notoserif-bold-subset.ttf - italic: notoserif-italic-subset.ttf - bold_italic: notoserif-bold_italic-subset.ttf - # M+ 1mn supports ASCII and the circled numbers used for conums - M+ 1mn: - normal: mplus1mn-regular-ascii-conums.ttf - bold: mplus1mn-bold-ascii.ttf - italic: mplus1mn-italic-ascii.ttf - bold_italic: mplus1mn-bold_italic-ascii.ttf - # M+ 1p supports Latin, Latin-1 Supplement, Latin Extended, Greek, Cyrillic, Vietnamese, Japanese & an assortment of symbols - # It also provides arrows for ->, <-, => and <= replacements in case these glyphs are missing from font - M+ 1p Fallback: - normal: mplus1p-regular-fallback.ttf - bold: mplus1p-regular-fallback.ttf - italic: mplus1p-regular-fallback.ttf - bold_italic: mplus1p-regular-fallback.ttf - fallbacks: - - M+ 1p Fallback -page: - background_color: ffffff - layout: portrait - margin: [0.5in, 0.67in, 0.67in, 0.67in] - # margin_inner and margin_outer keys are used for recto/verso print margins when media=prepress - margin_inner: 0.75in - margin_outer: 0.59in - #size: A4 # EE - size: Letter # EE -base: - align: justify - # color as hex string (leading # is optional) - font_color: 333333 - # color as RGB array - #font_color: [51, 51, 51] - # color as CMYK array (approximated) - #font_color: [0, 0, 0, 0.92] - #font_color: [0, 0, 0, 92%] - font_family: Noto Serif - # choose one of these font_size/line_height_length combinations - #font_size: 14 - #line_height_length: 20 - #font_size: 11.25 - #line_height_length: 18 - #font_size: 11.2 - #line_height_length: 16 - font_size: 10.5 - #line_height_length: 15 - # correct line height for Noto Serif metrics - line_height_length: 12 - #font_size: 11.25 - #line_height_length: 18 - line_height: $base_line_height_length / $base_font_size - font_size_large: round($base_font_size * 1.25) - font_size_small: round($base_font_size * 0.85) - font_size_min: $base_font_size * 0.75 - font_style: normal - border_color: eeeeee - border_radius: 4 - border_width: 0.5 -# FIXME vertical_rhythm is weird; we should think in terms of ems -#vertical_rhythm: $base_line_height_length * 2 / 3 -# correct line height for Noto Serif metrics (comes with built-in line height) -vertical_rhythm: $base_line_height_length -horizontal_rhythm: $base_line_height_length -# QUESTION should vertical_spacing be block_spacing instead? -vertical_spacing: $vertical_rhythm -link: - font_color: 428bca -# literal is currently used for inline monospaced in prose and table cells -literal: - font_color: b12146 - font_family: M+ 1mn -menu_caret_content: " \u203a " -heading: - align: left - #font_color: 181818 - font_color: $base_font_color - font_family: $base_font_family - font_style: bold - # h1 is used for part titles (book doctype) or the doctitle (article doctype) - #h1_font_size: floor($base_font_size * 2.6) # EE - h1_font_size: floor($base_font_size * 2.5) # EE, squeeze title onto one line - # h2 is used for chapter titles (book doctype only) - h2_font_size: floor($base_font_size * 2.15) - h3_font_size: round($base_font_size * 1.7) - h4_font_size: $base_font_size_large - h5_font_size: $base_font_size - h6_font_size: $base_font_size_small - #line_height: 1.4 - # correct line height for Noto Serif metrics (comes with built-in line height) - line_height: 1 - margin_top: $vertical_rhythm * 0.4 - margin_bottom: $vertical_rhythm * 0.9 -title_page: - align: right - logo: - top: 10% - title: - top: 55% - font_size: $heading_h1_font_size - font_color: 999999 - line_height: 0.9 - subtitle: - font_size: $heading_h3_font_size - font_style: bold_italic - line_height: 1 - authors: - margin_top: $base_font_size * 1.25 - font_size: $base_font_size_large - font_color: 181818 - revision: - margin_top: $base_font_size * 1.25 -block: - margin_top: 0 - margin_bottom: $vertical_rhythm -caption: - align: left - font_size: $base_font_size * 0.95 - font_style: italic - # FIXME perhaps set line_height instead of / in addition to margins? - margin_inside: $vertical_rhythm / 3 - #margin_inside: $vertical_rhythm / 4 - margin_outside: 0 -lead: - font_size: $base_font_size_large - line_height: 1.4 -abstract: - font_color: 5c6266 - font_size: $lead_font_size - line_height: $lead_line_height - font_style: italic - first_line_font_style: bold - title: - align: center - font_color: $heading_font_color - font_family: $heading_font_family - font_size: $heading_h4_font_size - font_style: $heading_font_style -admonition: - column_rule_color: $base_border_color - column_rule_width: $base_border_width - padding: [0, $horizontal_rhythm, 0, $horizontal_rhythm] - #icon: - # tip: - # name: fa-lightbulb-o - # stroke_color: 111111 - # size: 24 - label: - text_transform: uppercase - font_style: bold -blockquote: - font_color: $base_font_color - font_size: $base_font_size_large - border_color: $base_border_color - border_width: 5 - # FIXME disable negative padding bottom once margin collapsing is implemented - padding: [0, $horizontal_rhythm, $block_margin_bottom * -0.75, $horizontal_rhythm + $blockquote_border_width / 2] - cite_font_size: $base_font_size_small - cite_font_color: 999999 -# code is used for source blocks (perhaps change to source or listing?) -code: - font_color: $base_font_color - font_family: $literal_font_family - font_size: ceil($base_font_size) - padding: $code_font_size - line_height: 1.25 - # line_gap is an experimental property to control how a background color is applied to an inline block element - line_gap: 3.8 - background_color: f5f5f5 - border_color: cccccc - border_radius: $base_border_radius - border_width: 0.75 -conum: - font_family: M+ 1mn - font_color: $literal_font_color - font_size: $base_font_size - line_height: 4 / 3 -example: - border_color: $base_border_color - border_radius: $base_border_radius - border_width: 0.75 - background_color: ffffff - # FIXME reenable padding bottom once margin collapsing is implemented - padding: [$vertical_rhythm, $horizontal_rhythm, 0, $horizontal_rhythm] -image: - align: left -prose: - margin_top: $block_margin_top - margin_bottom: $block_margin_bottom -sidebar: - background_color: eeeeee - border_color: e1e1e1 - border_radius: $base_border_radius - border_width: $base_border_width - # FIXME reenable padding bottom once margin collapsing is implemented - padding: [$vertical_rhythm, $vertical_rhythm * 1.25, 0, $vertical_rhythm * 1.25] - title: - align: center - font_color: $heading_font_color - font_family: $heading_font_family - font_size: $heading_h4_font_size - font_style: $heading_font_style -thematic_break: - border_color: $base_border_color - border_style: solid - border_width: $base_border_width - margin_top: $vertical_rhythm * 0.5 - margin_bottom: $vertical_rhythm * 1.5 -description_list: - term_font_style: bold - term_spacing: $vertical_rhythm / 4 - description_indent: $horizontal_rhythm * 1.25 -outline_list: - indent: $horizontal_rhythm * 1.5 - #marker_font_color: 404040 - # NOTE outline_list_item_spacing applies to list items that do not have complex content - item_spacing: $vertical_rhythm / 2 -table: - background_color: $page_background_color - #head_background_color: - #head_font_color: $base_font_color - head_font_style: bold - #body_background_color: - body_stripe_background_color: f9f9f9 - foot_background_color: f0f0f0 - border_color: dddddd - border_width: $base_border_width - cell_padding: 3 -toc: - indent: $horizontal_rhythm - line_height: 1.4 - dot_leader: - #content: ". " - font_color: a9a9a9 - #levels: 2 3 -# NOTE in addition to footer, header is also supported -footer: - font_size: $base_font_size_small - # NOTE if background_color is set, background and border will span width of page - #border_color: dddddd # EE - #border_width: 0.25 # EE - height: $base_line_height_length * 2.5 - line_height: 1 - padding: [$base_line_height_length / 2, 1, 0, 1] - vertical_align: top - #image_vertical_align: or - # additional attributes for content: - # * {page-count} - # * {page-number} - # * {document-title} - # * {document-subtitle} - # * {chapter-title} - # * {section-title} - # * {section-or-chapter-title} - recto: - #columns: "<50% =0% >50%" - right: - #content: '{page-number}' # EE - #content: '{section-or-chapter-title} | {page-number}' - #content: '{document-title} | {page-number}' - content: '{document-title}{nbsp}{nbsp}{nbsp} *{page-number}*' # EE - #center: - # content: '{page-number}' - left: # EE - content: '{status}' # EE - verso: - #columns: $footer_recto_columns - left: - #content: $footer_recto_right_content # EE - #content: '{page-number} | {chapter-title}' - content: '*{page-number}* {nbsp}{nbsp}{nbsp}{document-title}' # EE - #center: - # content: '{page-number}' - right: # EE - content: '{status}' # EE -header: # EE - font_size: $base_font_size_small # EE - border_color: dddddd # EE - border_width: 0.25 # EE - height: $base_line_height_length * 2.5 # EE - line_height: 1 # EE - padding: [$base_line_height_length / 2, 1, 0, 1] # EE - vertical_align: top # EE - recto: # EE - right: # EE - content: '{section-or-chapter-title}' # EE - verso: # EE - left: # EE - content: '{section-or-chapter-title}' # EE