Skip to content

Commit

Permalink
JBEAP-9695 - Replace header markup syntax to use # and general cleanu…
Browse files Browse the repository at this point in the history 
…p of README files
  • Loading branch information
@sgilda
sgilda committed Mar 21, 2017
1 parent 0ce0c02 commit 78cd05b
Show file tree
Hide file tree
Showing 98 changed files with 2,040 additions and 3,112 deletions.
50 changes: 19 additions & 31 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,12 +1,11 @@
${product.name.full} (${product.name}) Quickstarts
====================
# ${product.name.full} (${product.name}) Quickstarts

Summary: 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 ${product.name.full} ${product.version} or later. We recommend using the ${product.name} ZIP file. This version uses the correct dependencies and ensures you test and compile against your runtime environment.
These quickstarts run on ${product.name.full} ${product.version} or later. We recommend using the ${product.name} 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:

Expand All @@ -26,14 +25,12 @@ Be sure to read this entire document before you attempt to work with the quickst

* [Contributing Guide](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONTRIBUTING.md#jboss-developer-contributing-guide): This document contains information targeted for developers who want to contribute to JBoss developer projects.

Use of ${jboss.home.name} and JBOSS_HOME Variables
---------------------------------
## Use of ${jboss.home.name} and JBOSS_HOME Variables

The quickstart README files use the *replaceable* value `${jboss.home.name}` to denote the path to the ${product.name} installation. When you encounter this value in a README file, be sure to replace it with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-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.

Expand All @@ -43,8 +40,7 @@ _Note_: Some of these quickstarts use the H2 database included with ${product.na
[TOC-quickstart]


Suggested Approach to the Quickstarts
-------------------------------------
## Suggested Approach to the Quickstarts

We suggest you approach the quickstarts as follows:

Expand All @@ -53,20 +49,18 @@ We suggest you approach the quickstarts as follows:
* 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 ${product.name.full} ${product.version} or later.
The applications these projects produce are designed to be run on ${product.name.full} ${product.version} or later.

All you need to build these projects is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](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) to make sure you are configured correctly for testing the quickstarts.

To run these quickstarts with the provided build scripts, you need the ${product.name} distribution ZIP. For information on how to install and run JBoss, see the [${product.name.full} Documentation](https://access.redhat.com/documentation/en/red-hat-jboss-enterprise-application-platform/) _Getting Started Guide_ located on the Customer Portal.

You can also use [JBoss Developer Studio or Eclipse](#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts) to run the quickstarts.
You can also use [JBoss Developer Studio or Eclipse](#use-jboss-developer-studio-or-eclipse-to-run-the-quickstarts) 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:

Expand All @@ -76,7 +70,7 @@ The root folder of each individual quickstart contains a README file with specif

### 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.
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
Expand All @@ -97,18 +91,17 @@ In most cases, you can use the following steps to build and deploy the applicati
3. Use this command to build and deploy the archive:

mvn clean install wildfly:deploy

#### Undeploy an Archive

The command to undeploy the quickstart is simply:
The command to undeploy the quickstart is simply:

mvn wildfly:undeploy


### 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.
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.

To build the quickstarts:

Expand All @@ -120,7 +113,6 @@ To build the quickstarts:


### 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.

Expand All @@ -135,21 +127,17 @@ You can undeploy quickstarts using the following procedure:
To undeploy any quickstarts that fail due to complex dependencies, follow the undeploy procedure described in the quickstart's README file.


Run the Quickstarts in Red Hat JBoss Developer Studio or Eclipse
------------------------------------------------------------
## 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 ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}).

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 ${product.name} server, and build and deploy a quickstart, see [Use JBoss Developer Studio or Eclipse to Run the Quickstarts](${use.eclipse.url}).

## 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.

* [Create Users Required by the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CREATE_USERS.md#create-users-required-by-the-quickstarts): Add a Management or Application user for the quickstarts that run in a secured mode.

* [Configure the PostgreSQL Database for Use with the Quickstarts](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): The PostgreSQL database is used for the distributed transaction quickstarts.

* [Configure Byteman for Use with the Quickstarts](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CONFIGURE_BYTEMAN.md#configure-byteman-for-use-with-the-quickstarts): This tool is used to demonstrate crash recovery for distributed transaction quickstarts.



48 changes: 18 additions & 30 deletions app-client/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
app-client: Use the ${product.name} Application Client Container
======================================================
# app-client: Use the ${product.name} Application Client Container

Author: Wolf-Dieter Fink
Level: Intermediate
Technologies: EJB, EAR, AppClient
Expand All @@ -8,8 +8,7 @@ Target Product: ${product.name}
Source: <${github.repo.url}>


What is it?
-----------
## What is it?

The `app-client` quickstart demonstrates how to use the ${product.name} client container to start the client `Main` program and provide Dependency Injections (DI) for client applications in ${product.name.full}. It also shows you how to use Maven to package the application according to the JavaEE specification.

Expand All @@ -26,22 +25,19 @@ The root `pom.xml` file builds each of the subprojects in the appropriate order.



System requirements
-------------------
## System Requirements

The application this project produces is designed to be run on ${product.name.full} ${product.version} or later.
The application this project produces is designed to be run on ${product.name.full} ${product.version} or later.

All you need to build this project is ${build.requirements}. See [Configure Maven for ${product.name} ${product.version}](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) to make sure you are configured correctly for testing the quickstarts.


Use of ${jboss.home.name}
---------------
## Use of ${jboss.home.name}

In the following instructions, replace `${jboss.home.name}` with the actual path to your ${product.name} installation. The installation path is described in detail here: [Use of ${jboss.home.name} and JBOSS_HOME Variables](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/USE_OF_${jboss.home.name}.md#use-of-eap_home-and-jboss_home-variables).


Add the Application Users
---------------
## Add the Application Users

If the client and server are run on different hosts, you must add the following users to the ${product.name} server side application. Be sure to use the names and passwords specified in the table as they are required to run this example.

Expand All @@ -63,8 +59,7 @@ To add the users, open a command prompt and type the following commands:
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: [Add an Application User](https://github.com/jboss-developer/jboss-developer-shared-resources/blob/master/guides/CREATE_USERS.md#add-an-application-user).


Start the ${product.name} Server
-------------------------
## Start the Server

1. Open a command prompt and navigate to the root of the ${product.name} directory.
2. The following shows the command line to start the server:
Expand All @@ -73,8 +68,7 @@ Start the ${product.name} Server
For Windows: ${jboss.home.name}\bin\standalone.bat


Build and Deploy the Quickstart
-------------------------
## Build and Deploy the Quickstart

1. Make sure you have started the ${product.name} server as described above.
2. Open a command prompt and navigate to the root directory of this quickstart.
Expand All @@ -84,8 +78,7 @@ Build and Deploy the Quickstart



Access the Remote Client Application from the same machine
---------------------
## Access the Remote Client Application from the Same Machine

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.

Expand All @@ -109,16 +102,15 @@ This example shows how to invoke an EJB from a remote standalone application on
ClientContext is here = {Client =myhost}


Access the Remote Client Application from a different machine
---------------------
## Access the Remote Client Application from a Different Machine

This example shows how to invoke an EJB from a remote standalone Java EE application on a different machine. In this case, the client needs to define a properties file to define properties to connect and authenticate to the server. The properties file is passed on the command line using the `--ejb-client-properties` argument.

### Configure Machine_1 (Remote Server Machine)

1. Install ${product.name} on this machine.
2. Add the application users to the ${product.name} server on this machine as described above.
3. Start the ${product.name} 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.
3. Start the ${product.name} 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.

For Linux: ${jboss.home.name}/bin/standalone.sh -b MACHINE_1_IP_ADDRESS -bmanagement MACHINE_1_IP_ADDRESS
For Windows: ${jboss.home.name}\bin\standalone.bat -b MACHINE_1_IP_ADDRESS -bmanagement MACHINE_1_IP_ADDRESS
Expand All @@ -127,7 +119,7 @@ This example shows how to invoke an EJB from a remote standalone Java EE applica
### Configure Machine_2 (Local Client Machine)

1. Install ${product.name} on this server. There is no need to add the application users to this server.
2. Download the `app-client` quickstart to this machine.
2. Download the `app-client` quickstart to this machine.
3. 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`.

remote.connectionprovider.create.options.org.xnio.Options.SSL_ENABLED=false
Expand Down Expand Up @@ -165,8 +157,8 @@ This example shows how to invoke an EJB from a remote standalone Java EE applica



Undeploy the Archive from the Local machine
--------------------
## Undeploy the Archive from the Local Machine


Follow these instructions if you are testing the quickstart on the same machine.

Expand All @@ -175,18 +167,14 @@ Follow these instructions if you are testing the quickstart on the same machine.
3. When you are finished testing, type this command to undeploy the archive from the local machine.

mvn wildfly:undeploy

Undeploy the Archive from the Remote Machine
--------------------

Follow these instructions if you are testing the quickstart on a diffent machine.
## Undeploy the Archive from the Remote Machine

Follow these instructions if you are testing the quickstart on a different machine.

1. Make sure you have started the ${product.name} server on the remote server machine, `Machine_1`, where the quickstart is deployed as described above.
2. Open a command prompt on the local client machine, `Machine_2`, and navigate to the root directory of this quickstart.
3. When you are finished testing, type this command to undeploy the archive from the remote server machine, `Machine_1`.

mvn wildfly:undeploy -Dwildfly.hostname=MACHINE_1_IP_ADDRESS [-Dwildfly.port=9099] -Dwildfly.username=admin -Dwildfly.password=admin-123


Loading

0 comments on commit 78cd05b

Please sign in to comment.