Red Hat JBoss Web Framework Kit 2.3 Errai Quickstart Guide

bootlessbwakInternet and Web Development

Nov 12, 2013 (3 years and 4 months ago)

59 views

Mike Brock
Jonathan Fuerth
Christian Sadilek
Red Hat JBoss Web Framework Kit
2.3
Errai Quickstart Guide
for use with Red Hat JBoss Enterprise Application Platform
Red Hat JBoss Web Framework Kit

2.3

Errai Quickstart Guide
for use with Red Hat JBoss Enterprise Application Platform
Mike

Brock
Jonathan

Fuerth
Christian

Sadilek
Edited by
RedHat Documentation Team
RedHat

Engineering Content Services
Legal Notice
Copyright
2013 Red Hat, Inc.
This document is licensed by Red Hat under the Creative Commons
Attribution-ShareAlike 3.0 Unported License. If you distribute this document, or a modified version of it,
you must provide attribution to Red Hat, Inc. and provide a link to the original. If the document is modified,
all Red Hat trademarks must be removed.
Red Hat, as the licensor of this document, waives the right to
enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable
law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, MetaMatrix, Fedora, the Infinity Logo,
and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux is
the registered trademark of Linus Torvalds in the United States and other countries.
Java is a registered
trademark of Oracle and/or its affiliates.
XFS is a trademark of Silicon Graphics International Corp. or its
subsidiaries in the United States and/or other countries.
MySQL is a registered trademark of MySQL AB
in the United States, the European Union and other countries.
Node.js is an official trademark of Joyent.
Red Hat Software Collections is not formally related to or endorsed by the official Joyent Node.js open
source or commercial project.
All other trademarks are the property of their respective owners.
1801
Varsity Drive
Raleigh, NC 27606-2072 USA
Phone: +1 919 754 3700
Phone: 888 733 4281
Fax: +1 919
754 3701
Keywords
Abstract
Errai provides a comprehensive framework and tools for building rich web applications, leveraging the
GWT compiler.
4
4
4
5
6
6
6
7
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
9
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
10
10
10
10
10
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
17
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Table of Contents
Preface
1. Document Conventions
1.1. Typographic Conventions
1.2. Pull-quote Conventions
1.3. Notes and Warnings
2. Getting Help and Giving Feedback
2.1. Do You Need Help?
2.2. Give us Feedback
Chapter 1. Technology Primer
Chapter 2. Errai Kitchen Sink Maven Archetype
Chapter 3. Errai and Red Hat JBoss Developer Studio
3.1. Required Plugins
3.1.1. Google Plugin for Eclipse (GPE)
3.1.2. Maven Integration for Eclipse (m2e)
3.2. Import into Red Hat JBoss Developer Studio
Revision History
Preface

5
Red Hat JBoss Web Framework Kit 2.3 Errai Quickstart Guide
6
Preface
1. Document Conventions
This manual uses several conventions to highlight certain words and phrases and draw attention to
specific pieces of information.
In PDF and paper editions, this manual uses typefaces drawn from the
Liberation Fonts
set. The
Liberation Fonts set is also used in HTML editions if the set is installed on your system. If not, alternative
but equivalent typefaces are displayed. Note: Red Hat Enterprise Linux 5 and later includes the
Liberation Fonts set by default.
1.1. Typographic Conventions
Four typographic conventions are used to call attention to specific words and phrases. These
conventions, and the circumstances they apply to, are as follows.
Mono-spaced Bold
Used to highlight system input, including shell commands, file names and paths. Also used to highlight
keys and key combinations. For example:
To see the contents of the file
my_next_bestselling_novel
in your current working
directory, enter the
cat my_next_bestselling_novel
command at the shell prompt
and press
Enter
to execute the command.
The above includes a file name, a shell command and a key, all presented in mono-spaced bold and all
distinguishable thanks to context.
Key combinations can be distinguished from an individual key by the plus sign that connects each part of
a key combination. For example:
Press
Enter
to execute the command.
Press
Ctrl
+
Alt
+
F2
to switch to a virtual terminal.
The first example highlights a particular key to press. The second example highlights a key combination:
a set of three keys pressed simultaneously.
If source code is discussed, class names, methods, functions, variable names and returned values
mentioned within a paragraph will be presented as above, in
mono-spaced bold
. For example:
File-related classes include
filesystem
for file systems,
file
for files, and
dir
for
directories. Each class has its own associated set of permissions.
Proportional Bold
This denotes words or phrases encountered on a system, including application names; dialog box text;
labeled buttons; check-box and radio button labels; menu titles and sub-menu titles. For example:
Choose
System

Preferences

Mouse
from the main menu bar to launch
Mouse
Preferences
. In the
Buttons
tab, click the
Left-handed mouse
check box and click
Close
to switch the primary mouse button from the left to the right (making the mouse
suitable for use in the left hand).
To insert a special character into a
gedit
file, choose
Applications

