Information for users installing JBoss Web Framework Kit
Legal Notice
Abstract
Chapter 1. Introduction to Red Hat JBoss Web Framework Kit
1.1. About Red Hat JBoss Web Framework Kit
1.2. About the JBoss Web Framework Kit Tiers
- Tier 1 - Included Components
- These are components that are based wholly or partly on open source technologies that support broad collaboration and where Red Hat maintains a leadership role; as such Red Hat is able to support these components and provide upgrades and fixes under our standard support terms and conditions.
- Tier 2 - Tested Frameworks
- These are third-party frameworks where Red Hat does not have sufficient influence and does not provide upgrades and fixes under our standard support terms and conditions. Commercially reasonable support is provided by Red Hat Global Support Services for these frameworks.
- Tier 3 - Frameworks in Tested Examples
- These are third-party frameworks where Red Hat does not have sufficient influence and does not provide upgrades and fixes under our standard support terms and conditions. Red Hat supports the examples these frameworks are used in and the generic use cases that these examples intend to demonstrate.
- Tier 4 - Confirmed Frameworks
- These are third-party frameworks that do not receive any support from Red Hat, but Red Hat verifies that the frameworks run successfully on Red Hat JBoss Enterprise Application Platform. Frameworks and versions not listed here have not been explicitly tested and certified, and thus may be subject to support limitations.
1.3. About the JBoss Web Framework Kit Distribution
- The component frameworks are available from the Red Hat Customer Portal. They are distributed in two alternative formats: a binary for each framework or together as one Maven repository. In addition, the source code for each framework is provided for inspection.
- The third party frameworks are not distributed by Red Hat and each must be obtained from its own source.
.zip file available to download from the Red Hat Customer Portal or from http://www.jboss.org/developer-materials/ on the JBoss Developer Framework website.
- TicketMonster is a moderately complex application demonstrating a number of the JBoss Web Framework Kit frameworks working together.
- Quickstarts and Maven archeypes illustrate subsets of the JBoss Web Framework Kit frameworks used to create simple applications.
- RichFaces, Snowdrop and Seam demonstrations showcase the power of each framework in web application development.
Chapter 2. System Requirements
2.1. Platforms
2.2. Supported Operating Systems and Java Developer Kits
2.3. Apache Maven
Chapter 3. Use the JBoss Web Framework Kit Maven Repository
3.1. About the JBoss Web Framework Kit Maven Repository
Important
- a complete set of the tier 1 framework APIs and their dependent artifacts
- several Bill of Materials (BOM) for JBoss stacks
Note
3.2. Download and make Available the Maven Repository
.zip file. Once downloaded, you must extract the contents of the file and make it available for use by your preferred Maven management system: local file system, web server, Nexus Maven repository manager. The latter two systems host Maven repositories so making them accessible to multiple users and may require additional configuration as noted in the procedure below.
Procedure 3.1. Download and make Available the Maven Repository
- Log into the Red Hat Customer Portal at http://access.redhat.com.
- Locate the downloads for this release version of JBoss Web Framework Kit.
- Download the
.zipfile for the Red Hat JBoss Web Framework Kit Maven Repository. - Complete the appropriate steps for your Maven management system:
- For a local file system installation, extract the contents of the downloaded
.zipfile to the local file system location where you want to keep them. - For an Apache Web Server:
- Extract the contents of the downloaded
.zipfile to a web-accessible directory in the Apache Web Server, for example,/var/www/maven-repositories/. - In
/etc/httpd/conf.d/, create a new text file namedmaven-repositories.conf. This file will be used to enable read access and directory browsing of/var/www/maven-repositories/. - In the
maven-repositories.conffile, add the following:<Directory "/var/www/maven-repositories"> Options Indexes FollowSymLinks AllowOverride None Require all granted </Directory> Alias /maven-repositories /var/www/maven-repositories
This grants access to the contents of/var/www/maven-repositories/and provides an alias for the Maven repository path. - Save and close the file.
- For a Nexus Maven Repository Manager:
- Extract the contents of the downloaded
.zipfile to a suitable location in the Nexus file system. - Start the Nexus Repository Manager
- Add the JBoss Web Framework Kit Maven repository as a hosted repository, pointing to the extracted
.zipfile contents. - Add the JBoss Web Framework Kit Maven hosted repository to the desired repository group to make it available for use.
3.3. Configure Maven to Use the Repository
settings.xml file. There are two options available for configuring this file: manually using a text editor or automatically using JBoss Developer Studio. Both methods are detailed in the following sections.
example-settings.xml, is provided in the JBoss Web Framework Kit Maven repository .zip file demonstrating the JBoss EAP and JBoss Web Framework Kit Maven repository declarations. The repository URLs must be specified in the configuration file <url> fields and vary depending on the type of Maven repository management system in use. The table below gives example URLs for the JBoss Web Framework Kit Maven repository for various Maven repository management systems.
Table 3.1. Example URLs for Maven Repository Management Systems
| Maven Repository Management System | Example URL |
|---|---|
| Local file system | file:///home/user/projects/maven-repositories/jboss-wfk-maven-repository/ |
| Apache Web Server | http://intra.acme.com/maven-repositories/jboss-wfk-maven-repository/ |
| Nexus Repository Manager | https://intra.acme.com/nexus/content/repositories/jboss-wfk-maven-repository/ |
3.3.1. Configure Maven Manually
settings.xml file manually using a text editor, as detailed in the procedure below. Depending on your Maven setup, the settings.xml file may be unique to each user or shared by multiple users.
Procedure 3.2. Configure the Maven settings.xml File Manually
- Open the Maven
settings.xmlfile in a text editor. - Open the provided
/path/to/jboss-wfk-maven-repository/example-settings.xmlfor viewing. - Copy the JBoss Web Framework Kit
<profile>and<activeProfile>sections from theexample-settings.xmlfile to thesettings.xmlfile. - Replace the placeholder
<url>text with the path to the JBoss Web Framework Kit Maven repository installation. - Save and close the
settings.xmlfile.
3.3.2. Configure Maven in JBoss Developer Studio
setting.xml file for the JBoss Web Framework Kit Maven repository, as detailed in the procedure below.
Note
settings.xml file to be in a user's .m2 directory. If you are using a settings.xml file located elsewhere, change the IDE Maven settings in Preferences under Maven→User Settings before starting this procedure.
Procedure 3.3. Configure Maven in JBoss Developer Studio
- In JBoss Developer Studio, click →, expand JBoss Tools and select JBoss Maven Integration.
- Click .
- Click .
- Click .
- Navigate to
path/to/jboss-wfk-maven-repositoryand click . JBoss Maven Tools recursively scans the path searching for the Maven repository. Once found, the fields in the Add Maven Repository wizard are automatically complete. - Modify the information in the ID and Name fields as desired, ensure the Active by default check box is selected and click .
- Click and at the prompt asking if you are sure you want to update the Maven configuration file click . If the specified configuration file does not exist, JBoss Maven Tools creates it.
- Click and click to close the Preferences window.
Chapter 4. Use the JBoss Stacks
.pom file. Specifying these BOMs in your project pom.xml files enables use of the appropriate stacks and removes the need to explicitly specify the versions of stack artifacts required by your project.
4.1. Available JBoss Stacks
.zip file available to download from the Red Hat Customer Portal and individually from the JBoss Developer website.
com.redhat.jboss.wfk.boms and org.jboss.bom.wfk. These stacks specify versions of all relevant dependencies required when using JBoss Web Framework Kit frameworks with the supported platforms. The stacks in the org.jboss.bom.wfk group additionally define versions of all dependencies on Java EE 6 Specification APIs. The tables here list the stacks in each group and the core frameworks of each stack.
Table 4.1. JBoss Stacks in com.redhat.jboss.wfk.boms group
| JBoss Stack | Frameworks |
|---|---|
| spring-2.5-bom [a] | Spring 2.5 and Snowdrop |
| spring-3.0-bom [b] | Spring 3.0 and Snowdrop |
| spring-3.1-bom [c] | Spring 3.1 and Snowdrop |
| spring-3.2-bom [d] | Spring 3.2 and Snowdrop |
[a]
Spring 2.5 is deprecated as of JBoss Web Framework Kit 2.4.0 but continues to be tested and supported in JBoss Web Framework Kit 2.
[b]
Spring 3.0 is deprecated as of JBoss Web Framework Kit 2.5.0 but continues to be tested and supported in JBoss Web Framework Kit 2.
[c]
Spring 3.1 is deprecated as of JBoss Web Framework Kit 2.5.0 but continues to be tested and supported in JBoss Web Framework Kit 2.
[d]
Use the replacement jboss-javaee-6.0-with-spring stack introduced in JBoss Web Framework Kit 2.4.0 instead of this stack.
| |
Table 4.2. JBoss Stacks in org.jboss.bom.wfk group
| JBoss Stack | Frameworks |
|---|---|
| jboss-javaee-6.0-with-deltaspike | Deltaspike |
| jboss-javaee-6.0-with-hsearch | Hibernate Search |
| jboss-javaee-6.0-with-richfaces | RichFaces |
| jboss-javaee-6.0-with-spring | Spring 3.2 and Snowdrop |
| jboss-javaee-6.0-with-spring4 | Spring 4 and Snowdrop |
| jboss-javaee-6.0-with-spring4.1 | Spring 4.1 and Snowdrop |
| jboss-javaee-6.0-with-tools | Arquillian, Shrinkwrap, Selenium and other tools |
4.2. Add a JBoss Stack to a Project
pom.xml file, as detailed in the procedure below, to take advantage of the certified stacks.
Procedure 4.1. Add a JBoss Stack to a Project
- Open your project
pom.xmlfile for editing. - Locate the
<dependencyManagement>section. - Within the
<dependencies>tags, add the following:<dependency> <groupId>stack_group</groupId> <artifactId>stack_name</artifactId> <type>pom</type> <version>stack_version</version> <scope>import</scope> </dependency>
- Replace stack_group, stack_name and stack_version with the appropriate JBoss stacks group and the individual JBoss stack name and version. For example, replace with
com.redhat.jboss.wfk.boms,spring-3.2-bomand2.7.0-redhat-1to use the JBoss Web Framework Kit 2.6 JBoss stack for Spring 3.2 and Snowdrop. - Within the
<dependencies>tags that follow the<dependencyManagement>section, add the following for each dependency required by your project:<dependency> <groupId>dependency_group</groupId> <artifactId>dependency_name</artifactId> </dependency>
- Replace dependency_group and dependency_name with the appropriate dependency group and name. For example,
org.springframeworkandspring-coreto use the Spring core dependency. The version for the dependency is taken from the included JBoss stack.
Chapter 5. Use the Archetypes
5.1. Available Archetypes
Table 5.1. Archetypes in org.jboss.archetype.wfk group
| Artifact Id | Generated Application |
|---|---|
| jboss-html5-mobile-archetype | This archetype generates a Java EE 6 application that utilizes HTML5 and JAX-RS to support both desktop and mobile web browsers. |
| jboss-html5-mobile-blank-archetype | This archetype generates a blank Java EE 6 application that utilizes HTML5 and JAX-RS to support both desktop and mobile web browsers. This archetype provides only the required dependencies to get started. |
| jboss-spring-mvc-archetype | This archetype generates a starter Spring MVC application with Java EE persistence settings including server bootstrapped JPA and JTA transaction management. |
| richfaces-archetype-kitchensink | This archetype generates a kitchensink application that features annotation-driven CDI and Java Bean Validation on both the client side and the server side, plus JPA and JAX-RS on the server side only. |
| richfaces-archetype-simpleapp | This archetype generates a simple RichFaces application. |
5.2. Use the Archetypes with the Command Line
Procedure 5.1. Create a Project from an Archetype Using the Command Line
- On the command line, navigate to the directory where you want to create the project.
- On the command line enter
$ mvn archetype:generate \ -DarchetypeGroupId=org.jboss.archetype.wfk \ -DarchetypeArtifactId=archetype \ -DarchetypeVersion=version.Final
where archetype denotes the unique Artifact Id and version denotes the complete three-digit version number for this JBoss Web Framework Kit release (for example, 2.7.0.Final for JBoss Web Framework Kit 2.7.0). This starts the project generation process, downloading the necessary dependencies, and may take some time to complete. - At the prompts, accept the default values or enter your own values for groupId, artifactId, version and package of the new project. Once generated, the command line output displays
[INFO] BUILD SUCCESS
together with summary information about the build process.
Procedure 5.2. Compile and Deploy an Application using the Command Line
- Compile the Maven-based example to verify it builds successfully
$ mvn compile
- Start JBoss EAP
For Linux and OS X $ EAP_HOME/bin/standalone.sh For Windows $ EAP_HOME\bin\standalone.bat
- Build and deploy the application to JBoss EAP
$ mvn clean install jboss-as:deploy
- View the deployed application in a web browser at http://localhost:8080/application_name/, where application_name is replaced by the name of your application.
5.3. Use the Archetypes with JBoss Developer Studio
Note
Procedure 5.3. Create a Project from an Archetype Using a Maven Project Wizard
- Click →→.
- Ensure the Create a simple project check box is not selected and click .
- Click .
- Complete the fields about the specific JBoss Web Framework Kit archetype as follows:
- In the Archetype Group Id field, type
org.jboss.archetype.wfk. - In the Archetype Artifact Id field, type the unique Artifact Id.
- In the Archetype Version field, type
version.Finalwhere version denotes the complete three-digit version number for this JBoss Web Framework Kit release. For example,2.7.0.Finalfor JBoss Web Framework Kit 2.7.0. - In the Repository URL field, type
http://central.sonatype.org/.
- Click .
- From the archetype list, ensure the added archetype is selected and click .
- Complete the fields about the project to be created as follows:
- In the Group Id field, type a package for the project.
- In the Artifact Id field, type a name for the project.
- Click . Once the project is created, it is listed in the Project Explorer view.
Procedure 5.4. Compile and Deploy an Application Using JBoss Server Tools
- In the Project Explorer view, right-click the project name and click →.
- Under How do you want to select the server?, ensure Choose an existing server is selected.
- In the Server table, expand localhost, select jboss-eap-version where version denotes the JBoss EAP version, and click .
- Ensure that your project is listed in the Configured column and click . The Console view automatically becomes the view in focus and displays the output from the JBoss EAP server. Once deploying is complete, the web application opens in the IDE default web browser.
Chapter 6. Use the Examples
6.1. Available Examples
.zip files, as detailed here.
- demo.zip
- Contains one or more demo applications, with a demo.zip for several of the Tier 1 frameworks. Each demo illustrates multiple features from a single framework in use in a medium sized application.
- quickstarts.zip
- Contains many small applications demonstrating one or more frameworks in use together. Some of the quickstarts are part of collections, for example those named kitchensink and helloworld, and illustrate how to achieve the same web application using different underlying technologies. The source code for all of the quickstarts can also be obtained from http://www.jboss.org/developer-materials/ on the JBoss Developer website and the source for a subset of quickstarts can also be accessed directly within JBoss Developer Studio.
- ticketmonster.zip
- Contains one application, TicketMonster. It is a moderately complex application that demonstrates how to build modern web applications optimized for mobile and desktop using an array of different technologies. TicketMonster is representative of an online ticketing broker, providing access to events with an online booking application. The source code for this application can also be obtained from http://www.jboss.org/ticket-monster/ on the JBoss Developer website.
6.2. Use the Examples with the Command Line
Procedure 6.1. Use the Examples with the Command Line
- On the command line, navigate to the directory of a specific example, where the
pom.xmlfile for the example is located. - Compile the Maven-based example to verify it builds successfully
$ mvn compile
- Start JBoss EAP
For Linux and OS X $ EAP_HOME/bin/standalone.sh For Windows $ EAP_HOME\bin\standalone.bat
- Build and deploy the application to JBoss EAP
$ mvn clean install jboss-as:deploy
- View the deployed application in a web browser at http://localhost:8080/application_name/, where application_name is replaced by the name of your application.
Note
README.md file distributed with the example for any additional deployment information.
6.3. Use the Examples with JBoss Developer Studio
Procedure 6.2. Create an Example Using a Project Wizard
- In JBoss Central, under Start from a sample, select an application category and click one of the samples.
- In the New Project Example wizard, click . Once created, the project is listed in the Project Explorer view.
Procedure 6.3. Import an Example Using an Import Wizard
- Click →, expand Maven and double-click Existing Maven Projects.
- In the Root Directory field, enter the path to the example source code. Alternatively, click to navigate to the source code location. The wizard recursively searches the path for a
pom.xmlfile, which identifies the project as a Maven project. Thepom.xmlfile is listed under Projects once it is found. - Click . Once imported, the project is listed in the Project Explorer view.
Procedure 6.4. Compile and Deploy an Application Using JBoss Server Tools
- In the Project Explorer view, right-click the project name and click →.
- Under How do you want to select the server?, ensure Choose an existing server is selected.
- In the Server table, expand localhost, select jboss-eap-version where version denotes the JBoss EAP version, and click .
- Ensure that your project is listed in the Configured column and click . The Console view automatically becomes the view in focus and displays the output from the JBoss EAP server. Once deploying is complete, the web application opens in the default IDE web browser.
Chapter 7. Upgrade from Earlier Versions of JBoss Web Framework Kit
7.1. Upgrade from Earlier Versions of JBoss Web Framework Kit
settings.xml file enabling the Maven repository corresponding to this release.
pom.xml files. Note that upgrading from JBoss Web Framework Kit 2.3.0 requires additional dependency changes because the JBoss stacks were refactored in the 2.4.0 release.
7.2. Upgrade JBoss Stacks from JBoss Web Framework Kit 2.3.0 and Earlier
pom.xml files:
- JBoss stacks previously distributed in the
org.jboss.bomgroup moved to theorg.jboss.bom.wfkgroup. If you use any of the stacks from the previous group in your projects, update thegroupIdin the dependency declarations accordingly. - The JBoss stack
org.jboss.bom:jboss-javaee-6.0-with-hibernatepreviously distributed in the JBoss Web Framework Kit Maven repository has been removed.- To use Hibernate in your projects, use the JBoss stack
org.jboss.bom.eap:jboss-javaee-6.0-with-hibernatefrom the JBoss EAP Maven repository. - To use Hibernate together with Hibernate Search, use the JBoss stack
org.jboss.bom.wfk:jboss-javaee-6.0-with-hsearchfrom the JBoss Web Framework Kit Maven repository.
- The JBoss stack
org.jboss.bom:jboss-bom-parenthas been replaced byorg.jboss.bom.wfk:jboss-wfk-bom-parent. If you use the original stack in your projects, update thegroupIdandartifactIdin the dependency management declarations accordingly. - The JBoss stack
org.jboss.bom.wfk:jboss-javaee-6.0-with-springhas been introduced. If you use the JBoss stackcom.redhat.jboss.wfk.boms:spring-3.2-bomin your projects, it is recommended to replace it with the JBoss stackjboss-javaee-6.0-with-spring.