Replace README.md with auto built flat README.adocs

.github/workflows/reduce_readme.yml

@@ -0,0 +1,47 @@
+name: JBoss EAP 8.0 Quickstarts Update 'README.adoc's
+
+on:
+  push:
+    branches:
+      - 8.0.x
+
+# Only run the latest job
+concurrency:
+  group: '${{ github.workflow }} @ ${{ github.ref || github.run_id }}'
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout Repository
+      uses: actions/checkout@v4
+    - name: Install Asciidoctor Reducer
+      run: sudo gem install asciidoctor-reducer
+    - name: Reduce README
+      run: |
+        CURRENT_DIR="$( pwd -P)"
+        #Get a list of subdirectories that don't start with a .
+        subdirs=`find . -maxdepth 1 -type d ! -iname ".*"`
+        #Loop over the subdirectories
+        for subdir in $subdirs
+        do
+        cd $subdir
+        #Check if the directory contains README-source.adoc
+        if [ -e README-source.adoc ]
+        then
+        #Get the dirname to define artifactId in the adoc
+        ARTIFACT_ID=":artifactId: $(basename `pwd`)"
+        #Use asciidoctor-reducer to create a flattened README.adoc
+        asciidoctor-reducer --preserve-conditionals -o README.adoc README-source.adoc
+        #Insert the directory name with env-github def so that this only affects GitHub rendering
+        sed -i "1s/^/ifdef::env-github[]\n$ARTIFACT_ID\nendif::[]\n\n/" README.adoc
+        fi
+        cd $CURRENT_DIR
+        done
+        #Reduce root README
+        asciidoctor-reducer --preserve-conditionals -o README.adoc README-source.adoc
+    - name: Commit and Push README
+      uses: EndBug/add-and-commit@v9
+      with:
+        add: '*.adoc'

cmt/README-source.adoc

@@ -0,0 +1,86 @@
+include::../shared-doc/attributes.adoc[]
+
+= cmt: Container Managed Transactions (CMT)
+:author: Tom Jenkinson
+:level: Intermediate
+:technologies: EJB, CMT, JMS
+:openshift: true
+
+[abstract]
+The `cmt` quickstart demonstrates Container-Managed Transactions (CMT), showing how to use transactions managed by the container.
+
+:standalone-server-type: full
+:archiveType: war
+:uses-h2:
+
+== What is it?
+
+The `cmt` quickstart demonstrates how to use container-managed transactions (CMT), which are transactions managed by the container in {productNameFull}. It is a fairly typical scenario of updating a database and sending a JMS message in the same transaction. A simple MDB is provided that prints out the message sent but this is not a transactional MDB and is purely provided for debugging purposes.
+
+Aspects touched upon in the code:
+
+* XA transaction control using the container managed transaction annotations
+* XA access to the standard default datasource using the JPA API
+* XA access to a JMS queue
+
+=== What are Container Managed Transactions?
+
+Prior to EJB, getting the right incantation to ensure sound transactional operation of the business logic was a highly specialized skill. Although this still holds true to a great extent, EJB has provided a series of improvements to allow simplified transaction demarcation notation that is therefore easier to read and test.
+
+With CMT, the EJB container sets the boundaries of a transaction. This differs from BMT (bean-managed transactions), where the developer is responsible for initiating and completing a transaction using the `begin`, `commit`, and `rollback` methods on a `jakarta.transaction.UserTransaction`.
+
+=== What Makes This an Example of Container Managed Transactions?
+
+Take a look at `org.jboss.as.quickstarts.cmt.ejb.CustomerManagerEJB`. You can see that this stateless session bean has been marked up with the `@jakarta.ejb.TransactionAttribute` annotation.
+
+The following options are available for this annotation.
+
+Required:: As demonstrated in the quickstart. If a transaction does not already exist, this will initiate a transaction and complete it for you, otherwise the business logic will be integrated into the existing transaction.
+RequiresNew:: If there is already a transaction running, it will be suspended, the work performed within a new transaction which is completed at exit of the method and then the original transaction resumed.
+Mandatory:: If there is no transaction running, calling a business method with this annotation will result in an error.
+NotSupported:: If there is a transaction running, it will be suspended and no transaction will be initiated for this business method.
+Supports:: This will run the method within a transaction if a transaction exists, alternatively, if there is no transaction running, the method will not be executed within the scope of a transaction.
+Never:: If the client has a transaction running and does not suspend it but calls a method annotated with Never then an EJB exception will be raised.
+
+// Considerations for Use in a Production Environment
+include::../shared-doc/development-shortcuts.adoc[leveloffset=+1]
+// System Requirements
+include::../shared-doc/system-requirements.adoc[leveloffset=+1]
+// Use of {jbossHomeName}
+include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1]
+
+// build and run with standard server distribution
+[[build_and_run_the_quickstart_with_server_dist]]
+== Building and running the quickstart application with a {productName} server distribution
+// Start the {productName} Standalone Server
+include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+2]
+// Build and Deploy the Quickstart
+include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+2]
+
+=== Access the Application
+
+The application will be running at the following URL: http://localhost:8080/{artifactId}/
+
+You are presented with a simple form for adding customers to a database.
+
+After a customer is successfully added to the database, a message is produced containing the details of the customer. An example MDB dequeues this message and print the following contents.
+
+[source,options="nowrap"]
+----
+Received Message: Created invoice for customer named:  Jack
+----
+
+If an existing customer name is provided, no JMS message is sent. Instead of the above message, a duplicate warning is displayed.
+
+The customer name should match: letter & '-', otherwise an error is given. This is to show that a `LogMessage` entity is still stored in the database. That is because the `logCreateCustomer` method in the `LogMessageManagerEJB` EJB is decorated with the `@TransactionAttribute(TransactionAttributeType.REQUIRES_NEW)` annotation.
+
+// Testing with Arquillian
+include::../shared-doc/run-arquillian-integration-tests-with-server-distribution.adoc[leveloffset=+2]
+// Undeploy the Quickstart
+include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2]
+
+// Build and run sections for other environments/builds
+ifndef::ProductRelease,EAPXPRelease[]
+include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1]
+endif::[]
+include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1]