Accessories

Preface

7
Character Map
from the main menu bar. Next, choose
Search

Find…
from the
Character Map
menu bar, type the name of the character in the
Search
field and click
Next
. The character you sought will be highlighted in the
Character Table
. Double-click
this highlighted character to place it in the
Text to copy
field and then click the
Copy
button. Now switch back to your document and choose
Edit

Paste
from the
gedit
menu
bar.
The above text includes application names; system-wide menu names and items; application-specific
menu names; and buttons and text found within a GUI interface, all presented in proportional bold and all
distinguishable by context.
Mono-spaced Bold Italic
or
Proportional Bold Italic
Whether mono-spaced bold or proportional bold, the addition of italics indicates replaceable or variable
text. Italics denotes text you do not input literally or displayed text that changes depending on
circumstance. For example:
To connect to a remote machine using ssh, type
ssh
username
@
domain.name
at a shell
prompt. If the remote machine is
example.com
and your username on that machine is
john, type
ssh john@example.com
.
The
mount -o remount
file-system
command remounts the named file system. For
example, to remount the
/home
file system, the command is
mount -o remount /home
.
To see the version of a currently installed package, use the
rpm -q
package
command. It
will return a result as follows:
package-version-release
.
Note the words in bold italics above — username, domain.name, file-system, package, version and
release. Each word is a placeholder, either for text you enter when issuing a command or for text
displayed by the system.
Aside from standard usage for presenting the title of a work, italics denotes the first use of a new and
important term. For example:
Publican is a
DocBook
publishing system.
1.2. Pull-quote Conventions
Terminal output and source code listings are set off visually from the surrounding text.
Output sent to a terminal is set in
mono-spaced roman
and presented thus:
books Desktop documentation drafts mss photos stuff svn
books_tests Desktop1 downloads images notes scripts svgs
Source-code listings are also set in
mono-spaced roman
but add syntax highlighting as follows:
Red Hat JBoss Web Framework Kit 2.3 Errai Quickstart Guide
8
package org.
jboss
.
book
.
jca
.
ex1
;
import
javax.naming.InitialContext;
public

class
ExClient
{

public

static

void

main
(String args[])

throws
Exception
{
InitialContext iniCtx =
new
InitialContext();
Object ref = iniCtx.
lookup
(
"EchoBean"
);
EchoHome home = (EchoHome) ref;
Echo echo = home.
create
();
System.
out
.
println
(
"Created Echo"
);
System.
out
.
println
(
"Echo.echo('Hello') = "
+ echo.
echo
(
"Hello"
));
}
}
1.3. Notes and Warnings
Finally, we use three visual styles to draw attention to information that might otherwise be overlooked.
Note
Notes are tips, shortcuts or alternative approaches to the task at hand. Ignoring a note should
have no negative consequences, but you might miss out on a trick that makes your life easier.
Important
Important boxes detail things that are easily missed: configuration changes that only apply to the
current session, or services that need restarting before an update will apply. Ignoring a box
labeled 'Important' will not cause data loss but may cause irritation and frustration.
Warning
Warnings should not be ignored. Ignoring warnings will most likely cause data loss.
2. Getting Help and Giving Feedback
2.1. Do You Need Help?
If you experience difficulty with a procedure described in this documentation, visit the Red Hat Customer
Portal at
http://access.redhat.com
. Through the customer portal, you can:
search or browse through a knowledgebase of technical support articles about Red Hat products.
submit a support case to Red Hat Global Support Services (GSS).
access other product documentation.
Chapter 2. Errai Kitchen Sink Maven Archetype

