diff --git a/README.adoc b/README.adoc index 8969c1b0e0..a40d99ff9a 100644 --- a/README.adoc +++ b/README.adoc @@ -9,32 +9,35 @@ include::attributes.adoc[] [abstract] The quickstarts demonstrate Java EE 7 and a few additional technologies from the JBoss stack. They provide small, specific, working examples that can be used as a reference for your own project. +[[introduction]] == Introduction These quickstarts run on {productNameFull} {productVersion} or later. We recommend using the {productName} ZIP file. This version uses the correct dependencies and ensures you test and compile against your runtime environment. Be sure to read this entire document before you attempt to work with the quickstarts. It contains the following information: -* <>: List of the available quickstarts and details about each one. +* <>: List of the available quickstarts and details about each one. -* <>: A suggested approach on how to work with the quickstarts. +* <>: A suggested approach on how to work with the quickstarts. -* <>: List of software required to run the quickstarts. +* <>: List of software required to run the quickstarts. -* https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven]: How to configure the Maven repository for use by the quickstarts. +* link:{configureMavenDocUrl}[Configure Maven]: How to configure the Maven repository for use by the quickstarts. -* <>: General instructions for building, deploying, and running the quickstarts. +* <>: General instructions for building, deploying, and running the quickstarts. -* https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests[Run the Arquillian Tests]: How to run the Arquillian tests provided by some of the quickstarts. +* link:{arquillianTestsDocUrl}[Run the Arquillian Tests]: How to run the Arquillian tests provided by some of the quickstarts. -* <>: How to install and configure optional components required by some of the quickstarts. +* <>: How to install and configure optional components required by some of the quickstarts. -* https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONTRIBUTING.md#jboss-developer-contributing-guide[Contributing Guide]: This document contains information targeted for developers who want to contribute to JBoss developer projects. +* https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONTRIBUTING.adoc#jboss_developer_contributing_guide[Contributing Guide]: This document contains information targeted for developers who want to contribute to JBoss developer projects. +[[use_of_product_home_and_jboss_home_variables]] == Use of {jbossHomeName} and JBOSS_HOME Variables -The quickstart README files use the _replaceable_ value `{jbossHomeName}` to denote the path to the {productName} installation. When you encounter this value in a README file, be sure to replace it with the actual path to your {productName} installation. The installation path is described in detail here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_{jbossHomeName}.md#use-of-eap_home-and-jboss_home-variables[Use of {jbossHomeName} and JBOSS_HOME Variables]. +The quickstart README files use the _replaceable_ value `__{jbossHomeName}__` to denote the path to the {productName} installation. When you encounter this value in a README file, be sure to replace it with the actual path to your {productName} installation. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of {jbossHomeName} and JBOSS_HOME Variables]. +[[available_quickstarts]] == Available Quickstarts All available quickstarts can be found here: http://www.jboss.org/developer-materials/#!formats=jbossdeveloper_quickstart. You can filter by the quickstart name, the product, and the technologies demonstrated by the quickstart. You can also limit the results based on skill level and date published. The resulting page provides a brief description of each matching quickstart, the skill level, and the technologies used. Click on the quickstart to see more detailed information about how to run it. Some quickstarts require deployment of other quickstarts. This information is noted in the `Prerequisites` section of the quickstart README file. @@ -44,7 +47,7 @@ NOTE: Some of these quickstarts use the H2 database included with {productName}. // [cols="1,1,2,1,1", options="header"] |=== -| Quickstart Name | Demonstrated Technologies | Description | Experience Level Required | Prerequisites +| Quickstart Name | Demonstrated Technologies | Description | Experience Level Required | Prerequisites | link:app-client/README{outfilesuffix}[app-client]|EJB, EAR, AppClient | The `app-client` quickstart demonstrates how to code and package a client app and use the {productName} client container to start the client Main program. | Intermediate | _none_ | link:batch-processing/README{outfilesuffix}[batch-processing]|CDI, Batch 1.0, JSF | The `batch-processing` quickstart shows how to use chunk oriented batch jobs to import a file to a database. | Intermediate | _none_ | link:bean-validation/README{outfilesuffix}[bean-validation]|CDI, JPA, BV | The `bean-validation` quickstart provides Arquillian tests to demonstrate how to use CDI, JPA, and Bean Validation. | Beginner | _none_ @@ -64,7 +67,7 @@ NOTE: Some of these quickstarts use the H2 database included with {productName}. | link:ejb-security-context-propagation/README{outfilesuffix}[ejb-security-context-propagation]|EJB, Security | The `ejb-security-context-propagation` quickstart demonstrates how the security context can be propagated to a remote EJB using a remote outbound connection configuration | Advanced | _none_ | link:ejb-security-jaas/README{outfilesuffix}[ejb-security-jaas]|EJB, Security | The `ejb-security-jaas` quickstart demonstrates how legacy `JAAS` security domains can be used in conjunction with `Elytron` | Intermediate | _none_ | link:ejb-security-programmatic-auth/README{outfilesuffix}[ejb-security-programmatic-auth]|EJB, Security | The `ejb-security-programmatic-auth` quickstart demonstrates how to programmatically setup different identities when invoking a remote secured EJB. | Intermediate | _none_ -| link:ejb-throws-exception/README{outfilesuffix}[ejb-throws-exception]|EJB, EAR | The `ejb-throws-exception` quickstart demonstrates how to throw and handle Exceptions across JARs in an EAR. | Intermediate | _none_ +| link:ejb-throws-exception/README{outfilesuffix}[ejb-throws-exception]|EJB, EAR | The `ejb-throws-exception` quickstart demonstrates how to throw and handle exceptions across JARs in an EAR. | Intermediate | _none_ | link:ejb-timer/README{outfilesuffix}[ejb-timer]|EJB Timer | The `ejb-timer` quickstart demonstrates how to use the EJB timer service `@Schedule` and `@Timeout` annotations with {productName}. | Beginner | _none_ | link:forge-from-scratch/README{outfilesuffix}[forge-from-scratch]|Forge | The `forge-from-scratch` quickstart demonstrates how *JBoss Forge* can generate a Java EE (JPA, EJB, JAX-RS, JSF) web-enabled database application. | Intermediate | _none_ | link:greeter/README{outfilesuffix}[greeter]|CDI, JSF, JPA, EJB, JTA | The `greeter` quickstart demonstrates the use of *CDI*, *JPA*, *JTA*, *EJB* and *JSF* in {productName}. | Beginner | _none_ @@ -74,7 +77,7 @@ NOTE: Some of these quickstarts use the H2 database included with {productName}. | link:helloworld-classfiletransformer/README{outfilesuffix}[helloworld-classfiletransformer]|ClassLoading | This is a WAR based application showing you how Wildfly let you apply a ClassTransformer to the classes in your enterprise archive. | Advanced | _none_ | link:helloworld-html5/README{outfilesuffix}[helloworld-html5]|CDI, JAX-RS, HTML5 | The `helloworld-html5` quickstart demonstrates the use of *CDI 1.2* and *JAX-RS 2.0* using the HTML5 architecture and RESTful services on the backend. | Beginner | _none_ | link:helloworld-jms/README{outfilesuffix}[helloworld-jms]|JMS | The `helloworld-jms` quickstart demonstrates the use of external JMS clients with {productName}. | Intermediate | _none_ -| link:helloworld-mbean/README{outfilesuffix}[helloworld-mbean]|CDI, JMX, MBean | The `helloworld-mbean` quickstart demonstrates the use of *CDI* and *MBean* in {productName} and includes JConsole instructions and Arquillian tests. | Intermediate | _none_ +| link:helloworld-mbean/README{outfilesuffix}[helloworld-mbean]|CDI, JMX, MBean | The `helloworld-mbean` quickstart demonstrates the use of CDI and MBean in {productName} and includes JConsole instructions and Arquillian tests. | Intermediate | _none_ | link:helloworld-mdb/README{outfilesuffix}[helloworld-mdb]|JMS, EJB, MDB | The `helloworld-mdb` quickstart uses *JMS* and *EJB Message-Driven Bean* (MDB) to create and deploy JMS topic and queue resources in {productName}. | Intermediate | _none_ | link:helloworld-mdb-propertysubstitution/README{outfilesuffix}[helloworld-mdb-propertysubstitution]|JMS, EJB, MDB | The `helloworld-mdb-propertysubstitution` quickstart demonstrates the use of *JMS* and *EJB MDB*, enabling property substitution with annotations. | Intermediate | _none_ | link:helloworld-mutual-ssl/README{outfilesuffix}[helloworld-mutual-ssl]|Mutual SSL, Undertow | The `helloworld-mutual-ssl` quickstart is a basic example that demonstrates mutual SSL configuration in {productName} | Intermediate | _none_ @@ -94,8 +97,8 @@ NOTE: Some of these quickstarts use the H2 database included with {productName}. | link:jaxws-retail/README{outfilesuffix}[jaxws-retail]|JAX-WS | The `jaxws-retail` quickstart is a working example of a simple web service endpoint. | Beginner | _none_ | link:jsonp/README{outfilesuffix}[jsonp]|CDI, JSF, JSON-P | The `jsonp` quickstart demonstrates how to use the JSON-P API to produce object-based structures and then parse and consume them as stream-based JSON strings. | Beginner | _none_ | link:jta-crash-rec/README{outfilesuffix}[jta-crash-rec]|JTA, Crash Recovery | The `jta-crash-rec` quickstart uses JTA and Byteman to show how to code distributed (XA) transactions in order to preserve ACID properties on server crash. | Advanced | _none_ -| link:jts/README{outfilesuffix}[jts]|JTS, EJB, JMS | The `jts` quickstart shows how to use JTS to perform distributed transactions across multiple containers, fulfilling the properties of an ACID transaction. | Intermediate | cmt -| link:jts-distributed-crash-rec/README{outfilesuffix}[jts-distributed-crash-rec]|JTS, Crash Recovery | The `jts-distributed-crash-rec` quickstart uses JTS and Byteman to demonstrate distributed crash recovery across multiple application servers. | Advanced | jts +| link:jts/README{outfilesuffix}[jts]|JTS, EJB, JMS | The `jts` quickstart shows how to use JTS to perform distributed transactions across multiple containers, fulfilling the properties of an ACID transaction. | Intermediate | link:cmt/README{outfilesuffix}[cmt] +| link:jts-distributed-crash-rec/README{outfilesuffix}[jts-distributed-crash-rec]|JTS, Crash Recovery | The `jts-distributed-crash-rec` quickstart uses JTS and Byteman to demonstrate distributed crash recovery across multiple application servers. | Advanced | link:jts/README{outfilesuffix}[jts] | link:kitchensink/README{outfilesuffix}[kitchensink]|CDI, JSF, JPA, EJB, JAX-RS, BV | The `kitchensink` quickstart demonstrates a Java EE 7 web-enabled database application using JSF, CDI, EJB, JPA, and Bean Validation. | Intermediate | _none_ | link:kitchensink-angularjs/README{outfilesuffix}[kitchensink-angularjs]|AngularJS, CDI, JPA, EJB, JPA, JAX-RS, BV | The `kitchensink-angularjs` quickstart demonstrates a Java EE 7 application using AngularJS with JAX-RS, CDI, EJB, JPA, and Bean Validation. | Intermediate | _none_ | link:kitchensink-ear/README{outfilesuffix}[kitchensink-ear]|CDI, JSF, JPA, EJB, JAX-RS, BV, EAR | The `kitchensink-ear` quickstart demonstrates web-enabled database application, using JSF, CDI, EJB, JPA, and Bean Validation, packaged as an EAR. | Intermediate | _none_ @@ -104,15 +107,15 @@ NOTE: Some of these quickstarts use the H2 database included with {productName}. | link:kitchensink-ml/README{outfilesuffix}[kitchensink-ml]|CDI, JSF, JPA, EJB, JAX-RS, BV, i18n, l10n | The `kitchensink-ml` quickstart demonstrates a localized Java EE 7 compliant application using JSF, CDI, EJB, JPA, and Bean Validation. | Intermediate | _none_ | link:kitchensink-utjs-angularjs/README{outfilesuffix}[kitchensink-utjs-angularjs]|Undertow.js, Angular.js | Based on kitchensink, but uses a Angular for the front end and Undertow.js for the back end. | Intermediate | _none_ | link:kitchensink-utjs-mustache/README{outfilesuffix}[kitchensink-utjs-mustache]|Undertow.js, Mustache | Based on kitchensink, but uses Mustache for the front end and Undertow.js for the back end. | Intermediate | _none_ -| link:logging/README{outfilesuffix}[logging]|Logging | The `logging` quickstart demonstrates how to configure different logging levels in {productName}. It also includes an asynchronous logging example. | Intermediate | None +| link:logging/README{outfilesuffix}[logging]|Logging | The `logging` quickstart demonstrates how to configure different logging levels in {productName}. It also includes an asynchronous logging example. | Intermediate | _none_ | link:logging-tools/README{outfilesuffix}[logging-tools]|JBoss Logging Tools | The `logging-tools` quickstart shows how to use JBoss Logging Tools to create internationalized loggers, exceptions, and messages and localize them. | Beginner | _none_ | link:mail/README{outfilesuffix}[mail]|JavaMail, CDI, JSF | The `mail` quickstart demonstrates how to send email using CDI and JSF and the default Mail provider that ships with {productName}. | Beginner | _none_ | link:managed-executor-service/README{outfilesuffix}[managed-executor-service]|EE Concurrency Utilities, JAX-RS, JAX-RS Client API | The `managed-executor-service` quickstart demonstrates how Java EE applications can submit tasks for asynchronous execution. | Beginner | _none_ -| link:messaging-clustering/README{outfilesuffix}[messaging-clustering]|JMS, MDB | The `messaging-clustering` quickstart does not contain any code and instead uses the `helloworld-mdb` quickstart to demonstrate clustering using ActiveMQ Messaging. | Intermediate | helloworld-mdb +| link:messaging-clustering/README{outfilesuffix}[messaging-clustering]|JMS, MDB | The `messaging-clustering` quickstart does not contain any code and instead uses the `helloworld-mdb` quickstart to demonstrate clustering using ActiveMQ Messaging. | Intermediate | link:helloworld-mdb/README{outfilesuffix}[helloworld-mdb] | link:messaging-clustering-singleton/README{outfilesuffix}[messaging-clustering-singleton]|JMS, MDB, Clustering | The `messaging-clustering-singleton` quickstart uses a JMS topic and a queue to demonstrate clustering using {productName} messaging with MDB singleton configuration where only one node in the cluster will be active. | Advanced | _none_ | link:numberguess/README{outfilesuffix}[numberguess]|CDI, JSF | The `numberguess` quickstart demonstrates the use of *CDI* (Contexts and Dependency Injection) and *JSF* (JavaServer Faces) in {productName}. | Beginner | _none_ | link:payment-cdi-event/README{outfilesuffix}[payment-cdi-event]|CDI, JSF | The `payment-cdi-event` quickstart demonstrates how to create credit and debit *CDI Events* in {productName}, using a JSF front-end client. | Beginner | _none_ -| link:resteasy-jaxrs-client/README{outfilesuffix}[resteasy-jaxrs-client]|JAX-RS, CDI | The `resteasy-jaxrs-client` quickstart demonstrates an external JAX-RS RestEasy client, which interacts with a JAX-RS Web service that uses *CDI* and *JAX-RS*. | Intermediate | helloworld-rs +| link:resteasy-jaxrs-client/README{outfilesuffix}[resteasy-jaxrs-client]|JAX-RS, CDI | The `resteasy-jaxrs-client` quickstart demonstrates an external JAX-RS RestEasy client, which interacts with a JAX-RS Web service that uses *CDI* and *JAX-RS*. | Intermediate | link:helloworld-rs/README{outfilesuffix}[helloworld-rs] | link:security-domain-to-domain/README{outfilesuffix}[security-domain-to-domain]|Servlet, EJB, Security | The `security-domain-to-domain` quickstart demonstrates the propagation of an identity across two different deployments using different security domains. | Advanced | _none_ | link:servlet-async/README{outfilesuffix}[servlet-async]|Asynchronous Servlet, CDI, EJB | The `servlet-async` quickstart demonstrates how to use asynchronous servlets to detach long-running tasks and free up the request processing thread. | Intermediate | _none_ | link:servlet-filterlistener/README{outfilesuffix}[servlet-filterlistener]|Servlet Filter, Servlet Listener | The `servlet-filterlistener` quickstart demonstrates how to use Servlet filters and listeners in an application. | Intermediate | _none_ @@ -125,8 +128,8 @@ NOTE: Some of these quickstarts use the H2 database included with {productName}. | link:spring-petclinic/README{outfilesuffix}[spring-petclinic]|JPA, Junit, JMX, Spring MVC Annotations, AOP, Spring Data, JSP, webjars, Dandellion | The `spring-petclinic` quickstart shows how to run the Spring PetClinic Application in {productName} using the {productName} BOMs. | Advanced | _none_ | link:spring-resteasy/README{outfilesuffix}[spring-resteasy]|Resteasy, Spring | The `spring-resteasy` quickstart demonstrates how to package and deploy a web application that includes resteasy-spring integration. | Beginner | _none_ | link:tasks/README{outfilesuffix}[tasks]|JPA, Arquillian | The `tasks` quickstart includes a persistence unit and sample persistence code to demonstrate how to use JPA for database access in {productName}. | Intermediate | _none_ -| link:tasks-jsf/README{outfilesuffix}[tasks-jsf]|JSF, JPA | The `tasks-jsf` quickstart demonstrates how to use JPA persistence with JSF as the view layer. | Intermediate | tasks -| link:tasks-rs/README{outfilesuffix}[tasks-rs]|JPA, JAX-RS | The `tasks-rs` quickstart demonstrates how to implement a JAX-RS service that uses JPA persistence. | Intermediate | tasks +| link:tasks-jsf/README{outfilesuffix}[tasks-jsf]|JSF, JPA | The `tasks-jsf` quickstart demonstrates how to use JPA persistence with JSF as the view layer. | Intermediate | link:tasks/README{outfilesuffix}[tasks] +| link:tasks-rs/README{outfilesuffix}[tasks-rs]|JPA, JAX-RS | The `tasks-rs` quickstart demonstrates how to implement a JAX-RS service that uses JPA persistence. | Intermediate | link:tasks/README{outfilesuffix}[tasks] | link:temperature-converter/README{outfilesuffix}[temperature-converter]|CDI, JSF, SLSB EJB | The `temperature-converter` quickstart does temperature conversion using an *EJB Stateless Session Bean* (SLSB), *CDI*, and a *JSF* front-end client. | Beginner | _none_ | link:thread-racing/README{outfilesuffix}[thread-racing]|Batch, CDI, EE Concurrency, JAX-RS, JMS, JPA, JSON, Web Sockets | A thread racing web application that demonstrates technologies introduced or updated in the latest Java EE specification. | Beginner | _none_ | link:websocket-client/README{outfilesuffix}[websocket-client]|Web Socket, CDI Events, JSON, SSL | Demonstrates use of a Javascript WebSocket client, WebSocket configuration, programmatic binding, and secure WebSocket. | Intermediate | _none_ @@ -141,66 +144,73 @@ NOTE: Some of these quickstarts use the H2 database included with {productName}. |=== // +[[suggested_approach_to_the_quickstarts]] == Suggested Approach to the Quickstarts We suggest you approach the quickstarts as follows: -* Regardless of your level of expertise, we suggest you start with the *helloworld* quickstart. It is the simplest example and is an easy way to prove your server is configured and started correctly. -* If you are a beginner or new to JBoss, start with the quickstarts labeled *Beginner*, then try those marked as *Intermediate*. When you are comfortable with those, move on to the *Advanced* quickstarts. +* Regardless of your level of expertise, we suggest you start with the `helloworld` quickstart. It is the simplest example and is an easy way to prove your server is configured and started correctly. +* If you are a beginner or new to JBoss, start with the quickstarts labeled `Beginner`, then try those marked as `Intermediate`. When you are comfortable with those, move on to the `Advanced` quickstarts. * Some quickstarts are based upon other quickstarts but have expanded capabilities and functionality. If a prerequisite quickstart is listed, be sure to deploy and test it before looking at the expanded version. +[[system_requirements]] == System Requirements The applications these projects produce are designed to be run on {productNameFull} {productVersion} or later. -All you need to build these projects is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build these projects is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. To run these quickstarts with the provided build scripts, you need the {productName} distribution ZIP. For information on how to install and run JBoss, see the https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/[{productNameFull} Documentation] _Getting Started Guide_ located on the Customer Portal. -You can also use <> to run the quickstarts. +You can also use <> to run the quickstarts. +[[run_the_quickstarts]] == Run the Quickstarts The root folder of each individual quickstart contains a README file with specific details on how to build and run the example. In most cases you do the following: -* https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/START_JBOSS_EAP.md#start-the-jboss-eap-server[Start the {productName} Server] -* <> +* link:{StartServerDocUrl}[Start the {productName} Server] +* <> +[[build_and_deploy_the_quickstarts]] === Build and Deploy the Quickstarts See the README file in each individual quickstart folder for specific details and information on how to run and access the example. +[[build_the_quickstart_archive]] ==== Build the Quickstart Archive -In most cases, you can use the following steps to build the application to test for compile errors or to view the contents of the archive. See the specific quickstart README file for complete details. +In most cases, you can use the following steps to build the application to test for compile errors or to view the contents of the archive. See the specific quickstart `README` file for complete details. -. Open a command prompt and navigate to the root directory of the quickstart you want to build. +. Open a terminal and navigate to the root directory of the quickstart you want to build. . Use this command if you only want to build the archive, but not deploy it: ---- -mvn clean install +$ mvn clean install ---- - +[[build_and_deploy_the_quickstart_archive]] ==== Build and Deploy the Quickstart Archive In most cases, you can use the following steps to build and deploy the application. See the specific quickstart README file for complete details. . Make sure you start the {productName} server as described in the quickstart README file. -. Open a command prompt and navigate to the root directory of the quickstart you want to run. +. Open a terminal and navigate to the root directory of the quickstart you want to run. . Use this command to build and deploy the archive: + ---- -mvn clean install wildfly:deploy +$ mvn clean install wildfly:deploy ---- +[[undeploy_an_archive]] ==== Undeploy an Archive The command to undeploy the quickstart is simply: ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- +[[verify_the_quickstarts_build_with_one_command]] === Verify the Quickstarts Build with One Command You can verify the quickstarts build using one command. However, quickstarts that have complex dependencies must be skipped. For example, the `resteasy-jaxrs-client` quickstart is a RESTEasy client that depends on the deployment of the `helloworld-rs` quickstart. As noted above, the root `pom.xml` file defines a `complex-dependencies` profile to exclude these quickstarts from the root build process. @@ -208,13 +218,14 @@ You can verify the quickstarts build using one command. However, quickstarts tha To build the quickstarts: . Do not start the {productName} server. -. Open a command prompt and navigate to the root directory of the quickstarts. +. Open a terminal and navigate to the root directory of the quickstarts. . Use this command to build the quickstarts that do not have complex dependencies: + ---- -mvn clean install '-Pdefault,!complex-dependencies' +$ mvn clean install '-Pdefault,!complex-dependencies' ---- +[[undeploy_the_deployed_quickstarts_with_one_command]] === Undeploy the Deployed Quickstarts with One Command To undeploy the quickstarts from the root of the quickstart folder, you must pass the argument `-fae` (fail at end) on the command line. This allows the command to continue past quickstarts that fail due to complex dependencies and quickstarts that only have Arquillian tests and do not deploy archives to the server. @@ -222,25 +233,27 @@ To undeploy the quickstarts from the root of the quickstart folder, you must pas You can undeploy quickstarts using the following procedure: . Start the {productName} server. -. Open a command prompt and navigate to the root directory of the quickstarts. +. Open a terminal and navigate to the root directory of the quickstarts. . Use this command to undeploy any deployed quickstarts: + ---- -mvn wildfly:undeploy -fae +$ mvn wildfly:undeploy -fae ---- To undeploy any quickstarts that fail due to complex dependencies, follow the undeploy procedure described in the quickstart's README file. +[[use_jboss_developer_studio_or_eclipse_to_run_the_quickstarts]] == Run the Quickstarts in Red Hat JBoss Developer Studio or Eclipse You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a {productName} server, and build and deploy a quickstart, see link:{useEclipseUrl}[Use JBoss Developer Studio or Eclipse to Run the Quickstarts]. +[[optional_components]] == Optional Components The following components are needed for only a small subset of the quickstarts. Do not install or configure them unless the quickstart requires it. -* https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CREATE_USERS.md#create-users-required-by-the-quickstarts[Create Users Required by the Quickstarts]: Add a Management or Application user for the quickstarts that run in a secured mode. +* link:{addUserDocUrl}[Create Users Required by the Quickstarts]: Add a Management or Application user for the quickstarts that run in a secured mode. -* https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_POSTGRESQL_EAP7.md#configure-the-postgresql-database-for-use-with-the-quickstarts[Configure the PostgreSQL Database for Use with the Quickstarts]: The PostgreSQL database is used for the distributed transaction quickstarts. +* link:{configurePostgresDocUrl}[Configure the PostgreSQL Database for Use with the Quickstarts]: The PostgreSQL database is used for the distributed transaction quickstarts. -* https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_BYTEMAN.md#configure-byteman-for-use-with-the-quickstarts[Configure Byteman for Use with the Quickstarts]: This tool is used to demonstrate crash recovery for distributed transaction quickstarts. +* link:{configureBytemanQuickstartsDocUrl}[Configure Byteman for Use with the Quickstarts]: This tool is used to demonstrate crash recovery for distributed transaction quickstarts. diff --git a/app-client/README.adoc b/app-client/README.adoc index ca067c9438..05d724c543 100644 --- a/app-client/README.adoc +++ b/app-client/README.adoc @@ -20,9 +20,9 @@ The `app-client` quickstart demonstrates how to use the {productName} client con This example consists of the following Maven projects, each with a shared parent: -[cols="<,<"] +[cols="30%,70%",options="headers"] |=== -|*Sub-project* |*Description* +|Sub-project |Description |`ejb` |An application that can be called by the `client`. |`ear` |The EAR packaging contains the server and client side. @@ -35,59 +35,57 @@ The root `pom.xml` file builds each of the subprojects in the appropriate order. The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Use of {jbossHomeName} -In the following instructions, replace `{jbossHomeName}` with the actual path to your {productName} installation. The installation path is described in detail here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_{jbossHomeName}.md#use-of-eap_home-and-jboss_home-variables[Use of {jbossHomeName} and JBOSS_HOME Variables]. +In the following instructions, replace `__{jbossHomeName}__` with the actual path to your {productName} installation. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of {jbossHomeName} and JBOSS_HOME Variables]. == Add the Application Users If the client and server are run on different hosts, you must add the following users to the {productName} server side application. Be sure to use the names and passwords specified in the table as they are required to run this example. -[cols="<,<,<,<"] +[cols="20%,20%,20%,40%",options="headers"] |=== -|*UserName* |*Realm* |*Password* |*Roles* +|UserName |Realm |Password |Roles -|admin |ManagementRealm |admin-123 |_leave blank for none_ -|quickuser |ApplicationRealm |quick-123 |_leave blank for none_ +|admin |ManagementRealm |admin-123 |_leave blank for none_ +|quickuser |ApplicationRealm |quick-123 |_leave blank for none_ |=== -To add the users, open a command prompt and type the following commands: +To add the users, open a terminal and type the following commands: - -[subs=normal] +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: - {jbossHomeName}/bin/add-user.sh -u admin -p admin-123 - {jbossHomeName}/bin/add-user.sh -a -u quickuser -p quick-123 - -For Windows: - {jbossHomeName}\bin\add-user.bat -u admin -p admin-123 - {jbossHomeName}\bin\add-user.bat -a -u quickuser -p quick-123 +$ __{jbossHomeName}__/bin/add-user.sh -u admin -p admin-123 +$ __{jbossHomeName}__/bin/add-user.sh -a -u quickuser -p quick-123 ---- -If you prefer, you can use the add-user utility interactively. For an example of how to use the add-user utility, see the instructions located here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CREATE_USERS.md#add-an-application-user[Add an Application User]. +NOTE: For Windows, use the `__{jbossHomeName}__\bin\add-user.bat` script. -== Start the Server +If you prefer, you can use the `add-user` utility interactively. For an example of how to use the add-user utility, see the instructions located here: link:{addApplicationUserDocUrl}[Add an Application User]. -. Open a command prompt and navigate to the root of the {productName} directory. -. The following shows the command line to start the server: +== Start the Server -[subs=normal] +. Open a terminal and navigate to the root of the {productName} directory. +. Use the following command to start the server: ++ +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +$ __{jbossHomeName}__/bin/standalone.sh ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. == Build and Deploy the Quickstart . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type this command to build the artifacts: - ++ +[source,options="nowrap"] ---- -mvn clean install wildfly:deploy +$ mvn clean install wildfly:deploy ---- == Access the Remote Client Application from the Same Machine @@ -95,15 +93,18 @@ mvn clean install wildfly:deploy This example shows how to invoke an EJB from a remote standalone application on the same machine. Both the client and server are on the same machine, so the defaults are sufficient and no authentication is necessary. . Be sure the quickstart deployed successfully as described above. -. Navigate to the root directory of this quickstart and type the following command to run the application. Be sure to replace `{jbossHomeName}` with the path to your {productName} installation. - +. Navigate to the root directory of this quickstart and type the following command to run the application. Be sure to replace `__{jbossHomeName}__` with the path to your {productName} installation. ++ +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/appclient.sh ear/target/app-client.ear#simpleClient.jar Hello from command line -For Windows: {jbossHomeName}\bin\appclient.bat ear\target\app-client.ear#simpleClient.jar Hello from command line +$ __{jbossHomeName}__/bin/appclient.sh ear/target/app-client.ear#simpleClient.jar Hello from command line ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\appclient.bat` script. -. Review the result. The client outputs the following information provided by the server application: - +. Review the result. The client outputs the following information, which is provided by the server application: ++ +[source,options="nowrap"] ---- [org.jboss.as.quickstarts.appclient.acc.client.Main] (Thread-51) Main started with arguments [org.jboss.as.quickstarts.appclient.acc.client.Main] (Thread-51) [Hello, from, command, line] @@ -111,9 +112,10 @@ For Windows: {jbossHomeName}\bin\appclient.bat ear\target\app-client.ear#simpleC ---- . Review the server log files to see the bean invocations on the server. - ++ +[source,options="nowrap"] ---- - ClientContext is here = {Client =dev84, jboss.source-address=localhost/127.0.0.1:45315} +ClientContext is here = {Client =dev84, jboss.source-address=localhost/127.0.0.1:45315} ---- == Access the Remote Client Application from a Different Machine @@ -124,49 +126,55 @@ This example shows how to invoke an EJB from a remote standalone Java EE applica . Install {productName} on this machine. . Add the application users to the {productName} server on this machine as described above. -. Start the {productName} server with the following command. Be sure to replace `MACHINE_1_IP_ADDRESS` with the IP address of this machine. These arguments make the server accessible to the network. - -[subs=normal] +. Start the {productName} server with the following command. Be sure to replace `__MACHINE_1_IP_ADDRESS__` with the IP address of this machine. These arguments make the server accessible to the network. ++ +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -b MACHINE_1_IP_ADDRESS -bmanagement MACHINE_1_IP_ADDRESS -For Windows: {jbossHomeName}\bin\standalone.bat -b MACHINE_1_IP_ADDRESS -bmanagement MACHINE_1_IP_ADDRESS +$ __{jbossHomeName}__/bin/standalone.sh -b __MACHINE_1_IP_ADDRESS__ -bmanagement __MACHINE_1_IP_ADDRESS__ ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. + === Configure Machine_2 (Local Client Machine) . Install {productName} on this server. There is no need to add the application users to this server. . Download the `app-client` quickstart to this machine. -. Create a `jboss-ejb-client.properties` file. This file can be located anywhere in the file system, but for ease of demonstration, we create it in the root directory of this quickstart. Add the following content, replacing `MACHINE_1_IP_ADDRESS` with the IP address of `Machine_1`. - +. Create a `jboss-ejb-client.properties` file. This file can be located anywhere in the file system, but for ease of demonstration, we create it in the root directory of this quickstart. Add the following content, replacing `__MACHINE_1_IP_ADDRESS__` with the IP address of `Machine_1`. ++ +[source,subs="+quotes,attributes+",options="nowrap"] ---- remote.connectionprovider.create.options.org.xnio.Options.SSL_ENABLED=false remote.connections=default -remote.connection.default.host=MACHINE_1_IP_ADDRESS +remote.connection.default.host=__MACHINE_1_IP_ADDRESS__ remote.connection.default.port=8080 remote.connection.default.connect.options.org.xnio.Options.SASL_POLICY_NOANONYMOUS=false remote.connection.default.username=quickuser remote.connection.default.password=quick-123 ---- -. Open a command prompt and navigate to the root directory of the quickstart. +. Open a terminal and navigate to the root directory of the quickstart. . Deploy the `app-client` quickstart to the remote machine using the following command: - ++ +[source,subs="+quotes,attributes+",options="nowrap"] ---- -mvn clean install wildfly:deploy -Dwildfly.hostname=MACHINE_1_IP_ADDRESS [-Dwildfly.port=9099] -Dwildfly.username=admin -Dwildfly.password=admin-123 +$ mvn clean install wildfly:deploy -Dwildfly.hostname=__MACHINE_1_IP_ADDRESS__ [-Dwildfly.port=9099] -Dwildfly.username=admin -Dwildfly.password=admin-123 ---- . Be sure that the quickstart deployed successfully and the server is running on `Machine_1` as described above. . Type this command to run the `app-client` application: - -[subs=normal] ++ +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/appclient.sh --ejb-client-properties=ejb-client.properties ear/target/app-client.ear#simpleClient.jar Hello from command line -For Windows: {jbossHomeName}\bin\appclient.bat --ejb-client-properties=ejb-client.properties ear\target\app-client.ear#simpleClient.jar Hello from command line +$ __{jbossHomeName}__/bin/appclient.sh --ejb-client-properties=ejb-client.properties ear/target/app-client.ear#simpleClient.jar Hello from command ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\appclient.bat` script. . Review the result. The client outputs the following information, which was provided by the application: - ++ +[source,options="nowrap"] ---- [org.jboss.as.quickstarts.appclient.acc.client.Main] (Thread-51) Main started with arguments [org.jboss.as.quickstarts.appclient.acc.client.Main] (Thread-51) [Hello, from, command, line] @@ -174,9 +182,10 @@ For Windows: {jbossHomeName}\bin\appclient.bat --ejb-client-properties=ejb-clien ---- . Review the server log files on the remote machine to see the bean invocations on the server. - ++ +[source,options="nowrap"] ---- - ClientContext is here = {Client =dev84, jboss.source-address=localhost/127.0.0.1:45315} +ClientContext is here = {Client =dev84, jboss.source-address=localhost/127.0.0.1:45315} ---- == Undeploy the Archive from the Local Machine @@ -184,11 +193,12 @@ For Windows: {jbossHomeName}\bin\appclient.bat --ejb-client-properties=ejb-clien Follow these instructions if you are testing the quickstart on the same machine. . Make sure you have started the {productName} server on the machine where the quickstart is deployed as described above. -. Open a command prompt on that server and navigate to the root directory of this quickstart. +. Open a terminal on that server and navigate to the root directory of this quickstart. . When you are finished testing, type this command to undeploy the archive from the local machine. - ++ +[source,options="nowrap"] ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- == Undeploy the Archive from the Remote Machine @@ -196,9 +206,10 @@ mvn wildfly:undeploy Follow these instructions if you are testing the quickstart on a different machine. . Make sure you have started the {productName} server on the remote server machine, `Machine_1`, where the quickstart is deployed as described above. -. Open a command prompt on the local client machine, `Machine_2`, and navigate to the root directory of this quickstart. +. Open a terminal on the local client machine, `Machine_2`, and navigate to the root directory of this quickstart. . When you are finished testing, type this command to undeploy the archive from the remote server machine, `Machine_1`. - ++ +[source,subs="+quotes,attributes+",options="nowrap"] +---- +$ mvn wildfly:undeploy -Dwildfly.hostname=__MACHINE_1_IP_ADDRESS__ [-Dwildfly.port=9099] -Dwildfly.username=admin -Dwildfly.password=admin-123 ---- -mvn wildfly:undeploy -Dwildfly.hostname=MACHINE_1_IP_ADDRESS [-Dwildfly.port=9099] -Dwildfly.username=admin -Dwildfly.password=admin-123 ----- \ No newline at end of file diff --git a/attributes.adoc b/attributes.adoc index 1b4d3d207f..7581312d1c 100644 --- a/attributes.adoc +++ b/attributes.adoc @@ -3,6 +3,27 @@ :jbossHomeName: WILDFLY_HOME :productVersion: 12 :buildRequirements: Java 8.0 (Java SDK 1.8) or later and Maven 3.3.1 or later -:githubRepoUrl: https://github.com/wildfly/quickstart/ -:useEclipseUrl: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts :jbdsEapServerName: WildFly Application Server 11.x +:githubRepoUrl: https://github.com/wildfly/quickstart/ +:useEclipseUrl: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.adoc#use_red_hat_jboss_developer_studio_or_eclipse_to_run_the_quickstarts +:useEclipseDeployJavaClientDocUrl: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.adoc#deploy_and_undeploy_a_quickstart_containing_server_and_java_client_projects +:useEclipseDeployEARDocUrl: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.adoc#deploy_and_undeploy_a_quickstart_ear_project +:useProductHomeDocUrl: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_{jbossHomeName}.adoc#use_of_product_home_and_jboss_home_variables +:configureMavenDocUrl: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP.adoc#configure_maven_to_build_and_deploy_the_quickstarts +:arquillianTestsDocUrl: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.adoc#run_the_arquillian_tests +:addUserDocUrl: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CREATE_USERS.adoc#create_users_required_by_the_quickstarts +:addApplicationUserDocUrl: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CREATE_USERS.adoc#add_an_application_user +:addManagementUserDocUrl: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CREATE_USERS.adoc#add_an_management_user +:startServerDocUrl: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/START_JBOSS_EAP.adoc#start_the_jboss_eap_server +:configurePostgresDocUrl: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_POSTGRESQL_JBOSS_EAP.adoc#configure_the_postgresql_database_for_use_with_the_quickstarts +:configurePostgresDownloadDocUrl: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_POSTGRESQL_JBOSS_EAP.adoc#download_and_install_postgresql +:configurePostgresCreateUserDocUrl: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_POSTGRESQL_JBOSS_EAP.adoc#create_a_database_user +:configurePostgresAddModuleDocUrl: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_POSTGRESQL_JBOSS_EAP.adoc#add_the_postgres_module_to_the_jboss_eap_server +:configurePostgresDriverDocUrl: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_POSTGRESQL_JBOSS_EAP.adoc#configure_the_postgresql_driver_in_the_jboss_eap_server +:configureBytementDownloadDocUrl: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_BYTEMAN.adoc#download_and_configure_byteman +:configureBytemanDisableDocUrl: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_BYTEMAN.adoc#disable_the_byteman_script +:configureBytemanClearDocUrl: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_BYTEMAN.adoc#clear_the_transaction_object_store +:configureBytemanQuickstartDocUrl: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_BYTEMAN.adoc#configure_byteman_for_use_with_the_quickstarts +:configureBytemanHaltDocUrl: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_BYTEMAN.adoc#use_byteman_to_halt_the_application[ +:configureBytemanQuickstartsDocUrl: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_BYTEMAN.adoc#configure_byteman_for_use_with_the_quickstarts +>>>>>>> 3712738... JBEAP-13958 part 1: Update quickstart README files - replace shared doc links with new adoc versions, fix formatting up to ejb quickstarts diff --git a/batch-processing/README.adoc b/batch-processing/README.adoc index 2ff0a1f6ec..efcd05aeec 100644 --- a/batch-processing/README.adoc +++ b/batch-processing/README.adoc @@ -16,48 +16,59 @@ The `batch-processing` quickstart shows how to use chunk oriented batch jobs to == What is it? -This quickstart simulates a file importation using batch jobs. To make it easy, this quickstart offers the user a way to generate files. The generate file can have its name and the number of records customized. The user may also specify if the file contains an error or not. +This quickstart simulates a file importation using batch jobs. To make it easy, this quickstart offers the user a way to generate files. The generated file can have its name and the number of records customized. The user can also specify if the file contains an error or not. -The Job contains two steps (tasks): +The job contains two tasks: -. Import the file (Chunk oriented) - The chunk size was set to `3`. The `RecordsReader` is responsible for parsing the file and create an instance of `Contact`. The `ContactsFormatter` applies the proper case to the Contact name and it also applies a mask to the phone number. Finally, `ContactsPersister` will send the Contact instance to the Database. -. Log the number of records imported +. It imports the file using a chunk oriented approach. -The database schema defines that the column for name is unique. For that reason, any atempt to persist a duplicate value will throw an exception. On the second attempt to run the job, the `ChunkCheckpoint` will provide information to skip the Contacts that were already persisted. +* The chunk size is set to `3`. +* The `RecordsReader` is responsible for parsing the file and create an instance of `Contact`. +* The `ContactsFormatter` applies the proper case to the contact name and it also applies a mask to the phone number. +* Finally, `ContactsPersister` sends the contact instance to the database. -_Note: This quickstart uses the H2 database included with {productNameFull} {productVersion}. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ +. It logs the number of records imported. -_Note: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in {productName} and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/[Configuration Guide] for {productNameFull}._ +The database schema defines that the column for name is unique. For that reason, any attempt to persist a duplicate value will throw an exception. On the second attempt to run the job, the `ChunkCheckpoint` provides information to skip the contacts that were already persisted. + +//************************************************* +// Add notes about use in a production environment. +//************************************************* +:uses-h2: +:uses-ds-xml: +include::../development-shortcuts.adoc[leveloffset=+1] == System Requirements The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Use of {jbossHomeName} -In the following instructions, replace `{jbossHomeName}` with the actual path to your {productName} installation. The installation path is described in detail here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_{jbossHomeName}.md#use-of-eap_home-and-jboss_home-variables[Use of {jbossHomeName} and JBOSS_HOME Variables]. +In the following instructions, replace `__{jbossHomeName}__` with the actual path to your {productName} installation. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of {jbossHomeName} and JBOSS_HOME Variables]. == Start the Server . Open a command line and navigate to the root of the {productName} directory. . The following shows the command line to start the server with the default profile: - -[subs=normal] ++ +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +$ __{jbossHomeName}__/bin/standalone.sh ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. == Build and Deploy the Quickstart . Make sure you have started the {productName} server as described above. . Open a command line and navigate to the root directory of this quickstart. . Type this command to build and deploy the archive: - ++ +[source,options="nowrap"] ---- -mvn clean package wildfly:deploy +$ mvn clean package wildfly:deploy ---- . This will deploy `target/{artifactId}.war` to the running instance of the server. @@ -70,14 +81,15 @@ You are presented with a simple form that allows you to generate sample files to === Usage 1: Import the file without any errors -Click on `Generate a new file and start import job` button. This will generate a new file with 10 unique records to be imported. After the file is generated, the import job will start. +Click on *Generate a new file and start import job* button. This will generate a new file with 10 unique records to be imported. After the file is generated, the import job will start. -You will see a table containing information about the task that was just started. You can click on `Update jobs list` button and verify that the job was completed. +You will see a table containing information about the task that was just started. You can click on *Update jobs list* button and verify that the job was completed. ==== Investigate the Console Output At the logs you will see that the files with 10 records were processed using 3 records at a time. +[source,options="nowrap"] ---- INFO [org.jboss.as.quickstarts.batch.controller.BatchController] (default task-3) Starting to generate 10 in file /var/folders/j8/63sgdmbn5tqdkyw0tz6df53r0000gn/T/temp-file.txt INFO [org.jboss.as.quickstarts.batch.controller.BatchController] (default task-3) File generated at /var/folders/j8/63sgdmbn5tqdkyw0tz6df53r0000gn/T/temp-file.txt @@ -107,13 +119,13 @@ INFO [org.jboss.as.quickstarts.batch.job.listener.JobListener] (Batch Thread - === Usage 2: Import an error file and fix it -Now we will simulate a file with duplicate records. This will raise an exception and stop the processing. After that, we will fix the file and continue the importing where it stopped. +Now you will simulate a file with duplicate records. This will raise an exception and stop the processing. After that, you will fix the file and continue the importing where it stopped. -Mark the `Generate a duplicate record` checkbox and click on `Generate a new file and start import job` button. If you click on `Update jobs list` button, you will see that the job failed with the following Exit Status: `Error : org.hibernate.exception.ConstraintViolationException: could not execute statement`. This was caused because the job tried to insert a duplicate record at the Database. You will also see `org.h2.jdbc.JdbcSQLException: Unique index or primary key violation` exception stacktraces in the server log. +Mark the *Generate a duplicate record* checkbox and click on *Generate a new file and start import job* button. If you click on *Update jobs list* button, you will see that the job failed with the following Exit Status: `Error : org.hibernate.exception.ConstraintViolationException: could not execute statement`. This was caused because the job tried to insert a duplicate record at the Database. You will also see `org.h2.jdbc.JdbcSQLException: Unique index or primary key violation` exception stacktraces in the server log. -Now we will fix the file and restart that job execution. Uncheck the `Generate a duplicate record` checkbox and click on `Generate a new file` button. This will generate file without errors. +Next, you will fix the file and restart that job execution. Uncheck the *Generate a duplicate record* checkbox and click on *Generate a new file* button. This will generate file without errors. -Click on `Restart` button in the last column for that job instance in the `List of Jobs` table. If you click on `Update jobs list` button, you will see that the job was completed. +Click on *Restart* button in the last column for that job instance in the *List of Jobs* table. If you click on *Update jobs list* button, you will see that the job was completed. Analyze the logs and check that the job started from the last checkpoint. @@ -146,14 +158,15 @@ INFO [org.jboss.as.quickstarts.batch.job.listener.JobListener] (Batch Thread - === Usage 3: Import an error file and do not fix the errors -Check the `Generate a duplicate record` checkbox and click on `Generate a new file ans start import job` button. If you click on `Update jobs list` button, you will see that the job failed with the following Exit Status: `Error : org.hibernate.exception.ConstraintViolationException: could not execute statement`. This was caused because we tried to insert a duplicate record at the Database. +Check the *Generate a duplicate record* checkbox and click on *Generate a new file ans start import job* button. If you click on *Update jobs list* button, you will see that the job failed with the following Exit Status: `Error : org.hibernate.exception.ConstraintViolationException: could not execute statement`. This was caused because you tried to insert a duplicate record at the Database. -This time we will not fix the file. Just click on `Restart` button again. If you click on `Update jobs list` button, you will see that the job was marked as `ABANDONED` this time because it was restarted once. Notice that there is a new parameter: `restartedOnce=true`. This behavior was implemented at `JobListener` for demonstration purpose to avoid that a `FAILED` job that was already restarted once, to be restarted twice. +This time you will not fix the file. Just click on *Restart* button again. If you click on *Update jobs list* button, you will see that the job was marked as `ABANDONED` this time because it was restarted once. Notice that there is a new parameter: `restartedOnce=true`. This behavior was implemented at `JobListener` for demonstration purpose to avoid that a `FAILED` job that was already restarted once, to be restarted twice. == Server Log: Expected Warnings and Errors -NOTE: You will see the following warnings in the server log. You can ignore these warnings. +You will see the following warnings in the server log. You can ignore these warnings. +[source,options="nowrap"] ---- WFLYJCA0091: -ds.xml file deployments are deprecated. Support may be removed in a future version. @@ -163,11 +176,12 @@ HHH000431: Unable to determine H2 database version, certain features may not wor == Undeploy the Archive . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . When you are finished testing, type this command to undeploy the archive: - ++ +[source,options="nowrap"] ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- == Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse @@ -178,6 +192,7 @@ You can also start the server and deploy the quickstarts or run the Arquillian t If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. +[source,options="nowrap"] +---- +$ mvn dependency:sources ---- -mvn dependency:sources ----- \ No newline at end of file diff --git a/bean-validation-custom-constraint/README.adoc b/bean-validation-custom-constraint/README.adoc index 37cb54925a..f6cf96bb53 100644 --- a/bean-validation-custom-constraint/README.adoc +++ b/bean-validation-custom-constraint/README.adoc @@ -18,46 +18,50 @@ The `bean-validation-custom-constraint` quickstart demonstrates how to use the B The `bean-validation-custom-constraint` quickstart demonstrates how to use CDI, JPA, and Bean Validation in {productNameFull}. Bean Validation API allows the developers to define their own constraints by creating a new annotation and writing the validator which is used to validate the value. This quickstart will show you how to create custom constraints and then use it to validate your data. It includes a persistence unit and some sample persistence code to introduce you to database access in enterprise Java. -This quickstart does not contain a user interface layer. The purpose of this project is to show you how to test bean validation using custom constraints with Arquillian. In this quickstart, the personAddress field of entity Person is validated using a set of custom constraints defined in the class AddressValidator. If you want to see an example of how to test bean validation with a user interface, look at the link:../kitchensink/README.md[kitchensink] example. +This quickstart does not contain a user interface layer. The purpose of this project is to show you how to test bean validation using custom constraints with Arquillian. In this quickstart, the personAddress field of entity Person is validated using a set of custom constraints defined in the class AddressValidator. If you want to see an example of how to test bean validation with a user interface, look at the link:../kitchensink/README.adoc[kitchensink] example. -_Note: This quickstart uses the H2 database included with {productNameFull} {productVersion}. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ - -_Note: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in {productName} and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/[Configuration Guide] for {productNameFull}._ +//************************************************* +// Add notes about use in a production environment. +//************************************************* +:uses-h2: +:uses-ds-xml: +include::../development-shortcuts.adoc[leveloffset=+1] == System Requirements The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Use of {jbossHomeName} -In the following instructions, replace `{jbossHomeName}` with the actual path to your {productName} installation. The installation path is described in detail here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_{jbossHomeName}.md#use-of-eap_home-and-jboss_home-variables[Use of {jbossHomeName} and JBOSS_HOME Variables]. +In the following instructions, replace `__{jbossHomeName}__` with the actual path to your {productName} installation. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of {jbossHomeName} and JBOSS_HOME Variables]. == Start the Server -. Open a command prompt and navigate to the root of the {productName} directory. +. Open a terminal and navigate to the root of the {productName} directory. . The following shows the command line to start the server: - -[subs=normal] ++ +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +$ __{jbossHomeName}__/bin/standalone.sh ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. == Run the Arquillian Tests This quickstart provides Arquillian tests. By default, these tests are configured to be skipped as Arquillian tests require the use of a container. . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type the following command to run the test goal with the following profile activated: - ++ ---- -mvn clean verify -Parq-remote +$ mvn clean verify -Parq-remote ---- -You can also let Arquillian manage the {productName} server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests[Run the Arquillian Tests]. +You can also let Arquillian manage the {productName} server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see link:{arquillianTestsDocUrl}[Run the Arquillian Tests]. == Investigate the Console Output @@ -83,7 +87,7 @@ INFO [[org.jboss.as.server] (management-handler-thread - 2) WFLYSRV0009: Undeplo == Server Log: Expected Warnings and Errors -NOTE: You will see the following warnings in the server log. You can ignore these warnings. +You will see the following warnings in the server log. You can ignore these warnings. ---- WFLYJCA0091: -ds.xml file deployments are deprecated. Support may be removed in a future version. @@ -100,12 +104,12 @@ You can also start the server and deploy the quickstarts or run the Arquillian t If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. ---- - mvn dependency:sources +$ mvn dependency:sources ---- -You may see the following message when you run the command. It indicates the source is not provided in the third-party `antlr` JAR. +You might see the following message when you run the command. It indicates the source is not provided in the third-party `antlr` JAR. ---- - [INFO] The following files have NOT been resolved: - [INFO] antlr:antlr:jar:sources:2.7.7:provided ----- \ No newline at end of file +[INFO] The following files have NOT been resolved: +[INFO] antlr:antlr:jar:sources:2.7.7:provided +---- diff --git a/bean-validation/README.adoc b/bean-validation/README.adoc index 22bb624c77..f8b29c6ba7 100644 --- a/bean-validation/README.adoc +++ b/bean-validation/README.adoc @@ -18,48 +18,53 @@ The `bean-validation` quickstart provides Arquillian tests to demonstrate how to The `bean-validation` quickstart demonstrates how to use CDI, JPA, and Bean Validation in {productNameFull}. It includes a persistence unit and some sample persistence code to introduce you to database access in enterprise Java. -This quickstart does not contain a user interface layer. The purpose of this project is to show you how to test bean validation with Arquillian. If you want to see an example of how to test bean validation with a user interface, look at the link:../kitchensink/README.md[kitchensink] example. +This quickstart does not contain a user interface layer. The purpose of this project is to show you how to test bean validation with Arquillian. If you want to see an example of how to test bean validation with a user interface, look at the link:../kitchensink/README.adoc[kitchensink] example. This quickstart is a basic example of bean validation and is not localized. Because it is not localized, English messages are hard-coded in the constraint annotations in the `Member` class to ensure the test violation messages are matched when running the {productName} server using another language. For examples of localized quickstarts, see the `kitchensink-ml`, `kitchensink-ml-ear`, and `logging-tools` quickstarts. -_Note: This quickstart uses the H2 database included with {productNameFull} {productVersion}. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ - -_Note: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in {productName} and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/[Configuration Guide] for {productNameFull}._ +//************************************************* +// Add notes about use in a production environment. +//************************************************* +:uses-h2: +:uses-ds-xml: +include::../development-shortcuts.adoc[leveloffset=+1] == System Requirements The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Use of {jbossHomeName} -In the following instructions, replace `{jbossHomeName}` with the actual path to your {productName} installation. The installation path is described in detail here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_{jbossHomeName}.md#use-of-eap_home-and-jboss_home-variables[Use of {jbossHomeName} and JBOSS_HOME Variables]. +In the following instructions, replace `__{jbossHomeName}__` with the actual path to your {productName} installation. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of {jbossHomeName} and JBOSS_HOME Variables]. == Start the Server -. Open a command prompt and navigate to the root of the {productName} directory. +. Open a terminal and navigate to the root of the {productName} directory. . The following shows the command line to start the server: - -[subs=normal] ++ +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +$ __{jbossHomeName}__/bin/standalone.sh ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. + == Run the Arquillian Tests This quickstart provides Arquillian tests. By default, these tests are configured to be skipped as Arquillian tests require the use of a container. . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type the following command to run the test goal with the following profile activated: - ++ ---- -mvn clean verify -Parq-remote +$ mvn clean verify -Parq-remote ---- -You can also let Arquillian manage the {productName} server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests[Run the Arquillian Tests]. +You can also let Arquillian manage the {productName} server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see link:{arquillianTestsDocUrl}[Run the Arquillian Tests]. == Investigate the Console Output @@ -85,7 +90,7 @@ INFO [[org.jboss.as.server] (management-handler-thread - 2) WFLYSRV0009: Undeplo == Server Log: Expected Warnings and Errors -NOTE: You will see the following warnings in the server log. You can ignore these warnings. +You will see the following warnings in the server log. You can ignore these warnings. ---- WFLYJCA0091: -ds.xml file deployments are deprecated. Support may be removed in a future version. @@ -102,5 +107,5 @@ You can also start the server and deploy the quickstarts or run the Arquillian t If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. ---- - mvn dependency:sources ----- \ No newline at end of file +$ mvn dependency:sources +---- diff --git a/bmt/README.adoc b/bmt/README.adoc index 1418ff5dd5..77c13471da 100644 --- a/bmt/README.adoc +++ b/bmt/README.adoc @@ -26,41 +26,44 @@ When you run this example, you will be provided with a `Use bean managed Entity {productName} ships with H2, an in-memory database written in Java. This example shows how to transactionally insert key value pairs into the H2 database and demonstrates the requirements on the developer with respect to the JPA Entity Manager. -_Note: This quickstart uses the H2 database included with {productNameFull} {productVersion}. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ - -_Note: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in {productName} and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/[Configuration Guide] for {productNameFull}._ - -_NOTE: A Java EE container is designed with robustness in mind, so you should carefully analyze the scalabiltiy, concurrency, and performance needs of your application before taking advantage of these techniques in your own applications._ +//*************************************** +// Add notes about use in a production environment. +//*************************************** +:uses-h2: +:uses-ds-xml: +:performance-scalability: +include::../development-shortcuts.adoc[leveloffset=+1] == System Requirements The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Use of {jbossHomeName} -In the following instructions, replace `{jbossHomeName}` with the actual path to your {productName} installation. The installation path is described in detail here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_{jbossHomeName}.md#use-of-eap_home-and-jboss_home-variables[Use of {jbossHomeName} and JBOSS_HOME Variables]. +In the following instructions, replace `__{jbossHomeName}__` with the actual path to your {productName} installation. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of {jbossHomeName} and JBOSS_HOME Variables]. == Start the Server -. Open a command prompt and navigate to the root of the {productName} directory. +. Open a terminal and navigate to the root of the {productName} directory. . The following shows the command line to start the server: - -[subs=normal] ++ +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +$ __{jbossHomeName}__/bin/standalone.sh ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. == Build and Deploy the Quickstart . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type this command to build and deploy the archive: - ++ ---- -mvn clean install wildfly:deploy +$ mvn clean install wildfly:deploy ---- . This will deploy `target/{artifactId}.war` to the running instance of the server. @@ -73,11 +76,11 @@ You will be presented with a simple form for adding key/value pairs and a checkb . To list all pairs leave the key input box empty. . To add or update the value of a key fill in the key and value input boxes. -. Press the submit button to see the results. +. Click the *submit* button to see the results. == Server Log: Expected Warnings and Errors -NOTE: You will see the following warnings in the server log. You can ignore these warnings. +You will see the following warnings in the server log. You can ignore these warnings. ---- WFLYJCA0091: -ds.xml file deployments are deprecated. Support may be removed in a future version. @@ -88,11 +91,11 @@ HHH000431: Unable to determine H2 database version, certain features may not wor == Undeploy the Archive . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . When you are finished testing, type this command to undeploy the archive: - ++ ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- == Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse @@ -104,5 +107,5 @@ You can also start the server and deploy the quickstarts or run the Arquillian t If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. ---- - mvn dependency:sources ----- \ No newline at end of file +$ mvn dependency:sources +---- diff --git a/cmt/README.adoc b/cmt/README.adoc index 8c2b6d7590..58fc5f5754 100644 --- a/cmt/README.adoc +++ b/cmt/README.adoc @@ -20,71 +20,77 @@ The `cmt` quickstart demonstrates using transactions managed by the container in 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 +* 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 After users complete this quickstart, they are invited to run through the following quickstarts: -. link:../jts/README.md[jts] - The JTS quickstart builds upon this quickstart by distributing the CustomerManager and InvoiceManager -. link:../jts-distributed-crash-rec/README.md[jts-distributed-crash-rec] - The crash recovery quickstart builds upon the link:../jts/README.md[jts] quickstart by demonstrating the fault tolerance of {productName}. +* link:../jts/README.adoc[jts] - The JTS quickstart builds upon this quickstart by distributing the CustomerManager and InvoiceManager +* link:../jts-distributed-crash-rec/README.adoc[jts-distributed-crash-rec] - The crash recovery quickstart builds upon the link:../jts/README.adoc[jts] quickstart by demonstrating the fault tolerance of {productName}. -_Note: This quickstart uses the H2 database included with {productNameFull} {productVersion}. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ + +//*************************************** +// Add notes about use in a production environment. +//*************************************** +:uses-h2: +include::../development-shortcuts.adoc[leveloffset=+1] === What are Container Managed Transactions? -Prior to EJB, getting the right incantation to ensure sound transactional operation of the business logic was a highly specialised 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. +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 via the methods begin, commit, rollback on a `javax.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 @javax.ejb.TransactionAttribute annotation. +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 `@javax.ejb.TransactionAttribute` annotation. The available options for this annotation are as follows: -* 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. +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. == System Requirements The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Use of {jbossHomeName} -In the following instructions, replace `{jbossHomeName}` with the actual path to your {productName} installation. The installation path is described in detail here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_{jbossHomeName}.md#use-of-eap_home-and-jboss_home-variables[Use of {jbossHomeName} and JBOSS_HOME Variables]. +In the following instructions, replace `__{jbossHomeName}__` with the actual path to your {productName} installation. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of {jbossHomeName} and JBOSS_HOME Variables]. == Start the Server with the Full Profile -. Open a command prompt and navigate to the root of the {productName} directory. +. Open a terminal and navigate to the root of the {productName} directory. . The following shows the command line to start the server with the full profile: - -[subs=normal] ++ +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -c standalone-full.xml -For Windows: {jbossHomeName}\bin\standalone.bat -c standalone-full.xml +$ __{jbossHomeName}__/bin/standalone.sh -c standalone-full.xml ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. == Build and Deploy the Quickstart -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type this command to build and deploy the archive: - ++ ---- -mvn clean install wildfly:deploy +$ mvn clean install wildfly:deploy ---- . This will deploy `target/{artifactId}.war` to the running instance of the server. == Access the Application -The application will be running at the following URL: http://localhost:8080/{artifactId}/. +The application will be running at the following URL: http://localhost:8080/{artifactId}/ You will be presented with a simple form for adding customers to a database. @@ -101,7 +107,7 @@ that the method logCreateCustomer in the EJB LogMessageManagerEJB is decorated w == Server Log: Expected Warnings and Errors -NOTE: You will see the following warnings in the server log. You can ignore these warnings. +You will see the following warnings in the server log. You can ignore these warnings. ---- HHH000431: Unable to determine H2 database version, certain features may not work @@ -110,11 +116,11 @@ HHH000431: Unable to determine H2 database version, certain features may not wor == Undeploy the Archive . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . When you are finished testing, type this command to undeploy the archive: - ++ ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- == Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse @@ -128,5 +134,5 @@ NOTE: Within JBoss Developer Studio, be sure to define a server runtime environm If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. ---- - mvn dependency:sources ----- \ No newline at end of file +$ mvn dependency:sources +---- diff --git a/contacts-jquerymobile/README.adoc b/contacts-jquerymobile/README.adoc index 4662d1f48c..a98f6fd585 100644 --- a/contacts-jquerymobile/README.adoc +++ b/contacts-jquerymobile/README.adoc @@ -36,7 +36,7 @@ This application focuses on *CRUD* in a strictly mobile app using only *jQuery M The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. An HTML5 compatible browser such as Chrome, Safari 5+, Firefox 5+, or IE 9+ is required. Note that some behaviors, such as validation, will vary slightly based on browser support, especially IE 9. @@ -48,21 +48,19 @@ With the prerequisites out of the way, you are ready to build and deploy. . Open a command line and navigate to the root of the {productName} directory. . The following shows the command line to start the server with the default profile: - -[subs=normal] ++ +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +$ __{jbossHomeName}__/bin/standalone.sh ---- - -Note: Adding `-b 0.0.0.0` to the above commands will allow external clients, such as phones, tablets, and desktops, connect through your local network. - -For example - -[subs=normal] ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. ++ +Adding `-b 0.0.0.0` to the above command will allow external clients, such as phones, tablets, and desktops, connect through your local network. For example: ++ +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -b 0.0.0.0 -For Windows: {jbossHomeName}\bin\standalone.bat -b 0.0.0.0 +$ __{jbossHomeName}__/bin/standalone.sh -b 0.0.0.0 ---- == Build and Deploy the Quickstart @@ -70,9 +68,9 @@ For Windows: {jbossHomeName}\bin\standalone.bat -b 0.0.0.0 . Make sure you have started the {productName} server as described above. . Open a command line and navigate to the root directory of this quickstart. . Type this command to build and deploy the archive: - ++ ---- -mvn clean package wildfly:deploy +$ mvn clean package wildfly:deploy ---- . This deploys `target/{artifactId}.war` to the running instance of the server. @@ -81,47 +79,47 @@ mvn clean package wildfly:deploy Access the running client application in a browser at the following URL: http://localhost:8080/{artifactId}/. -The app is made up of the following pages: +The application is made up of the following pages: *Main page* -* Displays a list of contacts -* Search bar for the list -* Details button changes to the Detailed list -* Clicking on a contact brings up an Edit form -* Menu button (in upper left) opens menu +* Displays a list of contacts. +* Search bar for the list. +* Details button changes to the Detailed list. +* Clicking on a contact brings up an Edit form. +* Menu button (in upper left) opens menu. *Menu pullout* -* Add a new Contact -* List/Detail view switcher, depending on what is currently displayed -* About information -* Theming - apply various themes (only on the List view) +* Add a new contact. +* List/Detail view switcher, depending on what is currently displayed. +* About information. +* Theming - apply various themes (only on the List view). *Details page* -* Same as Main page except all information is displayed with each contact +* Same as Main page except all information is displayed with each contact. *Add form* -* First name, Last name, Phone, Email, and BirthDate fields -* Save = submit the form -* Clear = reset the form but stay on the form -* Cancel = reset the form and go the Main page +* *First name*, *Last name*, *Phone*, *Email*, and *BirthDate* fields. +* *Save* submits the form. +* *Clear* resets the form but stays on the form. +* *Cancel* resets the form and goes the Main page. *Edit form* -* Same as Add form -* Delete button will delete the contact currently viewed and return you to the Main page +* Same as *Add form*. +* *Delete* button will delete the contact currently viewed and return you to the Main page. == Undeploy the Archive . Make sure you have started the {productName} server as described above. . Open a command line and navigate to the root directory of this quickstart. . When you are finished testing, type this command to undeploy the archive: - ++ ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- == Minification @@ -130,22 +128,22 @@ By default, the project uses the http://code.google.com/p/wro4j/[wro4j] plugin, With just a few quick changes to the project, you can link to the minified versions of your JavaScript and CSS files. -First, in the `<project-root>/src/main/webapp/index.html` file, search for references to minification and comment or uncomment the appropriate lines. +First, in the `/src/main/webapp/index.html` file, search for references to minification and comment or uncomment the appropriate lines. Finally, wro4j runs in the compile phase so any standard build command like package, install, etc. will trigger it. The plug-in is in a profile with an id of `minify` so you will want to specify that profile in your maven build. -NOTE: By default there are turn off tests so you must use the arquillian test profile to run tests when minifying. For example: +By default, tests are disabled, so you must use the Arquillian test profile to run tests when minifying. +* For example, to deploy with no tests: ++ ---- -#No Tests -mvn clean package wildfly:deploy -Pminify +$ mvn clean package wildfly:deploy -Pminify ---- -OR - +* To deploy with tests: ++ ---- -#With Tests -mvn clean verify wildfly:deploy -Pminify,arq-remote +$ mvn clean verify wildfly:deploy -Pminify,arq-remote ---- == Run the Arquillian Tests @@ -155,18 +153,14 @@ By default, tests are configured to be skipped. The reason is that the sample te To run the test in JBoss, first start the container instance. Then, run the test goal with the following profile activated: ---- -mvn clean verify -Parq-remote +$ mvn clean verify -Parq-remote ---- == Run the QUnit tests QUnit is a JavaScript unit testing framework used and built by jQuery. Because JavaScript code is the core of this HTML5 application, this quickstart provides a set of QUnit tests that automate testing of this code in various browsers. Executing QUnit test cases are quite easy. -Simply load the following HTML in the browser you wish to test. - ----- - QUICKSTART_HOME/contacts-jquerymobile/src/test/qunit/index.html ----- +Simply load the `contacts-jquerymobile/src/test/qunit/index.html` file in the browser you wish to test. NOTE: If you use *Chrome*, some date tests fail. These are false failures and are known issues with Chrome. FireFox, Safari, and IE run the tests correctly. You can also display the tests using the Eclipse built-in browser. @@ -180,25 +174,25 @@ To run these tests, you must build the main project as described above. . Open a command line and navigate to the root directory of this quickstart. . Build the quickstart WAR using the following command: - ++ ---- -mvn clean package +$ mvn clean package ---- . Navigate to the functional-tests/ directory in this quickstart. . If you have a running instance of the {productName} server, as described above, run the remote tests by typing the following command: - ++ ---- -mvn clean verify -Parq-remote +$ mvn clean verify -Parq-remote ---- . If you prefer to run the functional tests using managed instance of the {productName} server, meaning the tests will start the server for you, type the following command: - -_NOTE: For this to work, Arquillian needs to know the location of the {productName} server. This can be declared through the `JBOSS_HOME` environment variable or the `jbossHome` property in `arquillian.xml`. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests[Run the Arquillian Tests] for complete instructions and additional options._ - ++ +_NOTE: For this to work, Arquillian needs to know the location of the {productName} server. This can be declared through the `JBOSS_HOME` environment variable or the `jbossHome` property in `arquillian.xml`. See link:{arquillianTestsDocUrl}[Run the Arquillian Tests] for complete instructions and additional options._ ++ ---- - mvn clean verify -Parq-managed +$ mvn clean verify -Parq-managed ---- == Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse @@ -211,6 +205,6 @@ If you want to be able to debug into the source code or look at the Javadocs of either of the following two commands to pull them into your local repository. The IDE should then detect them. ---- -mvn dependency:sources -mvn dependency:resolve -Dclassifier=javadoc ----- \ No newline at end of file +$ mvn dependency:sources +$ mvn dependency:resolve -Dclassifier=javadoc +---- diff --git a/development-shortcuts.adoc b/development-shortcuts.adoc new file mode 100644 index 0000000000..cab285edd1 --- /dev/null +++ b/development-shortcuts.adoc @@ -0,0 +1,14 @@ +[[considerations_for_use_in_a_production_environment]] += Considerations for Use in a Production Environment + +ifdef::uses-h2[] +* This quickstart uses the H2 database included with {productNameFull} {productVersion}. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment. +endif::[] + +ifdef::uses-ds-xml[] +* This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in {productName} and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/[_Configuration Guide_] for {productNameFull}. +endif::[] + +ifdef::performance-scalability[] +* A Java EE container is designed with robustness in mind, so you should carefully analyze the scalabiltiy, concurrency, and performance needs of your application before taking advantage of these techniques in your own applications. +endif::[] diff --git a/ejb-asynchronous/README.adoc b/ejb-asynchronous/README.adoc index 0cdc1c0305..19eafd6758 100644 --- a/ejb-asynchronous/README.adoc +++ b/ejb-asynchronous/README.adoc @@ -29,31 +29,32 @@ The root `pom.xml` builds each of the submodules in the above order and deploys The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Use of {jbossHomeName} -In the following instructions, replace `{jbossHomeName}` with the actual path to your {productName} installation. The installation path is described in detail here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_{jbossHomeName}.md#use-of-eap_home-and-jboss_home-variables[Use of {jbossHomeName} and JBOSS_HOME Variables]. +In the following instructions, replace `__{jbossHomeName}__` with the actual path to your {productName} installation. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of {jbossHomeName} and JBOSS_HOME Variables]. == Start the Server -. Open a command prompt and navigate to the root of the {productName} directory. +. Open a terminal and navigate to the root of the {productName} directory. . The following shows the command line to start the server: - -[subs=normal] ++ +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +$ __{jbossHomeName}__/bin/standalone.sh ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. == Build and Deploy the Quickstart . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type this command to build and deploy the archive: - ++ ---- -mvn clean install wildfly:deploy +$ mvn clean install wildfly:deploy ---- . This will deploy `ejb/target/{artifactId}-ejb.jar` to the running instance of the server. @@ -62,16 +63,16 @@ Check whether the application is deployed successfully. == Access the Application -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type this command to start the client - ++ ---- cd client mvn exec:exec ---- . Check the client output - ++ ---- INFO: The server log should contain a message at (about) , indicating that the call to the asynchronous bean completed. INFO: Got the async result as expected => returning at , duration was 200ms @@ -81,17 +82,17 @@ INFO: Results of the parallel (server) processing : [returning at duratio ---- . Check the server log. - ++ There should be two INFO log messages for the `fireAndForget` invocation: == Undeploy the Archive . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . When you are finished testing, type this command to undeploy the archive: - ++ ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- == Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse @@ -101,18 +102,18 @@ You can also start the server and deploy the quickstarts or run the Arquillian t This quickstart consists of multiple projects, so it deploys and runs differently in JBoss Developer Studio than the other quickstarts. . Install the required Maven artifacts and deploy the asynchronous EJB quickstart project. -** Right-click on the `{artifactId}-ejb` project and choose `Run As` –> `Maven Install`. -** Right-click on the `{artifactId}-ejb` project and choose `Run As` –> `Run on Server`. +** Right-click on the *{artifactId}-ejb* project and choose *Run As* -> *Maven Install*. +** Right-click on the *{artifactId}-ejb* project and choose *Run As* -> *Run on Server*. . Build and run the client side of the quickstart project. -** Right-click on the `{artifactId}-client` project and choose `Run As` –> `Java Application`. -** In the `Select Java Application` window, choose `AsynchronousClient - org.jboss.as.quickstarts.ejb.asynchronous.client` and click `OK`. -** The client output displays in the `Console` window. -. To undeploy the project, right-click on the `{artifactId}-ejb` project and choose `Run As` –> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. +** Right-click on the *{artifactId}-client* project and choose *Run As* -> *Java Application*. +** In the *Select Java Application* window, choose *AsynchronousClient - org.jboss.as.quickstarts.ejb.asynchronous.client* and click *OK*. +** The client output displays in the *Console* window. +. To undeploy the project, right-click on the *{artifactId}-ejb* project and choose *Run As* -> *Maven build*. Enter *wildfly:undeploy* for the *Goals* and click *Run*. == Debug the Application If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. ---- -mvn dependency:sources ----- \ No newline at end of file +$ mvn dependency:sources +---- diff --git a/ejb-in-ear/README.adoc b/ejb-in-ear/README.adoc index 8015487566..82a43b35d2 100644 --- a/ejb-in-ear/README.adoc +++ b/ejb-in-ear/README.adoc @@ -40,31 +40,32 @@ The example follows the common "Hello World" pattern. These are the steps that o The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Use of {jbossHomeName} -In the following instructions, replace `{jbossHomeName}` with the actual path to your {productName} installation. The installation path is described in detail here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_{jbossHomeName}.md#use-of-eap_home-and-jboss_home-variables[Use of {jbossHomeName} and JBOSS_HOME Variables]. +In the following instructions, replace `__{jbossHomeName}__` with the actual path to your {productName} installation. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of {jbossHomeName} and JBOSS_HOME Variables]. == Start the Server -. Open a command prompt and navigate to the root of the {productName} directory. +. Open a terminal and navigate to the root of the {productName} directory. . The following shows the command line to start the server: - -[subs=normal] ++ +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +$ __{jbossHomeName}__/bin/standalone.sh ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. == Build and Deploy the Quickstart . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type this command to build and deploy the archive: - ++ ---- -mvn clean install wildfly:deploy +$ mvn clean install wildfly:deploy ---- . This will deploy `ear/target/{artifactId}.ear` to the running instance of the server. @@ -78,28 +79,28 @@ Enter a name in the input field and click the _Greet_ button to see the response == Undeploy the Archive . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . When you are finished testing, type this command to undeploy the archive: - ++ ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- == Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a {productName} server, and build and deploy a quickstart, see link:{useEclipseUrl}[Use JBoss Developer Studio or Eclipse to Run the Quickstarts]. -For this quickstart, follow the special instructions to build https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#deploy-and-undeploy-a-quickstart-ear-project[Quickstarts Containing an EAR]. +For this quickstart, follow the special instructions to build link:{useEclipseDeployEARDocUrl}[Quickstarts Containing an EAR]. -. Right-click on the `{artifactId}-ear` subproject, and choose `Run As` –> `Run on Server`. -. Choose the server and click `Finish`. +. Right-click on the *{artifactId}-ear* subproject, and choose *Run As* -> *Run on Server*. +. Choose the server and click *Finish*. . This starts the server, deploys the application, and opens a browser window that accesses the running application. -. To undeploy the project, right-click on the `{artifactId}-ear` project and choose `Run As` –> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. +. To undeploy the project, right-click on the *{artifactId}-ear* project and choose *Run As* -> *Maven build*. Enter `wildfly:undeploy` for the *Goals* and click *Run*. == Debug the Application If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. ---- - mvn dependency:sources ----- \ No newline at end of file +$ mvn dependency:sources +---- diff --git a/ejb-in-war/README.adoc b/ejb-in-war/README.adoc index f4bd0a66db..8ff310c799 100644 --- a/ejb-in-war/README.adoc +++ b/ejb-in-war/README.adoc @@ -30,31 +30,32 @@ The example follows the common "Hello World" pattern. These are the steps that o The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Use of {jbossHomeName} -In the following instructions, replace `{jbossHomeName}` with the actual path to your {productName} installation. The installation path is described in detail here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_{jbossHomeName}.md#use-of-eap_home-and-jboss_home-variables[Use of {jbossHomeName} and JBOSS_HOME Variables]. +In the following instructions, replace `__{jbossHomeName}__` with the actual path to your {productName} installation. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of {jbossHomeName} and JBOSS_HOME Variables]. == Start the Server -. Open a command prompt and navigate to the root of the {productName} directory. +. Open a terminal and navigate to the root of the {productName} directory. . The following shows the command line to start the server: - -[subs=normal] ++ +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +$ __{jbossHomeName}__/bin/standalone.sh ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. == Build and Deploy the Quickstart . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type this command to build and deploy the archive: - ++ ---- -mvn clean install wildfly:deploy +$ mvn clean install wildfly:deploy ---- . This will deploy `target/{artifactId}.war` to the running instance of the server. @@ -66,11 +67,11 @@ The application will be running at the following URL http://localhost:8080/{arti == Undeploy the Archive . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . When you are finished testing, type this command to undeploy the archive: - ++ ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- == Run the Arquillian Tests @@ -78,14 +79,14 @@ mvn wildfly:undeploy This quickstart provides Arquillian tests. By default, these tests are configured to be skipped as Arquillian tests require the use of a container. . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type the following command to run the test goal with the following profile activated: - ++ ---- -mvn clean verify -Parq-remote +$ mvn clean verify -Parq-remote ---- -You can also let Arquillian manage the {productName} server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests[Run the Arquillian Tests]. +You can also let Arquillian manage the {productName} server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see link:{arquillianTestsDocUrl}[Run the Arquillian Tests]. == Investigate the Console Output @@ -118,5 +119,5 @@ You can also start the server and deploy the quickstarts or run the Arquillian t If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. ---- - mvn dependency:sources ----- \ No newline at end of file +$ mvn dependency:sources +---- diff --git a/ejb-multi-server/README.adoc b/ejb-multi-server/README.adoc index 1b551839d6..1bb169d2c2 100644 --- a/ejb-multi-server/README.adoc +++ b/ejb-multi-server/README.adoc @@ -20,9 +20,9 @@ The `ejb-multi-server` quickstart demonstrates communication between application This example consists of the following Maven projects, each with a shared parent: -[cols="<,<"] +[cols="40%,60%",options="headers"] |=== -|*Sub-project* |*Description* +|Sub-project |Description |`app-main` |An application that can be called by the `client`. It can also call the different sub-applications. |`app-one` and `app-two` |These are simple applications that contain an EJB sub-project to build the `ejb.jar` file and an EAR sub-project to build the `app.ear` file. Each application contains only one EJB that logs a statement on a method call and returns the `jboss.node.name` and credentials. @@ -38,7 +38,7 @@ The server configuration is done using CLI batch scripts located in the root of The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Start with a Clean Server Install @@ -46,49 +46,45 @@ It is important to start with a clean version of {productName} before testing th == Use of {jbossHomeName} -In the following instructions, replace `{jbossHomeName}` with the actual path to your {productName} installation. The installation path is described in detail here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_{jbossHomeName}.md#use-of-eap_home-and-jboss_home-variables[Use of {jbossHomeName} and JBOSS_HOME Variables]. +In the following instructions, replace `__{jbossHomeName}__` with the actual path to your {productName} installation. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of {jbossHomeName} and JBOSS_HOME Variables]. == Add the Application Users The following users must be added to the `ApplicationRealm` to run this quickstart. Be sure to use the names and passwords specified in the table as they are required to run this example. -[cols="<,<,<,<"] +[cols="20%,20%,20%,40%",options="headers"] |=== -|*UserName* |*Realm* |*Password* |*Roles* +|UserName |Realm |Password |Roles |quickuser |ApplicationRealm |quick-123 |_leave blank for none_ |quickuser1 |ApplicationRealm |quick123+ |_leave blank for none_ |quickuser2 |ApplicationRealm |quick+123 |_leave blank for none_ |=== -To add the users, open a command prompt and type the following commands: +To add the users, open a terminal and type the following commands: -[subs=normal] +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: - {jbossHomeName}/bin/add-user.sh -a -u quickuser -p quick-123 - {jbossHomeName}/bin/add-user.sh -a -u quickuser1 -p quick123+ - {jbossHomeName}/bin/add-user.sh -a -u quickuser2 -p quick+123 - -For Windows: - {jbossHomeName}\bin\add-user.bat -a -u quickuser -p quick-123 - {jbossHomeName}\bin\add-user.bat -a -u quickuser1 -p quick123+ - {jbossHomeName}\bin\add-user.bat -a -u quickuser2 -p quick+123 +$ __{jbossHomeName}__/bin/add-user.sh -a -u quickuser -p quick-123 +$ __{jbossHomeName}__/bin/add-user.sh -a -u quickuser1 -p quick123+ +$ __{jbossHomeName}__/bin/add-user.sh -a -u quickuser2 -p quick+123 ---- -If you prefer, you can use the add-user utility interactively. For an example of how to use the add-user utility, see the instructions located here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CREATE_USERS.md#add-an-application-user[Add an Application User]. +NOTE: For Windows, use the `__{jbossHomeName}__\bin\add-user.bat` script. + +If you prefer, you can use the `add-user` utility interactively. For an example of how to use the add-user utility, see the instructions located here: link:{addApplicationUserDocUrl}[Add an Application User]. == Back Up the Server Configuration Files -{productName} server configuration for this quickstart is very complicated and not easily restored by running a JBoss CLI script, so it is important to back up your server configuration files before you begin. +The {productName} server configuration for this quickstart is very complicated and not easily restored by running a JBoss CLI script, so it is important to back up your server configuration files before you begin. . If it is running, stop the {productName} server. -. Back up the following files, replacing {jbossHomeName} with the path to your {productName} installation: +. Back up the following files, replacing __{jbossHomeName}__ with the path to your {productName} installation: + -[subs=normal] +[source,subs="+quotes,attributes+",options="nowrap"] ---- -{jbossHomeName}/domain/configuration/domain.xml -{jbossHomeName}/domain/configuration/host.xml +__{jbossHomeName}__/domain/configuration/domain.xml +__{jbossHomeName}__/domain/configuration/host.xml ---- . After you have completed testing and undeployed this quickstart, you can replace these files to restore the server to its original configuration. @@ -97,31 +93,34 @@ If you prefer, you can use the add-user utility interactively. For an example of You configure the domain server by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a `install-domain.cli` script provided in the root directory of this quickstart. -. Start with a fresh instance of the {productName} as noted above under <>. +. Start with a fresh instance of the {productName} as noted above under <>. -. Be sure you add the required users as specified above under <>. +. Be sure you add the required users as specified above under <>. -. Before you begin, make sure you followed the instructions above under <>. +. Before you begin, make sure you followed the instructions above under <>. . Start the {productName} server -** Open a command prompt and navigate to the root of the EAP directory. +** Open a terminal and navigate to the root of the EAP directory. ** Start the server using the following command: + +[source,subs="+quotes,attributes+",options="nowrap"] ---- -bin/domain.sh +$ __EAP_HOME__/bin/domain.sh ---- ++ +NOTE: For Windows, use the `__EAP_HOME__/bin/domain.bat` script. . Review the `install-domain.cli` file in the root of this quickstart directory. This script configures and starts multiple servers needed to run this quickstart. -. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing {jbossHomeName} with the path to your server: +. 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: + -[subs=normal] +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/jboss-cli.sh -c --file=install-domain.cli -For Windows: {jbossHomeName}\bin\jboss-cli.bat -c --file=install-domain.cli +$ __{jbossHomeName}__/bin/jboss-cli.sh -c --file=install-domain.cli ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. -[NOTE] -Depending on your machine configuration, you may see "Exception in thread "main" java.lang.OutOfMemoryError: unable to create new native thread" exceptions in the server log when you run this script. If you do, you must increase the ulimit open files and max user processes settings. Instructions to do this are located here: http://ithubinfo.blogspot.com/2013/07/how-to-increase-ulimit-open-file-and.html. After you update the ulimit settings, be sure to reboot and start with a fresh instance of the server._ +IMPORTANT: Depending on your machine configuration, you might see "Exception in thread "main" java.lang.OutOfMemoryError: unable to create new native thread" exceptions in the server log when you run this script. If you do, you must increase the ulimit open files and max user processes settings. Instructions to do this are located here: http://ithubinfo.blogspot.com/2013/07/how-to-increase-ulimit-open-file-and.html. After you update the ulimit settings, be sure to reboot and start with a fresh instance of the server. == Review the Modified Server Configuration @@ -130,23 +129,25 @@ There are too many additions to the configuration files to list here. Feel free == Build and Deploy the Quickstart . Make sure you have started and configured the {productName} server successfully as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type this command to build the artifacts: + ---- -mvn clean install +$ mvn clean install ---- ++ You should see `BUILD SUCCESS` at the end of the build `SUCCESS` messages for each component. -. In the same command prompt, deploy the applications using the provided CLI batch script by typing the following command: +. In the same terminal, deploy the applications using the provided CLI batch script by typing the following command: + -[subs=normal] +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/jboss-cli.sh -c --file=deploy-domain.cli -For Windows: {jbossHomeName}\bin\jboss-cli.bat -c --file=deploy-domain.cli +$ __{jbossHomeName}__/bin/jboss-cli.sh -c --file=deploy-domain.cli ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. -NOTE: If ERRORs appear in the `server.log` when installing or deploying the quickstart, stop the domain and restart it. This should ensure further steps run correctly. +IMPORTANT: If ERRORs appear in the `server.log` when installing or deploying the quickstart, stop the domain and restart it. This should ensure further steps run correctly. == Access the Remote Client Application @@ -157,21 +158,21 @@ This example shows how to invoke an EJB from a remote standalone application. . Type this command to run the application: + ---- -mvn exec:java +$ mvn exec:java ---- -. If it is necessary to invoke the client with a different {productName} version the main class can be invoked by using the following command from the root directory of this quickstart. Replace {jbossHomeName} with your current installation path. The output should be similar to the previous mvn executions. +. If it is necessary to invoke the client with a different {productName} version the main class can be invoked by using the following command from the root directory of this quickstart. Replace __{jbossHomeName}__ with your current installation path. The output should be similar to the previous mvn executions. + [subs=normal] ---- -java -cp {jbossHomeName}/bin/client/jboss-client.jar:app-main/ejb/target/ejb-multi-server-app-main-ejb-client.jar:app-two/ejb/target/ejb-multi-server-app-two-ejb-client.jar:client/target/ejb-multi-server-client.jar org.jboss.as.quickstarts.ejb.multi.server.Client +java -cp $ __{jbossHomeName}__/bin/client/jboss-client.jar:app-main/ejb/target/ejb-multi-server-app-main-ejb-client.jar:app-two/ejb/target/ejb-multi-server-app-two-ejb-client.jar:client/target/ejb-multi-server-client.jar org.jboss.as.quickstarts.ejb.multi.server.Client ---- -[NOTE] --- -* _If exec is called multiple times, the invocation for `app1` might use `app-oneA` and `app-oneB` node due to cluster loadbalancing._ -* _A {productName} will deny the invocation of unsecured methods of `appOne`/`appTwo` since security is enabled but the method does not include @Roles. You need to set `default-missing-method-permissions-deny-access = false` for the `ejb3` subsystem within the domain profile `ha` and `default` to allow the method invocation. See the `install-domain.cli` script._ --- +[IMPORTANT] +==== +* If `exec` is called multiple times, the invocation for `app1` might use `app-oneA` and `app-oneB` node due to cluster loadbalancing. +* A {productName} will deny the invocation of unsecured methods of `appOne`/`appTwo` since security is enabled but the method does not include `@Roles`. You need to set `default-missing-method-permissions-deny-access = false` for the `ejb3` subsystem within the domain profile `ha` and `default` to allow the method invocation. See the `install-domain.cli` script. +==== == Access the JSF application Inside the Main Application @@ -193,19 +194,20 @@ An example how to access EJBs from a separate instance which only contains a web == Undeploy the Archives . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . When you are finished testing, type this command to undeploy the archive: + -[subs=normal] +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/jboss-cli.sh --connect --file=undeploy-domain.cli -For Windows: {jbossHomeName}\bin\jboss-cli.bat --connect --file=undeploy-domain.cli +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=undeploy-domain.cli ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat`. == Remove the Server Domain Configuration . If it is running, stop the {productName} server. -. Restore the `{jbossHomeName}/domain/configuration/domain.xml` and `{jbossHomeName}/domain/configuration/host.xml` files with the back-up copies of the files. Be sure to replace {jbossHomeName} with the path to your server. +. Restore the `__{jbossHomeName}__/domain/configuration/domain.xml` and `__{jbossHomeName}__/domain/configuration/host.xml` files with the back-up copies of the files. Be sure to replace `__{jbossHomeName}__` with the path to your server. == Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse @@ -216,5 +218,5 @@ EJB Client (ejb-client) currently has limited support in the Eclipse Web Tools P If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. ---- -mvn dependency:sources +$ mvn dependency:sources ---- diff --git a/ejb-remote/README.adoc b/ejb-remote/README.adoc index 780a6f2820..57f51d5eba 100644 --- a/ejb-remote/README.adoc +++ b/ejb-remote/README.adoc @@ -21,11 +21,11 @@ The `ejb-remote` quickstart shows how to access an EJB from a remote Java client There are two components to this example: . A server side component: - ++ The server component is comprised of a stateful EJB and a stateless EJB. It provides both an EJB JAR that is deployed to the server and a JAR file containing the remote business interfaces required by the remote client application. . A remote client application that accesses the server component. - ++ The remote client application depends on the remote business interfaces from the server component. This application looks up the stateless and stateful beans via JNDI and invokes a number of methods on them. Each component is defined in its own standalone Maven module. The quickstart provides a top level Maven module to simplify the packaging of the artifacts. @@ -34,59 +34,60 @@ Each component is defined in its own standalone Maven module. The quickstart pro The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Use of {jbossHomeName} -In the following instructions, replace `{jbossHomeName}` with the actual path to your {productName} installation. The installation path is described in detail here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_{jbossHomeName}.md#use-of-eap_home-and-jboss_home-variables[Use of {jbossHomeName} and JBOSS_HOME Variables]. +In the following instructions, replace `__{jbossHomeName}__` with the actual path to your {productName} installation. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of {jbossHomeName} and JBOSS_HOME Variables]. == Start the Server -. Open a command prompt and navigate to the root of the {productName} directory. +. Open a terminal and navigate to the root of the {productName} directory. . The following shows the command line to start the server: - -[subs=normal] ++ +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +$ __{jbossHomeName}__/bin/standalone.sh ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. == Build and Deploy the Quickstart Since this quickstart builds two separate components, you can not use the standard _Build and Deploy_ commands used by most of the other quickstarts. You must follow these steps to build, deploy, and run this quickstart. . Make sure you have started the {productName} server. See the instructions in the previous section. -. Open a command prompt and navigate to the ejb-remote quickstart directory +. Open a terminal and navigate to the ejb-remote quickstart directory . Build and install the server side component: ** Build the EJB and client interfaces JARs and install them in your local Maven repository. - ++ ---- -mvn clean install +$ mvn clean install ---- ** Deploy the EJB JAR to your server. This Maven goal will deploy `server-side/target/{artifactId}-server-side.jar`. You can check the {productName} server console to see information messages regarding the deployment. - ++ ---- -mvn wildfly:deploy +$ mvn wildfly:deploy ---- . Build and run the client application ** Navigate to the client subdirectory: - ++ ---- -cd ../client +$ cd ../client ---- ** Compile the client code - ++ ---- -mvn clean compile +$ mvn clean compile ---- ** Execute the client application within Maven - ++ ---- -mvn exec:exec +$ mvn exec:exec ---- == Investigate the Console Output @@ -139,22 +140,22 @@ Logging statements have been removed from this output here to make it clearer. The remote client application can also be built as a standalone executable JAR with all of its dependencies. -. Open a command prompt and navigate to the ejb-remote/client quickstart directory - +. Open a terminal and navigate to the ejb-remote/client quickstart directory ++ ---- -cd client +$ cd client ---- . Type the following in the command line: - ++ ---- -mvn clean package assembly:single +$ mvn clean package assembly:single ---- . You can then run the executable JAR using the `java -jar` command. You will see the same console output as above. - ++ ---- -java -jar target/{artifactId}-client-jar-with-dependencies.jar +$ java -jar target/{artifactId}-client-jar-with-dependencies.jar ---- == Undeploy the Archive @@ -162,15 +163,15 @@ java -jar target/{artifactId}-client-jar-with-dependencies.jar To undeploy the server-side component from the {productName} server: . Navigate to the server-side subdirectory: - ++ ---- -cd ../server-side +$ cd ../server-side ---- . Type the following command: - ++ ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- == Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse @@ -181,19 +182,19 @@ This quickstart consists of multiple projects, so it deploys and runs differentl . Install the required Maven artifacts and deploy the server side of the quickstart project. -** Right-click on the `{artifactId}-server-side` project and choose `Run As` –> `Maven Install`. -** Right-click on the `{artifactId}-server-side` project and choose `Run As` –> `Run on Server`. +** Right-click on the *{artifactId}-server-side* project and choose *Run As* -> *Maven Install*. +** Right-click on the *{artifactId}-server-side* project and choose *Run As* -> *Run on Server*. . Build and run the client side of the quickstart project. -** Right-click on the `{artifactId}-client` project and choose `Run As` –> `Java Application`. -** In the `Select Java Application` window, choose `RemoteEJBClient - org.jboss.as.quickstarts.ejb.remote.client` and click `OK`. -** The client output displays in the `Console` window. -. To undeploy the project, right-click on the `{artifactId}-server-side` project and choose `Run As` –> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. +** Right-click on the *{artifactId}-client* project and choose *Run As* -> *Java Application*. +** In the *Select Java Application* window, choose *RemoteEJBClient - org.jboss.as.quickstarts.ejb.remote.client* and click *OK*. +** The client output displays in the *Console* window. +. To undeploy the project, right-click on the *{artifactId}-server-side* project and choose *Run As* -> *Maven build*. Enter `wildfly:undeploy` for the *Goals* and click *Run*. == Debug the Application If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. ---- - mvn dependency:sources ----- \ No newline at end of file +$ mvn dependency:sources +---- diff --git a/ejb-security-context-propagation/README.adoc b/ejb-security-context-propagation/README.adoc index 6ed304d9ae..726a955d93 100644 --- a/ejb-security-context-propagation/README.adoc +++ b/ejb-security-context-propagation/README.adoc @@ -60,7 +60,7 @@ to run the test. The application this project produces is designed to be run on {productNameFull} {productVersion}. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. To run these quickstarts with the provided build scripts, you need the {productName} distribution ZIP. For information on how to install and run JBoss, see the https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/[{productNameFull} Documentation] _Getting Started Guide_ located on the Customer Portal. @@ -75,38 +75,35 @@ It is recommended that you test this approach in a separate and clean environmen == Use of {jbossHomeName} -In the following instructions, replace `{jbossHomeName}` with the actual path to your {productName} installation. The -installation path is described in detail here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_{jbossHomeName}.md#use-of-eap_home-and-jboss_home-variables[Use of {jbossHomeName} and JBOSS_HOME Variables]. +In the following instructions, replace `__{jbossHomeName}__` with the actual path to your {productName} installation. The +installation path is described in detail here: link:{useProductHomeDocUrl}[Use of {jbossHomeName} and JBOSS_HOME Variables]. == Add the Application Users This quickstart uses secured management interfaces and is built around the default `ApplicationRealm` as configured in the {productName} distribution. You must create the following application user to access the running application: -[cols="<,<,<,<"] +[cols="20%,20%,20%,40%",options="headers"] |=== -|*UserName* |*Realm* |*Password* |*Roles* +|UserName |Realm |Password |Roles |quickstartUser |ApplicationRealm |quickstartPwd1! |guest,user |superUser |ApplicationRealm |superPwd1! |guest,user,admin |=== -To add the user, open a command prompt and type the following commands: +To add the user, open a terminal and type the following commands: -[source, bash, subs=normal] +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: - {jbossHomeName}/bin/add-user.sh -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest,user' - {jbossHomeName}/bin/add-user.sh -a -u 'superUser' -p 'superPwd1!' -g 'guest,user,admin' - -For Windows: - {jbossHomeName}\bin\add-user.bat -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest,user' - {jbossHomeName}\bin\add-user.bat -a -u 'superUser' -p 'superPwd1!' -g 'guest,user,admin' +$ __{jbossHomeName}__/bin/add-user.sh -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest,user' +$ __{jbossHomeName}__/bin/add-user.sh -a -u 'superUser' -p 'superPwd1!' -g 'guest,user,admin' ---- +NOTE: For Windows, use the `__{jbossHomeName}__\bin\add-user.bat` script. + The `quickstart` user establishes the actual connection to the server. -If you prefer, you can use the add-user utility interactively. -For an example of how to use the add-user utility, see the instructions located here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CREATE_USERS.md#add-an-application-user[Add an Application User]. +If you prefer, you can use the `add-user` utility interactively. +For an example of how to use the add-user utility, see the instructions located here: link:{addApplicationUserDocUrl}[Add an Application User]. == Configure the Server @@ -117,41 +114,45 @@ You configure the security domain by running JBoss CLI commands. For your conven . Before you begin, back up your server configuration file ** If it is running, stop the {productName} server. -** Back up the file: `{jbossHomeName}/standalone/configuration/standalone.xml` +** Back up the file: `__{jbossHomeName}__/standalone/configuration/standalone.xml` ** After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration. . Start the {productName} server by typing the following: + -[source, bash, subs=normal] +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +$ __{jbossHomeName}__/bin/standalone.sh ---- +NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. + . 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 deployment. Comments in the script describe the purpose of each block of commands. -. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing {jbossHomeName} with the path to your server: +. 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, bash, subs=normal] +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/jboss-cli.sh --connect --file=configure-elytron.cli -For Windows: {jbossHomeName}\bin\jboss-cli.bat --connect --file=configure-elytron.cli +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=configure-elytron.cli ---- + -. Because this example quickstart demonstrates security, exceptions are thrown when secured EJB access is attempted by an invalid user. If you want to review the security exceptions in the server log, you can skip this step. If you want to suppress these exceptions in the server log, run the following command, replacing {jbossHomeName} with the path to your server: +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. + ++ +. Because this example quickstart demonstrates security, exceptions are thrown when secured EJB access is attempted by an invalid user. If you want to review the security exceptions in the server log, you can skip this step. If you want to suppress these exceptions in the server log, run the following command, replacing `__{jbossHomeName}__` with the path to your server: + -[source, bash, subs=normal] +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/jboss-cli.sh --connect --file=configure-system-exception.cli -For Windows: {jbossHomeName}\bin\jboss-cli.bat --connect --file=configure-system-exception.cli +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=configure-system-exception.cli ---- ++ +NOTE: For Windows,use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. . Stop the {productName} server. == Review the Modified Server Configuration -After stopping the server, open the `{jbossHomeName}/standalone/configuration/standalone.xml` file and review the changes. +After stopping the server, open the `__{jbossHomeName}__/standalone/configuration/standalone.xml` file and review the changes. . The following `application-security-domain` was added to the `ejb3` subsystem: + -[source, xml] +[source,xml,options="nowrap"] ---- @@ -160,7 +161,7 @@ After stopping the server, open the `{jbossHomeName}/standalone/configuration/st + . The following `ejb-outbound-configuration` authentication configuration and `ejb-outbound-context` authentication context were added to the `elytron` subsystem: + -[source, xml] +[source,xml,options="nowrap"] ---- @@ -170,7 +171,7 @@ After stopping the server, open the `{jbossHomeName}/standalone/configuration/st . The following `ejb-outbound` outbound-socket-binding connection was created within the `standard-sockets` socket-binding-group: + -[source, xml] +[source,xml,options="nowrap"] ---- @@ -179,7 +180,7 @@ After stopping the server, open the `{jbossHomeName}/standalone/configuration/st + . The following `ejb-outbound-connection` remote-outbound-connection was added to the outbound-connections within the `remoting` subsytem: + -[source, xml] +[source,xml,options="nowrap"] ---- @@ -188,13 +189,13 @@ After stopping the server, open the `{jbossHomeName}/standalone/configuration/st . The `http-connector` in the `remoting` subsystem was updated to use the `application-sasl-authentication` authentication factory. It allows for the identity that was established in the connection authentication to be propagated to the components. + -[source, xml] +[source,xml,options="nowrap"] ---- ---- . Finally, the `application-sasl-authentication` factory was updated in the `elytron` subsystem to include the `PLAIN` mechanism: + -[source, xml] +[source,xml,options="nowrap"] ---- @@ -209,51 +210,51 @@ After stopping the server, open the `{jbossHomeName}/standalone/configuration/st . If you chose to run the script to suppress system exceptions, you should see the following configuration in the `ejb3` subsystem. + -[source, xml] +[source,xml,options="nowrap"] ---- ---- == Start the Server -. Open a command prompt and navigate to the root of the {productName} directory. +. Open a terminal and navigate to the root of the {productName} directory. . The following shows the command line to start the server: + -[subs=normal] +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +$ __{jbossHomeName}__/bin/standalone.sh ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. == Build and Deploy the Quickstart . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type this command to build and deploy the archive: + ---- -mvn clean package wildfly:deploy +$ mvn clean package wildfly:deploy ---- . This will deploy `target/{artifactId}.jar` to the running instance of the server. == Run the Client -Before you run the client, make sure you have already successfully deployed the EJBs to the server in the previous step and that your command prompt is still in the same folder. +Before you run the client, make sure you have already successfully deployed the EJBs to the server in the previous step and that your terminal is still in the same folder. Type this command to execute the client: ---- -mvn exec:exec +$ mvn exec:exec ---- == Investigate the Console Output When you run the `mvn exec:exec` command, you see the following output. Note there may be other log messages interspersed between these. - +[source,options="nowrap"] ---- * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * - * * IntermediateEJB - Begin Testing with principal quickstartUser * * Remote Security Information: [Principal=[quickstartUser], In role [guest]=true, In role [user]=true, In role [admin]=false] @@ -262,11 +263,8 @@ Can invoke userMethod? true Can invoke adminMethod? false * * IntermediateEJB - End Testing * * - * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * - * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * - * * IntermediateEJB - Begin Testing with principal superUser * * Remote Security Information: [Principal=[superUser], In role [guest]=true, In role [user]=true, In role [admin]=true] @@ -275,7 +273,6 @@ Can invoke userMethod? true Can invoke adminMethod? true * * IntermediateEJB - End Testing * * - * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * ---- @@ -288,6 +285,7 @@ If you chose not to run the script to suppress system exceptions, you should see server console or log. The exceptions are logged for each of the tests where a request is rejected because the user is not authorized. +[source,options="nowrap"] ---- 12:26:06,556 ERROR [org.jboss.as.ejb3.invocation] (default task-57) WFLYEJB0034: EJB Invocation failed on component SecuredEJB for method public abstract java.lang.String org.jboss.as.quickstarts.ejb_security_context_propagation.SecuredEJBRemote.adminMethod(): javax.ejb.EJBAccessException: WFLYEJB0364: Invocation on method: public abstract java.lang.String org.jboss.as.quickstarts.ejb_security_context_propagation.SecuredEJBRemote.adminMethod() of bean: SecuredEJB is not allowed at org.jboss.as.ejb3.security.RolesAllowedInterceptor.processInvocation(RolesAllowedInterceptor.java:67) @@ -326,11 +324,11 @@ authorized. == Undeploy the Archive . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . When you are finished testing, type this command to undeploy the archive: + ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- == Restore the Server Configuration @@ -343,30 +341,33 @@ You can restore the original server configuration by running the `restore-config + [source, subs=normal] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +$ __{jbossHomeName}__/bin/standalone.sh ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. -. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing {jbossHomeName} with the path to your server: +. 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=normal] ---- -For Linux: {jbossHomeName}/bin/jboss-cli.sh --connect --file=restore-configuration.cli -For Windows: {jbossHomeName}\bin\jboss-cli.bat --connect --file=restore-configuration.cli +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=restore-configuration.cli ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. -. If you choose to run the script to suppress system exceptions, run the following command, replacing {jbossHomeName} with the path to your server: +. If you choose to run the script to suppress system exceptions, run the following command, replacing `__{jbossHomeName}__` with the path to your server: + [source, subs=normal] ---- -For Linux: {jbossHomeName}/bin/jboss-cli.sh --connect --file=restore-system-exception.cli -For Windows: {jbossHomeName}\bin\jboss-cli.bat --connect --file=restore-system-exception.cli +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=restore-system-exception.cli ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. === Restore the Server Configuration Manually . If it is running, stop the {productName} server. -. Replace the `{jbossHomeName}/standalone/configuration/standalone.xml` file with the backup copy of the file. +. Replace the `__{jbossHomeName}__/standalone/configuration/standalone.xml` file with the backup copy of the file. == Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse @@ -376,11 +377,11 @@ This quickstart requires additional configuration and deploys and runs different . Be sure to <> as described above. . Follow the steps above to <>. Stop the server at the end of that step. -. To deploy the application to the {productName} server, right-click on the `{artifactId}` project and choose `Run As` –> `Run on Server`. -. To access the application, right-click on the `{artifactId}` project and choose `Run As` –> `Java Application`. -. Choose `RemoteClient - org.jboss.as.quickstarts.ejb_security_context_propagation` and click `OK`. +. To deploy the application to the {productName} server, right-click on the *{artifactId}* project and choose *Run As* -> *Run on Server*. +. To access the application, right-click on the *{artifactId}* project and choose *Run As* -> *Java Application*. +. Choose *RemoteClient - org.jboss.as.quickstarts.ejb_security_context_propagation* and click *OK*. . Review the output in the console window. -. To undeploy the project, right-click on the `{artifactId}` project and choose `Run As` –> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. +. To undeploy the project, right-click on the *{artifactId}* project and choose *Run As* -> *Maven build*. Enter `wildfly:undeploy` for the *Goals* and click *Run*. . Be sure to <> when you have completed testing this quickstart. == Debug the Application @@ -388,5 +389,5 @@ This quickstart requires additional configuration and deploys and runs different If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. ---- -mvn dependency:sources +$ mvn dependency:sources ---- diff --git a/ejb-security-jaas/README.adoc b/ejb-security-jaas/README.adoc index 48a9f8f843..dc3b4f83a0 100644 --- a/ejb-security-jaas/README.adoc +++ b/ejb-security-jaas/README.adoc @@ -14,7 +14,7 @@ include::../attributes.adoc[] [abstract] The `ejb-security-jaas` quickstart demonstrates how legacy `JAAS` security domains can be used in conjunction with `Elytron` -Source: <{githubRepoUrl}> +Source: <{githubRepoUrl}> == What is it? @@ -32,38 +32,39 @@ The overall steps required to use the `JAAS` integration are as follows: The applications these projects produce are designed to be run on {productNameFull} {productVersion} or later. -All you need to build these projects is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build these projects is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. To run these quickstarts with the provided build scripts, you need the {productName} distribution ZIP. For information on how to install and run JBoss, see the https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/[{productNameFull} Documentation] _Getting Started Guide_ located on the Customer Portal. -You can also use <> to run the quickstarts. +You can also use <> to run the quickstarts. == Use of {jbossHomeName} -In the following instructions, replace `{jbossHomeName}` with the actual path to your {productName} installation. The installation path is described in detail here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_{jbossHomeName}.md#use-of-eap_home-and-jboss_home-variables[Use of {jbossHomeName} and JBOSS_HOME Variables]. +In the following instructions, replace `__{jbossHomeName}__` with the actual path to your {productName} installation. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of {jbossHomeName} and JBOSS_HOME Variables]. == Create the Properties Files for the JAAS Security Domain . Open a command line and navigate to the {productName} server `configuration` directory: - -[subs="+quotes,attributes+"] ++ +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/standalone/configuration -For Windows: {jbossHomeName}\standalone\configuration +$ cd __{jbossHomeName}__/standalone/configuration/ ---- . Create a file named `users.properties` and add the following username/password pair: - ++ ---- quickstartUser=quickstartPwd1! ---- . Create a file named `roles.properties` and add the following username/roles pair: - ++ ---- quickstartUser=guest ---- +== Configure the Server + These steps assume you are running the server in standalone mode and using the default `standalone.xml` supplied with the distribution. You configure the security domain by running JBoss CLI commands. For your convenience, this quickstart batches the commands into a `configure-elytron-jaas.cli` script provided in the root directory of this quickstart. @@ -71,34 +72,36 @@ You configure the security domain by running JBoss CLI commands. For your conven . Before you begin, back up your server configuration file ** If it is running, stop the {productName} server. -** Back up the file: `{jbossHomeName}/standalone/configuration/standalone.xml` +** Back up the file: `__{jbossHomeName}__/standalone/configuration/standalone.xml` ** After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration. . Start the {productName} server by typing the following: - -[subs="attributes+"] ++ +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +$ __{jbossHomeName}__/bin/standalone.sh ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. . Review the `configure-elytron-jaas.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 command prompt, navigate to the root directory of this quickstart, and run the following command, replacing {jbossHomeName} with the path to your server: - -[subs="+quotes,attributes+"] +. 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"] ---- -For Linux: {jbossHomeName}/bin/jboss-cli.sh --connect --file=configure-elytron-jaas.cli -For Windows: {jbossHomeName}\bin\jboss-cli.bat --connect --file=configure-elytron-jaas.cli +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=configure-elytron-jaas.cli ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. . Stop the {productName} server. == Review the Modified Server Configuration -After stopping the server, open the `{jbossHomeName}/standalone/configuration/standalone.xml` file and review the changes. +After stopping the server, open the `__{jbossHomeName}__/standalone/configuration/standalone.xml` file and review the changes. . The following `security-domain` was added to the legacy `security` subsystem: + -[source, xml] +[source,xml,options="nowrap"] ---- @@ -121,7 +124,7 @@ After stopping the server, open the `{jbossHomeName}/standalone/configuration/st . The following `elytron-realm` was added to the legacy `security` subsystem: + -[source, xml] +[source,xml,options="nowrap"] ---- @@ -132,7 +135,7 @@ After stopping the server, open the `{jbossHomeName}/standalone/configuration/st . The following `security-domain` was added to the `elytron` subsystem: + -[source, xml] +[source,xml,options="nowrap"] ---- @@ -142,7 +145,7 @@ After stopping the server, open the `{jbossHomeName}/standalone/configuration/st . The following `http-authentication-factory` was added to the `elytron` subsystem: + -[source, xml] +[source,xml,options="nowrap"] ---- @@ -155,7 +158,7 @@ After stopping the server, open the `{jbossHomeName}/standalone/configuration/st . The following `application-security-domain` mapping was added to the `undertow` subsystem: + -[source, xml] +[source,xml,otions="nowrap"] ---- @@ -165,7 +168,7 @@ After stopping the server, open the `{jbossHomeName}/standalone/configuration/st . The following `sasl-authentication-factory` was added to the `elytron` subsystem: + -[source, xml] +[source,xml,options="nowrap"] ---- @@ -177,7 +180,7 @@ After stopping the server, open the `{jbossHomeName}/standalone/configuration/st . The `http-remoting-connector` in the `remoting` subsystem was updated to use the `sasl-authentication-factory` created in step 6: + -[source, xml] +[source,xml,options="nowrap"] ---- ---- @@ -185,7 +188,7 @@ After stopping the server, open the `{jbossHomeName}/standalone/configuration/st . Finally, the following `application-security-domain` mapping was added to the `ejb3` subsystem: + -[source, xml] +[source,xml,options="nowrap"] ---- @@ -194,23 +197,24 @@ After stopping the server, open the `{jbossHomeName}/standalone/configuration/st == Start the Server -. Open a command prompt and navigate to the root of the {productName} directory. +. Open a terminal and navigate to the root of the {productName} directory. . The following shows the command line to start the server: - -[subs=normal] ++ +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +$ __{jbossHomeName}__/bin/standalone.sh ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. == Build and Deploy the Quickstart . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type this command to build and deploy the archive: - ++ ---- -mvn clean install wildfly:deploy +$ mvn clean install wildfly:deploy ---- . This will deploy `target/{artifactId}.war` to the running instance of the server. @@ -223,7 +227,7 @@ When you access the application, you are presented with a browser login challeng . If you attempt to login with a user name and password combination that has not been added to the server, the login challenge will be redisplayed. . When you login successfully using `quickstartUser`/`quickstartPwd1!`, the browser displays the following security info: - ++ ---- Successfully called Secured EJB @@ -234,20 +238,20 @@ Authentication Type : BASIC ---- . The application can also be accessed directly by a remote client. Type the following command in the root directory of the quickstart: - ++ ---- -mvn exec:exec +$ mvn exec:exec ---- . Next, change the exported realm so that it now uses the legacy role mappers as defined in the legacy `JAAS` security domain. - -Make sure you are still in the root directory of this quickstart, and run the following command, replacing {jbossHomeName} ++ +Make sure you are still in the root directory of this quickstart, and run the following command, replacing `__{jbossHomeName}__` with the path to your server: . If you didn't close your web browser, re-load the quickstart application page. Otherwise open a new browser, point it to the URL http://localhost:8080/{artifactId}/ and login with `quickstartUser/quickstartPwd1!`. It should now display a page confirming the user now has the `admin` role that was provided by the legacy role mapper: - ++ ---- Successfully called Secured EJB @@ -258,7 +262,7 @@ Authentication Type : BASIC ---- . The same result can be observed when re-running the remote client application: - ++ ---- * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * @@ -272,11 +276,11 @@ Authentication Type : BASIC == Undeploy the Archive . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . When you are finished testing, type this command to undeploy the archive: - ++ ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- == Restore the Server Configuration @@ -287,47 +291,49 @@ You can restore the original server configuration by running the `restore-config . Start the {productName} server by typing the following: + -[subs="+quotes,attributes+"] +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +$ __{jbossHomeName}__/bin/standalone.sh ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. -. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing {jbossHomeName} with the path to your server: +. 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: + -[subs="+quotes,attributes+"] +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/jboss-cli.sh --connect --file=restore-configuration.cli -For Windows: {jbossHomeName}\bin\jboss-cli.bat --connect --file=restore-configuration.cli +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=restore-configuration.cli ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. === Restore the Server Configuration Manually . If it is running, stop the {productName} server. -. Replace the `{jbossHomeName}/standalone/configuration/standalone.xml` file with the backup copy of the file. +. Replace the `__{jbossHomeName}__/standalone/configuration/standalone.xml` file with the backup copy of the file. == Remove the Properties Files from the Server After you are done with this quickstart, remember to remove the `users.properties` and `roles.properties` files from the -server configuration directory (`{jbossHomeName}/standalone/configuration/`). +server configuration directory (`__{jbossHomeName}__/standalone/configuration/`). == Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a {productName} server, and build and deploy a quickstart, see link:{useEclipseUrl}[Use JBoss Developer Studio or Eclipse to Run the Quickstarts]. -* Be sure to <> as described above. +* Be sure to <> as described above. * Be sure to configure the server by running the JBoss CLI script as described above under <>. Stop the server at the end of that step. -* To deploy the application to the {productName} server, right-click on the `{artifactId}` project and choose `Run As` –> `Run on Server`. -* You are presented with a browser login challenge. Enter the credentials as described above under <> to see the running application. Note that `Has admin permission` is `false`. -* Leave the application running in JBoss Developer Studio. To configure the server to use the legacy role mappers, open a terminal, and run the `enable-role-mappers.cli` script as described above under <>. -* Go back to JBoss Developer Studio and click `Refresh the current page`. Note that `Has admin permission` is now `true`. -* To undeploy the project, right-click on the `{artifactId}` project and choose `Run As` –> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. -* Be sure to <> when you have completed testing this quickstart. +* To deploy the application to the {productName} server, right-click on the *{artifactId}* project and choose *Run As* -> *Run on Server*. +* You are presented with a browser login challenge. Enter the credentials as described above under <> to see the running application. Note that *Has admin permission* is `false`. +* Leave the application running in JBoss Developer Studio. To configure the server to use the legacy role mappers, open a terminal, and run the `enable-role-mappers.cli` script as described above under <>. +* Go back to JBoss Developer Studio and click *Refresh the current page*. Note that *Has admin permission* is now `true`. +* To undeploy the project, right-click on the *{artifactId}* project and choose *Run As* -> *Maven build*. Enter `wildfly:undeploy` for the *Goals* and click *Run*. +* Be sure to <> when you have completed testing this quickstart. == Debug the Application If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. ---- -mvn dependency:sources ----- \ No newline at end of file +$ mvn dependency:sources +---- diff --git a/ejb-security-programmatic-auth/README.adoc b/ejb-security-programmatic-auth/README.adoc index b9a138c353..cf0367a42a 100644 --- a/ejb-security-programmatic-auth/README.adoc +++ b/ejb-security-programmatic-auth/README.adoc @@ -22,7 +22,7 @@ The `ejb-security-programmatic-auth` quickstart demonstrates how to invoke a rem The applications these projects produce are designed to be run on {productNameFull} {productVersion} or later. -All you need to build these projects is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build these projects is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. To run these quickstarts with the provided build scripts, you need the {productName} distribution ZIP. For information on how to install and run JBoss, see the https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/[{productNameFull} Documentation] _Getting Started Guide_ located on the Customer Portal. @@ -30,37 +30,33 @@ You can also use < @@ -107,64 +105,62 @@ After stopping the server, open the `{jbossHomeName}/standalone/configuration/st . The `http-connector` in the `remoting` subsystem was updated to use the `application-sasl-authentication` authentication factory: + -[source, xml] +[source,xml,options="nowrap"] ---- ---- == Start the Server -. Open a command prompt and navigate to the root of the {productName} directory. +. Open a terminal and navigate to the root of the {productName} directory. . The following shows the command line to start the server: - -[subs=normal] ++ +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +$ __{jbossHomeName}__/bin/standalone.sh ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. == Build and Deploy the Quickstart . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type this command to build and deploy the archive: - ++ ---- -mvn clean package wildfly:deploy +$ mvn clean package wildfly:deploy ---- . This will deploy `target/{artifactId}.jar` to the running instance of the server. == Access the Application -Before you run the client, make sure you have already successfully deployed the EJBs to the server in the previous step and that your command prompt is still in the same folder. +Before you run the client, make sure you have already successfully deployed the EJBs to the server in the previous step and that your terminal is still in the same folder. Type this command to execute the client: ---- -mvn exec:exec +$ mvn exec:exec ---- == Investigate the Console Output When you run the `mvn exec:exec` command, you see the following output. Note there may be other log messages interspersed between these. +[source,options="nowrap"] ---- - * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * - - Called secured bean, caller principal quickstartUser - - Principal has admin permission: false - - * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * - - * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * +* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * +Called secured bean, caller principal quickstartUser - Called secured bean, caller principal superUser +Principal has admin permission: false +* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * - Principal has admin permission: true +* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * +Called secured bean, caller principal superUser - * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * +Principal has admin permission: true +* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * ---- As expected, the `quickstart` user is able to call the methods available for `guest`s but does not have the `admin` permission to call administrative methods on the remote EJB. The `superUser` on the other hand has permissions to call both methods. @@ -172,11 +168,12 @@ As expected, the `quickstart` user is able to call the methods available for `gu == Undeploy the Archive . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . When you are finished testing, type this command to undeploy the archive: - ++ +[source,options="nowrap"] ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- == Restore the Server Configuration @@ -187,26 +184,28 @@ You can restore the original server configuration by running the `restore-config . Start the {productName} server by typing the following: + -[subs="+quotes,attributes+"] +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +$ __{jbossHomeName}__/bin/standalone.sh ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. -. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing {jbossHomeName} +. 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: + -[subs="+quotes,attributes+"] +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/jboss-cli.sh --connect --file=restore-configuration.cli -For Windows: {jbossHomeName}\bin\jboss-cli.bat --connect --file=restore-configuration.cli +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=restore-configuration.cli ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. === Restore the Server Configuration Manually . If it is running, stop the {productName} server. -. Replace the `{jbossHomeName}/standalone/configuration/standalone.xml` file with the back-up copy of the file. +. Replace the `__{jbossHomeName}__/standalone/configuration/standalone.xml` file with the back-up copy of the file. == Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse @@ -214,31 +213,25 @@ You can also start the server and deploy the quickstarts or run the Arquillian t * Be sure to <> as described above. * Be sure to configure the server by running the JBoss CLI script as described above under <>. -* Right-click on the `{artifactId}` project and choose `Run As` –> `Maven build`. -Enter `clean package wildfly:deploy` for the `Goals:` and click `Run`. This deploys the `{artifactId}` JAR to the {productName} server. -* Right-click on the `{artifactId}` project and choose `Run As` –> `Run Configurations...`. -* Enter `exec:exec` for the `Goals` and click `Run`. +* Right-click on the *{artifactId}* project and choose *Run As* -> *Maven build*. +Enter `clean package wildfly:deploy` for the *Goals* and click *Run*. This deploys the `{artifactId}` JAR to the {productName} server. +* Right-click on the *{artifactId}* project and choose *Run As* -> *Run Configurations...*. +* Enter `exec:exec` for the *Goals* and click *Run*. * Review the output in the console window. You should see the following output. + +[source,options="nowrap"] ---- * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * - Called secured bean, caller principal quickstartUser - Principal has admin permission: false - * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * - * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * - Called secured bean, caller principal superUser - Principal has admin permission: true - * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * ---- -* To undeploy the project, right-click on the `{artifactId}` project and choose `Run As` –> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. +* To undeploy the project, right-click on the *{artifactId}* project and choose *Run As* -> *Maven build*. Enter `wildfly:undeploy` for the *Goals* and click *Run*. * Be sure to <> when you have completed testing this quickstart. @@ -246,6 +239,7 @@ Principal has admin permission: true If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. +[source,options="nowrap"] +---- +$ mvn dependency:sources ---- -mvn dependency:sources ----- \ No newline at end of file diff --git a/ejb-security/README.adoc b/ejb-security/README.adoc index d61c7faa5e..2a0ea04a5f 100644 --- a/ejb-security/README.adoc +++ b/ejb-security/README.adoc @@ -33,7 +33,7 @@ annotation in the EJB but it should not be granted access to the administrative The applications these projects produce are designed to be run on {productNameFull} {productVersion} or later. -All you need to build these projects is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build these projects is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. To run these quickstarts with the provided build scripts, you need the {productName} distribution ZIP. For information on how to install and run {productName}, see the {productNameFull} https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/[_Getting Started Guide_] located on the Customer Portal. @@ -41,34 +41,32 @@ You can also < @@ -115,42 +115,42 @@ After stopping the server, open the `{jbossHomeName}/standalone/configuration/st . The `http-remoting-connector` in the `remoting` subsystem was updated to use the `application-sasl-authentication` factory: + -[source, xml] +[source,xml,options="nowrap"] ---- - + ---- == Start the Server -. Open a command prompt and navigate to the root of the {productName} directory. +. Open a terminal and navigate to the root of the {productName} directory. . The following shows the command line to start the server: + -[subs=normal] +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +$ __{jbossHomeName}__/bin/standalone.sh ---- +NOTE: For Window, use the `__{jbossHomeName}__\bin\standalone.bat` script. == Build and Deploy the Quickstart . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type this command to build and deploy the archive: - ++ ---- -mvn clean package wildfly:deploy +$ mvn clean package wildfly:deploy ---- . This will deploy `target/{artifactId}.jar` to the running instance of the server. == Run the Client -Before you run the client, make sure you have already successfully deployed the EJBs to the server in the previous step and that your command prompt is still in the root directory of this quickstart. +Before you run the client, make sure you have already successfully deployed the EJBs to the server in the previous step and that your terminal is still in the root directory of this quickstart. Type this command to execute the client: ---- -mvn exec:exec +$ mvn exec:exec ---- == Investigate the Console Output @@ -177,15 +177,13 @@ NOTE: You should also see the following `EJBAccessException` printed in the serv As an exercise, you can rerun the `add-user` script described in the <> section, but this time grant the `quickstartUser` the admin role as follows: -[subs="+quotes,attributes+"] +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: - {jbossHomeName}/bin/add-user.sh -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest,admin' - -For Windows: - {jbossHomeName}\bin\add-user.bat -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest,admin' +$ __{jbossHomeName}__/bin/add-user.sh -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest,admin' ---- +NOTE: For Windows, use the `__{jbossHomeName}__\bin\add-user.bat` scripts. + After you update the `quickstartUser` user role, you must restart the server for it to take effect. Running the client again should immediately reflect the new permission level of the user: ---- @@ -201,11 +199,11 @@ Principal has admin permission: true == Undeploy the Archive . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . When you are finished testing, type this command to undeploy the archive: - ++ ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- == Restore the Server Configuration @@ -216,24 +214,26 @@ You can restore the original server configuration by running the `restore-config . Start the {productName} server by typing the following: + -[subs="+quotes,attributes+"] +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +$ __{jbossHomeName}__/bin/standalone.sh ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. -. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing {jbossHomeName} with the path to your server: +. 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: + -[subs="+quotes,attributes+"] +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/jboss-cli.sh --connect --file=restore-configuration.cli -For Windows: {jbossHomeName}\bin\jboss-cli.bat --connect --file=restore-configuration.cli +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=restore-configuration.cli ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. === Restore the Server Configuration Manually . If it is running, stop the {productName} server. -. Replace the `{jbossHomeName}/standalone/configuration/standalone.xml` file with the back-up copy of the file. +. Replace the `__{jbossHomeName}__/standalone/configuration/standalone.xml` file with the back-up copy of the file. == Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse @@ -241,10 +241,10 @@ You can also start the server and deploy the quickstarts or run the Arquillian t . Be sure to <> as described above. . Be sure to configure the server by running the JBoss CLI script as described above under <>. -. To deploy the server project, right-click on the `{artifactId}` project and choose `Run As` –> `Maven build`. Enter `clean package wildfly:deploy` for the `Goals:` and click `Run`. This deploys the `{artifactId}` JAR to the {productName} server. -. Right-click on the `{artifactId}` project and choose `Run As` –> `Run Configurations`. Enter `exec:exec` for the `Goals`, and then click `Run`. +. To deploy the server project, right-click on the *{artifactId}* project and choose *Run As* –> *Maven build*. Enter *clean package wildfly:deploy* for the *Goals* and click *Run*. This deploys the `{artifactId}` JAR to the {productName} server. +. Right-click on the *{artifactId}* project and choose *Run As* –> *Run Configurations*. Enter *exec:exec* for the *Goals*, and then click *Run*. . Review the output in the console window. You should see the same results as when running Maven in the command line. -. To undeploy the project, right-click on the `{artifactId}` project and choose `Run As` –> `Run Configurations`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. +. To undeploy the project, right-click on the *{artifactId}* project and choose *Run As* –> *Run Configurations*. Enter `wildfly:undeploy` for the *Goals* and click *Run*. . Be sure to <> when you have completed testing this quickstart. == Debug the Application @@ -252,5 +252,5 @@ You can also start the server and deploy the quickstarts or run the Arquillian t If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. ---- -mvn dependency:sources ----- \ No newline at end of file +$ mvn dependency:sources +---- diff --git a/ejb-throws-exception/README.adoc b/ejb-throws-exception/README.adoc index 665a2549a5..384fb7b192 100644 --- a/ejb-throws-exception/README.adoc +++ b/ejb-throws-exception/README.adoc @@ -12,17 +12,17 @@ include::../attributes.adoc[] :source: {githubRepoUrl} [abstract] -The `ejb-throws-exception` quickstart demonstrates how to throw and handle Exceptions across JARs in an EAR. +The `ejb-throws-exception` quickstart demonstrates how to throw and handle exceptions across JARs in an EAR. == What is it? -The `ejb-throws-exception` quickstart extends the link:../ejb-in-ear/README.md[ejb-in-ear] quickstart and demonstrates how to handle Exceptions across JARs in an EAR deployed to {productNameFull}. In this quickstart, an EJB in the EJB JAR throws a custom Exception. The web application in the client JAR catches the Exception and displays it in a nicely formatted message. The EAR contains: _JSF WAR_, an _EJB_ JAR and a client library JAR containg classes that both the WAR and EJB JAR use. +The `ejb-throws-exception` quickstart extends the link:../ejb-in-ear/README.adoc[ejb-in-ear] quickstart and demonstrates how to handle exceptions across JARs in an EAR deployed to {productNameFull}. In this quickstart, an EJB in the EJB JAR throws a custom exception. The web application in the client JAR catches the exception and displays it in a nicely formatted message. The EAR contains: _JSF WAR_, an _EJB_ JAR and a client library JAR containg classes that both the WAR and EJB JAR use. The example is composed of three Maven projects, each with a shared parent. The projects are as follows: -. `ejb`: This project contains the EJB code and can be built independently to produce the JAR archive. The EJB has a single method `sayHello` which will take in a String `name` and return `Hello <name>` if the `name` is not null or an empty String. If the `name` is null or an empty String, then it will throw a custom Exception (`GreeterException`) back to the client. +. `ejb`: This project contains the EJB code and can be built independently to produce the JAR archive. The EJB has a single method `sayHello` which will take in a String `name` and return `Hello <name>` if the `name` is not null or an empty String. If the `name` is null or an empty String, then it will throw a custom exception (`GreeterException`) back to the client. -. `web`: This project contains the JSF pages and the CDI managed bean. The CDI Managed Bean (GreeterBean) will be bound to the JSF page (index.xhtml) and will invoke the GreeterEJB and display the response back from the EJB. The GreeterBean catches the custom Exception (GreeterException) thrown by GreeterEJB and displays the Exception message in the response text on the JSF page. +. `web`: This project contains the JSF pages and the CDI managed bean. The CDI Managed Bean (GreeterBean) will be bound to the JSF page (index.xhtml) and will invoke the GreeterEJB and display the response back from the EJB. The GreeterBean catches the custom exception (`GreeterException`) thrown by GreeterEJB and displays the exception message in the response text on the JSF page. . `ear`: This project builds the EAR artifact and pulls in the ejb, web, and client artifacts. @@ -35,7 +35,7 @@ The example follows the common `Hello World` pattern. These are the steps that o . A JSF page (http://localhost:8080/{artifactId}/) asks for the user name. . On clicking `Say Hello`, the value of the `Name` input text is sent to a managed bean named `GreeterBean`. . On setting the name, the `Greeter` invokes the `GreeterEJB`, which was injected to the managed bean. Notice the field annotated with `@EJB`. -. The EJB responds with `Hello <name>` or throws an Exception if the name is empty or null. +. The EJB responds with `Hello <name>` or throws an exception if the name is empty or null. . The response or exception's message from invoking the `GreeterEJB` is stored in a field (response) of the managed bean. . The managed bean is annotated as `@RequestScoped`, so the same managed bean instance is used only for the request/response. @@ -43,31 +43,32 @@ The example follows the common `Hello World` pattern. These are the steps that o The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Use of {jbossHomeName} -In the following instructions, replace `{jbossHomeName}` with the actual path to your {productName} installation. The installation path is described in detail here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_{jbossHomeName}.md#use-of-eap_home-and-jboss_home-variables[Use of {jbossHomeName} and JBOSS_HOME Variables]. +In the following instructions, replace `__{jbossHomeName}__` with the actual path to your {productName} installation. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of {jbossHomeName} and JBOSS_HOME Variables]. == Start the Server -. Open a command prompt and navigate to the root of the {productName} directory. +. Open a terminal and navigate to the root of the {productName} directory. . The following shows the command line to start the server: - -[subs=normal] ++ +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +$ __{jbossHomeName}__/bin/standalone.sh ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. == Build and Deploy the Quickstart . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type this command to build and deploy the archive: - ++ ---- -mvn clean install wildfly:deploy +$ mvn clean install wildfly:deploy ---- . This will deploy `ear/target/{artifactId}.ear` to the running instance of the server. @@ -76,37 +77,37 @@ mvn clean install wildfly:deploy The application will be running at the following URL http://localhost:8080/{artifactId}/. -Enter a name in the input field `Name` and click the `Say Hello` button to see the response. +Enter a name in the input field *Name* and click the *Say Hello* button to see the response. -The `Response` output text will display the response from the EJB. -If the `Name` input text box is not empty, then the `Response` output text will display `Hello <name>` -If the `Name` input text box is empty, then the `Response` output text will display the message of the exception throw back from the EJB. +The *Response* output text will display the response from the EJB. +If the *Name* input text box is not empty, then the *Response* output text will display *Hello * +If the *Name* input text box is empty, then the *Response* output text will display the message of the exception throw back from the EJB. == Undeploy the Archive . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . When you are finished testing, type this command to undeploy the archive: - ++ ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- == Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a {productName} server, and build and deploy a quickstart, see link:{useEclipseUrl}[Use JBoss Developer Studio or Eclipse to Run the Quickstarts]. -For this quickstart, follow the special instructions to build https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#deploy-and-undeploy-a-quickstart-ear-project[Quickstarts Containing an EAR] +For this quickstart, follow the special instructions to build link:{useEclipseDeployEARDocUrl}[Quickstarts Containing an EAR]. -. Right-click on the `{artifactId}-ear` subproject, and choose `Run As` –> `Run on Server`. -. Choose the server and click `Finish`. +. Right-click on the *{artifactId}-ear* subproject, and choose *Run As* -> *Run on Server*. +. Choose the server and click *Finish*. . This starts the server, deploys the application, and opens a browser window that accesses the running application. -. To undeploy the project, right-click on the `{artifactId}-ear` project and choose `Run As` –> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. +. To undeploy the project, right-click on the *{artifactId}-ear* project and choose *Run As* -> *Maven build*. Enter `wildfly:undeploy` for the *Goals* and click *Run*. == Debug the Application If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. ---- - mvn dependency:sources ----- \ No newline at end of file +$ mvn dependency:sources +---- diff --git a/ejb-timer/README.adoc b/ejb-timer/README.adoc index 6389d48440..12625d7209 100644 --- a/ejb-timer/README.adoc +++ b/ejb-timer/README.adoc @@ -27,33 +27,35 @@ The following EJB Timer services are demonstrated: The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Use of {jbossHomeName} -In the following instructions, replace `{jbossHomeName}` with the actual path to your {productName} installation. The installation path is described in detail here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_{jbossHomeName}.md#use-of-eap_home-and-jboss_home-variables[Use of {jbossHomeName} and JBOSS_HOME Variables]. +In the following instructions, replace `__{jbossHomeName}__` with the actual path to your {productName} installation. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of {jbossHomeName} and JBOSS_HOME Variables]. == Start the Server -. Open a command prompt and navigate to the root of the {productName} directory. +. Open a terminal and navigate to the root of the {productName} directory. . The following shows the command line to start the server: - -[subs=normal] ++ +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +$ __{jbossHomeName}__/bin/standalone.sh ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. == Build and Deploy the Quickstart . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type this command to build and deploy the archive: - ++ +[source,options="nowrap"] ---- -mvn clean install wildfly:deploy +$ mvn clean install wildfly:deploy ---- - ++ This will deploy `target/{artifactId}.war` to the running instance of the server. == Access the Application @@ -61,13 +63,14 @@ This will deploy `target/{artifactId}.war` to the running instance of the server This application only prints messages to stdout. To see it working, check the server log. You should see similar output: +[source,options="nowrap"] ---- INFO [stdout] (EJB default - 10) ScheduleExample.doWork() invoked at 2014.11.25 AD at 11:57:12 EST INFO [stdout] (EJB default - 2) TimeoutExample.scheduler() EJB timer service timeout at 2014.11.25 AD at 11:57:12 EST INFO [stdout] (EJB default - 4) TimeoutExample.scheduler() EJB timer service timeout at 2014.11.25 AD at 11:57:15 EST INFO [stdout] (EJB default - 3) TimeoutExample.scheduler() EJB timer service timeout at 2014.11.25 AD at 11:57:18 EST INFO [stdout] (EJB default - 5) ScheduleExample.doWork() invoked at 2014.11.25 AD at 11:57:18 EST -INFO [stdout] (EJB default - 7) TimeoutExample.scheduler() EJB timer service timeout at 2014.11.25 AD at 11:57:21 EST +INFO [stdout] (EJB default -7) TimeoutExample.scheduler() EJB timer service timeout at 2014.11.25 AD at 11:57:21 EST INFO [stdout] (EJB default - 9) TimeoutExample.scheduler() EJB timer service timeout at 2014.11.25 AD at 11:57:24 EST INFO [stdout] (EJB default - 6) ScheduleExample.doWork() invoked at 2014.11.25 AD at 11:57:24 EST INFO [stdout] (EJB default - 8) TimeoutExample.scheduler() EJB timer service timeout at 2014.11.25 AD at 11:57:27 EST @@ -85,11 +88,12 @@ Existing threads in the thread pool handle the invocations. They are rotated and == Undeploy the Archive . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . When you are finished testing, type this command to undeploy the archive: - ++ +[source,options="nowrap"] ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- == Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse @@ -101,6 +105,7 @@ You can also start the server and deploy the quickstarts or run the Arquillian t If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. +[source,options="nowrap"] +---- +$ mvn dependency:sources ---- - mvn dependency:sources ----- \ No newline at end of file diff --git a/forge-from-scratch/README.adoc b/forge-from-scratch/README.adoc index 05623b52df..0b178cce80 100644 --- a/forge-from-scratch/README.adoc +++ b/forge-from-scratch/README.adoc @@ -16,13 +16,17 @@ The `forge-from-scratch` quickstart demonstrates how *JBoss Forge* can generate == What is it? -The `forge-from-scratch` quickstart demonstrates how to create a fully *Java EE compliant* project using *JBoss Forge* and *Red Hat JBoss Developer Studio* and deploy it to *{productNameFull} {productVersion}* or later. +The `forge-from-scratch` quickstart demonstrates how to create a fully Java EE compliant project using JBoss Forge and Red Hat JBoss Developer Studio, and deploy it to {productNameFull} {productVersion} or later. -The generated example will be a standard Maven, Java Web project with *JPA, EJB, CDI, JSF* with complete *JAX-RS* endpoints for all data Entities. It will also provide views to `Create`, `Read`, `Update`, and `Delete` records. +The generated example will be a standard Maven, Java Web project with JPA, EJB, CDI, JSF with complete JAX-RS endpoints for all data Entities. It will also provide views to `Create`, `Read`, `Update`, and `Delete` records. But that is not all! You can use Forge on your new or existing projects to continue to enhance any application. -_Note: This quickstart uses the H2 database included with {productNameFull} {productVersion}. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ +//************************************************* +// Add notes about use in a production environment. +//************************************************* +:uses-h2: +include::../development-shortcuts.adoc[leveloffset=+1] == System Requirements @@ -37,16 +41,18 @@ JBoss Developer Studio 10.3 ships with Forge 3.5.1.Final. === Generate and Build the Application . Start JBoss Developer Studio. -. Open the `Forge Console` Window. To open it, navigate to menu item _Window -> Show View -> Other_. Locate _Forge -> Forge Console_ and click _OK_. -. Click the _Start_ button (green triangle) in top right corner of the Forge Console to start the default Forge runtime. +. Open the *Forge Console* Window. To open it, navigate to menu item *Window* -> *Show View* -> *Other*. Locate *Forge* -> *Forge Console* and click *OK*. +. Click the *Start* button (green triangle) in top right corner of the Forge Console to start the default Forge runtime. . In the Forge Console Window, navigate to the root directory of this quickstart. - ++ +[source,subs="+quotes,attributes+",options="nowrap"] ---- -$ cd QUICKSTART_HOME/forge-from-scratch/ +$ cd __QUICKSTART_HOME__/forge-from-scratch/ ---- . Notice there is a file in this directory named `generate.fsh`. Run this file from the Forge console using the `run` command: - ++ +[source,options="nowrap"] ---- $ run generate.fsh ---- @@ -58,32 +64,36 @@ $ run generate.fsh ** This is followed by a number of commands that set up JPA, create an entity and its fields, set up and generate the scaffold, and set up CDI and REST. Each command should result in a `***SUCCESS***` message. ** Finally, the `build` command is executed, which should result in `***SUCCESS*** Build Success` near the end of the console output. -NOTE: After you run the `run generate.fsh` command, you will see the following warnings in the _Problems_ window for the generated files. You can ignore these warnings. +[NOTE] +==== +After you run the `run generate.fsh` command, you will see the following warnings in the _Problems_ window for the generated files. You can ignore these warnings. +[source,options="nowrap"] ---- - Web XML Problem: location references to "/faces/error.xhtml" that does not exist in web content web.xml /forge-example/src/main/webapp/WEB-INF line 17 - Web XML Problem: location references to "/faces/error.xhtml" that does not exist in web content web.xml /forge-example/src/main/webapp/WEB-INF line 21 - JPA Problem: No connection specified for project. No database-specific validation will be performed. forge-example +Web XML Problem: location references to "/faces/error.xhtml" that does not exist in web content web.xml /forge-example/src/main/webapp/WEB-INF line 17 +Web XML Problem: location references to "/faces/error.xhtml" that does not exist in web content web.xml /forge-example/src/main/webapp/WEB-INF line 21 +JPA Problem: No connection specified for project. No database-specific validation will be performed. forge-example ---- +==== === What Did This Create? This quickstart created a native Java EE 7 application. -* After the command completes, look in your `QUICKSTART_HOME/forge-from-scratch/` folder. You see a folder with the name `forge-example`. +* After the command completes, look in your `__QUICKSTART_HOME__/forge-from-scratch/` folder. You see a folder with the name `forge-example`. * This project also appears in the `Project Explorer` view in JBoss Developer Studio. * Browse through this project to see the code that was generated as a result of this command. === Deploy the Generated Application -. If you have not yet done so, add the {productName} {productVersion} runtime server to Red Hat JBoss Developer Studio. For general information about how to import a quickstart, add a {productName} server, and build and deploy a quickstart, see https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md[Use JBoss Developer Studio or Eclipse to Run the Quickstarts]. -. Right-click on the project name and choose `Run As` –> `Run on Server`. If you have more than one server, choose the {productName} {productVersion} Runtime server. Then click `Finish`. +. If you have not yet done so, add the {productName} {productVersion} runtime server to Red Hat JBoss Developer Studio. For general information about how to import a quickstart, add a {productName} server, and build and deploy a quickstart, see link:{useEclipseDeployJavaClientDocUrl}[Use JBoss Developer Studio or Eclipse to Run the Quickstarts]. +. Right-click on the project name and choose *Run As* -> *Run on Server*. If you have more than one server, choose the {productName} {productVersion} Runtime server. Then click *Finish*. . Upon successful deployment, a *Welcome to Forge Window* opens with the application running at the following URL: http://localhost:8080/forge-example/ === Server Log: Expected warnings and errors -NOTE: You will see the following warnings in the server log. You can ignore these warnings. - +You will see the following warnings in the server log. You can ignore these warnings. +[source,options="nowrap"] ---- WFLYTX0013: Node identifier property is set to the default value. Please make sure it is unique. WFLYDM0111: Keystore /home/user/eap-7.1/standalone/configuration/application.keystore not found, it will be auto generated on first use with a self signed certificate for host localhost @@ -95,6 +105,7 @@ HHH000431: Unable to determine H2 database version, certain features may not wor The application appears in a 'Welcome to Forge' Window and displays the following: +[source,options="nowrap"] ---- Welcome to Forge @@ -122,11 +133,12 @@ The running application also provides links to find more information about the F When you are ready to undeploy the application from {productName}: -. Go to the Red Hat JBoss Developer Studio `Servers` window. +. Go to the Red Hat JBoss Developer Studio *Servers* window. . Expand the {productName} Server to see the list of deployed applications. -. Choose the `forge-example` project created by this quickstart, right-click, and choose `Remove`. -. Click `OK` when asked if you are sure you want to remove resource from the server. You should see the following message: - +. Choose the *forge-example* project created by this quickstart, right-click, and choose *Remove*. +. Click *OK* when asked if you are sure you want to remove resource from the server. You should see the following message: ++ +[source,options="nowrap"] ---- INFO [org.jboss.as.server] (DeploymentScanner-threads - 1) WFLYSRV0009: Undeployed "forge-example.war" (runtime-name: "forge-example.war") ---- @@ -135,4 +147,4 @@ INFO [org.jboss.as.server] (DeploymentScanner-threads - 1) WFLYSRV0009: Undeplo Open `generate.fsh` and take a look inside! There is not much magic happening here. All of the commands used to generate this project are clearly listed just as if they were typed by your own hands. -Play around with creating more entities, relationships, UI, and generating JAX-RS endpoints,all with just a few simple commands. \ No newline at end of file +Play around with creating more entities, relationships, UI, and generating JAX-RS endpoints,all with just a few simple commands. diff --git a/greeter/README.adoc b/greeter/README.adoc index 490bb2666a..72750b130a 100644 --- a/greeter/README.adoc +++ b/greeter/README.adoc @@ -28,39 +28,43 @@ To test this example: . To create a new user, click the `Add a new user` link. Enter the username, first name, and last name and then click `Add User`. The user is added and a message displays the new user id number. . Click on the `Greet a user!` link to return to the `Greet!` page. -_Note: This quickstart uses the H2 database included with {productNameFull} {productVersion}. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ - -_Note: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in {productName} and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/[Configuration Guide] for {productNameFull}._ +//************************************************* +// Add notes about use in a production environment. +//************************************************* +:uses-h2: +:uses-ds-xml: +include::../development-shortcuts.adoc[leveloffset=+1] == System Requirements The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Use of {jbossHomeName} -In the following instructions, replace `{jbossHomeName}` with the actual path to your {productName} installation. The installation path is described in detail here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_{jbossHomeName}.md#use-of-eap_home-and-jboss_home-variables[Use of {jbossHomeName} and JBOSS_HOME Variables]. +In the following instructions, replace `__{jbossHomeName}__` with the actual path to your {productName} installation. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of {jbossHomeName} and JBOSS_HOME Variables]. == Start the Server -. Open a command prompt and navigate to the root of the {productName} directory. +. Open a terminal and navigate to the root of the {productName} directory. . The following shows the command line to start the server: - -[subs=normal] ++ +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +$ __{jbossHomeName}__/bin/standalone.sh ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. == Build and Deploy the Quickstart . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type this command to build and deploy the archive: - ++ ---- -mvn clean install wildfly:deploy +$ mvn clean install wildfly:deploy ---- . This will deploy `target/{artifactId}.war` to the running instance of the server. @@ -72,17 +76,16 @@ The application will be running at the following URL: http://localhost:8080/{art == Undeploy the Archive . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . When you are finished testing, type this command to undeploy the archive: - ++ ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- == Server Log: Expected Warnings and Errors -NOTE: You will see the following warnings in the server log. You can ignore these warnings. - +You will see the following warnings in the server log. You can ignore these warnings. ---- WFLYJCA0091: -ds.xml file deployments are deprecated. Support may be removed in a future version. @@ -98,5 +101,5 @@ You can also start the server and deploy the quickstarts or run the Arquillian t If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. ---- - mvn dependency:sources ----- \ No newline at end of file +$ mvn dependency:sources +---- diff --git a/ha-singleton-deployment/README.adoc b/ha-singleton-deployment/README.adoc index 5ea03e1387..6eacf19e52 100644 --- a/ha-singleton-deployment/README.adoc +++ b/ha-singleton-deployment/README.adoc @@ -26,11 +26,11 @@ For more information about singleton deployments, see _HA Singleton Deployments_ The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -Everything needed to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure the environment is configured correctly for testing the quickstarts. +Everything needed to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure the environment is configured correctly for testing the quickstarts. == Use of {jbossHomeName} -In the following instructions, replace `{jbossHomeName}` with the actual path to your {productName} installation. The installation path is described in detail here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_{jbossHomeName}.md#use-of-eap_home-and-jboss_home-variables[Use of {jbossHomeName} and JBOSS_HOME Variables]. +In the following instructions, replace `__{jbossHomeName}__` with the actual path to your {productName} installation. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of {jbossHomeName} and JBOSS_HOME Variables]. == Setting Up the Test Environment @@ -41,34 +41,40 @@ Note that the example can be run on a single node as well, but without observati Start the two {productName} servers with the same HA profile using the following commands. Note that a socket binding port offset and a unique node name must be passed to the second server if the servers are binding to the same host. -For Linux: -[subs="+quotes,attributes+"] +* Start server 1: ++ +[source,subs="+quotes,attributes+",options="nowrap"] ---- -Server 1: {jbossHomeName}_1/bin/standalone.sh -c standalone-ha.xml -Djboss.node.name=node1 -Server 2: {jbossHomeName}_2/bin/standalone.sh -c standalone-ha.xml -Djboss.node.name=node2 -Djboss.socket.binding.port-offset=100 +$ __{jbossHomeName}_1__/bin/standalone.sh -c standalone-ha.xml -Djboss.node.name=node1 ---- ++ +NOTE: For Windows, use the `{jbossHomeName}_1\bin\standalone.bat` script. -For Windows: -[subs="+quotes,attributes+"] +* Start server 2, using the port offset: ++ +[source,subs="+quotes,attributes+",options="nowrap"] ---- -Server 1: {jbossHomeName}_1\bin\standalone.bat -c standalone-ha.xml -Djboss.node.name=node1 -Server 2: {jbossHomeName}_2\bin\standalone.bat -c standalone-ha.xml -Djboss.node.name=node2 -Djboss.socket.binding.port-offset=100 +$ __{jbossHomeName}_2__/bin/standalone.sh -c standalone-ha.xml -Djboss.node.name=node2 -Djboss.socket.binding.port-offset=100 ---- ++ +NOTE: For Windows, use the `{jbossHomeName}_1\bin\standalone.bat` script. -The demonstration is not limited to two servers. Additional servers can be started by specifying a unique port offset for each one. +This example is not limited to two servers. Additional servers can be started by specifying a unique port offset for each one. == Running the Quickstart . Start the {productName} servers as described in the above section. -. Navigate to the root directory of this quickstart in the command prompt. +. Navigate to the root directory of this quickstart in the terminal. . Use the following command to clean up previously built artifacts, and build and deploy the EJB archive: + +[source,options="nowrap"] ---- -mvn clean install wildfly:deploy +$ mvn clean install wildfly:deploy ---- . Ensure the `target/{artifactId}.jar` archive is deployed to `node1` (the one without port offset) by observing the log. + +[source,options="nowrap"] ---- INFO [org.jboss.as.server.deployment] (MSC service thread 1-1) WFLYSRV0027: Starting deployment of "ha-singleton-deployment.jar" (runtime-name: "ha-singleton-deployment.jar") ... @@ -82,12 +88,14 @@ INFO [class org.jboss.as.quickstarts.ha.singleton.SingletonTimer] (EJB default . Use the following command to deploy the already built archive to the second server. Note that since the default socket binding port is `9990` and the second server has ports offsetted by `100`, the sum, `10090` must be passed as an argument to the deploy maven goal. + +[source,options="nowrap"] ---- mvn wildfly:deploy -Dwildfly.port=10090 ---- . Ensure the `service/target/{artifactId}.jar` archive is deployed to `node2` by observing the log. Note that even though the logs indicate "Deployed", the deployment does not actually deploy completely and the timer is not operating on this node. + +[source,options="nowrap"] ---- INFO [org.jboss.as.server.deployment] (MSC service thread 1-6) WFLYSRV0027: Starting deployment of "ha-singleton-deployment.jar" (runtime-name: "ha-singleton-deployment.jar") INFO [org.infinispan.remoting.transport.jgroups.JGroupsTransport] (MSC service thread 1-3) ISPN000078: Starting JGroups channel server @@ -102,12 +110,14 @@ INFO [org.jboss.as.server] (management-handler-thread - 2) WFLYSRV0010: Deploye . Verify the timer is running only on one instance by observing the logs. The node running the timer will output the following every 5 seconds: + +[source,options="nowrap"] ---- INFO [class org.jboss.as.quickstarts.ha.singleton.SingletonTimer] (EJB default - 1) SingletonTimer: Hello World! ---- -. Verify failover of the singleton deployment. Shutdown the server operating as the singleton master, for instance by using the `Ctrl` + `C` key combination in the command prompt. Observe the following messages on the node being shutdown: +. Verify failover of the singleton deployment. Shutdown the server operating as the singleton master, for instance by using the `Ctrl` + `C` key combination in the terminal. Observe the following messages on the node being shutdown: + +[source,options="nowrap"] ---- INFO [class org.jboss.as.quickstarts.ha.singleton.SingletonTimer] (EJB default - 3) SingletonTimer: Hello World! INFO [class org.jboss.as.quickstarts.ha.singleton.SingletonTimer] (EJB default - 4) SingletonTimer: Hello World! @@ -125,6 +135,7 @@ Make sure to start the server with an HA profile using `-c standalone-ha.xml`. Another common cause is that the server instances did not discover each other and each server is operating as a singleton cluster. Ensure that multicast is enabled or change the `jgroups` subsystem configuration to use a different discovery mechanism. Observe the following log line to ensure that the discovery was successful: +[source,options="nowrap"] ---- INFO [org.infinispan.remoting.transport.jgroups.JGroupsTransport] (MSC service thread 1-3) ISPN000094: Received new cluster view for channel server: [node1|1] (2) [node1, node2] ---- @@ -139,24 +150,27 @@ To demonstrate how to use deployment overlays, follow these steps: . Move the `src/main/resources/META-INF/singleton-deployment.xml` file into root directory of this quickstart. . Rebuild the project. Ensure that the servers are started, and redeploy the application, which will no longer be configured by singleton deployment by the archive: + +[source,options="nowrap"] ---- -mvn clean install -mvn wildfly:deploy -mvn wildfly:deploy -Dwildfly.port=10090 +$ mvn clean install +$ mvn wildfly:deploy +$ mvn wildfly:deploy -Dwildfly.port=10090 ---- . Start the management CLI and set up a deployment overlay on both servers: + -[subs="+quotes,attributes+"] +[source,subs="+quotes,attributes+",options="nowrap"] ---- -{jbossHomeName}_1/bin/jboss-cli.sh --connect +$ __{jbossHomeName}_1__/bin/jboss-cli.sh --connect deployment-overlay add --name=singleton-deployment --deployments=ha-singleton-deployment.jar --content=META-INF/singleton-deployment.xml=singleton-deployment.xml deployment-overlay redeploy-affected --name=singleton-deployment ---- ++ +NOTE: For Windows, use the ` __{jbossHomeName}_1__\bin\jboss-cli.bat` script. . Review the deployment overlay changes in the `standalone-ha.xml` server profile: + -[source, xml] +[source,xml,options="nowrap"] ---- @@ -170,6 +184,7 @@ deployment-overlay redeploy-affected --name=singleton-deployment . To remove the deployment overlay run the following CLI command: + +[source,options="nowrap"] ---- deployment-overlay remove --name=singleton-deployment deployment-overlay redeploy-affected --name=singleton-deployment @@ -180,10 +195,11 @@ For convenience, the management CLI scripts to add the deployment overlay, `sing == Undeploy the Archives . Ensure all {productName} servers are started. -. Navigate to the root directory of this quickstart in the command prompt. +. Navigate to the root directory of this quickstart in the terminal. . Use the following commands to undeploy the artifacts: + +[source,options="nowrap"] +---- +$ mvn wildfly:undeploy +$ mvn wildfly:undeploy -Dwildfly.port=10090 ---- -mvn wildfly:undeploy -mvn wildfly:undeploy -Dwildfly.port=10090 ----- \ No newline at end of file diff --git a/ha-singleton-service/README.adoc b/ha-singleton-service/README.adoc index 9e931e0b1c..879f5b672b 100644 --- a/ha-singleton-service/README.adoc +++ b/ha-singleton-service/README.adoc @@ -35,11 +35,11 @@ For more information about clustered singleton services, see _HA Singleton Servi The deployments this project produces are designed to be run on {productNameFull} {productVersion} or later. -Everything needed to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure the environment is configured correctly for testing the quickstarts. +Everything needed to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure the environment is configured correctly for testing the quickstarts. == Use of {jbossHomeName}_1 and {jbossHomeName}_2 -This quickstart requires that you clone your `{jbossHomeName}` installation directory and run two servers. The installation path is described in detail here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_{jbossHomeName}.md#use-of-eap_home-and-jboss_home-variables[Use of {jbossHomeName} and JBOSS_HOME Variables]. +This quickstart requires that you clone your `__{jbossHomeName}__` installation directory and run two servers. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of {jbossHomeName} and JBOSS_HOME Variables]. In the following instructions, replace `{jbossHomeName}_1` with the path to your first {productName} server and replace `{jbossHomeName}_2` with the path to your second cloned {productName} server. @@ -54,21 +54,23 @@ NOTE: You must start the server using the HA profile or the singleton service wi Start the two {productName} servers with the HA profile, passing a unique node ID. These logical node names are used in the log to identify which node is elected. If you are running the servers on the same host, you must also pass a socket binding port offset on the command line to start the second server. To start the servers, type the following commands. -For Linux: - -[subs="+quotes,attributes+"] +* Start server 1: ++ +[source,subs="+quotes,attributes+",options="nowrap"] ---- -Server 1: {jbossHomeName}_1/bin/standalone.sh -c standalone-ha.xml -Djboss.node.name=node1 -Server 2: {jbossHomeName}_2/bin/standalone.sh -c standalone-ha.xml -Djboss.node.name=node2 -Djboss.socket.binding.port-offset=100 +$ __{jbossHomeName}_1__/bin/standalone.sh -c standalone-ha.xml -Djboss.node.name=node1 ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}_1__\bin\standalone.bat` script. -For Windows: - -[subs="+quotes,attributes+"] +* Start server 2 with port offset: ++ +[source,subs="+quotes,attributes+",options="nowrap"] ---- -Server 1: {jbossHomeName}_1\bin\standalone.bat -c standalone-ha.xml -Djboss.node.name=node1 -Server 2: {jbossHomeName}_2\bin\standalone.bat -c standalone-ha.xml -Djboss.node.name=node2 -Djboss.socket.binding.port-offset=100 +$ __{jbossHomeName}_2__/bin/standalone.sh -c standalone-ha.xml -Djboss.node.name=node2 -Djboss.socket.binding.port-offset=100 ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}_2__\bin\standalone.bat` script. This example is not limited to two servers. Additional servers can be started by specifying a unique node name and port offset for each one. @@ -79,15 +81,17 @@ This example demonstrates a singleton service and a querying service that regula === Build and Deploy primary-only to Server 1 . Start the {productName} servers as described in the above section. -. Open a command prompt and navigate to the `primary-only/` directory located in the root directory of this quickstart. +. Open a terminal and navigate to the `primary-only/` directory located in the root directory of this quickstart. . Use the following command to clean up any previously built artifacts, and to build and deploy the JAR archive. - ++ +[source,options="nowrap"] ---- -mvn clean install wildfly:deploy +$ mvn clean install wildfly:deploy ---- . Investigate the primary-only Console Output for Server 1. Verify that the `target/ha-singleton-service-primary-only.jar` archive is deployed to `node1`, which is the first server started without port offset, by checking the server log. - ++ +[source,options="nowrap"] ---- INFO [org.jboss.as.server.deployment] (MSC service thread 1-7) WFLYSRV0027: Starting deployment of "ha-singleton-service-primary-only.jar" (runtime-name: "ha-singleton-service-primary-only.jar") INFO [org.jboss.as.quickstarts.ha.singleton.service.primary.ServiceActivator] (MSC service thread 1-5) Singleton and querying services activated. @@ -99,23 +103,29 @@ INFO [org.jboss.as.quickstarts.ha.singleton.service.primary.SingletonService] ( INFO [org.jboss.as.quickstarts.ha.singleton.service.primary.QueryingService] (pool-4-thread-1) Singleton service is running on node 'node1'. ---- -NOTE: You might see the following warnings in the server log after the applications are deployed. These warnings can be ignored in a development environment. +[NOTE] +==== +You might see the following warnings in the server log after the applications are deployed. These warnings can be ignored in a development environment. +[source,options="nowrap"] ---- WARN [org.jboss.as.clustering.jgroups.protocol.UDP] (ServerService Thread Pool -- 68) JGRP000015: the receive buffer of socket MulticastSocket was set to 20MB, but the OS only allocated 6.71MB. This might lead to performance problems. Please set your max receive buffer in the OS correctly (e.g. net.core.rmem_max on Linux) WARN [org.jboss.as.clustering.jgroups.protocol.UDP] (ServerService Thread Pool -- 68) JGRP000015: the receive buffer of socket MulticastSocket was set to 25MB, but the OS only allocated 6.71MB. This might lead to performance problems. Please set your max receive buffer in the OS correctly (e.g. net.core.rmem_max on Linux) ---- +==== === Deploy the primary-only Archive to Server 2 . Use the following command to deploy the same archive to the second server. Because the default socket binding port for deployment is `9990` and the second server ports are offset by `100`, you must pass the sum, `10090`, for the socket binding port as the argument to the `deploy` Maven goal. + +[source,options="nowrap"] ---- mvn wildfly:deploy -Dwildfly.port=10090 ---- . Investigate the primary-only console output for both servers. Verify that the `target/ha-singleton-service-primary-only.jar` archive is deployed to `node2` by checking the server log. + +[source,options="nowrap"] ---- INFO [org.jboss.as.repository] (management-handler-thread - 4) WFLYDR0001: Content added at location /Users/rhusar/wildfly/build/target/y/standalone/data/content/18/6efcc6c07b471f641cfcc97f9120505726e6bd/content INFO [org.jboss.as.server.deployment] (MSC service thread 1-1) WFLYSRV0027: Starting deployment of "ha-singleton-service-primary-only.jar" (runtime-name: "ha-singleton-service-primary-only.jar") @@ -129,6 +139,7 @@ INFO [org.jboss.as.quickstarts.ha.singleton.service.primary.QueryingService] (p . Inspect the server log of the first node. Since the cluster membership has changed, the election policy determines which node will run the singleton. + +[source,options="nowrap"] ---- INFO [org.infinispan.CLUSTER] (remote-thread--p7-t1) ISPN000336: Finished cluster-wide rebalance for cache default, topology id = 5 INFO [org.wildfly.clustering.server] (DistributedSingletonService - 1) WFLYCLSV0003: node1 elected as the singleton provider of the org.jboss.as.quickstarts.ha.singleton.service.primary-only service @@ -136,14 +147,16 @@ INFO [org.wildfly.clustering.server] (DistributedSingletonService - 1) WFLYCLSV . Verify that the querying service is running on all nodes and that all are querying the same singleton service instance by confirming that the same node name is printed in the log. Both nodes will output the following message every 5 seconds: + +[source,options="nowrap"] ---- INFO [org.jboss.as.quickstarts.ha.singleton.service.primary.QueryingService] (pool-4-thread-1) Singleton service is running on node 'node1'. ---- === Test Singleton Service Failover for the primary-only Example -. To verify failover of the singleton service, shut down the server operating as the singleton master by using the `Ctrl` + `C` key combination in the command prompt. The following messages confirm that the node is shut down. +. To verify failover of the singleton service, shut down the server operating as the singleton master by using the `Ctrl` + `C` key combination in the terminal. The following messages confirm that the node is shut down. + +[source,options="nowrap"] ---- INFO [org.jboss.as.quickstarts.ha.singleton.service.primary.QueryingService] (pool-4-thread-1) Singleton service is running on node 'node1'. INFO [org.jboss.as.server] (Thread-2) WFLYSRV0220: Server shutdown has been requested via an OS signal @@ -155,6 +168,7 @@ INFO [org.jboss.as] (MSC service thread 1-6) WFLYSRV0050: JBoss EAP 7.1.0.Beta1 . Now observe the log messages on the second server. The second node is now elected as the singleton master. + +[source,options="nowrap"] ---- INFO [org.wildfly.clustering.server] (DistributedSingletonService - 1) WFLYCLSV0003: node2 elected as the singleton provider of the org.jboss.as.quickstarts.ha.singleton.service.primary-only service INFO [org.wildfly.clustering.server] (DistributedSingletonService - 1) WFLYCLSV0001: This node will now operate as the singleton provider of the org.jboss.as.quickstarts.ha.singleton.service.primary-only service @@ -164,17 +178,19 @@ INFO [org.jboss.as.quickstarts.ha.singleton.service.primary.SingletonService] ( === Undeploy the primary-only Example . Start the {productName} servers as described in the above section. -. Open a command prompt and navigate to the `primary-only/` directory located in the root directory of this quickstart. +. Open a terminal and navigate to the `primary-only/` directory located in the root directory of this quickstart. . Use the following command to undeploy the JAR archive from Server 1. + +[source,options="nowrap"] ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- . Use the following command to undeploy the JAR archive from Server 2. + +[source,options="nowrap"] ---- -mvn wildfly:undeploy -Dwildfly.port=10090 +$ mvn wildfly:undeploy -Dwildfly.port=10090 ---- == Run the with-backups Example @@ -184,17 +200,19 @@ mvn wildfly:undeploy -Dwildfly.port=10090 This example demonstrates a singleton service that is installed with a backup service. The backup service is running on all nodes that are _not_ elected to be running the singleton service. . Start the {productName} servers as described in the above section. -. Open a command prompt and navigate to the `with-backups/` directory located in the root directory of this quickstart. +. Open a terminal and navigate to the `with-backups/` directory located in the root directory of this quickstart. . Use the following command to clean up any previously built artifacts, and build and deploy the JAR archive. + +[source,options="nowrap"] ---- -mvn clean install wildfly:deploy +$ mvn clean install wildfly:deploy ---- === Deploy the with-backups Archive to Server 2 Use the following command to deploy the same archive to the second server. Because the default socket binding port for deployment is `9990` and the second server ports are offset by `100`, you must pass the sum, `10090`, for the socket binding port as the argument to the `deploy` Maven goal. +[source,options="nowrap"] ---- mvn wildfly:deploy -Dwildfly.port=10090 ---- @@ -203,12 +221,14 @@ mvn wildfly:deploy -Dwildfly.port=10090 Verify that the `target/ha-singleton-service-with-backups.jar` archive is deployed to `node1`, which is the first server started without port offset, by checking the server log to see that the primary service is running. +[source,options="nowrap"] ---- INFO [org.jboss.as.quickstarts.ha.singleton.service.backups.SingletonService] (pool-18-thread-1) Primary singleton service is running on node 'node1'. ---- All other nodes log that the backup singleton service is running. +[source,options="nowrap"] ---- INFO [org.jboss.as.quickstarts.ha.singleton.service.backups.SingletonService] (pool-20-thread-1) Backup singleton service is running on node 'node2'. ---- @@ -216,17 +236,19 @@ INFO [org.jboss.as.quickstarts.ha.singleton.service.backups.SingletonService] ( === Undeploy the with-backups Example . Start the {productName} servers as described in the above section. -. Open a command prompt and navigate to the `with-backups/` directory located in the root directory of this quickstart. +. Open a terminal and navigate to the `with-backups/` directory located in the root directory of this quickstart. . Use the following command to undeploy the JAR archive from Server 1. + +[source,options="nowrap"] ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- . Use the following command to undeploy the JAR archive from Server 2. + +[source,options="nowrap"] ---- -mvn wildfly:undeploy -Dwildfly.port=10090 +$ mvn wildfly:undeploy -Dwildfly.port=10090 ---- == Configuring Election Policies @@ -243,20 +265,23 @@ This example configures the default election policy to be based on logical names . Start the two servers with the HA profile as described above. . Review the contents of the `name-preference-election-policy-add.cli` file located in the root of this quickstart directory. This script configures the default election policy to choose nodes in a preferred order of `node3`, `node2`, and `node1` using this command. + +[source,options="nowrap"] ---- /subsystem=singleton/singleton-policy=default/election-policy=simple:write-attribute(name=name-preferences,value=[node3,node2,node1]) ---- -. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command to execute the script for Server 1. Be sure to replace {jbossHomeName}_1 with the path to the target Server 1. +. Open a new terminal, navigate to the root directory of this quickstart, and run the following command to execute the script for Server 1. Be sure to replace {jbossHomeName}_1 with the path to the target Server 1. + +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}_1/bin/jboss-cli.sh --connect --file=name-preference-election-policy-add.cli -For Windows: {jbossHomeName}_1\bin\jboss-cli.bat --connect --file=name-preference-election-policy-add.cli +$ __{jbossHomeName}_1__/bin/jboss-cli.sh --connect --file=name-preference-election-policy-add.cli ---- ++ +NOTE: For Windows, use the ``{jbossHomeName}_1\bin\jboss-cli.bat` script. . Stop the server and review the changes made to the `standalone-ha.xml` server configuration file by the management CLI commands. The `singleton` subsystem now contains a `name-preferences` element under the `simple-election-policy` that specifies the preferences `node3 node2 node1`. + -[source, xml] +[source,xml,options="nowrap"] ---- @@ -271,14 +296,16 @@ For Windows: {jbossHomeName}_1\bin\jboss-cli.bat --connect --file=name-preferenc . Repeat these steps for the second server. Note that if the second server is using a port offset, you must specify the controller address on the command line by adding `--controller=localhost:10090`. + -[subs="+quotes,attributes+"] +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}_2/bin/jboss-cli.sh --connect --controller=localhost:10090 --file=name-preference-election-policy-add.cli -For Windows: {jbossHomeName}_2\bin\jboss-cli.bat --connect --controller=localhost:10090 --file=name-preference-election-policy-add.cli +$ __{jbossHomeName}_2__/bin/jboss-cli.sh --connect --controller=localhost:10090 --file=name-preference-election-policy-add.cli ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}_2__\bin\jboss-cli.bat` script. . Be sure both servers are started, deploy one of the examples to both servers, and verify that the election policy is now in effect. The server running the election policy should now log the following message. + +[source,options="nowrap"] ---- INFO [org.wildfly.clustering.server] (DistributedSingletonService - 1) WFLYCLSV0003: node2 elected as the singleton provider of the org.jboss.as.quickstarts.ha.singleton.service.primary-only service ---- @@ -291,23 +318,24 @@ This example configures an election policy that elects a random cluster member w . Start the two servers with the HA profile as described above. . Review the contents of the `random-election-policy-add.cli` file located in the root of this quickstart directory. This script removes the default simple election policy and configures the default election policy to elect a random cluster member using these commands. + +[source,options="nowrap"] ---- /subsystem=singleton/singleton-policy=default/election-policy=simple:remove(){allow-resource-service-restart=true} /subsystem=singleton/singleton-policy=default/election-policy=random:add() ---- -. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command to execute the script for Server 1. Be sure to replace {jbossHomeName}_1 with the path to the target Server 1. +. Open a new terminal, navigate to the root directory of this quickstart, and run the following command to execute the script for Server 1. Be sure to replace {jbossHomeName}_1 with the path to the target Server 1. + -[subs="+quotes,attributes+"] +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}_1/bin/jboss-cli.sh --connect --file=random-election-policy-add.cli -For Windows: {jbossHomeName}_1\bin\jboss-cli.bat --connect --file=random-election-policy-add.cli +$ __{jbossHomeName}_1__/bin/jboss-cli.sh --connect --file=random-election-policy-add.cli ---- - ++ +NOTE: For Windows, use the ``{jbossHomeName}_1\bin\jboss-cli.bat` script. . Stop the server and review the changes made to the `standalone-ha.xml` server configuration file by the management CLI commands. The `singleton` subsystem now contains a `random-election-policy` element under the `singleton-policy` that specifies the preferences `node3 node2 node1`. + -[source, xml] +[source,xml,options="nowrap"] ---- @@ -320,11 +348,12 @@ For Windows: {jbossHomeName}_1\bin\jboss-cli.bat --connect --file=random-electio . Repeat these steps for the second server. Note that if the second server is using a port offset, you must specify the controller address on the command line by adding `--controller=localhost:10090`. + -[subs="+quotes,attributes+"] +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}_2/bin/jboss-cli.sh --connect --controller=localhost:10090 --file=random-election-policy-add.cli -For Windows: {jbossHomeName}_2\bin\jboss-cli.bat --connect --controller=localhost:10090 --file=random-election-policy-add.cli +$ __{jbossHomeName}_2__/bin/jboss-cli.sh --connect --controller=localhost:10090 --file=random-election-policy-add.cli ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}_2__\bin\jboss-cli.bat` script. . Be sure both servers are started, deploy one of the examples to both servers, and verify that the election policy is now in effect. @@ -336,21 +365,23 @@ A quorum specifies the minimum number of cluster members that must be present fo . Start the two servers with the HA profile as described above. . Review the contents of the `quorum-add.cli` file located in the root of this quickstart directory. This script specifies the minimum number of cluster members required for the singleton policy using this command. + +[source,subs="+quotes,attributes+",options="nowrap"] ---- /subsystem=singleton/singleton-policy=default:write-attribute(name=quorum,value=2) ---- -. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command to execute the script for Server 1. Be sure to replace {jbossHomeName}_1 with the path to the target Server 1. +. Open a new terminal, navigate to the root directory of this quickstart, and run the following command to execute the script for Server 1. Be sure to replace {jbossHomeName}_1 with the path to the target Server 1. + [subs="+quotes,attributes+"] ---- -For Linux: {jbossHomeName}_1/bin/jboss-cli.sh --connect --file=quorum-add.cli -For Windows: {jbossHomeName}_1\bin\jboss-cli.bat --connect --file=quorum-add.cli +$ __{jbossHomeName}_1__/bin/jboss-cli.sh --connect --file=quorum-add.cli ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}_1__\bin\jboss-cli.bat` script. . Review the changes made to the `standalone-ha.xml` server configuration file by the management CLI commands. The `singleton` subsystem now contains a `quorum` attribute for the `singleton-policy` element that specifies the minimum number. + -[source, xml] +[source,xml,options="nowrap"] ---- @@ -363,20 +394,23 @@ For Windows: {jbossHomeName}_1\bin\jboss-cli.bat --connect --file=quorum-add.cli . Repeat these steps for the second server. Note that if the second server is using a port offset, you must specify the controller address on the command line by adding `--controller=localhost:10090`. + -[subs="+quotes,attributes+"] +[source,subs="+quotes,attributes+",options="nowrap"] ---- - For Linux: {jbossHomeName}_2/bin/jboss-cli.sh --connect --controller=localhost:10090 --file=quorum-add.cli - For Windows: {jbossHomeName}_2\bin\jboss-cli.bat --connect --controller=localhost:10090 --file=quorum-add.cli +$ __{jbossHomeName}_2__/bin/jboss-cli.sh --connect --controller=localhost:10090 --file=quorum-add.cli ---- ++ +NOTE: For Windows, use the __{jbossHomeName}_2__\bin\jboss-cli.bat` script. . Be sure both servers are started, deploy one of the examples to both servers. While both servers are running, observe the server logs. The server running the election policy should now log the following message. + +[source,options="nowrap"] ---- INFO [org.wildfly.clustering.server] (DistributedSingletonService - 1) WFLYCLSV0007: Just reached required quorum of 2 for org.jboss.as.quickstarts.ha.singleton.service.primary-only service. If this cluster loses another member, no node will be chosen to provide this service. ---- -. Shut down one of the servers by using the `Ctrl` + `C` key combination in the command prompt to verify that no singleton service will be running after the quorum is not reached. +. Shut down one of the servers by using the `Ctrl` + `C` key combination in the terminal to verify that no singleton service will be running after the quorum is not reached. + +[source,options="nowrap"] ---- WARN [org.wildfly.clustering.server] (DistributedSingletonService - 1) WFLYCLSV0006: Failed to reach quorum of 2 for org.jboss.as.quickstarts.ha.singleton.service.primary-only service. No singleton master will be elected. INFO [org.wildfly.clustering.server] (thread-20) WFLYCLSV0002: This node will no longer operate as the singleton provider of the org.jboss.as.quickstarts.ha.singleton.service.primary-only service @@ -396,6 +430,7 @@ If the singleton is running on multiple nodes, check for the following issues. * Another common cause is because the server instances did not discover each other and each server is operating as a singleton cluster. Ensure that `multicast` is enabled or change the `jgroups` subsystem configuration to use a different discovery mechanism. Confirm the following message in the server log to ensure that the discovery was successful. + +[source,options="nowrap"] ---- INFO [org.infinispan.remoting.transport.jgroups.JGroupsTransport] (MSC service thread 1-3) ISPN000094: Received new cluster view for channel server: [node1|1] (2) [node1, node2] ---- @@ -405,12 +440,13 @@ INFO [org.infinispan.remoting.transport.jgroups.JGroupsTransport] (MSC service If you have not yet done so, you can undeploy all of the deployed artifacts by following these steps. . Start the two servers with the HA profile as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Use the following commands to undeploy all of the artifacts. + +[source,options="nowrap"] ---- -mvn wildfly:undeploy -mvn wildfly:undeploy -Dwildfly.port=10090 +$ mvn wildfly:undeploy +$ mvn wildfly:undeploy -Dwildfly.port=10090 ---- == Restoring the Default Singleton Subsystem Configuration @@ -418,28 +454,22 @@ mvn wildfly:undeploy -Dwildfly.port=10090 Some of these examples require that you modify the election policies for the `singleton` subsystem by running management CLI scripts. After you have completed testing each configuration, it is important to restore the `singleton` subsystem to its default configuration before you run any other examples. . Start both servers with the HA profile as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Restore your default server configurations by running these commands. -** For Linux: + -[subs="+quotes,attributes+"] +[source,subs="+quotes,attributes+",options="nowrap"] ---- -{jbossHomeName}_1/bin/jboss-cli.sh --connect --file=restore-singleton-subsystem.cli -{jbossHomeName}_2/bin/jboss-cli.sh --connect --controller=localhost:10090 --file=restore-singleton-subsystem.cli +$ __{jbossHomeName}_1__/bin/jboss-cli.sh --connect --file=restore-singleton-subsystem.cli +$ __{jbossHomeName}_2__/bin/jboss-cli.sh --connect --controller=localhost:10090 --file=restore-singleton-subsystem.cli ---- - -** For Windows: + -[subs="+quotes,attributes+"] ----- -{jbossHomeName}_1\bin\jboss-cli.bat --connect --file=restore-singleton-subsystem.cli -{jbossHomeName}_2\bin\jboss-cli.bat --connect --controller=localhost:10090 --file=restore-singleton-subsystem.cli ----- +NOTE: For Windows, use the `__{jbossHomeName}_1__\bin\jboss-cli.bat` and `__{jbossHomeName}_2__\bin\jboss-cli.bat` scripts. == Debug the Application If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. +[source,options="nowrap"] +---- +$ mvn dependency:sources ---- - mvn dependency:sources ----- \ No newline at end of file diff --git a/helloworld-html5/README.adoc b/helloworld-html5/README.adoc index 54f88c4412..b0017c8d62 100644 --- a/helloworld-html5/README.adoc +++ b/helloworld-html5/README.adoc @@ -16,13 +16,13 @@ The `helloworld-html5` quickstart demonstrates the use of *CDI 1.2* and *JAX-RS == What is it? -The `helloworld-html5` quickstart demonstrates the use of _CDI 1.2_ and _JAX-RS 2.0_ in {productNameFull} {productVersion} or later using the HTML5 + REST architecture. +The `helloworld-html5` quickstart demonstrates the use of CDI 1.2 and JAX-RS 2.0 in {productNameFull} {productVersion} or later using the HTML5 + REST architecture. The application is basically a smart, HTML5+CSS3+JavaScript front-end using RESTful services on the backend. -* HelloWorld.java - establishes the RESTful endpoints using JAX-RS -* Web.xml - maps RESTful endpoints to `/hello` -* index.html - is a jQuery augmented plain old HTML5 web page +* `HelloWorld.java`: Establishes the RESTful endpoints using JAX-RS. +* `web.xml`: Maps RESTful endpoints to `/hello`. +* `index.html`: Is a jQuery augmented plain old HTML5 web page. The example can be deployed using Maven from the command line or from Eclipse using JBoss Tools. @@ -30,7 +30,7 @@ The example can be deployed using Maven from the command line or from Eclipse us The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. An HTML5 compatible browser such as Chrome, Safari 5+, Firefox 5+, or IE 9+ is required. @@ -40,23 +40,23 @@ With the prerequisites out of the way, you are ready to build and deploy. . Open a command line and navigate to the root of the {productName} directory. . The following shows the command line to start the server with the default profile: - -[subs=normal] ++ +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +$ __{jbossHomeName}__/bin/standalone.sh ---- ++ +For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. == Build and Deploy the Quickstart -_NOTE: The following build command assumes you have configured your Maven user settings. If you have not, you must include Maven setting arguments on the command line. See link:../README.md#build-and-deploy-the-quickstarts[Build and Deploy the Quickstarts] for complete instructions and additional options._ - . Make sure you have started the {productName} server as described above. . Open a command line and navigate to the root directory of this quickstart. . Type this command to build and deploy both the client and service applications: - ++ +[source,options="nowrap"] ---- -mvn clean package wildfly:deploy +$ mvn clean package wildfly:deploy ---- . This will deploy `target/{artifactId}.war` to the running instance of the server. @@ -65,24 +65,25 @@ mvn clean package wildfly:deploy The application will be running at the following URL http://localhost:8080/{artifactId}/. -You can also test the REST endpoint by sending an HTTP _POST_ request to the URLs below. Feel free to replace `YOUR_NAME` with a name of your choosing. +You can also test the REST endpoint by sending an HTTP `POST` request to the URLs below. Replace `__YOUR_NAME__` with a name of your choosing. -* The _XML_ content can be tested by sending an HTTP _POST_ to the following URL: http://localhost:8080/{artifactId}/hello/xml/YOUR_NAME +* The XML content can be tested by sending an HTTP `POST` to the following URL: http://localhost:8080/{artifactId}/hello/xml/__YOUR_NAME__ -To issue the _POST_ command using cURL, type the following command in terminal: +To issue the `POST` command using cURL, type the following command in terminal: -* The _JSON_ content can be tested by sending an HTTP _POST_ to the following URL: http://localhost:8080/{artifactId}/hello/json/YOUR_NAME +* The JSON content can be tested by sending an HTTP `POST` to the following URL: http://localhost:8080/{artifactId}/hello/json/__YOUR_NAME__ -To issue the _POST_ command using cURL, type the following command in terminal: +To issue the `POST` command using cURL, type the following command in terminal: == Undeploy the Archive . Make sure you have started the {productName} server as described above. . Open a command line and navigate to the root directory of this quickstart. . When you are finished testing, type this command to undeploy the archive: - ++ +[source,options="nowrap"] ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- == Run the Arquillian Functional Tests @@ -94,23 +95,26 @@ To run these tests, you must build the main project as described above. . Open a command line and navigate to the root directory of this quickstart. . Build the quickstart WAR using the following command: - ++ +[source,options="nowrap"] ---- -mvn clean package +$ mvn clean package ---- . Navigate to the functional-tests/ directory in this quickstart. . If you have a running instance of the {productName} server, as described above, run the remote tests by typing the following command: - ++ +[source,options="nowrap"] ---- -mvn clean verify -Parq-remote +$ mvn clean verify -Parq-remote ---- . If you prefer to run the functional tests using managed instance of the {productName} server, meaning the tests will start the server for you, type fhe following command: - ++ +[source,options="nowrap"] ---- -mvn clean verify -Parq-managed +$ mvn clean verify -Parq-managed ---- == Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse @@ -121,7 +125,8 @@ You can also start the server and deploy the quickstarts or run the Arquillian t If you want to debug the source code or look at the Javadocs of any library in the project, run either of the following commands to pull them into your local repository. The IDE should then detect them. +[source,options="nowrap"] +---- +$ mvn dependency:sources +$ mvn dependency:resolve -Dclassifier=javadoc ---- - mvn dependency:sources - mvn dependency:resolve -Dclassifier=javadoc ----- \ No newline at end of file diff --git a/helloworld-jms/README.adoc b/helloworld-jms/README.adoc index 3c73d5f837..140f331b82 100644 --- a/helloworld-jms/README.adoc +++ b/helloworld-jms/README.adoc @@ -28,33 +28,33 @@ It contains the following: The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Use of {jbossHomeName} -In the following instructions, replace `{jbossHomeName}` with the actual path to your {productName} installation. The installation path is described in detail here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_{jbossHomeName}.md#use-of-eap_home-and-jboss_home-variables[Use of {jbossHomeName} and JBOSS_HOME Variables]. +In the following instructions, replace `__{jbossHomeName}__` with the actual path to your {productName} installation. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of {jbossHomeName} and JBOSS_HOME Variables]. == Add an Application User This quickstart uses secured management interfaces and requires that you create the following application user to access the running application. -[cols="<,<,<,<"] +[cols="20%,20%,20%,40%",options="headers"] |=== -|*UserName* |*Realm* |*Password* |*Roles* +|UserName |Realm |Password |Roles -|quickstartUser |ApplicationRealm |quickstartPwd1! |guest +|quickstartUser |ApplicationRealm |quickstartPwd1! |guest |=== -To add the application user, open a command prompt and type the following command: +To add the application user, open a terminal and type the following command: -[subs="+quotes,attributes+"] +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/add-user.sh -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest' -For Windows: {jbossHomeName}\bin\add-user.bat -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest' +$ __{jbossHomeName}__/bin/add-user.sh -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest' ---- +NOTE: For Window, use the `__{jbossHomeName}__\bin\add-user.bat` script. -If you prefer, you can use the add-user utility interactively. -For an example of how to use the add-user utility, see the instructions located here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CREATE_USERS.md#add-an-application-user[Add an Application User]. +If you prefer, you can use the `add-user` utility interactively. +For an example of how to use the add-user utility, see the instructions located here: link:{addApplicationUserDocUrl}[Add an Application User]. == Configure the Server @@ -66,20 +66,21 @@ You configure the JMS `test` queue by running JBoss CLI commands. For your conve ** After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration. . Start the {productName} server by typing the following: + -[subs="+quotes,attributes+"] +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -c standalone-full.xml -For Windows: {jbossHomeName}\bin\standalone.bat -c standalone-full.xml +$ __{jbossHomeName}__/bin/standalone.sh -c standalone-full.xml ---- +For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. . Review the `configure-jms.cli` file in the root of this quickstart directory. This script adds the `test` queue to the `messaging` subsystem in the server configuration file. -. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing {jbossHomeName} with the path to your server: +. 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: + -[subs="+quotes,attributes+"] +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/jboss-cli.sh --connect --file=configure-jms.cli -For Windows: {jbossHomeName}\bin\jboss-cli.bat --connect --file=configure-jms.cli +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=configure-jms.cli ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. . You should see the following result when you run the script: + @@ -91,25 +92,26 @@ The batch executed successfully == Review the Modified Server Configuration -After stopping the server, open the `{jbossHomeName}/standalone/configuration/standalone-full.xml` file and review the changes. +After stopping the server, open the `__{jbossHomeName}__/standalone/configuration/standalone-full.xml` file and review the changes. The following `testQueue` jms-queue was configured in the default server configuration of the `messaging-activemq` subsystem. -[source, xml] +[source,xml,options="nowrap"] ---- - + ---- == Start the Server with the Full Profile -. Open a command prompt and navigate to the root of the {productName} directory. +. Open a terminal and navigate to the root of the {productName} directory. . The following shows the command line to start the server with the full profile: + -[subs=normal] +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -c standalone-full.xml -For Windows: {jbossHomeName}\bin\standalone.bat -c standalone-full.xml +$ __{jbossHomeName}__/bin/standalone.sh -c standalone-full.xml ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. == Build and Execute the Quickstart @@ -117,7 +119,7 @@ To run the quickstart from the command line: . Make sure you have started the {productName} server. See the instructions in the previous section. -. Open a command prompt and navigate to the root of the helloworld-jms quickstart directory: +. Open a terminal and navigate to the root of the helloworld-jms quickstart directory: + ---- cd PATH_TO_QUICKSTARTS/helloworld-jms @@ -126,15 +128,18 @@ cd PATH_TO_QUICKSTARTS/helloworld-jms . Type the following command to compile and execute the quickstart: + ---- -mvn clean compile exec:java +$ mvn clean compile exec:java ---- -NOTE: If you execute this command multiple times, you may see the following warning and exception, followed by a stacktrace. This is caused by a bug in Artemis that has been fixed, but not yet released. For details, see https://issues.apache.org/jira/browse/ARTEMIS-158. You can ignore this warning._ +[NOTE] +==== +If you execute this command multiple times, you may see the following warning and exception, followed by a stacktrace. This is caused by a bug in Artemis that has been fixed, but not yet released. For details, see https://issues.apache.org/jira/browse/ARTEMIS-158. You can ignore this warning._ ---- WARN: AMQ212007: connector.create or connectorFactory.createConnector should never throw an exception, implementation is badly behaved, but we will deal with it anyway. java.lang.IllegalArgumentException: port out of range:-1 ---- +==== == Investigate the Console Output @@ -162,33 +167,32 @@ INFO: Received message with content Hello, World! The example provides for a certain amount of customization for the `mvn:exec` plug-in using the system properties. -* `username` - -This username is used for both the JMS connection and the JNDI look-up. Instructions to set up the quickstart application user can be found here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CREATE_USERS.md#add-an-application-user[Add an Application User]. - -* `password` - -This password is used for both the JMS connection and the JNDI look-up. Instructions to set up the quickstart application user can be found here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CREATE_USERS.md#add-an-application-user[Add an Application User] - -* `connection.factory` - -The name of the JMS ConnectionFactory you want to use. - -* `destination` +[cols="30%,70%",options="headers"] +|=== +| Property +| Description -The name of the JMS Destination you want to use. +| username +| This `username` is used for both the JMS connection and the JNDI look up. Instructions to set up the quickstart application user can be found here: link:{addApplicationUserDocUrl}[Add an Application User]. -* `message.count` +| password +| This `password` is used for both the JMS connection and the JNDI look up. Instructions to set up the quickstart application user can be found here: link:{addApplicationUserDocUrl}[Add an Application User] -The number of JMS messages you want to produce and consume. +| connection.factory +| The name of the JMS `ConnectionFactory` you want to use. -* `message.content` +| destination +| The name of the JMS `Destination` you want to use. -The content of the JMS TextMessage. +| message.count +| The number of JMS messages you want to produce and consume. -* `java.naming.provider.url` +| message.content +| The content of the JMS `TextMessage`. -This property allows configuration of the JNDI directory used to lookup the JMS destination. This is useful when the client resides on another host. +| java.naming.provider.url +| This property allows configuration of the JNDI directory used to look up the JMS destination. This is useful when the client resides on another host. +|=== == Remove the JMS Configuration @@ -198,23 +202,25 @@ You can remove the JMS configuration by running the `remove-jms.cli` script prov . Start the {productName} server by typing the following: + -[subs="+quotes,attributes+"] +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -c standalone-full.xml -For Windows: {jbossHomeName}\bin\standalone.bat -c standalone-full.xml +$ __{jbossHomeName}__/bin/standalone.sh -c standalone-full.xml ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. -. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing {jbossHomeName} with the path to your server: +. 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: + -[subs="+quotes,attributes+"] +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/jboss-cli.sh --connect --file=remove-jms.cli -For Windows: {jbossHomeName}\bin\jboss-cli.bat --connect --file=remove-jms.cli +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=remove-jms.cli ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. . This script removes the `test` queue from the `messaging` subsystem in the server configuration. You should see the following result when you run the script: + -[subs="+quotes,attributes+"] +[source,options="nowrap"] ---- The batch executed successfully ---- @@ -222,7 +228,7 @@ The batch executed successfully === Remove the JMS Configuration Manually . If it is running, stop the {productName} server. -. Replace the `{jbossHomeName}/standalone/configuration/standalone-full.xml` file with the back-up copy of the file. +. Replace the `__{jbossHomeName}__/standalone/configuration/standalone-full.xml` file with the back-up copy of the file. == Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse @@ -235,8 +241,8 @@ This quickstart consists of multiple projects, so it deploys and runs differentl ** Define a server runtime environment that uses the `standalone-full.xml` configuration file. ** Start the server defined in the previous step. . Outside of JBoss Developer Studio, configure the JMS `test` queue by running the JBoss CLI commands as described above under <>. -. In JBoss Developer Studio, right-click on the `{artifactId}` project and choose `Run As` –> `Java Application`. In the `Select Java Application` window, choose `HellowWorldJMSClient - org.jboss.as.quickstarts.jms` and click `OK`. The client output displays in the `Console` window. -The output messages appear in the `Console` window. +. In JBoss Developer Studio, right-click on the *{artifactId}* project and choose *Run As* -> *Java Application*. In the *Select Java Application* window, choose *HellowWorldJMSClient - org.jboss.as.quickstarts.jms* and click *OK*. The client output displays in the *Console* window. +The output messages appear in the *Console* window. . Be sure to <> when you have completed testing this quickstart. == Debug the Application @@ -244,5 +250,5 @@ The output messages appear in the `Console` window. If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. ---- -mvn dependency:sources ----- \ No newline at end of file +$ mvn dependency:sources +---- diff --git a/helloworld-mbean/README.adoc b/helloworld-mbean/README.adoc index 90623ab804..d59684761a 100644 --- a/helloworld-mbean/README.adoc +++ b/helloworld-mbean/README.adoc @@ -10,9 +10,11 @@ include::../attributes.adoc[] :level: Intermediate :technologies: CDI, JMX, MBean :source: {githubRepoUrl} +:imagesdir: images/ + [abstract] -The `helloworld-mbean` quickstart demonstrates the use of *CDI* and *MBean* in {productName} and includes JConsole instructions and Arquillian tests. +The `helloworld-mbean` quickstart demonstrates the use of CDI and MBean in {productName} and includes JConsole instructions and Arquillian tests. == What is it? @@ -20,43 +22,45 @@ The `helloworld-mbean` quickstart demonstrates the use of _CDI_ and _MBean_ in { The example is composed of the following MBeans: -* `AnnotatedComponentHelloWorld`: This MBean is a managed bean with `@MXBean` annotation. +AnnotatedComponentHelloWorld:: This MBean is a managed bean with `@MXBean` annotation. -* `MXComponentHelloWorld`: This MBean is a managed bean with `MXBean` interface. +MXComponentHelloWorld:: This MBean is a managed bean with `MXBean` interface. -* `MXPojoHelloWorld`: This MBean is a pojo using MXBean interface and declared in the `jboss-service.xml` file. +MXPojoHelloWorld:: This MBean is a POJO using `MXBean` interface and declared in the `jboss-service.xml` file. -* `SarMXPojoHelloWorld`: This MBean is a pojo using MXBean interface and declared in jboss-service.xml in SAR packaging. +SarMXPojoHelloWorld:: This MBean is a pojo using `MXBean` interface and declared in the `jboss-service.xml` file using SAR packaging. == System Requirements The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Use of {jbossHomeName} -In the following instructions, replace `{jbossHomeName}` with the actual path to your {productName} installation. The installation path is described in detail here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_{jbossHomeName}.md#use-of-eap_home-and-jboss_home-variables[Use of {jbossHomeName} and JBOSS_HOME Variables]. +In the following instructions, replace `__{jbossHomeName}__` with the actual path to your {productName} installation. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of {jbossHomeName} and JBOSS_HOME Variables]. == Start the {productName} Server -. Open a command prompt and navigate to the root of the {productName} directory. -. The following shows the command line to start the server: - -[subs=normal] +. Open a terminal and navigate to the root of the {productName} directory. +. Type this command to start the server: ++ +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +$ __{jbossHomeName}__/bin/standalone.sh ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. == Build and Deploy the Quickstart . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type this command to build and deploy the archive: - ++ +[source,options="nowrap"] ---- -mvn clean install wildfly:deploy +$ mvn clean install wildfly:deploy ---- . This will deploy `{artifactId}-webapp/target/{artifactId}-webapp.war` and `{artifactId}-service/target/{artifactId}-service.sar` to the running instance of the server. @@ -69,40 +73,43 @@ The following sections describe how to use _JConsole_ to inspect and test the MB == Start JConsole -To connect to the {productName} server using _JConsole_, open a command prompt and type the following command : - +. To connect to the {productName} server using _JConsole_, open a terminal and type the following command, replacing __JDK_HOME__ with the path to your JDK installation : ++ +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: JDK_HOME/bin/jconsole -For Windows: JDK_HOME\bin\jconsole.exe +__JDK_HOME__/bin/jconsole ---- +NOTE: For Windows, type `JDK_HOME\bin\jconsole.exe`. -Select the local `org.jboss.modules.Main` process and click `Connect`. +. Select the local *org.jboss.modules.Main* process and click *Connect*. ++ +image:jconsole_connection.png[MBeans in JConsole Connection] -image:{artifactId}-webapp/src/main/webapp/jconsole_connection.png[MBeans in JConsole Connection] +. A dialog displays with the warning: `Secure connection failed. Retry insecurely?` -A dialog displays with the warning `Secure connection failed. Retry insecurely?`. Click `Insecure` to continue. +. Click *Insecure* to continue. == Test the MBeans in JConsole You can use _JConsole_ to inspect and use the MBeans : -image:{artifactId}-webapp/src/main/webapp/jconsole.png[MBeans in JConsole] +image:jconsole.png[MBeans in JConsole] . Click on the MBeans tab. -. Expand `quickstarts` in the left column of the console. -. Under `quickstarts`, you see the 4 MBeans: `AnnotatedComponentHelloWorld`, `MXComponentHelloWorld`, `MXPojoHelloWorld`, and `SarMXPojoHelloWorld` -. Expand each MBean and choose: `Operations` –> `sayHello`. -. Type your name in the (p0 String ) input text box and click the `sayHello` button. -* For the `AnnotatedComponentHelloWorld` and `MXComponentHelloWorld` examples, you will see a popup Window displaying `Hello <your name>!`. -* For the `MXPojoHelloWorld` and `SarMXPojoHelloWorld` examples, you will see a popup Window displaying `Welcome <your name>!`. +. Expand *quickstarts* in the left column of the console. +. Under *quickstarts*, you see the 4 MBeans: *AnnotatedComponentHelloWorld*, *MXComponentHelloWorld*, *MXPojoHelloWorld*, and *SarMXPojoHelloWorld* +. Expand each MBean and choose: *Operations* -> *sayHello*. +. Type your name in the *(p0 String )* input text box and click the *sayHello* button. +* For the *AnnotatedComponentHelloWorld* and *MXComponentHelloWorld* examples, you will see a popup Window displaying *Hello !*. +* For the *MXPojoHelloWorld* and *SarMXPojoHelloWorld* examples, you will see a popup Window displaying *Welcome !*. == Undeploy the Archive . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . When you are finished testing, type this command to undeploy the archive: - ++ ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- == Run the Arquillian Tests @@ -110,14 +117,14 @@ mvn wildfly:undeploy This quickstart provides Arquillian tests. By default, these tests are configured to be skipped as Arquillian tests require the use of a container. . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type the following command to run the test goal with the following profile activated: - ++ ---- -mvn clean verify -Parq-remote +$ mvn clean verify -Parq-remote ---- -You can also let Arquillian manage the {productName} server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests[Run the Arquillian Tests]. +You can also let Arquillian manage the {productName} server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see link:{arquillianTestsDocUrl}[Run the Arquillian Tests]. == Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse @@ -126,20 +133,20 @@ You can also start the server and deploy the quickstarts or run the Arquillian t This quickstart consists of multiple projects and requires installation of the `JBoss Tools Maven Packaging Configurator`, so it deploys and runs differently in JBoss Developer Studio than the other quickstarts. . Install the JBoss Tools Maven Packaging Configurator -** If the `Red Hat Central` page is not showing, open it by choosing `Help` –> `Red Hat Central`. -** Click the `Software/Update` tab at the bottom of the `Red Hat Central`. -** Scroll down to the `Maven` section, select the `JBoss Tools Maven Packaging Configurator` and click `Install/Update`. -. Right click on the parent `{artifactId}` parent project and choose `Maven` –> `Update Project...`. Select all projects and click `OK`. -. Right-click on the `{artifactId}-service` project and choose `Run As` –> `Run on Server`. -. Right-click on the `{artifactId}-webapp` project and choose `Run As` –> `Run on Server`. +** If the *Red Hat Central* page is not showing, open it by choosing *Help* -> *Red Hat Central*. +** Click the *Software/Update* tab at the bottom of the *Red Hat Central*. +** Scroll down to the *Maven* section, select the *JBoss Tools Maven Packaging Configurator* and click *Install/Update*. +. Right click on the parent *{artifactId}* parent project and choose *Maven* -> *Update Project...*. Select all projects and click *OK*. +. Right-click on the *{artifactId}-service* project and choose *Run As* -> *Run on Server*. +. Right-click on the *{artifactId}-webapp* project and choose *Run As* -> *Run on Server*. . <> and <> as described above. -. To undeploy the web application, right-click on the `{artifactId}-wepapp` project and choose `Run As` –> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. -. To undeploy the web service, right-click on the `{artifactId}-service` project and choose `Run As` –> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. +. To undeploy the web application, right-click on the *{artifactId}-wepapp* project and choose *Run As* -> *Maven build*. Enter `wildfly:undeploy` for the *Goals* and click *Run*. +. To undeploy the web service, right-click on the *{artifactId}-service* project and choose *Run As* -> *Maven build*. Enter `wildfly:undeploy` for the *Goals* and click *Run*. == Debug the Application If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. ---- -mvn dependency:sources ----- \ No newline at end of file +$ mvn dependency:sources +---- diff --git a/helloworld-mbean/helloworld-mbean-webapp/src/main/webapp/jconsole.png b/helloworld-mbean/images/jconsole.png similarity index 100% rename from helloworld-mbean/helloworld-mbean-webapp/src/main/webapp/jconsole.png rename to helloworld-mbean/images/jconsole.png diff --git a/helloworld-mbean/helloworld-mbean-webapp/src/main/webapp/jconsole_connection.png b/helloworld-mbean/images/jconsole_connection.png similarity index 100% rename from helloworld-mbean/helloworld-mbean-webapp/src/main/webapp/jconsole_connection.png rename to helloworld-mbean/images/jconsole_connection.png diff --git a/helloworld-mdb-propertysubstitution/README.adoc b/helloworld-mdb-propertysubstitution/README.adoc index 1466b6b018..7e6763c23c 100644 --- a/helloworld-mdb-propertysubstitution/README.adoc +++ b/helloworld-mdb-propertysubstitution/README.adoc @@ -18,7 +18,7 @@ The `helloworld-mdb-propertysubstitution` quickstart demonstrates the use of *JM The `helloworld-mdb-propertysubstitution` quickstart demonstrates the use of _JMS_ and _EJB Message-Driven Bean_ in {productNameFull}. -It is based on the link:../helloworld-mdb/README.md[helloworld-mdb] quickstart, but has been enhanced to enable property substitution using the `@Resource` and `@ActivationConfigProperty` annotations. +It is based on the link:../helloworld-mdb/README.adoc[helloworld-mdb] quickstart, but has been enhanced to enable property substitution using the `@Resource` and `@ActivationConfigProperty` annotations. This project creates two JMS resources: @@ -29,11 +29,11 @@ This project creates two JMS resources: The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Use of {jbossHomeName} -In the following instructions, replace `{jbossHomeName}` with the actual path to your {productName} installation. The installation path is described in detail here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_{jbossHomeName}.md#use-of-eap_home-and-jboss_home-variables[Use of {jbossHomeName} and JBOSS_HOME Variables]. +In the following instructions, replace `__{jbossHomeName}__` with the actual path to your {productName} installation. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of {jbossHomeName} and JBOSS_HOME Variables]. == Configure the Server @@ -44,22 +44,23 @@ You enable MDB property substitution by running JBoss CLI commands. For your con ** Back up the file: `{jbossHomeName}/standalone/configuration/standalone-full.xml` ** After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration. . Start the {productName} server by typing the following: - + -[subs="+quotes,attributes+"] +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -c standalone-full.xml -For Windows: {jbossHomeName}\bin\standalone.bat -c standalone-full.xml +$ __{jbossHomeName}__/bin/standalone.sh -c standalone-full.xml ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. . Review the `enable-mdb-property-substitution.cli` script file in the root of this quickstart directory. This script first enables MDB annotation property substitution the `ee` subsystem of the server configuration file by creating an `annotation-property-replacement` property with a value of `true`. It then defines the system properties that are used in the substitution. -. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing {jbossHomeName} with the path to your server: +. 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: + -[subs="+quotes,attributes+"] +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/jboss-cli.sh --connect --file=enable-mdb-property-substitution.cli -For Windows: {jbossHomeName}\bin\jboss-cli.bat --connect --file=enable-mdb-property-substitution.cli +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=enable-mdb-property-substitution.cli ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. . Stop the {productName} server. @@ -67,9 +68,9 @@ For Windows: {jbossHomeName}\bin\jboss-cli.bat --connect --file=enable-mdb-prope After stopping the server, open the `{jbossHomeName}/standalone/configuration/standalone-full.xml` file and review the changes. -The `<annotation-property-replacement>` attribute is set to true in the `ee` subsystem : +The `` attribute is set to true in the `ee` subsystem : -[source, xml] +[source,xml,options="nowrap"] ---- ... @@ -80,7 +81,7 @@ The `<annotation-property-replacement>` attribute is set to true in the `e The following system properties are defined and appear after the `<extensions>`: -[source, xml] +[source,xml,options="nowrap"] ---- @@ -91,28 +92,30 @@ The following system properties are defined and appear after the `<extensions == Start the Server with the Full Profile -. Open a command prompt and navigate to the root of the {productName} directory. +. Open a terminal and navigate to the root of the {productName} directory. . The following shows the command line to start the server with the full profile: - + -[subs=normal] +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -c standalone-full.xml -For Windows: {jbossHomeName}\bin\standalone.bat -c standalone-full.xml +$ __{jbossHomeName}__/bin/standalone.sh -c standalone-full.xml ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. == Build and Deploy the Quickstart . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type this command to build and deploy the archive: + +[source,options="nowrap"] ---- -mvn clean install wildfly:deploy +$ mvn clean install wildfly:deploy ---- . This will deploy `target/{artifactId}.war` to the running instance of the server. Look at the {productName} console or Server log and you should see log messages corresponding to the deployment of the message-driven beans and the JMS destinations: - ++ +[source,options="nowrap"] ---- INFO [org.wildfly.extension.messaging-activemq] (MSC service thread 1-8) WFLYMSGAMQ0002: Bound messaging object to jndi name java:/${property.helloworldmdb.queue} INFO [org.wildfly.extension.messaging-activemq] (MSC service thread 1-5) WFLYMSGAMQ0002: Bound messaging object to jndi name java:/${property.helloworldmdb.topic} @@ -136,6 +139,7 @@ To send messages to the topic, use the following URL: http://localhost:8080/{art Look at the {productName} console or Server log and you should see log messages like the following: +[source,options="nowrap"] ---- INFO [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-9 (ActiveMQ-client-global-threads-1189700957)) Received Message from queue: This is message 5 INFO [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-6 (ActiveMQ-client-global-threads-1189700957)) Received Message from queue: This is message 1 @@ -147,11 +151,12 @@ INFO [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-4 (ActiveM == Undeploy the Archive . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . When you are finished testing, type this command to undeploy the archive: - ++ +[source,options="nowrap"] ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- == Restore the Server Configuration @@ -162,24 +167,25 @@ You can remove the server configuration by running the `disable-mdb-property-sub . Start the {productName} server by typing the following: + -[subs="+quotes,attributes+"] +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -c standalone-full.xml -For Windows: {jbossHomeName}\bin\standalone.bat -c standalone-full.xml +$ __{jbossHomeName}__/bin/standalone.sh -c standalone-full.xml ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat -c standalone-full.xml` script. -. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing {jbossHomeName} with the path to your server: +. 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: + -[subs="+quotes,attributes+"] +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/jboss-cli.sh --connect --file=disable-mdb-property-substitution.cli -For Windows: {jbossHomeName}\bin\jboss-cli.bat --connect --file=disable-mdb-property-substitution.cli +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=disable-mdb-property-substitution.cli ---- +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. === Restore the Configuration Manually . If it is running, stop the {productName} server. -. Replace the `{jbossHomeName}/standalone/configuration/standalone-full.xml` file with the back-up copy of the file. +. Replace the `__{jbossHomeName}__/standalone/configuration/standalone-full.xml` file with the back-up copy of the file. == Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse @@ -193,6 +199,7 @@ You can also start the server and deploy the quickstarts or run the Arquillian t If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. +[source,options="nowrap"] +---- +$ mvn dependency:sources ---- -mvn dependency:sources ----- \ No newline at end of file diff --git a/helloworld-mdb/README.adoc b/helloworld-mdb/README.adoc index e6d6fc4421..a3ac67af4d 100644 --- a/helloworld-mdb/README.adoc +++ b/helloworld-mdb/README.adoc @@ -27,31 +27,32 @@ This project creates two JMS resources: The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Use of {jbossHomeName} -In the following instructions, replace `{jbossHomeName}` with the actual path to your {productName} installation. The installation path is described in detail here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_{jbossHomeName}.md#use-of-eap_home-and-jboss_home-variables[Use of {jbossHomeName} and JBOSS_HOME Variables]. +In the following instructions, replace `__{jbossHomeName}__` with the actual path to your {productName} installation. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of {jbossHomeName} and JBOSS_HOME Variables]. == Start the Server with the Full Profile -. Open a command prompt and navigate to the root of the {productName} directory. +. Open a terminal and navigate to the root of the {productName} directory. . The following shows the command line to start the server with the full profile: - -[subs=normal] ++ +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -c standalone-full.xml -For Windows: {jbossHomeName}\bin\standalone.bat -c standalone-full.xml +$ __{jbossHomeName}__/bin/standalone.sh -c standalone-full.xml ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. == Build and Deploy the Quickstart . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type this command to build and deploy the archive: + ---- -mvn clean install wildfly:deploy +$ mvn clean install wildfly:deploy ---- . This will deploy `target/{artifactId}.war` to the running instance of the server. Look at the {productName} console or Server log and you should see log messages corresponding to the deployment of the message-driven beans and the JMS destinations: @@ -89,11 +90,11 @@ INFO [class org.jboss.as.quickstarts.mdb.HelloWorldQueueMDB] (Thread-4 (ActiveM == Undeploy the Archive . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . When you are finished testing, type this command to undeploy the archive: + ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- == Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse @@ -107,5 +108,5 @@ NOTE: Within JBoss Developer Studio, be sure to define a server runtime environm If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. ---- -mvn dependency:sources ----- \ No newline at end of file +$ mvn dependency:sources +---- diff --git a/helloworld-mutual-ssl-secured/README.adoc b/helloworld-mutual-ssl-secured/README.adoc index 1f7bc21ca6..4246771f33 100644 --- a/helloworld-mutual-ssl-secured/README.adoc +++ b/helloworld-mutual-ssl-secured/README.adoc @@ -26,7 +26,7 @@ This quickstart shows how to configure {productName} to enable TLS/SSL configura The applications these projects produce are designed to be run on {productNameFull} {productVersion} or later. -All you need to build these projects is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build these projects is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. To run these quickstarts with the provided build scripts, you need the {productName} distribution ZIP. For information on how to install and run {productName}, see the https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/[{productNameFull} Documentation] _Getting Started Guide_ located on the Customer Portal. @@ -34,48 +34,45 @@ You can also use <keytool -genkey -keyalg RSA -keystore server.keystore -storepass secret -keypass secret -validity 365 @@ -97,7 +94,7 @@ Is CN=localhost, OU=wildfly, O=jboss, L=Raleigh, ST=Carolina, C=US correct? . Create the client certificate, which is used to authenticate against the server when accessing a resource through SSL. + -[subs="+quotes,attributes+"] +[source,options="nowrap"] ---- $>keytool -genkey -keystore client.keystore -storepass secret -validity 365 -keyalg RSA -keysize 2048 -storetype pkcs12 @@ -117,9 +114,9 @@ Is CN=quickstartUser, OU=Sales, O=My Company, L=Sao Paulo, ST=Sao Paulo, C=BR co [no]: yes ---- -. Export the client certificate and create a truststore by importing this certificate: +. Export the client certificate and create a truststore by importing this certificate. + -[subs="+quotes,attributes+"] +[source,options="nowrap"] ---- $>keytool -exportcert -keystore client.keystore -storetype pkcs12 -storepass secret -keypass secret -file client.crt $>keytool -import -file client.crt -alias quickstartUser -keystore client.truststore -storepass secret @@ -149,8 +146,9 @@ Trust this certificate? [no]: yes Certificate was added to keystore ---- -. Export client certificate to pkcs12 format +. Export client certificate to pkcs12 format. + +[source,options="nowrap"] ---- $>keytool -importkeystore -srckeystore client.keystore -srcstorepass secret -destkeystore clientCert.p12 -srcstoretype PKCS12 -deststoretype PKCS12 -deststorepass secret ---- @@ -169,22 +167,24 @@ You configure the SSL context and required security domain by running JBoss CLI ** Back up the file: `{jbossHomeName}/standalone/configuration/standalone.xml` ** After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration. . Start the {productName} server by typing the following: - + -[subs="+quotes,attributes+"] +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +$ __{jbossHomeName}__/bin/standalone.sh ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. . Review the `configure-ssl.cli` file in the root of this quickstart directory. Comments in the script describe the purpose of each block of commands. -. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing {jbossHomeName} with the path to your server: +. 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: + -[subs="+quotes,attributes+"] +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/jboss-cli.sh --connect --file=configure-ssl.cli -For Windows: {jbossHomeName}\bin\jboss-cli.bat --connect --file=configure-ssl.cli +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=configure-ssl.cli ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. + . Stop the {productName} server. @@ -194,7 +194,7 @@ After stopping the server, open the `{jbossHomeName}/standalone/configuration/st . The following `key-store`s were added to the `elytron` subsystem: + -[source, xml] +[source,xml,options="nowrap"] ---- @@ -210,7 +210,7 @@ After stopping the server, open the `{jbossHomeName}/standalone/configuration/st . The following `key-manager` was added to the `elytron` subsystem: + -[source, xml] +[source,xml,options="nowrap"] ---- @@ -221,7 +221,7 @@ After stopping the server, open the `{jbossHomeName}/standalone/configuration/st . The following `trust-manager` was added to the `elytron` subsystem: + -[source, xml] +[source,xml,options="nowrap"] ---- @@ -231,7 +231,7 @@ After stopping the server, open the `{jbossHomeName}/standalone/configuration/st . The following `ssl-context` was added to the `elytron` subsystem: + -[source, xml] +[source,xml,options="nowrap"] ---- @@ -241,7 +241,7 @@ After stopping the server, open the `{jbossHomeName}/standalone/configuration/st . The following realms were added to the `elytron` subsystem: + -[source, xml] +[source,xml,options="nowrap"] ---- @@ -251,7 +251,7 @@ After stopping the server, open the `{jbossHomeName}/standalone/configuration/st . The following `principal-decoder` and `security-domain` were added to the `elytron` subsystem: + -[source, xml] +[source,xml,options="nowrap"] ---- @@ -263,7 +263,7 @@ After stopping the server, open the `{jbossHomeName}/standalone/configuration/st . The following `http-authentication-factory` was added to the `elytron` subsystem: + -[source, xml] +[source,xml,options="nowrap"] ---- @@ -275,7 +275,7 @@ After stopping the server, open the `{jbossHomeName}/standalone/configuration/st . The `https-listener` in the `undertow` subsystem was changed to reference the `qsSSLContext` `ssl-context`: + -[source, xml] +[source,xml,options="nowrap"] ---- ---- @@ -283,7 +283,7 @@ After stopping the server, open the `{jbossHomeName}/standalone/configuration/st . The following `application-security-domain` was added to the `undertow` subsystem: + -[source, xml] +[source,xml,options="nowrap"] ---- @@ -302,20 +302,20 @@ Before you access the application, you must import the _clientCert.p12_, which h === Import the Certificate into Google Chrome -. Click the Chrome menu icon (3 dots) in the upper right on the browser toolbar and choose 'Settings'. This takes you to chrome://settings/. -. Scroll to the bottom of the page and click on the 'Advanced' link to reveal the advanced settings. -. Search for the 'Manage Certificates' line under 'Privacy and security' and then click on it. -. In the 'Manage certificates' screen, select the 'Your Certificates' tab and click on the 'Import' button. -. Select the `clientCert.p12` file. You will be prompted to enter the password: `secret`. +. Click the Chrome menu icon (3 dots) in the upper right on the browser toolbar and choose *Settings*. This takes you to chrome://settings/. +. Scroll to the bottom of the page and click on the *Advanced* link to reveal the advanced settings. +. Search for the *Manage Certificates* line under *Privacy and security* and then click on it. +. In the *Manage certificates* screen, select the *Your Certificates* tab and click on the *Import* button. +. Select the *clientCert.p12* file. You will be prompted to enter the password: `secret`. . The client certificate is now installed in the Google Chrome browser. === Import the Certificate into Mozilla Firefox -. Click the 'Edit' menu item on the browser menu and choose 'Preferences'. -. A new window will open. Select the 'Advanced' icon and after that the 'Certificates' tab. -. On the 'Certificates' tab, mark the option 'Ask me every time' and click the 'View Certificates' button. -. A new window will open. Select the 'Your Certificates' tab and click the 'Import' button. -. Select the `clientCert.p12` file. You will be prompted to enter the password: `secret`. +. Click the *Edit* menu item on the browser menu and choose *Preferences*. +. A new window will open. Select the *Advanced* icon and after that the *Certificates* tab. +. On the *Certificates* tab, mark the option *Ask me every time* and click the *View Certificates* button. +. A new window will open. Select the *Your Certificates* tab and click the *Import* button. +. Select the *clientCert.p12* file. You will be prompted to enter the password: `secret`. . The certificate is now installed in the Mozilla Firefox browser. == Start the Server @@ -323,22 +323,22 @@ Before you access the application, you must import the _clientCert.p12_, which h . Open a command line and navigate to the root of the {productName} directory. . The following shows the command line to start the server with the web profile: + -[subs="+quotes,attributes+"] +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: bin/standalone.sh -For Windows: bin\standalone.bat +$ __{jbossHomeName}__/bin/standalone.sh ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. == Build and Deploy the Quickstart -NOTE: The following build command assumes you have configured your Maven user settings. If you have not, you must include Maven setting arguments on the command line. See link:../README.md#build-and-deploy-the-quickstarts[Build and Deploy the Quickstarts] for complete instructions and additional options. - . Make sure you have started the {productName} server as described above. . Open a command line and navigate to the root directory of one of the quickstart. . Type this command to build and deploy the archive: - ++ +[source,options="nowrap"] ---- -mvn clean package wildfly:deploy +$ mvn clean package wildfly:deploy ---- . This will deploy `target/{artifactId}.war` to the running instance of the server. @@ -347,9 +347,11 @@ mvn clean package wildfly:deploy == Access the Application -The application will be running at the following URL: `<https://localhost:8443/{artifactId}>`. A page displaying the caller -principal and the client certificate used for mutual SSL should be visible: +The application will be running at the following URL: https://localhost:8443/{artifactId} + +A page displaying the caller principal and the client certificate used for mutual SSL should be visible: +[source,options="nowrap"] ---- Hello World ! Mutual SSL client authentication is successful and your war app is secured.!! @@ -374,8 +376,9 @@ ynfnMaOxI67FC2QzhfzERyKqHj47WuwN0xWbS/1gBypS2nUwvItyxaEQG2X5uQY8j8QoY9wcMzIIkP2M . Open a command line and navigate to the root directory of this quickstart. . When you are finished testing, type this command to undeploy the archive: + +[source,options="nowrap"] ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- == Restore the Server Configuration @@ -386,19 +389,21 @@ You can restore the original server configuration by running the `restore-config . Start the {productName} server by typing the following: + -[subs="+quotes,attributes+"] +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +$ __{jbossHomeName}__/bin/standalone.sh ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. -. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing {jbossHomeName} with the path to your server: +. 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: + -[subs="+quotes,attributes+"] +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/jboss-cli.sh --connect --file=restore-configuration.cli -For Windows: {jbossHomeName}\bin\jboss-cli.bat --connect --file=restore-configuration.cli +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=restore-configuration.cli ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. === Restore the Server Configuration Manually @@ -409,10 +414,12 @@ For Windows: {jbossHomeName}\bin\jboss-cli.bat --connect --file=restore-configur . Open a command line and navigate to the {productName} server `configuration` directory: + +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: standalone/configuration -For Windows: standalone\configuration +$ __{jbossHomeName}__/bin/standalone.sh ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. . Remove the `clientCert.p12`, `client.crt`, `client.keystore`, `client.truststore` and `server.keystore` files that were generated for this quickstart. @@ -422,20 +429,20 @@ After you are done with this quickstart, remember to remove the certificate that === Remove the Client Certificate from Google Chrome -. Click the Chrome menu icon (3 dots) in the upper right on the browser toolbar and choose 'Settings'. This takes you to chrome://settings/. -. Scroll to the bottom of the page and click on the 'Advanced' link to reveal the advanced settings. -. Search for the 'Manage Certificates' line under 'Privacy and security' and then click on it. -. In the 'Manage certificates' screen, select the 'Your Certificates' tab and then click on the arrow to the right of the certificate to be removed. -. The certificate is expanded, displaying the `quickstartUser` entry. Click on the icon (3 dots) to the right of it and then select 'Delete'. +. Click the Chrome menu icon (3 dots) in the upper right on the browser toolbar and choose *Settings*. This takes you to chrome://settings/. +. Scroll to the bottom of the page and click on the *Advanced* link to reveal the advanced settings. +. Search for the *Manage Certificates* line under *Privacy and security* and then click on it. +. In the *Manage certificates* screen, select the *Your Certificates* tab and then click on the arrow to the right of the certificate to be removed. +. The certificate is expanded, displaying the `quickstartUser` entry. Click on the icon (3 dots) to the right of it and then select *Delete*. . Confirm the deletion in the dialog box. The certificate has now been removed from the Google Chrome browser. === Remove the Client Certificate from Mozilla Firefox -. Click the 'Edit' menu item on the browser menu and choose 'Preferences'. -. A new window will open. Select the 'Advanced' icon and after that the 'Certificates' tab. -. On the 'Certificates' tab click the 'View Certificates' button. -. A new window will open. Select the 'Your Certificates' tab. -. Select the `quickstartUser` certificate and click the `Delete` button. +. Click the *Edit* menu item on the browser menu and choose *Preferences*. +. A new window will open. Select the *Advanced* icon and after that the *Certificates* tab. +. On the *Certificates* tab click the *View Certificates* button. +. A new window will open. Select the *Your Certificates* tab. +. Select the *quickstartUser* certificate and click the *Delete* button. . The certificate has now been removed from the Mozilla Firefox browser. == Run the Quickstart in JBoss Developer Studio or Eclipse @@ -449,6 +456,7 @@ You can also start the server and deploy the quickstarts or run the Arquillian t If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. +[source,options="nowrap"] ---- -mvn dependency:sources +$ mvn dependency:sources ---- diff --git a/helloworld-mutual-ssl/README.adoc b/helloworld-mutual-ssl/README.adoc index c21a187f3f..10f5bd67d2 100644 --- a/helloworld-mutual-ssl/README.adoc +++ b/helloworld-mutual-ssl/README.adoc @@ -26,7 +26,7 @@ Before you run this example, you must create certificates and configure the serv The applications these projects produce are designed to be run on {productNameFull} {productVersion} or later. -All you need to build these projects is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build these projects is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. To run these quickstarts with the provided build scripts, you need the {productName} distribution ZIP. For information on how to install and run JBoss, see the https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/[{productNameFull} Documentation] _Getting Started Guide_ located on the Customer Portal. @@ -34,20 +34,20 @@ You can also use <keytool -genkey -keyalg RSA -keystore server.keystore -storepass secret -keypass secret -validity 365 @@ -69,6 +69,7 @@ Is CN=localhost, OU=wildfly, O=jboss, L=Raleigh, ST=Carolina, C=US correct? . Create the client certificate, which is used to authenticate against the server when accessing a resource through SSL. + +[source,options="nowrap"] ---- $>keytool -genkey -keystore client.keystore -storepass secret -validity 365 -keyalg RSA -keysize 2048 -storetype pkcs12 @@ -90,6 +91,7 @@ Is CN=quickstartUser, OU=Sales, O=My Company, L=Sao Paulo, ST=Sao Paulo, C=BR co . Export the client certificate and create a truststore by importing this certificate: + +[source,options="nowrap"] ---- $>keytool -exportcert -keystore client.keystore -storetype pkcs12 -storepass secret -keypass secret -file client.crt $>keytool -import -file client.crt -alias quickstartUser -keystore client.truststore -storepass secret @@ -121,6 +123,7 @@ Certificate was added to keystore . Export client certificate to pkcs12 format + +[source,options="nowrap"] ---- $>keytool -importkeystore -srckeystore client.keystore -srcstorepass secret -destkeystore clientCert.p12 -srcstoretype PKCS12 -deststoretype PKCS12 -deststorepass secret ---- @@ -140,30 +143,32 @@ You configure the SSL context by running JBoss CLI commands. For your convenienc ** After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration. . Start the {productName} server by typing the following: + -[subs="+quotes,attributes+"] +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +$ __{jbossHomeName}__/bin/standalone.sh ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. . Review the `configure-ssl.cli` file in the root of this quickstart directory. Comments in the script describe the purpose of each block of commands. -. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing {jbossHomeName} with the path to your server: +. 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: + -[subs="+quotes,attributes+"] +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/jboss-cli.sh --connect --file=configure-ssl.cli -For Windows: {jbossHomeName}\bin\jboss-cli.bat --connect --file=configure-ssl.cli +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=configure-ssl.cli ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. . Stop the {productName} server. == Review the Modified Server Configuration -After stopping the server, open the `{jbossHomeName}/standalone/configuration/standalone.xml` file and review the changes. +After stopping the server, open the `__{jbossHomeName}__/standalone/configuration/standalone.xml` file and review the changes. -. The following `key-store`s were added to the `elytron` subsystem: +. The following `keystore` elements were added to the `elytron` subsystem: + -[source, xml] +[source,xml,options="nowrap"] ---- @@ -179,7 +184,7 @@ After stopping the server, open the `{jbossHomeName}/standalone/configuration/st . The following `key-manager` was added to the `elytron` subsystem: + -[source, xml] +[source,xml,options="nowrap"] ---- @@ -191,7 +196,7 @@ After stopping the server, open the `{jbossHomeName}/standalone/configuration/st . The following `trust-manager` was added to the `elytron` subsystem: + -[source, xml] +[source,xml,options="nowrap"] ---- @@ -201,7 +206,7 @@ After stopping the server, open the `{jbossHomeName}/standalone/configuration/st . The following `ssl-context` was added to the `elytron` subsystem: + -[source, xml] +[source,xml,options="nowrap"] ---- @@ -211,7 +216,7 @@ After stopping the server, open the `{jbossHomeName}/standalone/configuration/st . The `https-listener` in the `undertow` subsystem was changed to reference the `qsSSLContext` `ssl-context`: + -[source, xml] +[source,xml,options="nowrap"] ---- ---- @@ -228,20 +233,20 @@ Before you access the application, you must import the _clientCert.p12_, which h === Import the Client Certificate into Google Chrome -. Click the Chrome menu icon (3 dots) in the upper right on the browser toolbar and choose 'Settings'. This takes you to chrome://settings/. -. Scroll to the bottom of the page and click on the 'Advanced' link to reveal the advanced settings. -. Search for the 'Manage Certificates' line under 'Privacy and security' and then click on it. -. In the 'Manage certificates' screen, select the 'Your Certificates' tab and click on the 'Import' button. -. Select the `clientCert.p12` file. You will be prompted to enter the password: `secret`. +. Click the Chrome menu icon (3 dots) in the upper right on the browser toolbar and choose *Settings*. This takes you to `link:`chrome://settings/``. +. Scroll to the bottom of the page and click on the *Advanced* link to reveal the advanced settings. +. Search for the *Manage Certificates* line under *Privacy and security* and then click on it. +. In the *Manage certificates* screen, select the *Your Certificates* tab and click on the *Import* button. +. Select the *clientCert.p12* file. You will be prompted to enter the password: `secret`. . The client certificate is now installed in the Google Chrome browser. === Import the Client Certificate into Mozilla Firefox -. Click the 'Edit' menu item on the browser menu and choose 'Preferences'. -. A new window will open. Select the 'Advanced' icon and after that the 'Certificates' tab. -. On the 'Certificates' tab, mark the option 'Ask me every time' and click the 'View Certificates' button. -. A new window will open. Select the 'Your Certificates' tab and click the 'Import' button. -. Select the `clientCert.p12` file. You will be prompted to enter the password: `secret`. +. Click the *Edit* menu item on the browser menu and choose *Preferences*. +. A new window will open. Select the *Advanced* icon and after that the *Certificates* tab. +. On the *Certificates* tab, mark the option *Ask me every time* and click the *View Certificates* button. +. A new window will open. Select the *Your Certificates* tab and click the *Import* button. +. Select the *clientCert.p12* file. You will be prompted to enter the password: `secret`. . The certificate is now installed in the Mozilla Firefox browser. == Start the Server @@ -249,21 +254,22 @@ Before you access the application, you must import the _clientCert.p12_, which h . Open a command line and navigate to the root of the JBoss server directory. . The following shows the command line to start the server with the web profile: + +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: /bin/standalone.sh -For Windows: bin\standalone.bat +$ __{jbossHomeName}__/bin/standalone.sh ---- ++ +NOTE: For Windows, use the `__{jbossHomeName__\bin\standalone.bat` script. == Build and Deploy the Quickstart -NOTE: The following build command assumes you have configured your Maven user settings. If you have not, you must include Maven setting arguments on the command line. See link:../README.md#build-and-deploy-the-quickstarts[Build and Deploy the Quickstarts] for complete instructions and additional options._ - . Make sure you have started the {productName} server as described above. . Open a command line and navigate to the root directory of one of the quickstart. . Type this command to build and deploy the archive: + +[source,options="nowrap"] ---- -mvn clean package wildfly:deploy +$ mvn clean package wildfly:deploy ---- . This will deploy `target/{artifactId}.war` to the running instance of the server. @@ -274,6 +280,7 @@ The application will be running at the following URL: https://localhost:8443/{ar A page displaying the client certificate should be visible: +[source,options="nowrap"] ---- Hello World ! Wildfly mutual SSL is configured and client certificate is verified !! @@ -296,8 +303,9 @@ aEWK4zhPVFynfnMaOxI67FC2QzhfzERyKqHj47WuwN0xWbS/1gBypS2nUwvItyxaEQG2X5uQY8j8QoY9 . Open a command line and navigate to the root directory of this quickstart. . When you are finished testing, type this command to undeploy the archive: + +[source,options="nowrap"] ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- == Restore the Server Configuration @@ -308,32 +316,36 @@ You can restore the original server configuration by running the `restore-config . Start the {productName} server by typing the following: + -[subs="+quotes,attributes+"] +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +$ __{jbossHomeName}__/bin/standalone.sh ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. + -. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing {jbossHomeName} with the path to your server: +. 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: + -[subs="+quotes,attributes+"] +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/jboss-cli.sh --connect --file=restore-configuration.cli -For Windows: {jbossHomeName}\bin\jboss-cli.bat --connect --file=restore-configuration.cli +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=restore-configuration.cli ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. + === Restore the Server Configuration Manually . If it is running, stop the {productName} server. -. Replace the `{jbossHomeName}/standalone/configuration/standalone.xml` file with the back-up copy of the file. +. Replace the `__{jbossHomeName}__/standalone/configuration/standalone.xml` file with the back-up copy of the file. == Remove the keystores and certificates created for this quickstart . Open a command line and navigate to the {productName} server `configuration` directory: - ++ +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: standalone/configuration -For Windows: standalone\configuration +$ cd __{jbossHomeName}__/standalone/configuration/ ---- . Remove the `clientCert.p12`, `client.crt`, `client.keystore`, `client.truststore` and `server.keystore` files that @@ -345,19 +357,19 @@ After you are done with this quickstart, remember to remove the certificate that === Remove the Client Certificate from Google Chrome -. Click the Chrome menu icon (3 dots) in the upper right on the browser toolbar and choose 'Settings'. This takes you to chrome://settings/. -. Scroll to the bottom of the page and click on the 'Advanced' link to reveal the advanced settings. -. Search for the 'Manage Certificates' line under 'Privacy and security' and then click on it. -. In the 'Manage certificates' screen, select the 'Your Certificates' tab and then click on the arrow to the right of the certificate to be removed. -. The certificate is expanded, displaying the `quickstartUser` entry. Click on the icon (3 dots) to the right of it and then select 'Delete'. +. Click the Chrome menu icon (3 dots) in the upper right on the browser toolbar and choose *Settings*. This takes you to chrome://settings/. +. Scroll to the bottom of the page and click on the *Advanced* link to reveal the advanced settings. +. Search for the *Manage Certificates* line under *Privacy and security* and then click on it. +. In the *Manage certificates* screen, select the *Your Certificates* tab and then click on the arrow to the right of the certificate to be removed. +. The certificate is expanded, displaying the `quickstartUser` entry. Click on the icon (3 dots) to the right of it and then select *Delete*. . Confirm the deletion in the dialog box. The certificate has now been removed from the Google Chrome browser. === Remove the Client Certificate from Mozilla Firefox -. Click the 'Edit' menu item on the browser menu and choose 'Preferences'. -. A new window will open. Select the 'Advanced' icon and after that the 'Certificates' tab. -. On the 'Certificates' tab click the 'View Certificates' button. -. A new window will open. Select the 'Your Certificates' tab. +. Click the *Edit* menu item on the browser menu and choose *Preferences*. +. A new window will open. Select the *Advanced* icon and after that the *Certificates* tab. +. On the *Certificates* tab click the *View Certificates* button. +. A new window will open. Select the *Your Certificates* tab. . Select the `quickstartUser` certificate and click the `Delete` button. . The certificate has now been removed from the Mozilla Firefox browser. @@ -368,15 +380,16 @@ You can also start the server and deploy the quickstarts or run the Arquillian t * Be sure to configure the keystores and client certificates as described under <>. * Depending on the browser you choose, be sure to either <> or <>. * Be sure to configure the server by running the JBoss CLI commands as described above under <>. Stop the server at the end of that step. -* In JBoss Developer Studio, choose _Window_ –> _Web Browser_, then select the browser you chose to import the certificate. -* To deploy the application, right-click on the `{artifactId}` project and choose `Run As` –> `Run on Server`. +* In JBoss Developer Studio, choose *Window* –> *Web Browser*, then select the browser you chose to import the certificate. +* To deploy the application, right-click on the *{artifactId}* project and choose *Run As* –> *Run on Server*. * Be sure to <> when you have completed testing this quickstart. == Debug the Application If you want to debug the source code or look at the Javadocs of any library in the project, run either of the following commands to pull them into your local repository. The IDE should then detect them. +[source,options="nowrap"] +---- +$ mvn dependency:sources +$ mvn dependency:resolve -Dclassifier=javadoc ---- - mvn dependency:sources - mvn dependency:resolve -Dclassifier=javadoc ----- \ No newline at end of file diff --git a/helloworld-rs/README.adoc b/helloworld-rs/README.adoc index 17c2c7c82a..f05a76064e 100644 --- a/helloworld-rs/README.adoc +++ b/helloworld-rs/README.adoc @@ -22,31 +22,33 @@ The `helloworld-rs` quickstart demonstrates the use of _CDI_ and _JAX-RS_ in {pr The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Use of {jbossHomeName} -In the following instructions, replace `{jbossHomeName}` with the actual path to your {productName} installation. The installation path is described in detail here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_{jbossHomeName}.md#use-of-eap_home-and-jboss_home-variables[Use of {jbossHomeName} and JBOSS_HOME Variables]. +In the following instructions, replace `__{jbossHomeName}__` with the actual path to your {productName} installation. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of {jbossHomeName} and JBOSS_HOME Variables]. == Start the Server -. Open a command prompt and navigate to the root of the {productName} directory. +. Open a terminal and navigate to the root of the {productName} directory. . The following shows the command line to start the server: - -[subs=normal] ++ +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +$ __{jbossHomeName}__/bin/standalone.sh ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. == Build and Deploy the Quickstart . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type this command to build and deploy the archive: - ++ +[source,options="nowrap"] ---- -mvn clean install wildfly:deploy +$ mvn clean install wildfly:deploy ---- . This will deploy `target/{artifactId}.war` to the running instance of the server. @@ -62,11 +64,12 @@ The _JSON_ content can be viewed by accessing this URL: http://localhost:8080/{a == Undeploy the Archive . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . When you are finished testing, type this command to undeploy the archive: - ++ +[source,options="nowrap"] ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- == Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse @@ -77,6 +80,7 @@ You can also start the server and deploy the quickstarts or run the Arquillian t If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. +[source,options="nowrap"] +---- +$ mvn dependency:sources ---- - mvn dependency:sources ----- \ No newline at end of file diff --git a/helloworld-singleton/README.adoc b/helloworld-singleton/README.adoc index f854ab0697..d968c70975 100644 --- a/helloworld-singleton/README.adoc +++ b/helloworld-singleton/README.adoc @@ -22,31 +22,32 @@ The `helloworld-singleton` quickstart demonstrates the use of an _EJB Singleton The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Use of {jbossHomeName} -In the following instructions, replace `{jbossHomeName}` with the actual path to your {productName} installation. The installation path is described in detail here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_{jbossHomeName}.md#use-of-eap_home-and-jboss_home-variables[Use of {jbossHomeName} and JBOSS_HOME Variables]. +In the following instructions, replace `__{jbossHomeName}__` with the actual path to your {productName} installation. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of {jbossHomeName} and JBOSS_HOME Variables]. == Start the Server -. Open a command prompt and navigate to the root of the {productName} directory. +. Open a terminal and navigate to the root of the {productName} directory. . The following shows the command line to start the server: - -[subs=normal] ++ +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +$ __{jbossHomeName}__/bin/standalone.sh ---- +NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. == Build and Deploy the Quickstart . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type this command to build and deploy the archive: - ++ +[source,options="nowrap"] ---- -mvn clean install wildfly:deploy +$ mvn clean install wildfly:deploy ---- . This will deploy `target/{artifactId}.war` to the running instance of the server. @@ -64,11 +65,12 @@ To test the singleton bean, click on either `Increment A` or `Increment B`. The == Undeploy the Archive . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . When you are finished testing, type this command to undeploy the archive: - ++ +[source,options="nowrap"] ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- == Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse @@ -79,6 +81,7 @@ You can also start the server and deploy the quickstarts or run the Arquillian t If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. +[source,options="nowrap"] +---- +$ mvn dependency:sources ---- - mvn dependency:sources ----- \ No newline at end of file diff --git a/helloworld-ssl/README.adoc b/helloworld-ssl/README.adoc index b6801b342b..8e724747c1 100644 --- a/helloworld-ssl/README.adoc +++ b/helloworld-ssl/README.adoc @@ -26,7 +26,7 @@ Before you run this example, you must create certificates and configure the serv The applications these projects produce are designed to be run on {productNameFull} {productVersion} or later. -All you need to build these projects is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build these projects is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. To run these quickstarts with the provided build scripts, you need the {productName} distribution ZIP. For information on how to install and run JBoss, see the https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/[{productNameFull} Documentation] _Getting Started Guide_ located on the Customer Portal. @@ -34,19 +34,20 @@ You can also use <keytool -genkey -alias mycert -keyalg RSA -sigalg MD5withRSA -keystore server.keystore -storepass secret -keypass secret -validity 9999 @@ -79,21 +80,20 @@ You configure the SSL context by running JBoss CLI commands. For your convenienc ** After you have completed testing this quickstart, you can replace this file to restore the server to its original configuration. . Start the {productName} server by typing the following: + -[subs="+quotes,attributes+"] +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +$ __{jbossHomeName}__/bin/standalone.sh ---- +NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. . Review the `configure-ssl.cli` file in the root of this quickstart directory. Comments in the script describe the purpose of each block of commands. -. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing {jbossHomeName} with the path to your server: - +. 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: + -[subs="+quotes,attributes+"] +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/jboss-cli.sh --connect --file=configure-ssl.cli -For Windows: {jbossHomeName}\bin\jboss-cli.bat --connect --file=configure-ssl.cli +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=configure-ssl.cli ---- +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. . Stop the {productName} server. @@ -101,11 +101,11 @@ Now you're ready to connect to the SSL port of your instance https://localhost:8 == Review the Modified Server Configuration -After stopping the server, open the `{jbossHomeName}/standalone/configuration/standalone.xml` file and review the changes. +After stopping the server, open the `__{jbossHomeName}__/standalone/configuration/standalone.xml` file and review the changes. . The following `key-store` was added to the `elytron` subsystem: + -[source, xml] +[source,xml,options="nowrap"] ---- @@ -118,7 +118,7 @@ After stopping the server, open the `{jbossHomeName}/standalone/configuration/st . The following `key-manager` was added to the `elytron` subsystem: + -[source, xml] +[source,xml,options="nowrap"] ---- @@ -130,7 +130,7 @@ After stopping the server, open the `{jbossHomeName}/standalone/configuration/st . The following `ssl-context` was added to the `elytron` subsystem: + -[source, xml] +[source,xml,options="nowrap"] ---- @@ -140,7 +140,7 @@ After stopping the server, open the `{jbossHomeName}/standalone/configuration/st . The `https-listener` in the `undertow` subsystem was changed to reference the `qsSSLContext` `ssl-context`: + -[source, xml] +[source,xml,options="nowrap"] ---- ---- @@ -153,22 +153,24 @@ To test the SSL configuration, access: https://localhost:8443 . Open a command line and navigate to the root of the {productName} directory. . The following shows the command line to start the server with the web profile: - ++ +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: bin/standalone.sh -For Windows: bin\standalone.bat +$ __{jbossHomeName}__/bin/standalone.sh ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. -== Build and Deploy the Quickstart -_NOTE: The following build command assumes you have configured your Maven user settings. If you have not, you must include Maven setting arguments on the command line. See link:../README.md#build-and-deploy-the-quickstarts[Build and Deploy the Quickstarts] for complete instructions and additional options._ +== Build and Deploy the Quickstart . Make sure you have started the {productName} server as described above. . Open a command line and navigate to the root directory of one of the quickstart. . Type this command to build and deploy the archive: - ++ +[source,options="nowrap"] ---- -mvn clean package wildfly:deploy +$ mvn clean package wildfly:deploy ---- . This will deploy `target/{artifactId}.war` to the running instance of the server. @@ -182,9 +184,10 @@ The application will be running at the following URL: https://localhost:8443/{ar . Make sure you have started the JBoss Server as described above. . Open a command line and navigate to the root directory of this quickstart. . When you are finished testing, type this command to undeploy the archive: - ++ +[source,options="nowrap"] ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- == Restore the Server Configuration @@ -195,32 +198,33 @@ You can restore the original server configuration by running the `restore-config . Start the {productName} server by typing the following: + -[subs="+quotes,attributes+"] +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +$ __{jbossHomeName}__/bin/standalone.sh ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. -. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing {jbossHomeName} with the path to your server: +. 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: + -[subs="+quotes,attributes+"] +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/jboss-cli.sh --connect --file=restore-configuration.cli -For Windows: {jbossHomeName}\bin\jboss-cli.bat --connect --file=restore-configuration.cli +$ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=restore-configuration.cli ---- +NOTE: For Windows, use the `__{jbossHomeName}__\bin\jboss-cli.bat` script. === Restore the Server Configuration Manually . If it is running, stop the {productName} server. -. Replace the `{jbossHomeName}/standalone/configuration/standalone.xml` file with the back-up copy of the file. +. Replace the `__{jbossHomeName}__/standalone/configuration/standalone.xml` file with the back-up copy of the file. == Remove the keystore created for this quickstart . Open a command line and navigate to the {productName} server `configuration` directory: + +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: standalone/configuration -For Windows: standalone\configuration +$ cd __{jbossHomeName}__/standalone/configuration/ ---- . Remove the keystore generated for this quickstart. @@ -236,6 +240,7 @@ You can also start the server and deploy the quickstarts or run the Arquillian t If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. +[source,options="nowrap"] +---- +$ mvn dependency:sources ---- -mvn dependency:sources ----- \ No newline at end of file diff --git a/helloworld-ws/README.adoc b/helloworld-ws/README.adoc index 2beb265e1e..57407f6413 100644 --- a/helloworld-ws/README.adoc +++ b/helloworld-ws/README.adoc @@ -22,37 +22,40 @@ The `helloworld-ws` quickstart demonstrates the use of _JAX-WS_ in {productNameF The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Use of {jbossHomeName} -In the following instructions, replace `{jbossHomeName}` with the actual path to your {productName} installation. The installation path is described in detail here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_{jbossHomeName}.md#use-of-eap_home-and-jboss_home-variables[Use of {jbossHomeName} and JBOSS_HOME Variables]. +In the following instructions, replace `__{jbossHomeName}__` with the actual path to your {productName} installation. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of {jbossHomeName} and JBOSS_HOME Variables]. == Start the Server -. Open a command prompt and navigate to the root of the {productName} directory. +. Open a terminal and navigate to the root of the {productName} directory. . The following shows the command line to start the server: - -[subs=normal] ++ +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +$ __{jbossHomeName}__/bin/standalone.sh ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. == Build and Deploy the Quickstart . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type this command to build and deploy the archive: - ++ +[source,options="nowrap"] ---- -mvn clean install wildfly:deploy +$ mvn clean install wildfly:deploy ---- . This will deploy `target/{artifactId}.war` to the running instance of the server. . 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 @@ -71,11 +74,12 @@ You can verify that the Web Service is running and deployed correctly by accessi == Undeploy the Archive . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . When you are finished testing, type this command to undeploy the archive: - ++ +[source,options="nowrap"] ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- == Run the Client Tests Using Arquillian @@ -83,19 +87,21 @@ mvn wildfly:undeploy This quickstart provides Arquillian tests. By default, these tests are configured to be skipped as Arquillian tests require the use of a container. . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type the following command to run the test goal with the following profile activated: - ++ +[source,options="nowrap"] ---- -mvn clean verify -Parq-remote +$ mvn clean verify -Parq-remote ---- -You can also let Arquillian manage the {productName} server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests[Run the Arquillian Tests]. +You can also let Arquillian manage the {productName} server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see link:{arquillianTestsDocUrl}[Run the Arquillian Tests]. == Investigate the Console Output The following expected output should appear. The output shows what was said to the Web Service by the client and the responses it received. +[source,options="nowrap"] ---- ------------------------------------------------------- T E S T S @@ -120,6 +126,7 @@ When you deploy this quickstart, you are presented with a window that explains t If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. +[source,options="nowrap"] +---- +$ mvn dependency:sources ---- - mvn dependency:sources ----- \ No newline at end of file diff --git a/helloworld/README.adoc b/helloworld/README.adoc index 7bc35f3483..0370b248fb 100644 --- a/helloworld/README.adoc +++ b/helloworld/README.adoc @@ -22,30 +22,32 @@ The `helloworld` quickstart demonstrates the use of _CDI_ and _Servlet 3_ in {pr The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.1.1 or later. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is Java 8.0 (Java SDK 1.8) or later and Maven 3.1.1 or later. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Use of {jbossHomeName} -In the following instructions, replace `{jbossHomeName}` with the actual path to your {productName} installation. The installation path is described in detail here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_{jbossHomeName}.md#use-of-eap_home-and-jboss_home-variables[Use of {jbossHomeName} and JBOSS_HOME Variables]. +In the following instructions, replace `__{jbossHomeName}__` with the actual path to your {productName} installation. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of {jbossHomeName} and JBOSS_HOME Variables]. == Start the Server -. Open a command prompt and navigate to the root of the {productName} directory. +. Open a terminal and navigate to the root of the {productName} directory. . The following shows the command line to start the server: - ++ +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: bin/standalone.sh -For Windows: bin\standalone.bat +$ __{jbossHomeName}__/bin/standalone.sh ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. == Build and Deploy the Quickstart . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type this command to build and deploy the archive: - ++ ---- -mvn clean install wildfly:deploy +$ mvn clean install wildfly:deploy ---- . This will deploy `target/{artifactId}.war` to the running instance of the server. @@ -57,21 +59,21 @@ The application will be running at the following URL: http://localhost:8080/{art == Undeploy the Archive . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . When you are finished testing, type this command to undeploy the archive: - ++ ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- == Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a {productName} server, and build and deploy a quickstart, see https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts[Use JBoss Developer Studio or Eclipse to Run the Quickstarts]. +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a {productName} server, and build and deploy a quickstart, see link:{useEclipseUrl}[Use JBoss Developer Studio or Eclipse to Run the Quickstarts]. == Debug the Application If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. ---- - mvn dependency:sources ----- \ No newline at end of file +$ mvn dependency:sources +---- diff --git a/hibernate/README.adoc b/hibernate/README.adoc index ec01b751d4..ad6c188885 100644 --- a/hibernate/README.adoc +++ b/hibernate/README.adoc @@ -16,23 +16,26 @@ The `hibernate` quickstart demonstrates how to use Hibernate ORM 5 API over JPA, == What is it? -The `hibernate` quickstart is based upon the link:../kitchensink/README.md[kitchensink] example, but demonstrates how to use Hibernate Object/Relational Mapping (ORM) 5 over JPA in {productNameFull}. +The `hibernate` quickstart is based upon the link:../kitchensink/README.adoc[kitchensink] example, but demonstrates how to use Hibernate Object/Relational Mapping (ORM) 5 over JPA in {productNameFull}. This project is setup to allow you to create a compliant Java EE 7 application using JSF, CDI, EJB, JPA , Hibernate-Core and Hibernate Bean Validation. It includes a persistence unit associated with Hibernate session and some sample persistence and transaction code to help you with database access in enterprise Java. -_Note: This quickstart uses the H2 database included with {productNameFull} {productVersion}. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ - -_Note: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in {productName} and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/[Configuration Guide] for {productNameFull}._ +//************************************************* +// Add notes about use in a production environment. +//************************************************* +:uses-h2: +:uses-ds-xml: +include::../development-shortcuts.adoc[leveloffset=+1] == System Requirements The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Use of {jbossHomeName} -In the following instructions, replace `{jbossHomeName}` with the actual path to your {productName} installation. The installation path is described in detail here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_{jbossHomeName}.md#use-of-eap_home-and-jboss_home-variables[Use of {jbossHomeName} and JBOSS_HOME Variables]. +In the following instructions, replace `__{jbossHomeName}__` with the actual path to your {productName} installation. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of {jbossHomeName} and JBOSS_HOME Variables]. == Add the Correct Dependencies @@ -43,41 +46,44 @@ If you use Hibernate 5 packaged within {productName}, you will need to first imp This quickstart demonstrates usage of Hibernate Session and Hibernate Validators. If you look at the pom.xml file in the root of the hibernate quickstart directory, you will see that the dependencies for the Hibernate modules have been added with the scope as `provided`. -For example: +For example: +[source,xml,options="nowrap"] ---- - - org.hibernate - hibernate-validator - provided - - - org.slf4j - slf4j-api - - - + + org.hibernate + hibernate-validator + provided + + + org.slf4j + slf4j-api + + + ---- == Start the Server -. Open a command prompt and navigate to the root of the {productName} directory. +. Open a terminal and navigate to the root of the {productName} directory. . The following shows the command line to start the server: - -[subs=normal] ++ +[source,subs="+quotes,attributes+",options="nowrap"] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +$ __{jbossHomeName}__/bin/standalone.sh ---- ++ +NOTE: For Windows, use the `__{jbossHomeName}__\bin\standalone.bat` script. + == Build and Deploy the Quickstart . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type this command to build and deploy the archive: ---- -mvn clean install wildfly:deploy +$ mvn clean install wildfly:deploy ---- . This will deploy `target/{artifactId}.war` to the running instance of the server. @@ -88,7 +94,7 @@ The application will be running at the following URL: http://localhost:8080/{art == Server Log: Expected Warnings and Errors -NOTE: You will see the following warnings in the server log. You can ignore these warnings. +You will see the following warnings in the server log. You can ignore these warnings. ---- WFLYJCA0091: -ds.xml file deployments are deprecated. Support may be removed in a future version. @@ -99,23 +105,23 @@ HHH000431: Unable to determine H2 database version, certain features may not wor == Undeploy the Archive . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . When you are finished testing, type this command to undeploy the archive: - ++ ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- == Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse -You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a {productName} server, and build and deploy a quickstart, see link:{useEclipseUrl}[Use JBoss Developer Studio or Eclipse to Run the Quickstarts]. +You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a {productName} server, and build and deploy a quickstart, see link:{useEclipseUrl}[Use JBoss Developer Studio or Eclipse to Run the Quickstarts]. == Debug the Application If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. ---- - mvn dependency:sources +$ mvn dependency:sources ---- You may see the following message when you run the command. It indicates the source is not provided in the third-party `antlr` JAR. @@ -123,4 +129,4 @@ You may see the following message when you run the command. It indicates the sou ---- [INFO] The following files have NOT been resolved: [INFO] antlr:antlr:jar:sources:2.7.7:provided ----- \ No newline at end of file +---- diff --git a/inter-app/README.adoc b/inter-app/README.adoc index fc4203db08..7a69b03f1f 100644 --- a/inter-app/README.adoc +++ b/inter-app/README.adoc @@ -1,4 +1,4 @@ -= inter-app: Communicate Between Two Applications Using EJB and CDI +>= inter-app: Communicate Between Two Applications Using EJB and CDI :author: Pete Muir :productName: WildFly :productNameFull: WildFly Application Server @@ -30,31 +30,31 @@ In all, the project has three modules: The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Use of {jbossHomeName} -In the following instructions, replace `{jbossHomeName}` with the actual path to your {productName} installation. The installation path is described in detail here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_{jbossHomeName}.md#use-of-eap_home-and-jboss_home-variables[Use of {jbossHomeName} and JBOSS_HOME Variables]. +In the following instructions, replace `__{jbossHomeName}__` with the actual path to your {productName} installation. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of {jbossHomeName} and JBOSS_HOME Variables]. == Start the Server -. Open a command prompt and navigate to the root of the {productName} directory. +. Open a terminal and navigate to the root of the {productName} directory. . The following shows the command line to start the server: [subs=normal] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +For Linux: $ __{jbossHomeName}__/bin/standalone.sh +For Windows: __{jbossHomeName}__\bin\standalone.bat ---- == Build and Deploy the Quickstart . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type this command to build and deploy the archive: ---- -mvn clean install wildfly:deploy +$ mvn clean install wildfly:deploy ---- . This will deploy `shared/target/{artifactId}-app-shared.jar`, `appA/target/{artifactId}-app-appA.war` and `appB/target/{artifactId}-app-appB.war` to the running instance of the server. @@ -66,7 +66,7 @@ Access the running application in a browser at the following URLs: * http://localhost:8080/{artifactId}-appA * http://localhost:8080/{artifactId}-appB -You are presented with a form that allows you to set the value on the bean in the other application, as well as display of the value on this application's bean. Enter a new value and press `Update and Send!` to update the value on the other application. Do the same on the other application, and hit the button again on the first application. You should see the values shared between the applications. +You are presented with a form that allows you to set the value on the bean in the other application, as well as display of the value on this application's bean. Enter a new value and click *Update and Send!* to update the value on the other application. Do the same on the other application, and hit the button again on the first application. You should see the values shared between the applications. == Undeploy the Archive @@ -75,17 +75,17 @@ This quickstart undeploys differently than some of the others because of the WAR When you are finished testing, follow these steps to undeploy the archives: . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type the following command to undeploy the `inter-app-appA.war` and `inter-app-appB.war` archives. ---- -mvn wildfly:undeploy -pl appA,appB +$ mvn wildfly:undeploy -pl appA,appB ---- . Type the following command to undeploy the `inter-app-shared.jar` archive. ---- -mvn wildfly:undeploy -pl shared +$ mvn wildfly:undeploy -pl shared ---- == Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse @@ -94,19 +94,19 @@ You can also start the server and deploy the quickstarts or run the Arquillian t This quickstart consists of multiple projects containing interdependencies on each other, so it deploys and runs differently in JBoss Developer Studio than the other quickstarts. -. In the `Servers` tab, right-click on the {productName} server and choose `Start`. +. In the *Servers* tab, right-click on the {productName} server and choose *Start*. . Deploy the projects in one of the following ways. -** `Drag and Drop` mode: Click to multi-select the `{artifactId}-app-shared`, `{artifactId}-app-appA`, and `{artifactId}-app-appB` projects, then drag and drop them on the running {productName} server. This deploys the projects to the server without opening the browser. -** `Batch` mode: In the `Servers` tab, right-click on the server and choose `Add and Remove`. If the `{artifactId}-app-shared`, `{artifactId}-app-appA`, and `{artifactId}-app-appB` projects are the only projects in the list, click `Add All`. Otherwise, use multi-select to select them and click `Add`. Then click `Finish`. -. Right-click on the `{artifactId}-app-appA` project and choose `Run As` –> `Run on Server`. A browser window appears that accesses the running `appA` application. -. Right-click on the `{artifactId}-app-appB` project and choose `Run As` –> `Run on Server`. A browser window appears that accesses the running `appB` application. -. To undeploy the `{artifactId}-app-appB`project, right-click on it and choose `Run As` –> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. -. To undeploy the `{artifactId}-app-appA`project, right-click on it and choose `Run As` –> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. +** `Drag and Drop` mode: Click to multi-select the *{artifactId}-app-shared*, *{artifactId}-app-appA*, and *{artifactId}-app-appB* projects, then drag and drop them on the running {productName} server. This deploys the projects to the server without opening the browser. +** `Batch` mode: In the *Servers* tab, right-click on the server and choose *Add and Remove*. If the *{artifactId}-app-shared*, *{artifactId}-app-appA*, and *{artifactId}-app-appB* projects are the only projects in the list, click *Add All*. Otherwise, use multi-select to select them and click *Add*. Then click *Finish*. +. Right-click on the *{artifactId}-app-appA* project and choose *Run As* –>; *Run on Server*. A browser window appears that accesses the running `appA` application. +. Right-click on the *{artifactId}-app-appB* project and choose *Run As* –>; *Run on Server*. A browser window appears that accesses the running `appB` application. +. To undeploy the *{artifactId}-app-appB* project, right-click on it and choose *Run As* –>; *Maven build*. Enter `wildfly:undeploy` for the *Goals* and click *Run*. +. To undeploy the `{artifactId}-app-appA` project, right-click on it and choose *Run As* –>; *Maven build*. Enter `wildfly:undeploy` for the *Goals* and click *Run*. == Debug the Application If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. ---- -mvn dependency:sources ----- \ No newline at end of file +$ mvn dependency:sources +---- diff --git a/jaxrs-client/README.adoc b/jaxrs-client/README.adoc index 1bc5177c93..10839856ce 100644 --- a/jaxrs-client/README.adoc +++ b/jaxrs-client/README.adoc @@ -24,7 +24,7 @@ This client "calls" many POST, GET, DELETE operations using different ways: sync The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Start the Server @@ -33,8 +33,8 @@ All you need to build this project is {buildRequirements}. See https://github.co [subs=normal] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +For Linux: $ __{jbossHomeName}__/bin/standalone.sh +For Windows: __{jbossHomeName}__\bin\standalone.bat ---- == Build and Deploy the Quickstart @@ -44,7 +44,7 @@ For Windows: {jbossHomeName}\bin\standalone.bat . Type this command to build and deploy the archive: ---- -mvn package wildfly:deploy +$ mvn package wildfly:deploy ---- . This will deploy `target/{artifactId}.war` to the running instance of the server. @@ -58,10 +58,10 @@ This quickstart provides Arquillian tests. By default, these tests are configure . Type the following command to run the test goal with the following profile activated: ---- -mvn clean verify -Parq-remote +$ mvn clean verify -Parq-remote ---- -You can also let Arquillian manage the {productName} server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests[Run the Arquillian Tests]. +You can also let Arquillian manage the {productName} server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see link:{arquillianTestsDocUrl}[Run the Arquillian Tests]. == Investigate the Console Output @@ -132,11 +132,11 @@ You can also let Arquillian manage the {productName} server by using the `arq-ma == Undeploy the Archive . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . When you are finished testing, type this command to undeploy the archive: ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- == Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse @@ -153,5 +153,5 @@ To run the tests in Red Hat JBoss Developer Studio: If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. ---- -mvn dependency:sources +$ mvn dependency:sources ---- \ No newline at end of file diff --git a/jaxws-addressing/README.adoc b/jaxws-addressing/README.adoc index 16c54c39db..7aa38b9c93 100644 --- a/jaxws-addressing/README.adoc +++ b/jaxws-addressing/README.adoc @@ -22,31 +22,31 @@ The `jaxws-addressing` quickstart demonstrates the use of _JAX-WS_ in {productNa The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Use of {jbossHomeName} -In the following instructions, replace `{jbossHomeName}` with the actual path to your {productName} installation. The installation path is described in detail here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_{jbossHomeName}.md#use-of-eap_home-and-jboss_home-variables[Use of {jbossHomeName} and JBOSS_HOME Variables]. +In the following instructions, replace `__{jbossHomeName}__` with the actual path to your {productName} installation. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of {jbossHomeName} and JBOSS_HOME Variables]. == Start the Server -. Open a command prompt and navigate to the root of the {productName} directory. +. Open a terminal and navigate to the root of the {productName} directory. . The following shows the command line to start the server: [subs=normal] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +For Linux: $ __{jbossHomeName}__/bin/standalone.sh +For Windows: __{jbossHomeName}__\bin\standalone.bat ---- == Build and Deploy the Quickstart . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type this command to build and deploy the archive: ---- -mvn clean install wildfly:deploy +$ mvn clean install wildfly:deploy ---- . This will create the `{artifactId}-client.jar` and deploy `service/target/{artifactId}-service.war` to the running instance of the server. @@ -59,7 +59,7 @@ You can check that the Web Service is running and deployed correctly by accessin . Make sure the service deployed properly. -. Open a command prompt and navigate into the client directory of this quickstart. +. Open a terminal and navigate into the client directory of this quickstart. ---- cd client/ @@ -68,7 +68,7 @@ cd client/ . Type this command to run the client. ---- -mvn exec:java +$ mvn exec:java ---- . You should see the following output in the client console. @@ -80,18 +80,18 @@ Hello World! == Undeploy the Archive . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . When you are finished testing, type this command to undeploy the archive: ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- == Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a {productName} server, and build and deploy a quickstart, see link:{useEclipseUrl}[Use JBoss Developer Studio or Eclipse to Run the Quickstarts]. -For this quickstart, follow the special instructions to https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#deploy-and-undeploy-a-quickstart-containing-server-and-java-client-projects[Deploy and Undeploy a Quickstart Containing Server and Java Client Projects] +For this quickstart, follow the special instructions to link:{useEclipseDeployJavaClientDocUrl}[Deploy and Undeploy a Quickstart Containing Server and Java Client Projects] . To build all of the artifacts, right-click on the `{artifactId}` parent project, and choose `Run As` –> `Maven install`. . To deploy the service: @@ -114,5 +114,5 @@ Hello World! If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. ---- -mvn dependency:sources +$ mvn dependency:sources ---- \ No newline at end of file diff --git a/jaxws-ejb/README.adoc b/jaxws-ejb/README.adoc index 1ae6eca832..5a158dce91 100644 --- a/jaxws-ejb/README.adoc +++ b/jaxws-ejb/README.adoc @@ -22,31 +22,31 @@ The `jaxws-ejb` quickstart demonstrates the use of _JAX-WS_ in {productNameFull} The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Use of {jbossHomeName} -In the following instructions, replace `{jbossHomeName}` with the actual path to your {productName} installation. The installation path is described in detail here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_{jbossHomeName}.md#use-of-eap_home-and-jboss_home-variables[Use of {jbossHomeName} and JBOSS_HOME Variables]. +In the following instructions, replace `__{jbossHomeName}__` with the actual path to your {productName} installation. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of {jbossHomeName} and JBOSS_HOME Variables]. == Start the Server -. Open a command prompt and navigate to the root of the {productName} directory. +. Open a terminal and navigate to the root of the {productName} directory. . The following shows the command line to start the server: + [subs=normal] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +For Linux: $ __{jbossHomeName}__/bin/standalone.sh +For Windows: __{jbossHomeName}__\bin\standalone.bat ---- == Build and Deploy the Quickstart . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type this command to build and deploy the archive: + ---- -mvn clean install wildfly:deploy +$ mvn clean install wildfly:deploy ---- . This will deploy `service/target/{artifactId}-service.war` to the running instance of the server. @@ -59,7 +59,7 @@ You can check that the Web Service is running and deployed correctly by accessin . Make sure the service deployed properly. -. Open a command prompt and navigate into the client directory of this quickstart. +. Open a terminal and navigate into the client directory of this quickstart. + ---- cd client/ @@ -68,7 +68,7 @@ cd client/ . Type this command to run the client. + ---- -mvn exec:java +$ mvn exec:java ---- . You should see the following output in the client console. @@ -80,18 +80,18 @@ EJB3Bean returning: ejbClient calling == Undeploy the Archive . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . When you are finished testing, type this command to undeploy the archive: + ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- == Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a {productName} server, and build and deploy a quickstart, see link:{useEclipseUrl}[Use JBoss Developer Studio or Eclipse to Run the Quickstarts]. -For this quickstart, follow the special instructions to https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#deploy-and-undeploy-a-quickstart-containing-server-and-java-client-projects[Deploy and Undeploy a Quickstart Containing Server and Java Client Projects] +For this quickstart, follow the special instructions to link:{useEclipseDeployJavaClientDocUrl}[Deploy and Undeploy a Quickstart Containing Server and Java Client Projects] . To build all of the artifacts, right-click on the `{artifactId}` parent project, and choose `Run As` –> `Maven install`. . To deploy the service: @@ -113,7 +113,7 @@ EJB3Bean returning: ejbClient calling If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. ---- -mvn dependency:sources +$ mvn dependency:sources ---- NOTE: You will see the following informational messages. This is because the source files for these JARs are not available in the Maven repository. The `jaxws-ejb-service` source files are available in the `jaxws-ejb` project. diff --git a/jaxws-pojo/README.adoc b/jaxws-pojo/README.adoc index 9ccf291d6e..0f5fa354ac 100644 --- a/jaxws-pojo/README.adoc +++ b/jaxws-pojo/README.adoc @@ -22,31 +22,31 @@ The `jaxws-pojo` quickstart demonstrates the use of _JAX-WS_ in {productNameFull The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Use of {jbossHomeName} -In the following instructions, replace `{jbossHomeName}` with the actual path to your {productName} installation. The installation path is described in detail here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_{jbossHomeName}.md#use-of-eap_home-and-jboss_home-variables[Use of {jbossHomeName} and JBOSS_HOME Variables]. +In the following instructions, replace `__{jbossHomeName}__` with the actual path to your {productName} installation. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of {jbossHomeName} and JBOSS_HOME Variables]. == Start the Server -. Open a command prompt and navigate to the root of the {productName} directory. +. Open a terminal and navigate to the root of the {productName} directory. . The following shows the command line to start the server: [subs=normal] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +For Linux: $ __{jbossHomeName}__/bin/standalone.sh +For Windows: __{jbossHomeName}__\bin\standalone.bat ---- == Build and Deploy the Quickstart . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type this command to build and deploy the archive: ---- -mvn clean install wildfly:deploy +$ mvn clean install wildfly:deploy ---- . This will deploy `service/target/{artifactId}-service.war` to the running instance of the server. @@ -58,7 +58,7 @@ You can check that the Web Service is running and deployed correctly by accessin == Run the Client . Make sure the service deployed properly. -. Open a command prompt and navigate into the client directory of this quickstart. +. Open a terminal and navigate into the client directory of this quickstart. ---- cd client/ @@ -67,7 +67,7 @@ cd client/ . Type this command to run the client. ---- -mvn exec:java +$ mvn exec:java ---- . You should see the following response. @@ -79,18 +79,18 @@ JSEBean pojo: pojoClient calling == Undeploy the Archive . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . When you are finished testing, type this command to undeploy the archive: ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- == Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a {productName} server, and build and deploy a quickstart, see link:{useEclipseUrl}[Use JBoss Developer Studio or Eclipse to Run the Quickstarts]. -For this quickstart, follow the special instructions to https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#deploy-and-undeploy-a-quickstart-containing-server-and-java-client-projects[Deploy and Undeploy a Quickstart Containing Server and Java Client Projects] +For this quickstart, follow the special instructions to link:{useEclipseDeployJavaClientDocUrl}[Deploy and Undeploy a Quickstart Containing Server and Java Client Projects] . To build all of the artifacts, right-click on the `{artifactId}` parent project, and choose `Run As` –> `Maven install`. . To deploy the service: @@ -112,5 +112,5 @@ JSEBean pojo: pojoClient calling If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. ---- -mvn dependency:sources +$ mvn dependency:sources ---- \ No newline at end of file diff --git a/jaxws-retail/README.adoc b/jaxws-retail/README.adoc index adb99adfd3..b57bf0c4c6 100644 --- a/jaxws-retail/README.adoc +++ b/jaxws-retail/README.adoc @@ -22,31 +22,31 @@ The `jaxws-retail` quickstart demonstrates the use of _JAX-WS_ in {productNameFu The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Use of {jbossHomeName} -In the following instructions, replace `{jbossHomeName}` with the actual path to your {productName} installation. The installation path is described in detail here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_{jbossHomeName}.md#use-of-eap_home-and-jboss_home-variables[Use of {jbossHomeName} and JBOSS_HOME Variables]. +In the following instructions, replace `__{jbossHomeName}__` with the actual path to your {productName} installation. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of {jbossHomeName} and JBOSS_HOME Variables]. == Start the Server -. Open a command prompt and navigate to the root of the {productName} directory. +. Open a terminal and navigate to the root of the {productName} directory. . The following shows the command line to start the server: [subs=normal] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +For Linux: $ __{jbossHomeName}__/bin/standalone.sh +For Windows: __{jbossHomeName}__\bin\standalone.bat ---- == Build and Deploy the Quickstart . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type this command to build and deploy the archive: ---- -mvn clean install wildfly:deploy +$ mvn clean install wildfly:deploy ---- . This will deploy `service/target/{artifactId}-service.war` to the running instance of the server. @@ -77,7 +77,7 @@ You can check that the Web Service is running and deployed correctly by accessin . Make sure the service deployed properly. -. Open a command prompt and navigate into the client directory of this quickstart. +. Open a terminal and navigate into the client directory of this quickstart. ---- cd client/ @@ -86,7 +86,7 @@ cd client/ . Type this command to run the client. ---- -mvn exec:java +$ mvn exec:java ---- . You should see the following output in the client console. @@ -98,11 +98,11 @@ Jay Boss's discount is 10.00 == Undeploy the Archive . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . When you are finished testing, type this command to undeploy the archive: ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- == Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse @@ -142,7 +142,7 @@ This quickstart requires that you build the parent project, deploy the service, If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. ---- -mvn dependency:sources +$ mvn dependency:sources ---- NOTE: You will see the following informational messages. This is because the source files for this JAR are not available in the Maven repository. diff --git a/jsonp/README.adoc b/jsonp/README.adoc index 051a85c40f..19736b2a30 100644 --- a/jsonp/README.adoc +++ b/jsonp/README.adoc @@ -24,7 +24,7 @@ It shows how to use the JSON-P API to generate, parse, and consume JSON files. The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Start the Server @@ -33,8 +33,8 @@ All you need to build this project is {buildRequirements}. See https://github.co [subs=normal] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +For Linux: $ __{jbossHomeName}__/bin/standalone.sh +For Windows: __{jbossHomeName}__\bin\standalone.bat ---- == Build and Deploy the Quickstart @@ -44,7 +44,7 @@ For Windows: {jbossHomeName}\bin\standalone.bat . Type this command to build and deploy the archive: ---- -mvn clean package wildfly:deploy +$ mvn clean package wildfly:deploy ---- . This will deploy `target/{artifactId}` to the running instance of the server. @@ -64,11 +64,11 @@ Now, click on `Parse JSON String using Stream` button. The textarea below the bu == Undeploy the Archive . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . When you are finished testing, type this command to undeploy the archive: ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- == Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse @@ -80,5 +80,5 @@ You can also start the server and deploy the quickstarts or run the Arquillian t If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. ---- -mvn dependency:sources +$ mvn dependency:sources ---- \ No newline at end of file diff --git a/jta-crash-rec/README.adoc b/jta-crash-rec/README.adoc index 42c6e2e1b3..a9feceaf7a 100644 --- a/jta-crash-rec/README.adoc +++ b/jta-crash-rec/README.adoc @@ -31,25 +31,28 @@ In this example, you halt the {productName} server in the middle of an XA transa {productName} ships with H2, an in-memory database written in Java. In this example, we use H2 for the database. Although H2 XA support is not recommended for production systems, the example does illustrate the general steps you need to perform for any datasource vendor. This example provides its own H2 XA datasource configuration. It is defined in the `jta-crash-rec-ds.xml` file in the WEB-INF folder of the WAR archive. -_Note: This quickstart uses the H2 database included with {productNameFull} {productVersion}. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ - -_Note: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in {productName} and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/[Configuration Guide] for {productNameFull}._ +//************************************************* +// Add notes about use in a production environment. +//************************************************* +:uses-h2: +:uses-ds-xml: +include::../development-shortcuts.adoc[leveloffset=+1] == System Requirements The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Use of {jbossHomeName} -In the following instructions, replace `{jbossHomeName}` with the actual path to your {productName} installation. The installation path is described in detail here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_{jbossHomeName}.md#use-of-eap_home-and-jboss_home-variables[Use of {jbossHomeName} and JBOSS_HOME Variables]. +In the following instructions, replace `__{jbossHomeName}__` with the actual path to your {productName} installation. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of {jbossHomeName} and JBOSS_HOME Variables]. == Download and Configure Byteman -This quickstart uses _Byteman_ to help demonstrate crash recovery. You can find more information about _Byteman_ here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_BYTEMAN.md#configure-byteman-for-use-with-the-quickstarts[Configure Byteman for Use with the Quickstarts] +This quickstart uses _Byteman_ to help demonstrate crash recovery. You can find more information about _Byteman_ here: link:{configureBytemanQuickstartsDocUrl}[Configure Byteman for Use with the Quickstarts] -Follow the instructions here to download and configure _Byteman_: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_BYTEMAN.md#download-and-configure-byteman[Download and Configure Byteman] +Follow the instructions here to download and configure _Byteman_: link:{configureBytemanDownloadDocUrl}[Download and Configure Byteman] == Configure the Server @@ -59,23 +62,23 @@ _NOTE_: The _Byteman_ scripts only work in JTA mode. They do not work in JTS mod Start the {productName} Server with the Full Profile -. Open a command prompt and navigate to the root of the {productName} directory. +. Open a terminal and navigate to the root of the {productName} directory. . The following shows the command line to start the {productName} server with the full profile: [subs=normal] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -c standalone-full.xml -For Windows: {jbossHomeName}\bin\standalone.bat -c standalone-full.xml +For Linux: $ __{jbossHomeName}__/bin/standalone.sh -c standalone-full.xml +For Windows: __{jbossHomeName}__\bin\standalone.bat -c standalone-full.xml ---- == Build and Deploy the Quickstart . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type this command to build and deploy the archive: ---- -mvn clean install wildfly:deploy +$ mvn clean install wildfly:deploy ---- . This will deploy `target/{artifactId}.war` to the running instance of the server. @@ -98,8 +101,8 @@ The application will be running at the following URL: http://localhost:8080/{art . To demonstrate XA recovery, you must enable the Byteman tool to terminate the application server while _phase 2_ is running as follows: ** Stop the {productName} server. -** Follow the instructions here to clear the transaction objectstore remaining from any previous tests: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_BYTEMAN.md#clear-the-transaction-objectstore[Clear the Transaction ObjectStore] -** The following line of text must be appended to the server configuration file using the instructions located here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_BYTEMAN.md#use-byteman-to-halt-the-application[Use Byteman to Halt the Application] +** Follow the instructions here to clear the transaction objectstore remaining from any previous tests: link:{configureBytemanClearDocUrl}[Clear the Transaction ObjectStore] +** The following line of text must be appended to the server configuration file using the instructions located here: link:{configureBytemanHaltDocUrl}[Use Byteman to Halt the Application] For Linux: @@ -130,9 +133,9 @@ Password: sa select * from kvpair ---- -** Log out of the H2 console and be sure to close out the command prompt. H2 is limited to one connection and the application will need it from this point forward. +** Log out of the H2 console and be sure to close out the terminal. H2 is limited to one connection and the application will need it from this point forward. ** If you are using the default file based transaction logging store, there will be a record in the file system corresponding to the pending transaction. -*** Open a command prompt and navigate to the `{jbossHomeName}` directory +*** Open a terminal and navigate to the `__{jbossHomeName}__` directory *** List the contents of the following directory: + [subs="+quotes,attributes+"] @@ -148,13 +151,13 @@ ls {jbossHomeName}/standalone/data/tx-object-store/ShadowNoFileLockStore/default *** After recovery, log records are normally deleted automatically. However, logs may remain in the case where the Transaction Manager (TM) commit request was received and acted upon by a resource, but the TM crashed before it had time to clean up the logs of that resource. . To observe XA recovery -** Stop the H2 console and exit the command prompt to close the database connections. Otherwise, you may see messages like the following when you start your server: +** Stop the H2 console and exit the terminal to close the database connections. Otherwise, you may see messages like the following when you start your server: + ---- Database may be already in use: "Locked by another process" ---- -** https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_BYTEMAN.md#disable-the-byteman-script[Disable the Byteman script] by restoring the backup server configuration file. +** link:{configureBytemanDisableDocUrl}[Disable the Byteman script] by restoring the backup server configuration file. ** <> as instructed above. ** Load the web interface to the application ** By the time the {productName} server is ready, the transaction should have recovered. @@ -173,7 +176,7 @@ WARN [com.arjuna.ats.jta] (Periodic Recovery) ARJUNA016037: Could not find new WARN [com.arjuna.ats.jta] (Periodic Recovery) ARJUNA016038: No XAResource to recover < formatId=131077, gtrid_length=29, bqual_length=36, tx_uid=0:ffff7f000001:1040a11d:534ede43:1c, node_name=1, branch_uid=0:ffff7f000001:1040a11d:534ede43:20, subordinatenodename=null, eis_name=java:jboss/datasources/JTACrashRecQuickstartDS > ---- -. Do NOT forget to https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_BYTEMAN.md#disable-the-byteman-script[Disable the Byteman script] by restoring the backup server configuration file. The Byteman rule must be removed to ensure that your application server will be able to commit 2PC transactions! +. Do NOT forget to link:{configureBytemanDisableDocUrl}[Disable the Byteman script] by restoring the backup server configuration file. The Byteman rule must be removed to ensure that your application server will be able to commit 2PC transactions! == Server Log: Expected Warnings and Errors @@ -187,11 +190,11 @@ HHH000431: Unable to determine H2 database version, certain features may not wor == Undeploy the Archive . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . When you are finished testing, type this command to undeploy the archive: ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- == Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse @@ -205,5 +208,5 @@ NOTE: Within JBoss Developer Studio, be sure to define a server runtime environm If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. ---- - mvn dependency:sources ----- \ No newline at end of file + $ mvn dependency:sources +---- diff --git a/jts-distributed-crash-rec/README.adoc b/jts-distributed-crash-rec/README.adoc index 8b8b4cc0c6..237582a51c 100644 --- a/jts-distributed-crash-rec/README.adoc +++ b/jts-distributed-crash-rec/README.adoc @@ -10,7 +10,7 @@ include::../attributes.adoc[] :level: Advanced :technologies: JTS, Crash Recovery :source: {githubRepoUrl} -:prerequisites: jts +:prerequisites: link:jts/README{outfilesuffix}[jts] [abstract] The `jts-distributed-crash-rec` quickstart uses JTS and Byteman to demonstrate distributed crash recovery across multiple application servers. @@ -38,13 +38,13 @@ As an overview, the sequence of events to expect: The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Download and Configure Byteman -This quickstart uses _Byteman_ to help demonstrate crash recovery. You can find more information about _Byteman_ here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_BYTEMAN.md#configure-byteman-for-use-with-the-quickstarts[Configure Byteman for Use with the Quickstarts] +This quickstart uses _Byteman_ to help demonstrate crash recovery. You can find more information about _Byteman_ here: link:{configureBytemanQuickstartsDocUrl}[Configure Byteman for Use with the Quickstarts] -Follow the instructions here to download and configure _Byteman_: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_BYTEMAN.md#download-and-configure-byteman[Download and Configure Byteman] +Follow the instructions here to download and configure _Byteman_: link:{configureBytemanDownloadDocUrl}[Download and Configure Byteman] == Prerequisites @@ -53,13 +53,13 @@ Developers should be familiar with the concepts introduced in the following quic * _cmt_ * _jts_ -IMPORTANT: This quickstart depends on the deployment of the `jts` quickstart for its test. Before running this quickstart, see the link:../jts/README.md[jts README] file for details on how to deploy it. +IMPORTANT: This quickstart depends on the deployment of the `jts` quickstart for its test. Before running this quickstart, see the link:../jts/README.adoc[jts README] file for details on how to deploy it. You can verify the deployment of the `jts` quickstart by accessing the following URL: http://localhost:8080/jts-application-component-1/. == Use of {jbossHomeName} -In the following instructions, replace `{jbossHomeName}` with the actual path to your {productName} installation. The installation path is described in detail here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_{jbossHomeName}.md#use-of-eap_home-and-jboss_home-variables[Use of {jbossHomeName} and JBOSS_HOME Variables]. +In the following instructions, replace `__{jbossHomeName}__` with the actual path to your {productName} installation. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of {jbossHomeName} and JBOSS_HOME Variables]. == Test the Application @@ -67,18 +67,18 @@ NOTE: This quickstart README file uses the following replaceable values. When yo [subs="+quotes,attributes+"] ---- -`{jbossHomeName}` denotes the path to the original {productName} installation. +`__{jbossHomeName}__` denotes the path to the original {productName} installation. `{jbossHomeName}_1` denotes the path to the modified {productName} server 1 configuration. `{jbossHomeName}_2` denotes the path to the modified {productName} server 2 configuration. ---- -. If you have not yet done so, configure the two application servers and deploy the `jts` quickstart. Follow the instructions in the link:../jts/README.md[jts README] file. +. If you have not yet done so, configure the two application servers and deploy the `jts` quickstart. Follow the instructions in the link:../jts/README.adoc[jts README] file. . Configure _Byteman_ to halt {productName} server 1 ** Stop both {productName} servers. -** Follow the instructions here to clear the transaction objectstore remaining from any previous tests: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_BYTEMAN.md#clear-the-transaction-objectstore[Clear the Transaction ObjectStore] -** The following 2 lines of text must be appended to the server configuration file for server 1 only using the instructions located here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_BYTEMAN.md#use-byteman-to-halt-the-application[Use Byteman to Halt the Application] +** Follow the instructions here to clear the transaction objectstore remaining from any previous tests: link:{configureBytemanClearDocUrl}[Clear the Transaction ObjectStore] +** The following 2 lines of text must be appended to the server configuration file for server 1 only using the instructions located here: link:{configureBytemanHaltDocUrl}[Use Byteman to Halt the Application] For Linux: @@ -110,7 +110,7 @@ INFO [stdout] (default task-2) rule.debug{Fail 2PC after prepare} : !!!killing tree {jbossHomeName}_1/standalone/data/tx-object-store ---- -. https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_BYTEMAN.md#disable-the-byteman-script[Disable the Byteman script] by restoring the backup configuration file for server 1. +. link:{configureBytemanDisableDocUrl}[Disable the Byteman script] by restoring the backup configuration file for server 1. . Follow the steps above to restart server 1 and wait for recovery to complete. @@ -118,4 +118,4 @@ _IMPORTANT: By default, the recovery process checks the transactional state ever . After recovery is complete, access the application URL http://localhost:8080/jts-application-component-1/customers.jsf. The user you created should now appear in the list. -. Do NOT forget to https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_BYTEMAN.md#disable-the-byteman-script[Disable the Byteman script] by restoring the backup server configuration file. The Byteman rule must be removed to ensure that your application server will be able to commit 2PC transactions! \ No newline at end of file +. Do NOT forget to link:{configureBytemanDisableDocUrl}[Disable the Byteman script] by restoring the backup server configuration file. The Byteman rule must be removed to ensure that your application server will be able to commit 2PC transactions! diff --git a/jts/README.adoc b/jts/README.adoc index 11f8e0a9e1..9bfbb84cc7 100644 --- a/jts/README.adoc +++ b/jts/README.adoc @@ -10,7 +10,7 @@ include::../attributes.adoc[] :level: Intermediate :technologies: JTS, EJB, JMS :source: {githubRepoUrl} -:prerequisites: cmt +:prerequisites: link:cmt/README{outfilesuffix}[cmt] [abstract] The `jts` quickstart shows how to use JTS to perform distributed transactions across multiple containers, fulfilling the properties of an ACID transaction. @@ -28,7 +28,7 @@ ACID is a set of 4 properties that guarantee the resources are processed in the The example uses Java Transaction Service (JTS) to propagate a transaction context across two Container-Managed Transaction (CMT) EJBs that, although deployed in separate servers, participate in the same transaction. In this example, one server processes the Customer and Account data and the other server processes the Invoice data. -The code base is essentially the same as the link:../cmt/README.md[cmt] quickstart, however in this case the `InvoiceManager` has been separated to a different deployment archive to demonstrate the usage of JTS. You can see the changes in the +The code base is essentially the same as the link:../cmt/README.adoc[cmt] quickstart, however in this case the `InvoiceManager` has been separated to a different deployment archive to demonstrate the usage of JTS. You can see the changes in the following ways: * `cmt/src/main/java/org/jboss/as/quickstarts/cmt/ejb/InvoiceManagerEJB.java` has been moved to `application-component-2/src/main/java/org/jboss/as/quickstarts/cmt/jts/ejb/InvoiceManagerEJB` @@ -42,19 +42,23 @@ A simple MDB has been provided that prints out the messages sent but this is not Also, while the `cmt` quickstart uses the Java EE container default datasource, which is not distributed, this quickstart instead uses an external PostgreSQL database. -After you complete this quickstart, you are invited to run through the link:../jts-distributed-crash-rec/README.md[jts-distributed-crash-rec] quickstart. The crash recovery quickstart builds upon this quickstart by demonstrating the fault tolerance of {productNameFull}. +After you complete this quickstart, you are invited to run through the link:../jts-distributed-crash-rec/README.adoc[jts-distributed-crash-rec] quickstart. The crash recovery quickstart builds upon this quickstart by demonstrating the fault tolerance of {productNameFull}. -_Note: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in {productName} and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/[Configuration Guide] for {productNameFull}._ +//************************************************* +// Add notes about use in a production environment. +//************************************************* +:uses-ds-xml: +include::../development-shortcuts.adoc[leveloffset=+1] == System Requirements The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Use of {jbossHomeName} -In the following instructions, replace `{jbossHomeName}` with the actual path to your {productName} installation. The installation path is described in detail here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_{jbossHomeName}.md#use-of-eap_home-and-jboss_home-variables[Use of {jbossHomeName} and JBOSS_HOME Variables]. +In the following instructions, replace `__{jbossHomeName}__` with the actual path to your {productName} installation. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of {jbossHomeName} and JBOSS_HOME Variables]. == Prerequisites @@ -66,11 +70,11 @@ This quickstart requires the configuration of two servers. The first server must This quickstart requires the PostgreSQL database. -Instructions to install and configure PostgreSQL can be found here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_POSTGRESQL_EAP7.md#download-and-install-postgresql[Download and Install PostgreSQL] +Instructions to install and configure PostgreSQL can be found here: link:{configurePostgresDownloadDocUrl}[Download and Install PostgreSQL] _Note_: For the purpose of this quickstart, replace the word `QUICKSTART_DATABASE_NAME` with `jts-quickstart-database` in the PostgreSQL instructions. -Be sure to https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_POSTGRESQL_EAP7.md#create-a-database-user[Create a Database User] for the PostgeSQL database. +Be sure to link:{configurePostgresCreateUserDocUrl}[Create a Database User] for the PostgeSQL database. When you have completed these steps, be sure to start the PostgreSQL database. Unless you have set up the database to automatically start as a service, you must repeat the instructions to start the database server for your operating system every time you reboot your machine. @@ -84,7 +88,7 @@ Since both application servers must be configured in the same way, you must conf NOTE: This quickstart README file use the following replaceable values. When you encounter these values in a README file, be sure to replace them with the actual path to the correct {productName} server. -* `{jbossHomeName}` denotes the path to the original {productName} installation. +* `__{jbossHomeName}__` denotes the path to the original {productName} installation. * `{jbossHomeName}_1` denotes the path to the modified {productName} server 1 configuration. * `{jbossHomeName}_2` denotes the path to the modified {productName} server 2 configuration. @@ -100,16 +104,16 @@ You configure JTS transactions by running JBoss CLI commands. For your convenien + [subs="+quotes,attributes+"] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_1 -For Windows: {jbossHomeName}\bin\standalone.bat -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_1 +For Linux: $ __{jbossHomeName}__/bin/standalone.sh -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_1 +For Windows: __{jbossHomeName}__\bin\standalone.bat -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_1 ---- . Review the `configure-jts-transactions.cli` file in the root of this quickstart directory. This script configures the server to use jts transaction processing. -. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing {jbossHomeName} with the path to your server: +. 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: + ---- -For Linux: {jbossHomeName}/bin/jboss-cli.sh --connect --file=configure-jts-transactions.cli -For Windows: {jbossHomeName}\bin\jboss-cli.bat --connect --file=configure-jts-transactions.cli +For Linux: $ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=configure-jts-transactions.cli +For Windows: __{jbossHomeName}__\bin\jboss-cli.bat --connect --file=configure-jts-transactions.cli ---- . Stop the {productName} server. @@ -123,7 +127,7 @@ After stopping the server, open the `{jbossHomeName}/standalone/configuration/st . The orb initializers `transactions` attribute is changed from `spec` to `full` in the `iiop-openjdk` subsystem to enable JTS. + -[source, xml] +[source,xml,options="nowrap"] ---- @@ -133,7 +137,7 @@ After stopping the server, open the `{jbossHomeName}/standalone/configuration/st . An empty `<jts/>` element is added to the end of the `transactions` subsystem to enable JTS. + -[source, xml] +[source,xml,options="nowrap"] ---- @@ -157,8 +161,8 @@ Make a copy of this {productName} directory structure to use for the second serv Application server 1 must be now configured to use the PostgreSQL database created previously in the <> section. . Be sure to start the PostgreSQL database. Unless you have set up the database to automatically start as a service, you must repeat the instructions "Start the database server" for your operating system every time you reboot your machine. -. Follow the instructions to https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_POSTGRESQL_EAP7.md#add-the-postgresql-module-to-the-red-hat-jboss-enterprise-application-platform-server[Add the PostgreSQL Module to the {productName} Server] to the server 1 install only. -. Follow the instructions to https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_POSTGRESQL_EAP7.md#configure-the-postgresql-driver-in-the-red-hat-jboss-enterprise-application-platform-server[Configure the PostgreSQL Driver in the {productName} Server] for the server 1 configuration. Be sure to pass the `-Djboss.tx.node.id=UNIQUE_NODE_ID_1` on the command line when you start the first server to configure PostgreSQL. +. Follow the instructions to link:{configurePostgresAddModuleDocUrl}[Add the PostgreSQL Module to the {productName} Server] to the server 1 install only. +. Follow the instructions to link:{configurePostgresDriverDocUrl}[Configure the PostgreSQL Driver in the {ProductName} Server] for the server 1 configuration. Be sure to pass the `-Djboss.tx.node.id=UNIQUE_NODE_ID_1` on the command line when you start the first server to configure PostgreSQL. == Start the Servers @@ -185,11 +189,11 @@ Server 2: {jbossHomeName}_2\bin\standalone.bat -c standalone-full.xml -Djboss.tx Since this quickstart builds two separate components, you can not use the standard _Build and Deploy_ commands used by most of the other quickstarts. You must follow these steps to build, deploy, and run this quickstart. . Make sure you have started the {productName} server with the PostgreSQL driver -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type this command to build and deploy the archive: ---- -mvn clean install wildfly:deploy +$ mvn clean install wildfly:deploy ---- . This will deploy `{artifactId}-application-component-1.war` and `{artifactId}-application-component-2.jar` to the running instance of the server. @@ -225,11 +229,11 @@ WFLYJCA0091: -ds.xml file deployments are deprecated. Support may be removed in == Undeploy the Archive . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . When you are finished testing, type this command to undeploy the archive: ---- -mvn package wildfly:undeploy +$ mvn package wildfly:undeploy ---- == Remove the JTS Configuration From the Server @@ -248,7 +252,7 @@ For Linux: {jbossHomeName}_1/bin/standalone.sh -c standalone-full.xml -Djboss. For Windows: {jbossHomeName}_1\bin\standalone.bat -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_1 ---- -. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing {jbossHomeName} with the path to your server: +. 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: + [subs="+quotes,attributes+"] ---- @@ -266,7 +270,7 @@ For Linux: {jbossHomeName}_1/bin/standalone.sh -c standalone-full.xml -Djboss.t For Windows: {jbossHomeName}_1\bin\standalone.bat -c standalone-full.xml -Djboss.tx.node.id=UNIQUE_NODE_ID_1 ---- -. To start the JBoss CLI tool, open a new command prompt, navigate to the {jbossHomeName} directory, and type the following: +. To start the JBoss CLI tool, open a new terminal, navigate to the {jbossHomeName} directory, and type the following: + [subs="+quotes,attributes+"] ---- @@ -290,7 +294,7 @@ For Windows: {jbossHomeName}_1\bin\jboss-cli.bat --connect ** Find the `orb` subsystem and change the configuration back to its original state. + -[source, xml] +[source,xml,options="nowrap"] ---- @@ -300,7 +304,7 @@ For Windows: {jbossHomeName}_1\bin\jboss-cli.bat --connect ** Find the `transaction` subsystem and remove the `node-identifier` attribute from the `core-environment` element. Also remove the `<jts/>` element. + -[source, xml] +[source,xml,options="nowrap"] ---- @@ -310,4 +314,4 @@ For Windows: {jbossHomeName}_1\bin\jboss-cli.bat --connect ----- \ No newline at end of file +---- diff --git a/kitchensink-angularjs/README.adoc b/kitchensink-angularjs/README.adoc index 7605f627f9..7dc9d913ac 100644 --- a/kitchensink-angularjs/README.adoc +++ b/kitchensink-angularjs/README.adoc @@ -24,7 +24,7 @@ This project is setup to allow you to create a compliant Java EE 7 application u The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Start the Server @@ -43,7 +43,7 @@ For Windows: bin\standalone.bat . Type this command to build and deploy the archive: ---- -mvn clean package wildfly:deploy +$ mvn clean package wildfly:deploy ---- . This will deploy `target/{artifactId}.war` to the running instance of the server. @@ -59,7 +59,7 @@ The application will be running at the following URL: http://localhost:8080/{art . When you are finished testing, type this command to undeploy the archive: ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- == Run the Arquillian Tests @@ -71,10 +71,10 @@ This quickstart provides Arquillian tests. By default, these tests are configure . Type the following command to run the test goal with the following profile activated: ---- -mvn clean verify -Parq-remote +$ mvn clean verify -Parq-remote ---- -You can also let Arquillian manage the {productName} server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests[Run the Arquillian Tests]. +You can also let Arquillian manage the {productName} server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see link:{arquillianTestsDocUrl}[Run the Arquillian Tests]. == Run the Arquillian Functional Tests @@ -87,7 +87,7 @@ To run these tests, you must build the main project as described above. . Build the quickstart WAR using the following command: ---- -mvn clean package +$ mvn clean package ---- . Navigate to the `functional-tests/` directory in this quickstart. @@ -95,13 +95,13 @@ mvn clean package . If you have a running instance of the {productName} server, as described above, run the remote tests by typing the following command: ---- -mvn clean verify -Parq-remote +$ mvn clean verify -Parq-remote ---- . If you prefer to run the functional tests using managed instance of the {productName} server, meaning the tests will start the server for you, type fhe following command: ---- -mvn clean verify -Parq-managed +$ mvn clean verify -Parq-managed ---- == Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse @@ -128,6 +128,6 @@ HTML Problem: Undefined attribute name (ng-view) If you want to debug the source code or look at the Javadocs of any library in the project, run either of the following commands to pull them into your local repository. The IDE should then detect them. ---- - mvn dependency:sources - mvn dependency:resolve -Dclassifier=javadoc + $ mvn dependency:sources + $ mvn dependency:resolve -Dclassifier=javadoc ---- \ No newline at end of file diff --git a/kitchensink-ear/README.adoc b/kitchensink-ear/README.adoc index 88d7dcf3b2..2de28c8a88 100644 --- a/kitchensink-ear/README.adoc +++ b/kitchensink-ear/README.adoc @@ -18,41 +18,44 @@ The `kitchensink-ear` quickstart demonstrates web-enabled database application, The `kitchensink-ear` quickstart is a deployable Maven 3 project to help you get your foot in the door developing with Java EE 7 on {productNameFull}. -It demonstrates how to create a compliant Java EE 7 application using JSF, CDI, JAX-RS, EJB, JPA, and Bean Validation. It includes a persistence unit and some sample persistence and transaction code to introduce you to database access in enterprise Java. It is based on the link:../kitchensink/README.md[kitchensink] quickstart but is packaged as an EAR archive. +It demonstrates how to create a compliant Java EE 7 application using JSF, CDI, JAX-RS, EJB, JPA, and Bean Validation. It includes a persistence unit and some sample persistence and transaction code to introduce you to database access in enterprise Java. It is based on the link:../kitchensink/README.adoc[kitchensink] quickstart but is packaged as an EAR archive. -_Note: This quickstart uses the H2 database included with {productNameFull} {productVersion}. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ - -_Note: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in {productName} and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/[Configuration Guide] for {productNameFull}._ +//************************************************* +// Add notes about use in a production environment. +//************************************************* +:uses-h2: +:uses-ds-xml: +include::../development-shortcuts.adoc[leveloffset=+1] == System Requirements The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Use of {jbossHomeName} -In the following instructions, replace `{jbossHomeName}` with the actual path to your {productName} installation. The installation path is described in detail here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_{jbossHomeName}.md#use-of-eap_home-and-jboss_home-variables[Use of {jbossHomeName} and JBOSS_HOME Variables]. +In the following instructions, replace `__{jbossHomeName}__` with the actual path to your {productName} installation. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of {jbossHomeName} and JBOSS_HOME Variables]. == Start the Server -. Open a command prompt and navigate to the root of the {productName} directory. +. Open a terminal and navigate to the root of the {productName} directory. . The following shows the command line to start the server: [subs=normal] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +For Linux: $ __{jbossHomeName}__/bin/standalone.sh +For Windows: __{jbossHomeName}__\bin\standalone.bat ---- == Build and Deploy the Quickstart . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type this command to build and deploy the archive: ---- -mvn clean install wildfly:deploy +$ mvn clean install wildfly:deploy ---- . This will deploy `ear/target/{artifactId}.ear` to the running instance of the server. @@ -73,11 +76,11 @@ Registering _the_name_you_entered_ == Undeploy the Archive . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . When you are finished testing, type this command to undeploy the archive: ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- == Run the Arquillian Tests @@ -85,14 +88,14 @@ mvn wildfly:undeploy This quickstart provides Arquillian tests. By default, these tests are configured to be skipped as Arquillian tests require the use of a container. . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type the following command to run the test goal with the following profile activated: ---- -mvn clean verify -Parq-remote +$ mvn clean verify -Parq-remote ---- -You can also let Arquillian manage the {productName} server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests[Run the Arquillian Tests]. +You can also let Arquillian manage the {productName} server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see link:{arquillianTestsDocUrl}[Run the Arquillian Tests]. == Investigate the Console Output @@ -132,7 +135,7 @@ HHH000431: Unable to determine H2 database version, certain features may not wor You can also start the server and deploy the quickstarts or run the Arquillian tests from Eclipse using JBoss tools. For general information about how to import a quickstart, add a {productName} server, and build and deploy a quickstart, see link:{useEclipseUrl}[Use JBoss Developer Studio or Eclipse to Run the Quickstarts]. -For this quickstart, follow the special instructions to build https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_JBDS.md#deploy-and-undeploy-a-quickstart-ear-project[Quickstarts Containing an EAR] +For this quickstart, follow the special instructions to build link:link:{useEclipseDeployEARDocUrl}[Quickstarts Containing an EAR]. . Right-click on the `{artifactId}-ear` subproject, and choose `Run As` –> `Run on Server`. . Choose the server and click `Finish`. @@ -144,5 +147,5 @@ For this quickstart, follow the special instructions to build https://github.com If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. ---- - mvn dependency:sources ----- \ No newline at end of file + $ mvn dependency:sources +---- diff --git a/kitchensink-html5-mobile/README.adoc b/kitchensink-html5-mobile/README.adoc index c515ae64ad..2fbb6d7f38 100644 --- a/kitchensink-html5-mobile/README.adoc +++ b/kitchensink-html5-mobile/README.adoc @@ -26,7 +26,7 @@ What is a modern web application without mobile web support? This application al The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. An HTML5 compatible browser such as Chrome, Safari 5+, Firefox 5+, or IE 9+ are required. and note that some behaviors will vary slightly (ex. validations) based on browser support, especially IE 9. @@ -41,8 +41,8 @@ With the prerequisites out of the way, you are ready to build and deploy. [subs=normal] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +For Linux: $ __{jbossHomeName}__/bin/standalone.sh +For Windows: __{jbossHomeName}__\bin\standalone.bat ---- Note: Adding `-b 0.0.0.0` to the above commands will allow external clients, such as phones, tablets, and desktops, connect through your local network. @@ -51,8 +51,8 @@ For example [subs="+quotes,attributes+"] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -b 0.0.0.0 -For Windows: {jbossHomeName}\bin\standalone.bat -b 0.0.0.0 +For Linux: $ __{jbossHomeName}__/bin/standalone.sh -b 0.0.0.0 +For Windows: __{jbossHomeName}__\bin\standalone.bat -b 0.0.0.0 ---- == Build and Deploy the Quickstart @@ -62,7 +62,7 @@ For Windows: {jbossHomeName}\bin\standalone.bat -b 0.0.0.0 . Type this command to build and deploy the archive: ---- -mvn clean wildfly:deploy +$ mvn clean wildfly:deploy ---- . This deploys `target/{artifactId}.war` to the running instance of the server. @@ -78,7 +78,7 @@ Access the running client application in a browser at the following URL: http:// . When you are finished testing, type this command to undeploy the archive: ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- == Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse @@ -100,14 +100,14 @@ For example: ---- #No Tests -mvn clean wildfly:deploy -Pminify +$ mvn clean wildfly:deploy -Pminify ---- OR ---- #With Tests -mvn clean verify wildfly:deploy -Pminify,arq-remote +$ mvn clean verify wildfly:deploy -Pminify,arq-remote ---- == Run the Arquillian Tests @@ -117,7 +117,7 @@ By default, tests are configured to be skipped. The reason is that the sample te To run the test in JBoss, first start the container instance. Then, run the test goal with the following profile activated: ---- -mvn clean verify -Parq-remote +$ mvn clean verify -Parq-remote ---- == Run the QUnit tests @@ -143,6 +143,6 @@ You can also start the server and deploy the quickstarts or run the Arquillian t If you want to be able to debug into the source code or look at the Javadocs of any library in the project, you can run either of the following two commands to pull them into your local repository. The IDE should then detect them. ---- -mvn dependency:sources -mvn dependency:resolve -Dclassifier=javadoc +$ mvn dependency:sources +$ mvn dependency:resolve -Dclassifier=javadoc ---- \ No newline at end of file diff --git a/kitchensink-jsp/README.adoc b/kitchensink-jsp/README.adoc index 4b79c6556c..4e8ff8b133 100644 --- a/kitchensink-jsp/README.adoc +++ b/kitchensink-jsp/README.adoc @@ -18,41 +18,44 @@ The `kitchensink-jsp` quickstart demonstrates how to use JSP, JSTL, CDI, EJB, JP The `kitchensink-jsp` quickstart is a deployable Maven 3 project and demonstrates how to create a compliant Java EE 7 application using JSP 2.0, EL 2.0, JSTL 1.2, CDI, EJB, JPA, and Bean Validation in {productNameFull}. -This example is based on the link:../kitchensink/README.md[kitchensink] quickstart, but recreates the presentation tier using JSP and JSTL instead of JSF features. It reuses all other components from the Member Registration template. It also reuses the persistence unit and some sample persistence and transaction code to help you with database access in enterprise Java. +This example is based on the link:../kitchensink/README.adoc[kitchensink] quickstart, but recreates the presentation tier using JSP and JSTL instead of JSF features. It reuses all other components from the Member Registration template. It also reuses the persistence unit and some sample persistence and transaction code to help you with database access in enterprise Java. -_Note: This quickstart uses the H2 database included with {productNameFull} {productVersion}. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ - -_Note: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in {productName} and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/[Configuration Guide] for {productNameFull}._ +//************************************************* +// Add notes about use in a production environment. +//************************************************* +:uses-h2: +:uses-ds-xml: +include::../development-shortcuts.adoc[leveloffset=+1] == System Requirements The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Use of {jbossHomeName} -In the following instructions, replace `{jbossHomeName}` with the actual path to your {productName} installation. The installation path is described in detail here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_{jbossHomeName}.md#use-of-eap_home-and-jboss_home-variables[Use of {jbossHomeName} and JBOSS_HOME Variables]. +In the following instructions, replace `__{jbossHomeName}__` with the actual path to your {productName} installation. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of {jbossHomeName} and JBOSS_HOME Variables]. == Start the Server -. Open a command prompt and navigate to the root of the {productName} directory. +. Open a terminal and navigate to the root of the {productName} directory. . The following shows the command line to start the server: [subs=normal] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +For Linux: $ __{jbossHomeName}__/bin/standalone.sh +For Windows: __{jbossHomeName}__\bin\standalone.bat ---- == Build and Deploy the Quickstart . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type this command to build and deploy the archive: ---- -mvn clean install wildfly:deploy +$ mvn clean install wildfly:deploy ---- . This will deploy `target/{artifactId}.war` to the running instance of the server. @@ -74,11 +77,11 @@ HHH000431: Unable to determine H2 database version, certain features may not wor == Undeploy the Archive . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . When you are finished testing, type this command to undeploy the archive: ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- == Run the Arquillian Tests @@ -86,14 +89,14 @@ mvn wildfly:undeploy This quickstart provides Arquillian tests. By default, these tests are configured to be skipped as Arquillian tests require the use of a container. . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type the following command to run the test goal with the following profile activated: ---- -mvn clean verify -Parq-remote +$ mvn clean verify -Parq-remote ---- -You can also let Arquillian manage the {productName} server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests[Run the Arquillian Tests]. +You can also let Arquillian manage the {productName} server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see link:{arquillianTestsDocUrl}[Run the Arquillian Tests]. == Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse @@ -113,5 +116,5 @@ You can ignore this warning as it does not impact building or deploying the quic If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. ---- - mvn dependency:sources ----- \ No newline at end of file + $ mvn dependency:sources +---- diff --git a/kitchensink-ml/README.adoc b/kitchensink-ml/README.adoc index 69089ff711..9717d894fd 100644 --- a/kitchensink-ml/README.adoc +++ b/kitchensink-ml/README.adoc @@ -20,11 +20,14 @@ The `kitchensink-ml` quickstart is a deployable Maven 3 project to help you get It demonstrates how to create a _localized_ Java EE 7 compliant application using JSF, CDI, JAX-RS, EJB, JPA, and Bean Validation. A localized application is one that supports multiple languages. That is what the _-ml_ suffix denotes in the quickstart name _kitchensink-ml_. This quickstart also includes a persistence unit and some sample persistence and transaction code to introduce you to database access in enterprise Java. -This quickstart uses the link:../kitchensink/README.md[kitchensink] quickstart as its starting point. It has been enhanced to provide localization of labels and messages. A user sets the preferred language choice in the browser and, if the application supports that language, the application web page is rendered in that language. For demonstration purposes, this quickstart has been tranlated into French(fr) and Spanish (es) using http://translate.google.com, so the translations may not be ideal. +This quickstart uses the link:../kitchensink/README.adoc[kitchensink] quickstart as its starting point. It has been enhanced to provide localization of labels and messages. A user sets the preferred language choice in the browser and, if the application supports that language, the application web page is rendered in that language. For demonstration purposes, this quickstart has been tranlated into French(fr) and Spanish (es) using http://translate.google.com, so the translations may not be ideal. -_Note: This quickstart uses the H2 database included with {productNameFull} {productVersion}. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ - -_Note: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in {productName} and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/[Configuration Guide] for {productNameFull}._ +//************************************************* +// Add notes about use in a production environment. +//************************************************* +:uses-h2: +:uses-ds-xml: +include::../development-shortcuts.adoc[leveloffset=+1] === Localization Code Changes @@ -65,7 +68,7 @@ The following changes were made to the quickstart to enable it to use the browse @NotNull @Size(min = 1, max = 25) @Pattern(regexp = "[A-Za-z ]*", message = "{name_validation_message}") - private String name; + private String name; ---- * The `src/main/java/org/jboss/as/quickstarts/kitchensink/util/KitchensinkMessages.java` file was created, which defines default messages in English. The `jboss-logging-processor` will automatically generate an implementation for you, which can be accesssed via the `MESSAGES` static variable. @@ -112,31 +115,31 @@ How you set your browser preferred locale depends on the browser and version you The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Use of {jbossHomeName} -In the following instructions, replace `{jbossHomeName}` with the actual path to your {productName} installation. The installation path is described in detail here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_{jbossHomeName}.md#use-of-eap_home-and-jboss_home-variables[Use of {jbossHomeName} and JBOSS_HOME Variables]. +In the following instructions, replace `__{jbossHomeName}__` with the actual path to your {productName} installation. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of {jbossHomeName} and JBOSS_HOME Variables]. == Start the Server -. Open a command prompt and navigate to the root of the {productName} directory. +. Open a terminal and navigate to the root of the {productName} directory. . The following shows the command line to start the server: [subs=normal] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +For Linux: $ __{jbossHomeName}__/bin/standalone.sh +For Windows: __{jbossHomeName}__\bin\standalone.bat ---- == Build and Deploy the Quickstart . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type this command to build and deploy the archive: ---- -mvn clean install wildfly:deploy +$ mvn clean install wildfly:deploy ---- . This will deploy `target/{artifactId}.war` to the running instance of the server. @@ -160,11 +163,11 @@ HHH000431: Unable to determine H2 database version, certain features may not wor == Undeploy the Archive . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . When you are finished testing, type this command to undeploy the archive: ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- == Run the Arquillian Tests @@ -172,14 +175,14 @@ mvn wildfly:undeploy This quickstart provides Arquillian tests. By default, these tests are configured to be skipped as Arquillian tests require the use of a container. . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type the following command to run the test goal with the following profile activated: ---- -mvn clean verify -Parq-remote +$ mvn clean verify -Parq-remote ---- -You can also let Arquillian manage the {productName} server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests[Run the Arquillian Tests]. +You can also let Arquillian manage the {productName} server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see link:{arquillianTestsDocUrl}[Run the Arquillian Tests]. == Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse @@ -190,5 +193,5 @@ You can also start the server and deploy the quickstarts or run the Arquillian t If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. ---- -mvn dependency:sources ----- \ No newline at end of file +$ mvn dependency:sources +---- diff --git a/kitchensink/README.adoc b/kitchensink/README.adoc index 75dbee6499..158144d2c5 100644 --- a/kitchensink/README.adoc +++ b/kitchensink/README.adoc @@ -20,39 +20,43 @@ The `kitchensink` quickstart is a deployable Maven 3 project designed to help yo It demonstrates how to create a compliant Java EE 7 application using JSF, CDI, JAX-RS, EJB, JPA, and Bean Validation. It also includes a persistence unit and some sample persistence and transaction code to introduce you to database access in enterprise Java. -_Note: This quickstart uses the H2 database included with {productNameFull} {productVersion}. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ +//************************************************* +// Add notes about use in a production environment. +//************************************************* +:uses-h2: +:uses-ds-xml: +include::../development-shortcuts.adoc[leveloffset=+1] -_Note: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in {productName} and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/[Configuration Guide] for {productNameFull}._ == System Requirements The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Use of {jbossHomeName} -In the following instructions, replace `{jbossHomeName}` with the actual path to your {productName} installation. The installation path is described in detail here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_{jbossHomeName}.md#use-of-eap_home-and-jboss_home-variables[Use of {jbossHomeName} and JBOSS_HOME Variables]. +In the following instructions, replace `__{jbossHomeName}__` with the actual path to your {productName} installation. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of {jbossHomeName} and JBOSS_HOME Variables]. == Start the Server -. Open a command prompt and navigate to the root of the {productName} directory. +. Open a terminal and navigate to the root of the {productName} directory. . The following shows the command line to start the server: [subs=normal] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +For Linux: $ __{jbossHomeName}__/bin/standalone.sh +For Windows: __{jbossHomeName}__\bin\standalone.bat ---- == Build and Deploy the Quickstart . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type this command to build and deploy the archive: ---- -mvn clean install wildfly:deploy +$ mvn clean install wildfly:deploy ---- . This will deploy `target/{artifactId}.war` to the running instance of the server. @@ -74,11 +78,11 @@ HHH000431: Unable to determine H2 database version, certain features may not wor == Undeploy the Archive . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . When you are finished testing, type this command to undeploy the archive: ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- == Run the Arquillian Tests @@ -86,14 +90,14 @@ mvn wildfly:undeploy This quickstart provides Arquillian tests. By default, these tests are configured to be skipped as Arquillian tests require the use of a container. . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type the following command to run the test goal with the following profile activated: ---- -mvn clean verify -Parq-remote +$ mvn clean verify -Parq-remote ---- -You can also let Arquillian manage the {productName} server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests[Run the Arquillian Tests]. +You can also let Arquillian manage the {productName} server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see link:{arquillianTestsDocUrl}[Run the Arquillian Tests]. == Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse @@ -104,5 +108,5 @@ You can also start the server and deploy the quickstarts or run the Arquillian t If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. ---- -mvn dependency:sources ----- \ No newline at end of file +$ mvn dependency:sources +---- diff --git a/logging-tools/README.adoc b/logging-tools/README.adoc index 52c2c8ad54..90d649ffab 100644 --- a/logging-tools/README.adoc +++ b/logging-tools/README.adoc @@ -26,17 +26,17 @@ Instructions are included below for starting {productName} with a different loca The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Use of {jbossHomeName} -In the following instructions, replace `{jbossHomeName}` with the actual path to your {productName} installation. The installation path is described in detail here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_{jbossHomeName}.md#use-of-eap_home-and-jboss_home-variables[Use of {jbossHomeName} and JBOSS_HOME Variables]. +In the following instructions, replace `__{jbossHomeName}__` with the actual path to your {productName} installation. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of {jbossHomeName} and JBOSS_HOME Variables]. == Configure the Server to Start With a Different Locale (Optional) To start the {productName} server with a different locale than the system default: -. Make a backup copy of the `{jbossHomeName}/bin/standalone.conf` file. +. Make a backup copy of the `$ __{jbossHomeName}__/bin/standalone.conf` file. . Edit the file and append commands to set the JVM parameters for the required country and language. The following example sets the country to Germany (`DE`) and the language to German (`de`). @@ -49,23 +49,23 @@ For more information about internationalization and localization, see http://www == Start the Server -. Open a command prompt and navigate to the root of the {productName} directory. +. Open a terminal and navigate to the root of the {productName} directory. . The following shows the command line to start the server: [subs=normal] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +For Linux: $ __{jbossHomeName}__/bin/standalone.sh +For Windows: __{jbossHomeName}__\bin\standalone.bat ---- == Build and Deploy the Quickstart . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type this command to build and deploy the archive: ---- -mvn clean install wildfly:deploy +$ mvn clean install wildfly:deploy ---- . This will deploy `target/{artifactId}.war` to the running instance of the server. @@ -108,11 +108,11 @@ This landing page provides details and links to test the quickstart features. Yo == Undeploy the Archive . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . When you are finished testing, type this command to undeploy the archive: ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- == Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse @@ -133,5 +133,5 @@ You may see the following warning when you import this quickstart into JBoss Dev If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. ---- - mvn dependency:sources + $ mvn dependency:sources ---- \ No newline at end of file diff --git a/logging/README.adoc b/logging/README.adoc index d4d1dfaaf6..9ac6d6d9de 100644 --- a/logging/README.adoc +++ b/logging/README.adoc @@ -10,7 +10,6 @@ include::../attributes.adoc[] :level: Intermediate :technologies: Logging :source: {githubRepoUrl} -:prerequisites: None [abstract] The `logging` quickstart demonstrates how to configure different logging levels in {productName}. It also includes an asynchronous logging example. @@ -27,31 +26,31 @@ To better visualize how the logging configuration works, you first deploy and ac The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Use of {jbossHomeName} -In the following instructions, replace `{jbossHomeName}` with the actual path to your {productName} installation. The installation path is described in detail here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_{jbossHomeName}.md#use-of-eap_home-and-jboss_home-variables[Use of {jbossHomeName} and JBOSS_HOME Variables]. +In the following instructions, replace `__{jbossHomeName}__` with the actual path to your {productName} installation. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of {jbossHomeName} and JBOSS_HOME Variables]. == Start the Server -. Open a command prompt and navigate to the root of the {productName} directory. +. Open a terminal and navigate to the root of the {productName} directory. . The following shows the command line to start the {productName} server with the default profile: [subs=normal] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +For Linux: $ __{jbossHomeName}__/bin/standalone.sh +For Windows: __{jbossHomeName}__\bin\standalone.bat ---- == Build and Deploy the Quickstart . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type this command to build and deploy the archive: ---- -mvn clean install wildfly:deploy +$ mvn clean install wildfly:deploy ---- . This deploys `target/{artifactId}.war` to the running instance of the server. @@ -95,17 +94,17 @@ You configure server logging by running JBoss CLI commands. For your convenience = [subs="+quotes,attributes+"] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +For Linux: $ __{jbossHomeName}__/bin/standalone.sh +For Windows: __{jbossHomeName}__\bin\standalone.bat ---- . Review the `configure-logging.cli` file in the root of this quickstart directory. This script configures the logging subsytem in the server configuration file. It configures the periodic rotating file handlers and the async handlers, creates the logger for our quickstart class and sets the level to TRACE, and assigns the async handlers for our quickstart class. -. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing {jbossHomeName} with the path to your server: +. 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: + [subs="+quotes,attributes+"] ---- -For Linux: {jbossHomeName}/bin/jboss-cli.sh --connect --file=configure-logging.cli -For Windows: {jbossHomeName}\bin\jboss-cli.bat --connect --file=configure-logging.cli +For Linux: $ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=configure-logging.cli +For Windows: __{jbossHomeName}__\bin\jboss-cli.bat --connect --file=configure-logging.cli ---- == Review the Modified Server Configuration @@ -114,7 +113,7 @@ After stopping the server, open the `{jbossHomeName}/standalone/configuration/st The following XML was added to the `logging` subsystem. + -[source, xml] +[source,xml,options="nowrap"] ---- @@ -234,9 +233,9 @@ The following describes what happens when you access this quickstart: . Common uses of the 6 log levels are outlined below. You should use the level that makes the most sense in your environment. ---- -FATAL - Used to track critical system failures. When this log message is written, it is writing application error that has caused service to cease. This is the most narrow logging. +FATAL - Used to track critical system failures. When this log message is written, it is writing application error that has caused service to cease. This is the most narrow logging. ERROR - Used to track application errors that may cause one request to fail (not a service ceasement). -WARN - This is setting is used in most production environments. At this level, all *WARN*, *ERROR*, and *FATAL* messages are written. Use this level message as a predictive measure for possible forthcoming issues. +WARN - This is setting is used in most production environments. At this level, all *WARN*, *ERROR*, and *FATAL* messages are written. Use this level message as a predictive measure for possible forthcoming issues. INFO - Usually only used in a development environment. This provides any information - state transition, object values, etc DEBUG - Turned on in any environment when a problem is occuring. The information captured may be throughput, communication, object values, etc. TRACE - Turned on in any environment where you are trying to follow an execution path, for optimization or debugging. This is the most broad logging level and all messages are written. @@ -248,11 +247,11 @@ from TRACE to DEBUG, INFO, WARN, ERROR, or FATAL, then access the application. == Undeploy the Archive . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . When you are finished testing, type this command to undeploy the archive: ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- == Remove the Logging Configuration @@ -266,17 +265,17 @@ You can remove the logging configuration by running the `remove-logging.cli` scr + [subs="+quotes,attributes+"] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +For Linux: $ __{jbossHomeName}__/bin/standalone.sh +For Windows: __{jbossHomeName}__\bin\standalone.bat ---- -. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing {jbossHomeName} with the path to your server: +. 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: + [subs="+quotes,attributes+"] ---- -For Linux: {jbossHomeName}/bin/jboss-cli.sh --connect --file=remove-logging.cli -For Windows: {jbossHomeName}\bin\jboss-cli.bat --connect --file=remove-logging.cli +For Linux: $ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=remove-logging.cli +For Windows: __{jbossHomeName}__\bin\jboss-cli.bat --connect --file=remove-logging.cli ---- === Remove the Logging Configuration Manually @@ -296,5 +295,5 @@ You can also start the server and deploy the quickstarts or run the Arquillian t If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. ---- -mvn dependency:sources ----- \ No newline at end of file +$ mvn dependency:sources +---- diff --git a/mail/README.adoc b/mail/README.adoc index 5fba96daff..b3f5da8c2d 100644 --- a/mail/README.adoc +++ b/mail/README.adoc @@ -28,11 +28,11 @@ This example is a web application that takes `To`, `From`, `Subject`, and `Messa The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Use of {jbossHomeName} -In the following instructions, replace `{jbossHomeName}` with the actual path to your {productName} installation. The installation path is described in detail here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_{jbossHomeName}.md#use-of-eap_home-and-jboss_home-variables[Use of {jbossHomeName} and JBOSS_HOME Variables]. +In the following instructions, replace `__{jbossHomeName}__` with the actual path to your {productName} installation. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of {jbossHomeName} and JBOSS_HOME Variables]. == Configure an SMTP Server on Your Local Machine @@ -53,17 +53,17 @@ You configure the custom mail session in {productName} by running Management CLI + [subs="+quotes,attributes+"] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +For Linux: $ __{jbossHomeName}__/bin/standalone.sh +For Windows: __{jbossHomeName}__\bin\standalone.bat ---- . Review the `configure-mail-session.cli` file in the root of this quickstart directory. This script creates custom outbound socket binding port for SMTP, POP3, and IMAP. It then creates the custom `MyOtherMail` mail session and configures it to use the custom outbound socket binding ports. -. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing {jbossHomeName} with the path to your server: +. 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: + [subs="+quotes,attributes+"] ---- -For Linux: {jbossHomeName}/bin/jboss-cli.sh --connect --file=configure-mail-session.cli -For Windows: {jbossHomeName}\bin\jboss-cli.bat --connect --file=configure-mail-session.cli +For Linux: $ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=configure-mail-session.cli +For Windows: __{jbossHomeName}__\bin\jboss-cli.bat --connect --file=configure-mail-session.cli ---- . Stop the {productName} server. @@ -74,7 +74,7 @@ After stopping the server, open the `{jbossHomeName}/standalone/configuration/st The following `outbound-socket-binding` groups are added to the `standard-sockets` `<socket-binding-group>` element. -[source, xml] +[source,xml,options="nowrap"] ---- ... @@ -93,7 +93,7 @@ The following `outbound-socket-binding` groups are added to the `standard-socket The `MyOtherMail` mail session is added to the `mail` subsystem and configured to use the custom outbound socket binding ports. -[source, xml] +[source,xml,options="nowrap"] ---- @@ -109,23 +109,23 @@ The `MyOtherMail` mail session is added to the `mail` subsystem and configured t == Start the Server -. Open a command prompt and navigate to the root of the {productName} directory. +. Open a terminal and navigate to the root of the {productName} directory. . The following shows the command line to start the server: [subs=normal] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +For Linux: $ __{jbossHomeName}__/bin/standalone.sh +For Windows: __{jbossHomeName}__\bin\standalone.bat ---- == Build and Deploy the Quickstart . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type this command to build and deploy the archive: ---- -mvn clean install wildfly:deploy +$ mvn clean install wildfly:deploy ---- . This will deploy `target/{artifactId}.war` to the running instance of the server. @@ -139,11 +139,11 @@ NOTE: If you see `Error processing request` in the browser when you access the a == Undeploy the Archive . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . When you are finished testing, type this command to undeploy the archive: ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- == Remove the Mail Configuration @@ -156,16 +156,16 @@ You can remove the mail configuration by running the `remove-mail-session.cli` s + [subs="+quotes,attributes+"] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +For Linux: $ __{jbossHomeName}__/bin/standalone.sh +For Windows: __{jbossHomeName}__\bin\standalone.bat ---- -. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing {jbossHomeName} with the path to your server: +. 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: + [subs="+quotes,attributes+"] ---- -For Linux: {jbossHomeName}/bin/jboss-cli.sh --connect --file=remove-mail-session.cli -For Windows: {jbossHomeName}\bin\jboss-cli.bat --connect --file=remove-mail-session.cli +For Linux: $ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=remove-mail-session.cli +For Windows: __{jbossHomeName}__\bin\jboss-cli.bat --connect --file=remove-mail-session.cli ---- === Remove the Custom Mail Configuration Manually @@ -191,5 +191,5 @@ You can also start the server and deploy the quickstarts or run the Arquillian t If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. ---- -mvn dependency:sources ----- \ No newline at end of file +$ mvn dependency:sources +---- diff --git a/managed-executor-service/README.adoc b/managed-executor-service/README.adoc index 2ab1a0e239..537ffba768 100644 --- a/managed-executor-service/README.adoc +++ b/managed-executor-service/README.adoc @@ -24,15 +24,18 @@ A JAX-RS resource provides access to some operations that are executed asynchron This quickstart does not contain any user interface. The tests must be run to verify everything is working correctly. -_Note: This quickstart uses the H2 database included with {productNameFull} {productVersion}. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ - -_Note: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in {productName} and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/[Configuration Guide] for {productNameFull}._ +//************************************************* +// Add notes about use in a production environment. +//************************************************* +:uses-h2: +:uses-ds-xml: +include::../development-shortcuts.adoc[leveloffset=+1] == System Requirements The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Start the Server @@ -41,8 +44,8 @@ All you need to build this project is {buildRequirements}. See https://github.co [subs=normal] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +For Linux: $ __{jbossHomeName}__/bin/standalone.sh +For Windows: __{jbossHomeName}__\bin\standalone.bat ---- == Run the Arquillian Tests @@ -54,10 +57,10 @@ This quickstart provides Arquillian tests. By default, these tests are configure . Type the following command to run the test goal with the following profile activated: ---- -mvn clean verify -Parq-remote +$ mvn clean verify -Parq-remote ---- -You can also let Arquillian manage the {productName} server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests[Run the Arquillian Tests]. +You can also let Arquillian manage the {productName} server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see link:{arquillianTestsDocUrl}[Run the Arquillian Tests]. == Investigate the Console Output @@ -144,5 +147,5 @@ Then, to run the tests, right click on the project or individual classes and sel If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. ---- -mvn dependency:sources ----- \ No newline at end of file +$ mvn dependency:sources +---- diff --git a/messaging-clustering-singleton/README.adoc b/messaging-clustering-singleton/README.adoc index 830ed92012..2bdf6f3d66 100644 --- a/messaging-clustering-singleton/README.adoc +++ b/messaging-clustering-singleton/README.adoc @@ -16,7 +16,7 @@ The `messaging-clustering-singleton` quickstart uses a JMS topic and a queue to == What is it? -The `messaging-clustering-singleton` quickstart demonstrates the use of clustering with integrated Apache ActiveMQ Artemis. It uses the same code as in link:../helloworld-mdb/README.md[helloworld-mdb] quickstart, with only a difference in the configuration to run it as a clustered singleton. Instructions are provided to run the quickstart on either a standalone server or in a managed domain. +The `messaging-clustering-singleton` quickstart demonstrates the use of clustering with integrated Apache ActiveMQ Artemis. It uses the same code as in link:../helloworld-mdb/README.adoc[helloworld-mdb] quickstart, with only a difference in the configuration to run it as a clustered singleton. Instructions are provided to run the quickstart on either a standalone server or in a managed domain. These are the two JMS resources contained in this quickstart: @@ -51,21 +51,21 @@ If a delivery group is used in conjunction with singleton, as is the case of thi The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Use of {jbossHomeName} -In the following instructions, replace `{jbossHomeName}` with the actual path to your {productName} installation. The installation path is described in detail here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_{jbossHomeName}.md#use-of-eap_home-and-jboss_home-variables[Use of {jbossHomeName} and JBOSS_HOME Variables]. +In the following instructions, replace `__{jbossHomeName}__` with the actual path to your {productName} installation. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of {jbossHomeName} and JBOSS_HOME Variables]. == Build the Project Follow these steps to build the project without deploying it. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type this command to build the archive: ---- -mvn clean install +$ mvn clean install ---- == Configure the Server and Deploy the Quickstart @@ -94,13 +94,13 @@ After you have completed testing this quickstart, you can replace these files to ==== Start the Managed Domain -. Open a command prompt and navigate to the root of the {productName} directory. +. Open a terminal and navigate to the root of the {productName} directory. . The following shows the command line to start the server in a managed domain: + [subs="+quotes,attributes+"] ---- -For Linux: {jbossHomeName}/bin/domain.sh -For Windows: {jbossHomeName}\bin\domain.bat +For Linux: $ __{jbossHomeName}__/bin/domain.sh +For Windows: __{jbossHomeName}__\bin\domain.bat ---- ==== Configure the Domain Server and Deploy the Quickstart Using the JBoss CLI @@ -115,12 +115,12 @@ For Windows: {jbossHomeName}\bin\domain.bat ** Creates a delivery group named `my-mdb-delivery-group`, with initial active value set to `true`. ** Deploys the `{artifactId}.war` archive. ** Starts the servers that were added to the managed domain. -. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing {jbossHomeName} with the path to your server: +. 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: + [subs="+quotes,attributes+"] ---- -For Linux: {jbossHomeName}/bin/jboss-cli.sh --connect --file=install-domain.cli -For Windows: {jbossHomeName}\bin\jboss-cli.bat --connect --file=install-domain.cli +For Linux: $ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=install-domain.cli +For Windows: __{jbossHomeName}__\bin\jboss-cli.bat --connect --file=install-domain.cli ---- === Configure the Server and Deploy the Quickstart to a Standalone Server @@ -146,7 +146,7 @@ After you have completed testing this quickstart, you can replace this file to r ==== Start the Standalone Server Using the Full HA Profile. -. Open a command prompt and navigate to the root of the {productName} directory. +. Open a terminal and navigate to the root of the {productName} directory. . The following shows the command line to start the server with the `full-ha` profile. This profile supports HA clustering. + [subs="+quotes,attributes+"] @@ -164,7 +164,7 @@ For Windows: {jbossHomeName}_1\bin\standalone.bat -c standalone-full-ha.xml ** Creates a delivery group named `my-mdb-delivery-group`, with initial active value set to `true`. ** Deploys the `{artifactId}.war` archive. ** Reloads the server configuration. -. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing {jbossHomeName} with the path to your server: +. 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: + [subs="+quotes,attributes+"] ---- @@ -316,8 +316,8 @@ at java.lang.Thread.run(Thread.java:745) Run the following command, replacing {jbossHomeName} with the path to your server, and replacing `NODE_X` in the script name with either `node1` or `node2`, depending on whether the current singleton provider is `node1` or `node2`. ---- -For Linux: {jbossHomeName}/bin/jboss-cli.sh --connect --file=restart-NODE_X-domain.cli -For Windows: {jbossHomeName}\bin\jboss-cli.bat --connect --file=restart-NODE_X-domain.cli +For Linux: $ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=restart-NODE_X-domain.cli +For Windows: __{jbossHomeName}__\bin\jboss-cli.bat --connect --file=restart-NODE_X-domain.cli ---- === Rebooting the Singleton Provider Server Node in a Standalone Server @@ -337,15 +337,15 @@ Next, enable the delivery group using the appropriate `enable-delivery-group-dom To disable the delivery group named "my-mdb-delivery-group" to which the topic belongs, run the `disable-delivery-group-domain.cli` script, replacing {jbossHomeName} with the path to your server: ---- -For Linux: {jbossHomeName}/bin/jboss-cli.sh --connect --file=disable-delivery-group-domain.cli -For Windows: {jbossHomeName}\bin\jboss-cli.bat --connect --file=disable-delivery-group-domain.cli +For Linux: $ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=disable-delivery-group-domain.cli +For Windows: __{jbossHomeName}__\bin\jboss-cli.bat --connect --file=disable-delivery-group-domain.cli ---- Similarly, to enable the delivery group, run the `enable-delivery-group-domain.cli` script: ---- -For Linux: {jbossHomeName}/bin/jboss-cli.sh --connect --file=enable-delivery-group-domain.cli -For Windows: {jbossHomeName}\bin\jboss-cli.bat --connect --file=enable-delivery-group-domain.cli +For Linux: $ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=enable-delivery-group-domain.cli +For Windows: __{jbossHomeName}__\bin\jboss-cli.bat --connect --file=enable-delivery-group-domain.cli ---- === Disable and Enable Delivery Group in a Standalone Server @@ -375,17 +375,17 @@ When you are finished testing, use the following instructions to undeploy the qu === Undeploy the quickstart in a Managed Domain . Make sure you have started the managed domain as described above. -. Open a new command prompt, navigate to the root directory of this quickstart, and run the `undeploy-domain.cli` script, replacing {jbossHomeName} with the path to your server: +. Open a new terminal, navigate to the root directory of this quickstart, and run the `undeploy-domain.cli` script, replacing {jbossHomeName} with the path to your server: ---- -For Linux: {jbossHomeName}/bin/jboss-cli.sh --connect --file=undeploy-domain.cli -For Windows: {jbossHomeName}\bin\jboss-cli.bat --connect --file=undeploy-domain.cli +For Linux: $ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=undeploy-domain.cli +For Windows: __{jbossHomeName}__\bin\jboss-cli.bat --connect --file=undeploy-domain.cli ---- === Undeploy the quickstart in a Standalone Server . Make sure you have started the standalone server as described above. -. Open a command prompt, navigate to the root directory of this quickstart, and run the `undeploy-standalone.cli` script, replacing {jbossHomeName}_1 and {jbossHomeName}_2 with the path to the appropriate server: +. Open a terminal, navigate to the root directory of this quickstart, and run the `undeploy-standalone.cli` script, replacing {jbossHomeName}_1 and {jbossHomeName}_2 with the path to the appropriate server: ---- For Linux: {jbossHomeName}_1/bin/jboss-cli.sh --connect --file=undeploy-standalone.cli @@ -415,15 +415,15 @@ _Note: This script returns the server to a default configuration and the result . Start the {productName} server by typing the following: ---- -For Linux: {jbossHomeName}/bin/domain.sh -For Windows: {jbossHomeName}\bin\domain.bat +For Linux: $ __{jbossHomeName}__/bin/domain.sh +For Windows: __{jbossHomeName}__\bin\domain.bat ---- -. Open a new command prompt, navigate to the root directory of this quickstart, and run the `remove-domain.cli` script, replacing {jbossHomeName} with the path to your server. +. Open a new terminal, navigate to the root directory of this quickstart, and run the `remove-domain.cli` script, replacing {jbossHomeName} with the path to your server. ---- -For Linux: {jbossHomeName}/bin/jboss-cli.sh --connect --file=remove-domain.cli -For Windows: {jbossHomeName}\bin\jboss-cli.bat --connect --file=remove-domain.cli +For Linux: $ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=remove-domain.cli +For Windows: __{jbossHomeName}__\bin\jboss-cli.bat --connect --file=remove-domain.cli ---- This script removes the server configuration that was done by the `install-domain.cli` script. You should see the following result following the script commands: @@ -454,7 +454,7 @@ For Linux: {jbossHomeName}_1/bin/standalone.sh -c standalone-full-ha.xml For Windows: {jbossHomeName}_1\bin\domain.bat -c standalone-full-ha.xml ---- -. Open a new command prompt, navigate to the root directory of this quickstart, and run the `remove-standalone.cli` script, replacing {jbossHomeName}_2 with the path to your second server. +. Open a new terminal, navigate to the root directory of this quickstart, and run the `remove-standalone.cli` script, replacing {jbossHomeName}_2 with the path to your second server. ---- For Linux: {jbossHomeName}_1/bin/jboss-cli.sh --connect --file=remove-standalone.cli diff --git a/messaging-clustering/README.adoc b/messaging-clustering/README.adoc index cfc4fec99f..43af3e065c 100644 --- a/messaging-clustering/README.adoc +++ b/messaging-clustering/README.adoc @@ -10,37 +10,37 @@ include::../attributes.adoc[] :level: Intermediate :technologies: JMS, MDB :source: {githubRepoUrl} -:prerequisites: helloworld-mdb +:prerequisites: link:helloworld-mdb/README{outfilesuffix}[helloworld-mdb] [abstract] The `messaging-clustering` quickstart does not contain any code and instead uses the `helloworld-mdb` quickstart to demonstrate clustering using ActiveMQ Messaging. == What is it? -The `messaging-clustering` quickstart demonstrates the use of clustering with Apache ActiveMQ and {productNameFull}. It uses the link:../helloworld-mdb/README.md[helloworld-mdb] quickstart for its tests, so there is no code associated with this quickstart. Instructions are provided to run the quickstart on either a standalone server or in a managed domain. +The `messaging-clustering` quickstart demonstrates the use of clustering with Apache ActiveMQ and {productNameFull}. It uses the link:../helloworld-mdb/README.adoc[helloworld-mdb] quickstart for its tests, so there is no code associated with this quickstart. Instructions are provided to run the quickstart on either a standalone server or in a managed domain. == System Requirements The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Use of {jbossHomeName} -In the following instructions, replace `{jbossHomeName}` with the actual path to your {productName} installation. The installation path is described in detail here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_{jbossHomeName}.md#use-of-eap_home-and-jboss_home-variables[Use of {jbossHomeName} and JBOSS_HOME Variables]. +In the following instructions, replace `__{jbossHomeName}__` with the actual path to your {productName} installation. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of {jbossHomeName} and JBOSS_HOME Variables]. == Prerequisites *IMPORTANT:* This quickstart depends on the deployment of the `helloworld-mdb` quickstart WAR for its tests. Before you continue, you must build the `helloworld-mdb` quickstart WAR. -Open a command prompt and navigate to the root directory of the helloworld-mdb quickstart. +Open a terminal and navigate to the root directory of the helloworld-mdb quickstart. Type this command to build the WAR archive: ---- - mvn clean install + $ mvn clean install ---- -See the helloworld-mdb link:../helloworld-mdb/README.md[README] for further information about this quickstart. +See the helloworld-mdb link:../helloworld-mdb/README.adoc[README] for further information about this quickstart. == Configure the Server and Deploy the Quickstart @@ -71,12 +71,12 @@ You configure the server by running the install-domain.cli script provided in th ==== Start the server in domain mode. -. Open a command prompt and navigate to the root of the {productName} directory. +. Open a terminal and navigate to the root of the {productName} directory. . The following shows the command line to start the server in domain mode: ---- -For Linux: {jbossHomeName}/bin/domain.sh -For Windows: {jbossHomeName}\bin\domain.bat +For Linux: $ __{jbossHomeName}__/bin/domain.sh +For Windows: __{jbossHomeName}__\bin\domain.bat ---- ==== Configure the Domain Server and Deploy the Quickstart Using the JBoss CLI @@ -89,11 +89,11 @@ For Windows: {jbossHomeName}\bin\domain.bat ** Configures ActiveMQ clustering in the full-ha profile ** Deploys the `helloworld-mdb.war` archive ** Restarts the servers. -. Open a command prompt, navigate to the root directory of this quickstart, and run the following command to run the script: +. Open a terminal, navigate to the root directory of this quickstart, and run the following command to run the script: ---- -For Linux: {jbossHomeName}/bin/jboss-cli.sh --connect --file=install-domain.cli -For Windows: {jbossHomeName}\bin\jboss-cli.bat --connect --file=install-domain.cli +For Linux: $ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=install-domain.cli +For Windows: __{jbossHomeName}__\bin\jboss-cli.bat --connect --file=install-domain.cli ---- You should see "outcome" => "success" for all of the commands. @@ -108,7 +108,7 @@ Since both application servers must be configured in the same way, you must conf ==== Start the Server in Standalone Mode using the Full HA Profile. -. Open a command prompt and navigate to the root of the {productName} directory. +. Open a terminal and navigate to the root of the {productName} directory. . The following shows the command line to start the server with the full-ha profile. This profile supports clustering/HA ---- @@ -124,7 +124,7 @@ For Windows: {jbossHomeName}_1\bin\standalone.bat -c standalone-full-ha.xml ** Enables clustering in the RemoteConnectionFactory ** Deploys the `helloworld-mdb.war` archive ** Reloads the server configuration -. Open a command prompt, navigate to the root directory of this quickstart, and run the following command to run the script: +. Open a terminal, navigate to the root directory of this quickstart, and run the following command to run the script: ---- For Linux: {jbossHomeName}_1/bin/jboss-cli.sh --connect --file=install-standalone.cli @@ -219,17 +219,17 @@ When you are finished testing, use the following instructions to undeploy the qu === Undeploy the quickstart in Domain Mode . Make sure you have started the {productName} server in domain mode as described above. -. Open a command prompt, navigate to the root directory of this quickstart, and run the following command to undeploy the helloworld-mdb quickstart: +. Open a terminal, navigate to the root directory of this quickstart, and run the following command to undeploy the helloworld-mdb quickstart: ---- -For Linux: {jbossHomeName}/bin/jboss-cli.sh --connect --file=undeploy-domain.cli -For Windows: {jbossHomeName}\bin\jboss-cli.bat --connect --file=undeploy-domain.cli +For Linux: $ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=undeploy-domain.cli +For Windows: __{jbossHomeName}__\bin\jboss-cli.bat --connect --file=undeploy-domain.cli ---- === Undeploy the quickstart in Standalone Mode . Make sure you have started the {productName} server in standalone mode as described above. -. Open a command prompt, navigate to the root directory of this quickstart, and run the following command to undeploy the helloworld-mdb quickstart: +. Open a terminal, navigate to the root directory of this quickstart, and run the following command to undeploy the helloworld-mdb quickstart: ---- For Linux: {jbossHomeName}_1/bin/jboss-cli.sh --connect --file=undeploy-standalone.cli @@ -256,15 +256,15 @@ _Note: This script returns the server to a default configuration and the result . Start the {productName} server by typing the following: ---- -For Linux: {jbossHomeName}/bin/domain.sh -For Windows: {jbossHomeName}\bin\domain.bat +For Linux: $ __{jbossHomeName}__/bin/domain.sh +For Windows: __{jbossHomeName}__\bin\domain.bat ---- -. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing {jbossHomeName} with the path to your server. +. 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. ---- -For Linux: {jbossHomeName}/bin/jboss-cli.sh --connect --file=remove-domain.cli -For Windows: {jbossHomeName}\bin\jboss-cli.bat --connect --file=remove-domain.cli +For Linux: $ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=remove-domain.cli +For Windows: __{jbossHomeName}__\bin\jboss-cli.bat --connect --file=remove-domain.cli ---- _Note: If the `:stop-server` command does not complete before the next commands are issued, you may see an error similar to the following: @@ -297,7 +297,7 @@ For Linux: {jbossHomeName}_1/bin/standalone.sh -c standalone-full-ha.xml For Windows: {jbossHomeName}_1\bin\domain.bat -c standalone-full-ha.xml ---- -. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing {jbossHomeName}_1 with the path to your server. +. Open a new terminal, navigate to the root directory of this quickstart, and run the following command, replacing {jbossHomeName}_1 with the path to your server. ---- For Linux: {jbossHomeName}_1/bin/jboss-cli.sh --connect --file=remove-standalone.cli @@ -307,4 +307,4 @@ For Windows: {jbossHomeName}_1\bin\jboss-cli.bat --connect --file=remove-standal === Delete the Cloned Standalone {productName} Directory . If it is running, stop the second instance of the {productName} server. -. Delete the cloned directory. \ No newline at end of file +. Delete the cloned directory. diff --git a/numberguess/README.adoc b/numberguess/README.adoc index 1e59a8041e..be6dc75668 100644 --- a/numberguess/README.adoc +++ b/numberguess/README.adoc @@ -22,32 +22,32 @@ The `numberguess` quickstart demonstrates the use of _CDI_ (Contexts and Depende The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Use of {jbossHomeName} -In the following instructions, replace `{jbossHomeName}` with the actual path to your {productName} installation. The installation path is described in detail here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_{jbossHomeName}.md#use-of-eap_home-and-jboss_home-variables[Use of {jbossHomeName} and JBOSS_HOME Variables]. +In the following instructions, replace `__{jbossHomeName}__` with the actual path to your {productName} installation. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of {jbossHomeName} and JBOSS_HOME Variables]. == Start the Server -. Open a command prompt and navigate to the root of the {productName} directory. +. Open a terminal and navigate to the root of the {productName} directory. . The following shows the command line to start the server: + [subs="+quotes,attributes+"] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +For Linux: $ __{jbossHomeName}__/bin/standalone.sh +For Windows: __{jbossHomeName}__\bin\standalone.bat ---- == Build and Deploy the Quickstart . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type this command to build and deploy the archive: + ---- -mvn clean install wildfly:deploy +$ mvn clean install wildfly:deploy ---- . This will deploy `target/{artifactId}.war` to the running instance of the server. @@ -59,11 +59,11 @@ The application will be running at the following URL: http://localhost:8080/{art == Undeploy the Archive . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . When you are finished testing, type this command to undeploy the archive: ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- == Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse @@ -75,5 +75,5 @@ You can also start the server and deploy the quickstarts or run the Arquillian t If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. ---- - mvn dependency:sources + $ mvn dependency:sources ---- \ No newline at end of file diff --git a/payment-cdi-event/README.adoc b/payment-cdi-event/README.adoc index 00b803b1d8..1741b5ab4c 100644 --- a/payment-cdi-event/README.adoc +++ b/payment-cdi-event/README.adoc @@ -50,31 +50,31 @@ The `payment-cdi-event` quickstart defines the following classes and interfaces: The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Use of {jbossHomeName} -In the following instructions, replace `{jbossHomeName}` with the actual path to your {productName} installation. The installation path is described in detail here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_{jbossHomeName}.md#use-of-eap_home-and-jboss_home-variables[Use of {jbossHomeName} and JBOSS_HOME Variables]. +In the following instructions, replace `__{jbossHomeName}__` with the actual path to your {productName} installation. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of {jbossHomeName} and JBOSS_HOME Variables]. == Start the {productName} Server -. Open a command prompt and navigate to the root of the {productName} directory. +. Open a terminal and navigate to the root of the {productName} directory. . The following shows the command line to start the server: [subs=normal] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +For Linux: $ __{jbossHomeName}__/bin/standalone.sh +For Windows: __{jbossHomeName}__\bin\standalone.bat ---- == Build and Deploy the Quickstart . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type this command to build and deploy the archive: ---- -mvn clean install wildfly:deploy +$ mvn clean install wildfly:deploy ---- . This will deploy `target/{artifactId}.war` to the running instance of the server. @@ -86,11 +86,11 @@ The application will be running at the following URL: http://localhost:8080/{art == Undeploy the Archive . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . When you are finished testing, type this command to undeploy the archive: ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- == Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse @@ -102,5 +102,5 @@ You can also start the server and deploy the quickstarts or run the Arquillian t If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. ---- - mvn dependency:sources + $ mvn dependency:sources ---- \ No newline at end of file diff --git a/resteasy-jaxrs-client/README.adoc b/resteasy-jaxrs-client/README.adoc index 433c288f82..314dc4dc42 100644 --- a/resteasy-jaxrs-client/README.adoc +++ b/resteasy-jaxrs-client/README.adoc @@ -10,7 +10,7 @@ include::../attributes.adoc[] :level: Intermediate :technologies: JAX-RS, CDI :source: {githubRepoUrl} -:prerequisites: helloworld-rs +:prerequisites: link:helloworld-rs/README{outfilesuffix}[helloworld-rs] [abstract] The `resteasy-jaxrs-client` quickstart demonstrates an external JAX-RS RestEasy client, which interacts with a JAX-RS Web service that uses *CDI* and *JAX-RS*. @@ -20,19 +20,19 @@ The `resteasy-jaxrs-client` quickstart demonstrates an external JAX-RS RestEasy The `resteasy-jaxrs-client` quickstart demonstrates an external JAX-RS RestEasy client which interacts with a JAX-RS Web service that uses _CDI_ and _JAX-RS_ in {productNameFull}. -This client "calls" the HelloWorld JAX-RS Web Service that was created in the link:../helloworld-rs/README.md[helloworld-rs] quickstart. See the *Prerequisite* section below for details on how to build and deploy the link:../helloworld-rs/README.md[helloworld-rs] quickstart. +This client "calls" the HelloWorld JAX-RS Web Service that was created in the link:../helloworld-rs/README.adoc[helloworld-rs] quickstart. See the *Prerequisite* section below for details on how to build and deploy the link:../helloworld-rs/README.adoc[helloworld-rs] quickstart. == System Requirements The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Prerequisites -IMPORTANT: This quickstart depends on the deployment of the `helloworld-rs` quickstart for its test. Before running this quickstart, see the link:../helloworld-rs/README.md[helloworld-rs] README file for details on how to deploy it. +IMPORTANT: This quickstart depends on the deployment of the `helloworld-rs` quickstart for its test. Before running this quickstart, see the link:../helloworld-rs/README.adoc[helloworld-rs] README file for details on how to deploy it. -You can verify the deployment of the link:../helloworld-rs/README.md[helloworld-rs] quickstart by accessing the following content: +You can verify the deployment of the link:../helloworld-rs/README.adoc[helloworld-rs] quickstart by accessing the following content: * The _XML_ content can be viewed by accessing the following URL: http://localhost:8080/helloworld-rs/rest/xml * The _JSON_ content can be viewed by accessing this URL: http://localhost:8080/helloworld-rs/rest/json @@ -41,11 +41,11 @@ You can verify the deployment of the link:../helloworld-rs/README.md[helloworld- . Make sure you have started the {productName} server as described above. . Make sure the `helloworld-rs` quickstart has been deployed on the server as noted in the *Prerequisites* section above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type the following command to run the client: ---- -mvn clean package exec:java +$ mvn clean package exec:java ---- == Investigate the Console Output @@ -86,4 +86,4 @@ You can also start the server and deploy the quickstarts or run the Arquillian t ** Right-click on the `{artifactId}` project and choose `Run As` –> `Maven build`. ** Enter `clean package exec:java` for the `Goals:` and click `Run`. ** The client output displays in the `Console` window. -. To undeploy the `helloworld-rs` quickstart, right-click on the `helloworld-rs` project and choose `Run As` –> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. \ No newline at end of file +. To undeploy the `helloworld-rs` quickstart, right-click on the `helloworld-rs` project and choose `Run As` –> `Maven build`. Enter `wildfly:undeploy` for the `Goals` and click `Run`. diff --git a/servlet-async/README.adoc b/servlet-async/README.adoc index 99a76c261e..36be5d7032 100644 --- a/servlet-async/README.adoc +++ b/servlet-async/README.adoc @@ -32,31 +32,31 @@ not depend on this service. The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Use of {jbossHomeName} -In the following instructions, replace `{jbossHomeName}` with the actual path to your {productName} installation. The installation path is described in detail here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_{jbossHomeName}.md#use-of-eap_home-and-jboss_home-variables[Use of {jbossHomeName} and JBOSS_HOME Variables]. +In the following instructions, replace `__{jbossHomeName}__` with the actual path to your {productName} installation. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of {jbossHomeName} and JBOSS_HOME Variables]. == Start the Server -. Open a command prompt and navigate to the root of the {productName} directory. +. Open a terminal and navigate to the root of the {productName} directory. . The following shows the command line to start the server: [subs=normal] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +For Linux: $ __{jbossHomeName}__/bin/standalone.sh +For Windows: __{jbossHomeName}__\bin\standalone.bat ---- == Build and Deploy the Quickstart . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type this command to build and deploy the archive: ---- -mvn clean install wildfly:deploy +$ mvn clean install wildfly:deploy ---- . This will deploy `target/{artifactId}.war` to the running instance of the server. @@ -68,11 +68,11 @@ The application will be running at the following URL http://localhost:8080/{arti == Undeploy the Archive . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . When you are finished testing, type this command to undeploy the archive: ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- == Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse @@ -84,5 +84,5 @@ You can also start the server and deploy the quickstarts or run the Arquillian t If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. ---- - mvn dependency:sources + $ mvn dependency:sources ---- \ No newline at end of file diff --git a/servlet-filterlistener/README.adoc b/servlet-filterlistener/README.adoc index f6d9f54324..d91ce6eda9 100644 --- a/servlet-filterlistener/README.adoc +++ b/servlet-filterlistener/README.adoc @@ -28,31 +28,31 @@ This example contains the following classes: The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Use of {jbossHomeName} -In the following instructions, replace `{jbossHomeName}` with the actual path to your {productName} installation. The installation path is described in detail here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_{jbossHomeName}.md#use-of-eap_home-and-jboss_home-variables[Use of {jbossHomeName} and JBOSS_HOME Variables]. +In the following instructions, replace `__{jbossHomeName}__` with the actual path to your {productName} installation. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of {jbossHomeName} and JBOSS_HOME Variables]. == Start the Server -. Open a command prompt and navigate to the root of the {productName} directory. +. Open a terminal and navigate to the root of the {productName} directory. . The following shows the command line to start the server: [subs=normal] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +For Linux: $ __{jbossHomeName}__/bin/standalone.sh +For Windows: __{jbossHomeName}__\bin\standalone.bat ---- == Build and Deploy the Quickstart . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type this command to build and deploy the archive: ---- -mvn clean install wildfly:deploy +$ mvn clean install wildfly:deploy ---- . This will deploy `target/{artifactId}.war` to the running instance of the server. @@ -103,11 +103,11 @@ The following messages appear in the log when you type "This is only a test!" in == Undeploy the Archive . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . When you are finished testing, type this command to undeploy the archive: ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- == Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse @@ -119,5 +119,5 @@ You can also start the server and deploy the quickstarts or run the Arquillian t If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. ---- - mvn dependency:sources + $ mvn dependency:sources ---- \ No newline at end of file diff --git a/servlet-security/README.adoc b/servlet-security/README.adoc index b4ba565f02..3fc0a67051 100644 --- a/servlet-security/README.adoc +++ b/servlet-security/README.adoc @@ -47,17 +47,21 @@ Password: guestPwd1! Role: notauthorized ---- -_Note: This quickstart uses the H2 database included with {productNameFull} {productVersion}. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ +//************************************************* +// Add notes about use in a production environment. +//************************************************* +:uses-h2: +include::../development-shortcuts.adoc[leveloffset=+1] == System Requirements The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Use of {jbossHomeName} -In the following instructions, replace `{jbossHomeName}` with the actual path to your {productName} installation. The installation path is described in detail here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_{jbossHomeName}.md#use-of-eap_home-and-jboss_home-variables[Use of {jbossHomeName} and JBOSS_HOME Variables]. +In the following instructions, replace `__{jbossHomeName}__` with the actual path to your {productName} installation. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of {jbossHomeName} and JBOSS_HOME Variables]. == Configure the Server @@ -73,18 +77,18 @@ You can configure the server by running JBoss CLI commands. For your convenience + [subs="+quotes,attributes+"] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +For Linux: $ __{jbossHomeName}__/bin/standalone.sh +For Windows: __{jbossHomeName}__\bin\standalone.bat ---- . Review the `configure-server.cli` file in the root of this quickstart directory. This script adds security domain and HTTP authentication factory to the `elytron` subsystem in the server configuration and also configures the `undertow` subsystem to use the configured HTTP authentication factory for the Web application. -. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing {jbossHomeName} with the path to your server: +. 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: + [subs="+quotes,attributes+"] ---- -For Linux: {jbossHomeName}/bin/jboss-cli.sh --connect --file=configure-server.cli -For Windows: {jbossHomeName}\bin\jboss-cli.bat --connect --file=configure-server.cli +For Linux: $ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=configure-server.cli +For Windows: __{jbossHomeName}__\bin\jboss-cli.bat --connect --file=configure-server.cli ---- . Stop the {productName} server. @@ -95,7 +99,7 @@ After stopping the server, open the `{jbossHomeName}/standalone/configuration/st . The following datasource was added to the `datasources` subsystem. + -[source, xml] +[source,xml,options="nowrap"] ---- jdbc:h2:mem:servlet-security;DB_CLOSE_ON_EXIT=FALSE @@ -109,7 +113,7 @@ After stopping the server, open the `{jbossHomeName}/standalone/configuration/st . The following `security-realm` was added to the `elytron` subsystem. + -[source, xml] +[source,xml,options="nowrap"] ---- @@ -125,14 +129,14 @@ After stopping the server, open the `{jbossHomeName}/standalone/configuration/st . The following `role-decoder` was added to the `elytron` subsystem. + -[source, xml] +[source,xml,options="nowrap"] ---- ---- . The following `security-domain` was added to the `elytron` subsystem. + -[source, xml] +[source,xml,options="nowrap"] ---- @@ -141,7 +145,7 @@ After stopping the server, open the `{jbossHomeName}/standalone/configuration/st . The following `http-authentication-factory` was added to the `elytron` subsystem. + -[source, xml] +[source,xml,options="nowrap"] ---- @@ -154,7 +158,7 @@ After stopping the server, open the `{jbossHomeName}/standalone/configuration/st . The following `application-security-domain` was added to the `undertow` subsystem. + -[source, xml] +[source,xml,options="nowrap"] ---- @@ -165,23 +169,23 @@ This configuration tells `Undertow` that applications with the `servlet-security == Start the Server -. Open a command prompt and navigate to the root of the {productName} directory. +. Open a terminal and navigate to the root of the {productName} directory. . The following shows the command line to start the server: [subs=normal] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +For Linux: $ __{jbossHomeName}__/bin/standalone.sh +For Windows: __{jbossHomeName}__\bin\standalone.bat ---- == Build and Deploy the Quickstart . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type this command to build and deploy the archive: ---- -mvn clean install wildfly:deploy +$ mvn clean install wildfly:deploy ---- . This will deploy `target/{artifactId}.war` to the running instance of the server. @@ -219,11 +223,11 @@ HHH000431: Unable to determine H2 database version, certain features may not wor == Undeploy the Archive . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . When you are finished testing, type this command to undeploy the archive: ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- == Restore the Server Configuration @@ -237,17 +241,17 @@ You can restore the original server configuration by running the `restore-config + [subs="+quotes,attributes+"] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +For Linux: $ __{jbossHomeName}__/bin/standalone.sh +For Windows: __{jbossHomeName}__\bin\standalone.bat ---- -. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing {jbossHomeName} with the path to your server: +. 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: + [subs="+quotes,attributes+"] ---- -For Linux: {jbossHomeName}/bin/jboss-cli.sh --connect --file=restore-configuration.cli -For Windows: {jbossHomeName}\bin\jboss-cli.bat --connect --file=restore-configuration.cli +For Linux: $ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=restore-configuration.cli +For Windows: __{jbossHomeName}__\bin\jboss-cli.bat --connect --file=restore-configuration.cli ---- === Restore the Server Configuration Manually @@ -267,5 +271,5 @@ You can also start the server and deploy the quickstarts or run the Arquillian t If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. ---- -mvn dependency:sources ----- \ No newline at end of file +$ mvn dependency:sources +---- diff --git a/shopping-cart/README.adoc b/shopping-cart/README.adoc index 549c418ff3..3cfd121241 100644 --- a/shopping-cart/README.adoc +++ b/shopping-cart/README.adoc @@ -32,11 +32,11 @@ This simple Java client is launched using a `main` method. The remote client loo The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Use of {jbossHomeName} -In the following instructions, replace `{jbossHomeName}` with the actual path to your {productName} installation. The installation path is described in detail here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_{jbossHomeName}.md#use-of-eap_home-and-jboss_home-variables[Use of {jbossHomeName} and JBOSS_HOME Variables]. +In the following instructions, replace `__{jbossHomeName}__` with the actual path to your {productName} installation. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of {jbossHomeName} and JBOSS_HOME Variables]. == Configure the Server @@ -57,18 +57,18 @@ Follow the steps below to suppress system exception logging. + [subs="+quotes,attributes+"] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +For Linux: $ __{jbossHomeName}__/bin/standalone.sh +For Windows: __{jbossHomeName}__\bin\standalone.bat ---- . Review the `configure-system-exception.cli` file in the root of this quickstart directory. This script sets the `log-system-exceptions` attribute to `false` in the `ejb3` subsystem in the server configuration file. -. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing {jbossHomeName} with the path to your server: +. 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: + [subs="+quotes,attributes+"] ---- -For Linux: {jbossHomeName}/bin/jboss-cli.sh --connect --file=configure-system-exception.cli -For Windows: {jbossHomeName}\bin\jboss-cli.bat --connect --file=configure-system-exception.cli +For Linux: $ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=configure-system-exception.cli +For Windows: __{jbossHomeName}__\bin\jboss-cli.bat --connect --file=configure-system-exception.cli ---- . Stop the {productName} server. @@ -79,32 +79,32 @@ After stopping the server, open the `{jbossHomeName}/standalone/configuration/st You should see the following configuration in the `ejb3` subsystem. -[source, xml] +[source,xml,options="nowrap"] ---- - + ---- == Start the Server -. Open a command prompt and navigate to the root of the {productName} directory. +. Open a terminal and navigate to the root of the {productName} directory. . The following shows the command line to start the server: + [subs=normal] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +For Linux: $ __{jbossHomeName}__/bin/standalone.sh +For Windows: __{jbossHomeName}__\bin\standalone.bat ---- == Build and Deploy the Quickstart . Make sure you have started the {productName} server. See the instructions in the previous section. -. Open a command prompt and navigate to the `shopping-cart` quickstart directory +. Open a terminal and navigate to the `shopping-cart` quickstart directory . To build both the server component and the remote client program, deploy the server module, change into the examples shopping-cart directory and type the following: + ---- -mvn clean install wildfly:deploy +$ mvn clean install wildfly:deploy ---- . This Maven goal will deploy `server/target/{artifactId}-server.jar`. You can check the server console to see information messages regarding the deployment. @@ -129,19 +129,19 @@ INFO [org.jboss.as.server] (management-handler-thread - 3) WFLYSRV0010: Deploye Now start a client that will access the beans you just deployed. -You can use the command prompt from the previous step or open a new one and navigate to the root of the `shopping-cart` quickstart directory. +You can use the terminal from the previous step or open a new one and navigate to the root of the `shopping-cart` quickstart directory. Type the following command: ---- -mvn exec:java -f client/pom.xml +$ mvn exec:java -f client/pom.xml ---- NOTE: This quickstart requires `quickstart-parent` artifact to be installed in your local Maven repository. To install it, navigate to quickstarts project root directory and run the following command: ---- - mvn clean install + $ mvn clean install ---- == Investigate the Console Output @@ -188,17 +188,17 @@ You can restore the system exception configuration by running the `restore-syste + [subs="+quotes,attributes+"] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +For Linux: $ __{jbossHomeName}__/bin/standalone.sh +For Windows: __{jbossHomeName}__\bin\standalone.bat ---- -. Open a new command prompt, navigate to the root directory of this quickstart, and run the following command, replacing {jbossHomeName} with the path to your server: +. 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: + [subs="+quotes,attributes+"] ---- -For Linux: {jbossHomeName}/bin/jboss-cli.sh --connect --file=restore-system-exception.cli -For Windows: {jbossHomeName}\bin\jboss-cli.bat --connect --file=restore-system-exception.cli +For Linux: $ __{jbossHomeName}__/bin/jboss-cli.sh --connect --file=restore-system-exception.cli +For Windows: __{jbossHomeName}__\bin\jboss-cli.bat --connect --file=restore-system-exception.cli ---- === Restore the Server Configuration Manually @@ -209,11 +209,11 @@ For Windows: {jbossHomeName}\bin\jboss-cli.bat --connect --file=restore-system-e == Undeploy the Archive . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . When you are finished testing, type this command to undeploy the archive: + ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- == Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse @@ -233,5 +233,5 @@ This quickstart consists of multiple projects, so it deploys and runs differentl If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. ---- -mvn dependency:sources ----- \ No newline at end of file +$ mvn dependency:sources +---- diff --git a/shrinkwrap-resolver/README.adoc b/shrinkwrap-resolver/README.adoc index e8706beb83..46902f6840 100644 --- a/shrinkwrap-resolver/README.adoc +++ b/shrinkwrap-resolver/README.adoc @@ -44,7 +44,7 @@ The `shrinkwrap-resolver` quickstart demonstrates various use cases for ShrinkWr The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Start the Server @@ -53,8 +53,8 @@ All you need to build this project is {buildRequirements}. See https://github.co [subs=normal] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +For Linux: $ __{jbossHomeName}__/bin/standalone.sh +For Windows: __{jbossHomeName}__\bin\standalone.bat ---- == Run the Arquillian Tests @@ -66,10 +66,10 @@ This quickstart provides Arquillian tests. By default, these tests are configure . Type the following command to run the test goal with the following profile activated: ---- -mvn clean verify -Parq-remote +$ mvn clean verify -Parq-remote ---- -You can also let Arquillian manage the {productName} server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests[Run the Arquillian Tests]. +You can also let Arquillian manage the {productName} server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see link:{arquillianTestsDocUrl}[Run the Arquillian Tests]. == Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse @@ -102,6 +102,6 @@ Tests run: 3, Failures: 0, Errors: 0, Skipped: 0 If you want to debug the source code or look at the Javadocs of any library in the project, run either of the following commands to pull them into your local repository. The IDE should then detect them. ---- -mvn dependency:sources -mvn dependency:resolve -Dclassifier=javadoc +$ mvn dependency:sources +$ mvn dependency:resolve -Dclassifier=javadoc ---- \ No newline at end of file diff --git a/spring-greeter/README.adoc b/spring-greeter/README.adoc index 347a75578b..29c5e60b6c 100644 --- a/spring-greeter/README.adoc +++ b/spring-greeter/README.adoc @@ -46,7 +46,7 @@ The user is added and a message displays the new user id number. The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Start the Server @@ -63,7 +63,7 @@ For Windows: bin\standalone.bat . Make sure you have started the {productName} server as described above. . Open a command line and navigate to the root directory of this quickstart. . Type this command to build and deploy the archive: - mvn clean package wildfly:deploy + $ mvn clean package wildfly:deploy . This will deploy target/spring-greeter.war to the running instance of the server. If you do not have maven configured you can manually copy target/spring-greeter.war to {jbossHomeName}/standalone/deployments. @@ -79,7 +79,7 @@ The application will be running at the following URL: http://localhost:8080/{art . When you are finished testing, type this command to undeploy the archive: ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- Or you can manually remove the application by removing spring-greeter.war from {jbossHomeName}/standalone/deployments @@ -96,7 +96,7 @@ To run these tests, you must build the main project as described above. . Build the quickstart WAR using the following command: ---- -mvn clean package +$ mvn clean package ---- . Navigate to the functional-tests/ directory in this quickstart. @@ -104,14 +104,14 @@ mvn clean package . If you have a running instance of the {productName} server, as described above, run the remote tests by typing the following command: ---- -mvn clean verify -Parq-remote +$ mvn clean verify -Parq-remote ---- . If you prefer to run the functional tests using managed instance of the {productName} server, meaning the tests will start the server for you, type the following command: ---- -mvn clean verify -Parq-managed +$ mvn clean verify -Parq-managed ---- == Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse @@ -124,6 +124,6 @@ If you want to debug the source code or look at the Javadocs of any library in t commands to pull them into your local repository. The IDE should then detect them. ---- - mvn dependency:sources - mvn dependency:resolve -Dclassifier=javadoc + $ mvn dependency:sources + $ mvn dependency:resolve -Dclassifier=javadoc ---- \ No newline at end of file diff --git a/spring-kitchensink-basic/README.adoc b/spring-kitchensink-basic/README.adoc index d936b3fe27..04ebea3f49 100644 --- a/spring-kitchensink-basic/README.adoc +++ b/spring-kitchensink-basic/README.adoc @@ -32,7 +32,7 @@ and `<mvc:annotation-driven/>` are used to register both the non-rest and The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Start the Server @@ -41,8 +41,8 @@ All you need to build this project is {buildRequirements}. See https://github.co [subs=normal] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +For Linux: $ __{jbossHomeName}__/bin/standalone.sh +For Windows: __{jbossHomeName}__\bin\standalone.bat ---- == Build and Deploy the Quickstart @@ -52,7 +52,7 @@ For Windows: {jbossHomeName}\bin\standalone.bat . Type this command to build and deploy the archive: ---- -mvn clean install wildfly:deploy +$ mvn clean install wildfly:deploy ---- . This will deploy `target/{artifactId}.war` to the running instance of the server. @@ -68,7 +68,7 @@ The application will be running at the following URL: http://localhost:8080/{art . When you are finished testing, type this command to undeploy the archive: ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- == Run the Arquillian Functional Tests @@ -83,7 +83,7 @@ To run these tests, you must build the main project as described above. . Build the quickstart WAR using the following command: ---- -mvn clean package +$ mvn clean package ---- . Navigate to the functional-tests/ directory in this quickstart. @@ -91,14 +91,14 @@ mvn clean package . If you have a running instance of the {productName} server, as described above, run the remote tests by typing the following command: ---- -mvn clean verify -Parq-remote +$ mvn clean verify -Parq-remote ---- . If you prefer to run the functional tests using managed instance of the {productName} server, meaning the tests will start the server for you, type the following command: ---- -mvn clean verify -Parq-managed +$ mvn clean verify -Parq-managed ---- == Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse @@ -111,6 +111,6 @@ If you want to debug the source code or look at the Javadocs of any library in t commands to pull them into your local repository. The IDE should then detect them. ---- - mvn dependency:sources - mvn dependency:resolve -Dclassifier=javadoc + $ mvn dependency:sources + $ mvn dependency:resolve -Dclassifier=javadoc ---- \ No newline at end of file diff --git a/spring-kitchensink-springmvctest/README.adoc b/spring-kitchensink-springmvctest/README.adoc index 82aa483cb2..0bd9ef92af 100644 --- a/spring-kitchensink-springmvctest/README.adoc +++ b/spring-kitchensink-springmvctest/README.adoc @@ -35,7 +35,7 @@ and `<mvc:annotation-driven/>` are used to register both the non-rest and The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Start the Server @@ -44,8 +44,8 @@ All you need to build this project is {buildRequirements}. See https://github.co [subs=normal] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +For Linux: $ __{jbossHomeName}__/bin/standalone.sh +For Windows: __{jbossHomeName}__\bin\standalone.bat ---- == Build and Deploy the Quickstart @@ -55,7 +55,7 @@ For Windows: {jbossHomeName}\bin\standalone.bat . Type this command to build and deploy the archive: ---- -mvn clean install wildfly:deploy +$ mvn clean install wildfly:deploy ---- . This will deploy `target/{artifactId}.war` to the running instance of the server. @@ -71,7 +71,7 @@ The application will be running at the following URL: http://localhost:8080/{art . When you are finished testing, type this command to undeploy the archive: ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- == Run the Arquillian Functional Tests @@ -86,7 +86,7 @@ To run these tests, you must build the main project as described above. . Build the quickstart WAR using the following command: ---- -mvn clean package +$ mvn clean package ---- . Navigate to the functional-tests/ directory in this quickstart. @@ -94,14 +94,14 @@ mvn clean package . If you have a running instance of the {productName} server, as described above, run the remote tests by typing the following command: ---- -mvn clean verify -Parq-remote +$ mvn clean verify -Parq-remote ---- . If you prefer to run the functional tests using managed instance of the {productName} server, meaning the tests will start the server for you, type the following command: ---- -mvn clean verify -Parq-managed +$ mvn clean verify -Parq-managed ---- == Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse @@ -114,6 +114,6 @@ If you want to debug the source code or look at the Javadocs of any library in t commands to pull them into your local repository. The IDE should then detect them. ---- - mvn dependency:sources - mvn dependency:resolve -Dclassifier=javadoc + $ mvn dependency:sources + $ mvn dependency:resolve -Dclassifier=javadoc ---- \ No newline at end of file diff --git a/spring-petclinic/README.adoc b/spring-petclinic/README.adoc index a8d5faea8d..6bf3943939 100644 --- a/spring-petclinic/README.adoc +++ b/spring-petclinic/README.adoc @@ -51,7 +51,7 @@ _Note that the sample configurations for JDBC, JPA, and Spring Data JPA configur The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Start the Server @@ -60,8 +60,8 @@ All you need to build this project is {buildRequirements}. See https://github.co [subs=normal] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +For Linux: $ __{jbossHomeName}__/bin/standalone.sh +For Windows: __{jbossHomeName}__\bin\standalone.bat ---- == Build and Deploy the Quickstart @@ -71,7 +71,7 @@ For Windows: {jbossHomeName}\bin\standalone.bat . Type this command to build and deploy the archive: ---- -mvn clean package wildfly:deploy +$ mvn clean package wildfly:deploy ---- . This will deploy `spring-petclinic/target/{artifactId}.war` to the running instance of the server. @@ -100,7 +100,7 @@ WARN [com.github.dandelion.core.config.StandardConfigurationLoader] (default ta . When you are finished testing, type this command to undeploy the archive: ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- == Run the Arquillian Functional Tests @@ -113,13 +113,13 @@ NOTE: The arquillian-based functional tests deploy the application, so be sure y . If the application is still deployed from the previous section, undeploy it now. ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- . Build the quickstart WAR using the following command: ---- -mvn clean package +$ mvn clean package ---- . Navigate to the functional-tests/ directory in this quickstart. @@ -127,13 +127,13 @@ mvn clean package . If you have a running instance of the {productName} server, as described above, run the remote tests by typing the following command: ---- -mvn clean verify -Parq-remote +$ mvn clean verify -Parq-remote ---- . If you prefer to run the functional tests using managed instance of the {productName} server, meaning the tests will start the server for you, type the following command: ---- -mvn clean verify -Parq-managed +$ mvn clean verify -Parq-managed ---- . The `spring-petclinic` quickstart contains three configurations: JDBC, JPA, and Spring Data JPA. You should see the tests run 3 times, one for each configuration. @@ -162,6 +162,6 @@ Note: Eclipse/JBDS may generate a persistence.xml file in the src/main/resources If you want to debug the source code or look at the Javadocs of any library in the project, run either of the following commands to pull them into your local repository. The IDE should then detect them. ---- - mvn dependency:sources - mvn dependency:resolve -Dclassifier=javadoc + $ mvn dependency:sources + $ mvn dependency:resolve -Dclassifier=javadoc ---- \ No newline at end of file diff --git a/spring-resteasy/README.adoc b/spring-resteasy/README.adoc index 4182f72c33..e319a89f9f 100644 --- a/spring-resteasy/README.adoc +++ b/spring-resteasy/README.adoc @@ -23,7 +23,7 @@ The `spring-resteasy` quickstart demonstrates how to package and deploy a web ap The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Start the Server @@ -32,8 +32,8 @@ All you need to build this project is {buildRequirements}. See https://github.co [subs=normal] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +For Linux: $ __{jbossHomeName}__/bin/standalone.sh +For Windows: __{jbossHomeName}__\bin\standalone.bat ---- == Build and Deploy the Quickstart @@ -43,7 +43,7 @@ For Windows: {jbossHomeName}\bin\standalone.bat . Type this command to build and deploy the archive: ---- -mvn clean package wildfly:deploy +$ mvn clean package wildfly:deploy ---- . This deploys the `target/{artifactId}.war` to the running instance of the server. @@ -75,7 +75,7 @@ And the same set as above but using the `locating` path. . When you are finished testing, type this command to undeploy the archive: ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- == Run the Arquillian Functional Tests @@ -90,7 +90,7 @@ To run these tests, you must build the main project as described above. . Build the quickstart WAR using the following command: ---- -mvn clean package +$ mvn clean package ---- . Navigate to the functional-tests/ directory in this quickstart. @@ -98,12 +98,12 @@ mvn clean package . If you have a running instance of the {productName} server, as described above, run the remote tests by typing the following command: ---- -mvn clean verify -Parq-remote +$ mvn clean verify -Parq-remote ---- . If you prefer to run the functional tests using managed instance of the {productName} server, meaning the tests will start the server for you, type the following command: ---- -mvn clean verify -Parq-managed +$ mvn clean verify -Parq-managed ---- \ No newline at end of file diff --git a/tasks-jsf/README.adoc b/tasks-jsf/README.adoc index d4e4e715ca..35fe01a4c2 100644 --- a/tasks-jsf/README.adoc +++ b/tasks-jsf/README.adoc @@ -10,14 +10,14 @@ include::../attributes.adoc[] :level: Intermediate :technologies: JSF, JPA :source: {githubRepoUrl} -:prerequisites: tasks +:prerequisites: link:tasks/README{outfilesuffix}[tasks] [abstract] The `tasks-jsf` quickstart demonstrates how to use JPA persistence with JSF as the view layer. == What is it? -The `tasks-jsf` quickstart demonstrates how to use JPA persistence with JSF as view layer in an application deployed to {productNameFull}. It provides a JSF front end for the link:../tasks/README.md[tasks] quickstart. +The `tasks-jsf` quickstart demonstrates how to use JPA persistence with JSF as view layer in an application deployed to {productNameFull}. It provides a JSF front end for the link:../tasks/README.adoc[tasks] quickstart. The theme of this application is simple Task management with simple login. The project contains two entities - a `user` and a `task`. @@ -32,35 +32,39 @@ JSF is used to present the user two views. The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. -_Note: This quickstart uses the H2 database included with {productNameFull} {productVersion}. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ - -_Note: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in {productName} and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/[Configuration Guide] for {productNameFull}._ +//*************************************** +// Add notes about use in a production environment. +//*************************************** +:uses-h2: +:uses-ds-xml: +:performance-scalability: +include::../development-shortcuts.adoc[leveloffset=+1] == Use of {jbossHomeName} -In the following instructions, replace `{jbossHomeName}` with the actual path to your {productName} installation. The installation path is described in detail here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_{jbossHomeName}.md#use-of-eap_home-and-jboss_home-variables[Use of {jbossHomeName} and JBOSS_HOME Variables]. +In the following instructions, replace `__{jbossHomeName}__` with the actual path to your {productName} installation. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of {jbossHomeName} and JBOSS_HOME Variables]. == Start the {productName} Server -. Open a command prompt and navigate to the root of the {productName} directory. +. Open a terminal and navigate to the root of the {productName} directory. . The following shows the command line to start the server: [subs=normal] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +For Linux: $ __{jbossHomeName}__/bin/standalone.sh +For Windows: __{jbossHomeName}__\bin\standalone.bat ---- == Build and Deploy the Quickstart . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type this command to build and deploy the archive: ---- -mvn clean install wildfly:deploy +$ mvn clean install wildfly:deploy ---- . This will deploy `target/{artifactId}.war` to the running instance of the server. @@ -82,11 +86,11 @@ HHH000431: Unable to determine H2 database version, certain features may not wor == Undeploy the Archive . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . When you are finished testing, type this command to undeploy the archive: ---- -mvn wildfly:undeploy +$ mvn wildfly:undeploy ---- == Run the Arquillian Tests @@ -94,14 +98,14 @@ mvn wildfly:undeploy This quickstart provides Arquillian tests. By default, these tests are configured to be skipped as Arquillian tests require the use of a container. . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type the following command to run the test goal with the following profile activated: ---- -mvn clean verify -Parq-remote +$ mvn clean verify -Parq-remote ---- -You can also let Arquillian manage the {productName} server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/RUN_ARQUILLIAN_TESTS.md#run-the-arquillian-tests[Run the Arquillian Tests]. +You can also let Arquillian manage the {productName} server by using the `arq-managed` profile. For more information about how to run the Arquillian tests, see link:{arquillianTestsDocUrl}[Run the Arquillian Tests]. == Run the Quickstart in Red Hat JBoss Developer Studio or Eclipse @@ -112,5 +116,5 @@ You can also start the server and deploy the quickstarts or run the Arquillian t If you want to debug the source code of any library in the project, run the following command to pull the source into your local repository. The IDE should then detect it. ---- - mvn dependency:sources ----- \ No newline at end of file + $ mvn dependency:sources +---- diff --git a/tasks-rs/README.adoc b/tasks-rs/README.adoc index 1f12c8d2bb..ec46c825c9 100644 --- a/tasks-rs/README.adoc +++ b/tasks-rs/README.adoc @@ -10,7 +10,7 @@ include::../attributes.adoc[] :level: Intermediate :technologies: JPA, JAX-RS :source: {githubRepoUrl} -:prerequisites: tasks +:prerequisites: link:tasks/README{outfilesuffix}[tasks] [abstract] The `tasks-rs` quickstart demonstrates how to implement a JAX-RS service that uses JPA persistence. @@ -25,62 +25,65 @@ The `tasks-rs` quickstart demonstrates how to implement a JAX-RS service that us The application manages `User` and `Task` JPA entities. A user represents an authenticated principal and is associated with zero or more tasks. Service methods validate that there is an authenticated principal and the first time a principal is seen, a JPA User entity is created to correspond to the principal. JAX-RS annotated methods are provided for associating tasks with this user and for listing and removing tasks. -_Note: This quickstart uses the H2 database included with {productNameFull} {productVersion}. It is a lightweight, relational example datasource that is used for examples only. It is not robust or scalable, is not supported, and should NOT be used in a production environment!_ - -_Note: This quickstart uses a `*-ds.xml` datasource configuration file for convenience and ease of database configuration. These files are deprecated in {productName} and should not be used in a production environment. Instead, you should configure the datasource using the Management CLI or Management Console. Datasource configuration is documented in the https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/[Configuration Guide] for {productNameFull}._ +//************************************************* +// Add notes about use in a production environment. +//************************************************* +:uses-h2: +:uses-ds-xml: +include::../development-shortcuts.adoc[leveloffset=+1] == System Requirements The application this project produces is designed to be run on {productNameFull} {productVersion} or later. -All you need to build this project is {buildRequirements}. See https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_MAVEN_JBOSS_EAP7.md#configure-maven-to-build-and-deploy-the-quickstarts[Configure Maven for {productName} {productVersion}] to make sure you are configured correctly for testing the quickstarts. +All you need to build this project is {buildRequirements}. See link:{configureMavenDocUrl}[Configure Maven to Build and Deploy the Quickstarts] to make sure you are configured correctly for testing the quickstarts. == Use of {jbossHomeName} -In the following instructions, replace `{jbossHomeName}` with the actual path to your {productName} installation. The installation path is described in detail here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_{jbossHomeName}.md#use-of-eap_home-and-jboss_home-variables[Use of {jbossHomeName} and JBOSS_HOME Variables]. +In the following instructions, replace `__{jbossHomeName}__` with the actual path to your {productName} installation. The installation path is described in detail here: link:{useProductHomeDocUrl}[Use of {jbossHomeName} and JBOSS_HOME Variables]. == Add an Application User This quickstart uses secured management interfaces and requires that you create the following application user to access the running application. -[cols="<,<,<,<"] +[cols="20%,20%,20%,40%",options="headers"] |=== -|*UserName* |*Realm* |*Password* |*Roles* +|UserName |Realm |Password |Roles -|quickstartUser |ApplicationRealm |quickstartPwd1! |guest +|quickstartUser |ApplicationRealm |quickstartPwd1! |guest |=== -To add the application user, open a command prompt and type the following command: +To add the application user, open a terminal and type the following command: + [subs="+quotes,attributes+"] ---- -For Linux: {jbossHomeName}/bin/add-user.sh -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest' -For Windows: {jbossHomeName}\bin\add-user.bat -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest' +For Linux: $ __{jbossHomeName}__/bin/add-user.sh -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest' +For Windows: __{jbossHomeName}__\bin\add-user.bat -a -u 'quickstartUser' -p 'quickstartPwd1!' -g 'guest' ---- -If you prefer, you can use the add-user utility interactively. -For an example of how to use the add-user utility, see the instructions located here: https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CREATE_USERS.md#add-an-application-user[Add an Application User]. +If you prefer, you can use the `add-user` utility interactively. +For an example of how to use the add-user utility, see the instructions located here: link:{addApplicationUserDocUrl}[Add an Application User]. == Start the Server -. Open a command prompt and navigate to the root of the {productName} directory. +. Open a terminal and navigate to the root of the {productName} directory. . The following shows the command line to start the server: [subs=normal] ---- -For Linux: {jbossHomeName}/bin/standalone.sh -For Windows: {jbossHomeName}\bin\standalone.bat +For Linux: $ __{jbossHomeName}__/bin/standalone.sh +For Windows: __{jbossHomeName}__\bin\standalone.bat ---- == Build and Deploy the Quickstart . Make sure you have started the {productName} server as described above. -. Open a command prompt and navigate to the root directory of this quickstart. +. Open a terminal and navigate to the root directory of this quickstart. . Type this command to build and deploy the archive: ---- -mvn clean install wildfly:deploy +$ mvn clean install wildfly:deploy ---- . This will deploy `target/{artifactId}.war` to the running instance of the server. @@ -143,7 +146,7 @@ curl -H "Accept: application/xml" -u 'quickstartUser:quickstartPwd1!' -X GET htt Using either of the above _GET_ methods, you should see the following XML: -[source, xml] +[source,xml,options="nowrap"] ---- @@ -167,7 +170,7 @@ curl -H "Accept: application/xml" -u 'quickstartUser:quickstartPwd1!' -X GET htt Using either of the above _GET_ methods, you should see the following XML: -[source, xml] +[source,xml,options="nowrap"] ---- @@ -207,7 +210,7 @@ curl -u 'quickstartUser:quickstartPwd1!' -X GET http://localhost:8080/{artifactI You will see a response with an empty collection: -[source, xml] +[source,xml,options="nowrap"] ---- @@ -219,7 +222,7 @@ JSON is not part of the JAX-RS standard but most JAX-RS implementations do suppo . Open the `pom.xml` file and remove the comments from the dependency with artifactId `resteasy-jackson2-provider`. + -[source, xml] +[source,xml,options="nowrap"] ----