ee-security/README-source.adoc

@@ -0,0 +1,131 @@
+include::../shared-doc/attributes.adoc[]
+
+= ee-security: Using Jakarta EE Security
+:author: Darran Lofthouse
+:level: Intermediate
+:technologies: EE Security, Servlet, CDI
+:openshift: true
+
+[abstract]
+The `ee-security` quickstart demonstrates Jakarta EE security.
+
+:standalone-server-type: default
+:archiveType: war
+:restoreScriptName: restore-configuration.cli
+
+== What is it?
+
+The `ee-security` quickstart is an example project showing the use of Jakarta EE security in {productNameFull}.
+
+The deployment in this quickstart contains a simple HTTP servlet, which is secured using a custom `HttpAuthenticationMechanism`. The authentication mechanism in turn makes use of a custom `IdentityStore`.
+
+This quickstart is hard coded to work with a user `quickstartUser` with password `quickstartPwd1!`.
+
+// System Requirements
+include::../shared-doc/system-requirements.adoc[leveloffset=+1]
+// Use of {jbossHomeName}
+include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1]
+
+// build and run with standard server distribution
+[[build_and_run_the_quickstart_with_server_dist]]
+== Building and running the quickstart application with a {productName} server distribution
+// Back Up the {productName} Standalone Server Configuration
+include::../shared-doc/back-up-server-standalone-configuration.adoc[leveloffset=+2]
+// Start the {productName} Standalone Server
+include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+2]
+
+[[configure_the_server]]
+=== Configure the Server
+
+You configure the security domain by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a `configure-elytron.cli` script provided in the root directory of this quickstart.
+
+. Before you begin, make sure you do the following:
+
+* xref:back_up_standalone_server_configuration[Back up the {productName} standalone server configuration] as described above.
+* xref:start_the_eap_standalone_server[Start the {productName} server with the standalone default profile] as described above.
+
+. Review the `configure-elytron.cli` file in the root of this quickstart directory. This script adds the configuration that enables Elytron security for the quickstart components. Comments in the script describe the purpose of each block of commands.
+. Open a new terminal, navigate to the root directory of this quickstart, and run the following command, replacing `__{jbossHomeName}__` with the path to your server:
++
+[source,subs="+quotes,attributes+",options="nowrap"]
+----
+$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=configure-elytron.cli
+----
++
+NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script.
++
+
+You should see the following result when you run the script:
++
+[source,options="nowrap"]
+----
+The batch executed successfully
+process-state: reload-required
+----
+
+. You'll need to reload the configuration after that:
++
+[source,subs="+quotes,attributes+",options="nowrap"]
+----
+$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --commands=reload
+----
+
+// Build and Deploy the Quickstart
+include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+2]
+
+=== Access the Application
+
+The application will be running at the following URL: http://localhost:8080/{artifactId}/secured
+
+NOTE: If you attempt to access that URL, you will see "Unauthorized".
+
+To see and manipulate the HTTP headers within the HTTP requests, it is recommended to use a client like `curl` to invoke the servlet.
+
+[source,options="nowrap"]
+----
+$ curl -v http://localhost:8080/ee-security/secured
+...
+< HTTP/1.1 401 Unauthorized
+< Connection: keep-alive
+< X-MESSAGE: Please resubmit the request with a username specified using the X-USERNAME and a password specified using the X-PASSWORD header.
+----
+
+This first request shows the client is being prompted to authenticate. The `X-MESSAGE` header is providing additional information as to how the client can achieve this.
+
+The request can now be submitted with the previously added user.
+
+[source,options="nowrap"]
+----
+$ curl -v http://localhost:8080/ee-security/secured -H 'X-Username:quickstartUser' -H 'X-Password:quickstartPwd1!'
+...
+> GET /ee-security/secured HTTP/1.1
+> Host: localhost:8080
+> X-Username:quickstartUser
+> X-Password:quickstartPwd1!
+>
+< HTTP/1.1 200 OK
+< Connection: keep-alive
+< Content-Length: 125
+<
+SecuredServlet - doGet()
+Identity as available from SecurityContext 'quickstartUser'
+Identity as available from injection 'quickstartUser'
+----
+
+The resulting output shows authentication was successful and the correct identity has been established.
+
+// Testing with Arquillian
+include::../shared-doc/run-arquillian-integration-tests-with-server-distribution.adoc[leveloffset=+2]
+// Undeploy the Quickstart
+include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2]
+//  Restore the {productName} Standalone Server Configuration
+include::../shared-doc/restore-standalone-server-configuration.adoc[leveloffset=+2]
+// Restore the {productName} Standalone Server Configuration Manually
+include::../shared-doc/restore-standalone-server-configuration-manual.adoc[leveloffset=+3]
+
+// Build and run sections for other environments/builds
+ifndef::ProductRelease,EAPXPRelease[]
+include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1]
+endif::[]
+include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1]
+