9
Red Hat also hosts a large number of electronic mailing lists for discussion of Red Hat software and
technology. You can find a list of publicly available mailing lists at
https://www.redhat.com/mailman/listinfo
.
Click on the name of any mailing list to subscribe to that list or to access the list archives.
2.2. Give us Feedback
If you find a typographical error, or know how this guide can be improved, we would love to hear from
you. Submit a report in Bugzilla against the product
JBoss Enterprise WFK Platform 2
and the
component
doc-Errai-Quickstart-Guide
. The following link will take you to a pre-filled bug report
for this product:
http://bugzilla.redhat.com/
.
Fill out the following template in Bugzilla's
Description
field. Be as specific as possible when
describing the issue; this will help ensure that we can fix it quickly.
Document URL:
Section Number and Name:
Describe the issue:
Suggestions for improvement:
Additional information:
Be sure to give us your name so that you can receive full credit for reporting the issue.
Red Hat JBoss Web Framework Kit 2.3 Errai Quickstart Guide
10
Chapter 1. Technology Primer
Errai is an end-to-end framework whose certain parts run and operate in the client, while other parts run
and operate on the server. This chapter describes the most important technologies which Errai relies on.
It is recommended to get familiar with these technologies before starting to use Errai.
Google Web Toolkit (GWT)
Google Web Toolkit (GWT) is a toolkit built around a Java-to-JavaScript compiler. It provides a
Java Runtime Environment (JRE) emulation library, abstraction of browser quirks, a
development mode runtime, and tools for native JavaScript integration.
Errai uses GWT to accomplish the translation of concepts such as Contexts and Dependency
Injection (CDI) into the browser, which enables a consisted client and server programming
experience.
Contexts and Dependency Injection (CDI)
Contexts and Dependency Injection (CDI) is a standard part of the Java EE 6.0 stack, and is
specified in the
JSR-299
specification.
Errai supports CDI in two different ways. On the server-side, Errai integrates with Weld, which is
the reference implementation (RI) of the JSR-299 specification. On the client-side, CDI
integration is provided by the Errai CDI extension. The Errai CDI extension implements a subset
of the JSR-299 specification to provide the CDI programming model in client code.
ErraiBus
ErraiBus is an underlying transport technology which provides true bidirectional asynchronous
messaging between the client and the server. It powers a number of technologies throughout
the Errai framework, from remote procedure calls (RPC) to CDI events.
Java API for RESTful Web Services (JAX-RS)
Java API for RESTful Web Services (JAX-RS) is an API which provides a standardized
programming model for specifying web services based around the concept of Representational
State Transfer (REST) architecture.
REST has become the preferred way of developing web services, and is used pervasively in
modern web applications. Errai provides a set of tools that make working with JAX-RS easier.
Maven
Maven is a tool used to automate project builds and manage project dependencies. Errai itself
is built using Maven, and comes with a set of Maven archetypes published in the Maven Central
Repository. These archetypes can be used to generate a working skeleton of an Errai project,
as described in
Chapter 2,
Errai Kitchen Sink Maven Archetype
.
Chapter 3. Errai and Red Hat JBoss Developer Studio

11
Chapter 2. Errai Kitchen Sink Maven Archetype
The Errai Kitchen Sink archetype generates an Errai project that uses a large variety of different
technologies: 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. It also demonstrates usage of Errai RPC and GWT
UiBinder.
To create the Errai Kitchen Sink project layout using a Maven build structure suitable for import into Red
Hat JBoss Developer Studio, execute the following command:
mvn archetype:generate \
-DarchetypeGroupId=org.jboss.errai.archetypes \
-DarchetypeArtifactId=jboss-errai-kitchensink-archetype \
-DarchetypeVersion=2.3.2.Final \
-Denterprise=true
When prompted, customize the build properties according to your needs.
Define value for property 'groupId': : foo.bar
Define value for property 'artifactId': : my-kitchen-sink
Define value for property 'version': 1.0-SNAPSHOT: :
Define value for property 'package': foo.bar: : com.foo.bar
Confirm properties configuration:
groupId: foo.bar
artifactId: my-kitchen-sink
version: 1.0-SNAPSHOT
package: com.foo.bar
Y: : Y
The project will be created in a directory whose name corresponds to the provided
artifactId
.
In a few simple steps, you have created a build environment that can build, test, package, and launch the
Errai Kitchen Sink application. You can now launch GWT Development Mode, run integration tests with
coverage reporting, and package your web application for deployment.
To get your application running, ensure there is a local instance of JBoss Enterprise Application Platform
6.0.0 or newer running locally, and execute the following commands:
mvn package
mvn jboss-as:deploy
You can then try out the application by navigating your web browser to
http://localhost:8080/my-kitchen-
sink/
(where
my-kitchen-sink
is the
artifactId
you specified when generating the project).
To launch the application in GWT Development Mode, keep JBoss Enterprise Application Platform
running, change into the project directory (name corresponding to the provided
artifactId
), and
execute:
mvn gwt:run (launch hosted mode)
mvn gwt:debug (launch hosted with debug settings)
Please remember that in this project, GWT Development Mode's built-in Jetty server is disabled. Your
application must be running on JBoss Enterprise Application Platform, as mentioned previously.
Red Hat JBoss Web Framework Kit 2.3 Errai Quickstart Guide
12
Chapter 3. Errai and Red Hat JBoss Developer Studio
3.1. Required Plugins
3.1.1. Google Plugin for Eclipse (GPE)
Google Plugin for Eclipse (GPE)
is a plugin that facilitates development of Java applications utilizing
Google developer technologies. This includes Google Web Toolkit, the development toolkit on which the
Errai framework is based.
For detailed instructions on installing Google Plugin for Eclipse in Red Hat JBoss Developer Studio, see
Google Plugin for Eclipse Installation Instructions
. When selecting optional components during the
installation, make sure to select
Google Web Toolkit SDK
under the
SDKs
category.
3.1.2. Maven Integration for Eclipse (m2e)
To manage the Maven projects based on the archetypes presented in
Chapter 2,
Errai Kitchen Sink
Maven Archetype
from within JBoss Developer Studio, the
Maven Integration for Eclipse (m2e)
plugin is
required.
Maven Integration for Eclipse (m2e) is included in the default installation of JBoss Developer Studio, and
no installation nor additional configuration of this plugin is needed to successfully use it with your Errai
projects.
3.2. Import into Red Hat JBoss Developer Studio
Once you have the required plugins installed and a Maven project generated based on one of the Errai
archetypes, you can import the project into Red Hat JBoss Developer Studio by following
Procedure 3.1,
“Importing Errai Projects into Red Hat JBoss Developer Studio”
.
Procedure 3.1. Importing Errai Projects into Red Hat JBoss Developer Studio
1
.
To initiate the import process, choose
File

Import...
from JBoss Developer Studio's main
menu.
Chapter 3. Errai and Red Hat JBoss Developer Studio

13
Figure 3.1. Initiating the import process
2
.
You will be presented with the import source selection dialog. As you are importing a Maven
project, select
Maven

Existing Maven Projects
and click the
Next
button.
Figure 3.2. Import source selection dialog
3
.
The
Maven Projects
selection dialog will be displayed. In the
Root Directory
field, you
need to specify the path to the root directory of the generated project. This can be done either
manually, or by clicking the
Browse...
button and selecting the the directory from the displayed
directory tree.
Red Hat JBoss Web Framework Kit 2.3 Errai Quickstart Guide
14
Once you have the path specified, make sure that its
pom.xml
file is recognized and selected in
the
Projects
list. Then click the
Finish
button to initiate the import process.
Figure 3.3. Maven project selection
4
.
When the import process finishes, you will see your project imported in
Project Explorer
.
The
App
class generated by the archetype will be located within the
client.local
package
under the package root that you specified when generating the project.
Figure 3.4. The App class of the imported project
Chapter 3. Errai and Red Hat JBoss Developer Studio

15
5
.
The imported project needs to be configured as a Google Web Toolkit project in order to enable
the features of Google Plugin for Eclipse. You can do this by right-clicking the project root in
Project Explorer
and selecting the
Google

Web Toolkit Settings...
option from the
menu.
Figure 3.5. Accessing Google Web Toolkit settings
6
.
To enable the Google Web Toolkit features of the plugin, enable the
Use Google Web Toolkit
option in the dialog that appears.
Figure 3.6. Enabling Google Web Toolkit features
Red Hat JBoss Web Framework Kit 2.3 Errai Quickstart Guide
16
7
.
Click the
Add...
button next to the
Entry Point Modules
list. In the module selection dialog,
select the
App
module of the imported project and click
OK
.
Figure 3.7. Selecting the application's entry point module
8
.
Select the
Google

Web Application
setting category from the tree on the left. In the category,
enable the
This project has a WAR directory
option and enter
src/main/webapp
into the
WAR directory
field. Then click
OK
to close the settings dialog.
Figure 3.8. Specifying the application's WAR directory
9
.
After closing the settings dialog, you may be presented with a warning that Google Web Toolkit
Revision History

17
features require reopening of already open editors. In this case, click the
Re-open Java
editors
button to reopen them.
10
.
Right-click the application's root in
Project Explorer
and choose
Run As

Web
Application
.
Figure 3.9. Running the application
11
.
You will be presented with a dialog asking you to select the initial HTML page. Select the
App.html
page and click
OK
.
Figure 3.10. Initial HTML page selection dialog
Red Hat JBoss Web Framework Kit 2.3 Errai Quickstart Guide
18
12
.
The application will start and you will see the startup log display the Weld and Errai bootstrapping
information. When bootstrapping finishes, you will be presented with a panel showing the
application's URL. Double-click the URL to open the application.
Figure 3.11. Panel showing the application's URL
13
.
Your web browser will be opened, displaying imported application in full functionality. This means
that you have imported the generated application into JBoss Developer Studio successfully.
Figure 3.12. Application displayed in a web browser
Revision History

19
Revision History
Revision 2.3.0-100
Tue Jul 9 2013
Petr

Penicka
Incorporated changes for the release of JBoss Web Framework Kit 2.3.0.
Revision 2.2.0-100
Tue Apr 23 2013
Petr

Penicka
Incorporated changes for the release of JBoss Web Framework Kit 2.2.0.
Revision 2.1.0-100
Tue Oct 02 2012
Isaac

Rooskov
Incorporated changes for the release of JBoss Web Framework Kit 2.1.0.
Red Hat JBoss Web Framework Kit 2.3 Errai Quickstart Guide
20