helloworld-ws/README-source.adoc

@@ -0,0 +1,79 @@
+include::../shared-doc/attributes.adoc[]
+
+= helloworld-ws: Hello World JAX-WS Web Service
+:author: Lee Newson
+:level: Beginner
+:technologies: JAX-WS
+:openshift: true
+
+[abstract]
+The `helloworld-ws` quickstart demonstrates a simple Hello World application, bundled and deployed as a WAR, that uses JAX-WS to say Hello.
+
+:standalone-server-type: default
+:archiveType: war
+
+== What is it?
+
+The `helloworld-ws` quickstart demonstrates the use of JAX-WS in {productNameFull} as a simple Hello World application.
+
+// System Requirements
+include::../shared-doc/system-requirements.adoc[leveloffset=+1]
+// Use of {jbossHomeName}
+include::../shared-doc/use-of-jboss-home-name.adoc[leveloffset=+1]
+
+// build and run with standard server distribution
+[[build_and_run_the_quickstart_with_server_dist]]
+== Building and running the quickstart application with a {productName} server distribution
+// Start the {productName} Standalone Server
+include::../shared-doc/start-the-standalone-server.adoc[leveloffset=+2]
+// Build and Deploy the Quickstart
+include::../shared-doc/build-and-deploy-the-quickstart.adoc[leveloffset=+2]
+
+Review the server log to see useful information about the deployed web service endpoint.
+
+[source,options="nowrap"]
+----
+JBWS024061: Adding service endpoint metadata: id=org.jboss.as.quickstarts.wshelloworld.HelloWorldServiceImpl
+ address=http://localhost:8080/{artifactId}/HelloWorldService
+ implementor=org.jboss.as.quickstarts.wshelloworld.HelloWorldServiceImpl
+ serviceName={http://www.jboss.org/eap/quickstarts/wshelloworld/HelloWorld}HelloWorldService
+ portName={http://www.jboss.org/eap/quickstarts/wshelloworld/HelloWorld}HelloWorld
+ annotationWsdlLocation=null
+ wsdlLocationOverride=null
+ mtomEnabled=false
+----
+
+=== Access the Application
+
+You can verify that the Web Service is running and deployed correctly by accessing the following URL: http://localhost:8080/{artifactId}/HelloWorldService?wsdl. This URL will display the deployed WSDL endpoint for the Web Service.
+
+// Testing with Arquillian
+include::../shared-doc/run-arquillian-integration-tests-with-server-distribution.adoc[leveloffset=+2]
+
+=== Investigate the Console Output
+
+When you run the Arquillian tests, Maven prints summary of the performed tests to the console. You should see the following results.
+
+[source,options="nowrap"]
+----
+-------------------------------------------------------
+T E S T S
+-------------------------------------------------------
+Running org.jboss.as.quickstarts.wshelloworld.ClientArqTest
+[Client] Requesting the WebService to say Hello.
+[WebService] Hello World!
+[Client] Requesting the WebService to say Hello to John.
+[WebService] Hello John!
+[Client] Requesting the WebService to say Hello to John, Mary and Mark.
+[WebService] Hello John, Mary & Mark!
+Tests run: 3, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 1.988 sec
+----
+
+// Undeploy the Quickstart
+include::../shared-doc/undeploy-the-quickstart.adoc[leveloffset=+2]
+
+// Build and run sections for other environments/builds
+ifndef::ProductRelease,EAPXPRelease[]
+include::../shared-doc/build-and-run-the-quickstart-with-provisioned-server.adoc[leveloffset=+1]
+endif::[]
+include::../shared-doc/build-and-run-the-quickstart-with-openshift.adoc[leveloffset=+1]