= Errai Reference Guide
:doctype: book

[[sid-5833084]]

== Introduction

[[sid-5833083]]

=== What is it?

Errai is a GWT-based framework for building rich web applications using next-generation web technologies. Built on-top of ErraiBus, the framework provides a unified federation and RPC infrastructure with true, uniform, asynchronous messaging across the client and server.

[[sid-5833091]]

=== Required software

Errai requires a JDK version 6 or higher and depends on Apache Maven to build and run the examples, and for leveraging the quickstart utilities.

* JDK 6.0: http://java.sun.com/javase/downloads/index.jsp
* Apache Maven: http://maven.apache.org/download.html

[[sid-54493220]]

=== Getting Started with Errai

Errai is a framework which combines a constellation of web and server-side technologies to assist you in developing large, scaleable rich web applications using a consistent, standardized programming model for client and server development.

[[sid-54493220_GettingStartedwithErrai-TechnologyPrimer]]

==== Technology Primer

Since Errai is an end-to-end framework, in that, parts of the framework run and operate within the client and parts run and operate within the server, there is a set of various technologies upon which Errai relies. This section will detail the basic core technologies which you'll need to be familiar with.

[[sid-54493220_GettingStartedwithErrai-GoogleWebToolkit%28GWT%29]]

===== Google Web Toolkit (GWT)

GWT is a toolkit built around a Java-to-JavaScript compiler. It provides a 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 CDI into the browser, which enables a consistent client and server programming experience.

[[sid-54493220_GettingStartedwithErrai-ContextsandDependencyInjection%28CDI%29]]

===== Contexts and Dependency Injection (CDI)

CDI is a standard part of the Java EE 6.0 stack, and is defined in the link:$$http://jcp.org/en/jsr/detail?id=299$$[JSR-299] specification. CDI is the main programming model explored in this guide. As such, the basic concepts of CDI will be introduced in this guide, so pre-existing knowledge is not strictly necessary.

Errai's support for CDI is two-fold. For the server-side, Errai has integration with Weld, which is the reference implementation (RI) of the JSR-299 specification. The client-side integration for CDI is provided by the Errai CDI extension. Errai CDI implements a subset of the JSR-299 specification to provide the CDI programming model within client code.

[[sid-54493220_GettingStartedwithErrai-JavaAPIforRESTfulWebServices%28JAXRS%29]]

===== Java API for RESTful Web Services (JAX-RS)

JAX-RS is an API which provides a standardized programming model for specifying web services based around the concept of the Representational State Transfer (REST) architecture. REST has by and far become the preferred way of developing web services, and is used pervasively in modern web applications. Errai provides a set of tools to make working with JAX-RS easier.

[[sid-54493220_GettingStartedwithErrai-ErraiBus]]

===== ErraiBus

ErraiBus is an underlying transport technology which provides true, bidirectional, asynchronous messaging between the client and the server. It powers a myriad of technologies throughout the Errai framework, from RPC to CDI Events.

[[sid-54493220_GettingStartedwithErrai-Creatingyourfirstproject]]

==== Creating your first project

[IMPORTANT]
.Maven Required
====
The first thing you'll need to do if you have not already, is link:$$http://maven.apache.org/guides/getting-started/maven-in-five-minutes.html$$[install Maven]. If you have not already installed Maven, do so now.

Warning: If you use maven2, you will run into this problem: https://community.jboss.org/thread/177645
====

You have two options to set up an Errai application. You can start by copying an existing example application (i.e. the link:$$https://github.com/errai/errai-tutorial/archive/master.zip$$[errai tutorial demo]) or by building an app with the Errai Forge Addon:

[[sid-54493220_GettingStartedwithErrai-Startfromaworkingexampleapplication]]

===== Start from a working example application

Simply download and unzip this link:$$https://github.com/errai/errai-tutorial/archive/master.zip$$[demo]. Check out the README file and continue with running the app in <<sid-54493220_GettingStartedwithErrai-RunningtheappinGWT,GWT's development mode>> and importing the project into <<sid-54493220_GettingStartedwithErrai-ConfiguringyourprojectforEclipse,Eclipse>>.

[[sid-54493220_GettingStartedwithErrai-ErraiForgeAddon]]

===== Starting with the Errai Forge Addon

[WARNING]
.Deprecated
====
The Errai Forge Addon is deprecated. It is no longer being updated and will be removed in a future release.
====

Another way to start a new project with Errai is to use Forge and the Errai Forge Addon. To use this method, follow the instructions link:$$https://github.com/errai/errai/blob/master/errai-forge-addon/README.asciidoc$$[here] to install the Errai Forge Addon and create a new project.


In the upcomming sections, we will demonstrate how to run your app in GWT Development Mode through the command line and eclipse, so it would be nice to have something to run so that you are able to verify that everything is working. Here is a sample class you can use that displays an alert when the app loads:

[source,java]
----
// Add the package declaration here

import javax.annotation.PostConstruct;
import org.jboss.errai.ioc.client.api.EntryPoint;
import com.google.gwt.user.client.Window;

@EntryPoint
public class App {
  
  @PostConstruct
  public void onLoad() {
    Window.alert("Hello World!");
  }
}
----

For this code to run properly, you must use the Errai Forge Addon _Add Errai Features_ command to install _Errai IOC_.

Create new subfolder, _client/local_, under the folder containing your GWT module file. Then create a file, _App.java_, in this new package and copy the above sample code (making sure to replace the top comment with the package declaration).

[[sid-54493220_GettingStartedwithErrai-RunningtheappinGWT]]
==== Running and Debugging with GWT's Super Dev mode

As of GWT 2.7, we use Super Dev Mode to run your app in hosted mode during development. link:$$http://www.gwtproject.org/doc/latest/DevGuideCompilingAndDebugging.html#DevGuideDevMode$$[GWT's Super Dev Mode] allows for code-refresh development cycles. Simply change a client-side class and refresh the browser to see your changes. You can also debug client and server side code in your IDE of choice. These sections will describe how to use Super Dev Mode to develop and debug your web app.

===== Running the app in GWT

Change into your web app's project directory and type the following:

----
mvn clean gwt:run
----

This will begin the download of all the dependencies required to develop with and run Errai. It may take a few minutes to complete the download.

When it is finished, you should see the GWT Development Mode runtime window appear as shown in _Figure 1_.

[[img-gwt-dev]]
.GWT Development Mode
image::author/download/attachments/54493220/DevModeWindows.png[]

Next, click the _Launch Default Browser_ button. You should now see the application load.

If you are using errai-tutorial, you should see a page with a complaint form.

If you followed the instructions for using the Errai Forge plugin, there should be a blank page with an alert saying "Hello World!".

That's it! You've got your first Errai Application up and running. The next sections will describe how to set up your app with your IDE.

[[sid-54493220_GettingStartedwithErrai-ConfiguringyourprojectforEclipse]]

===== Debugging the app in GWT

To debug your app using GWT's development mode, you will need to start a remote debugger separately and run the following command in your project directory:

----
mvn clean gwt:debug
----

==== Running and Debugging in Eclipse using Maven tooling

There are two ways to configure your project in your IDE. One option is to use the built-in Maven tooling to set up Maven run and debug configurations within your IDE. The other option is to download and use GWT tooling that is available for your IDE, and create custom run/debug configurations with that. Note that for Intellij IDEA, the GWT tooling is only available for users of the Ultimate Edition.

[NOTE]
.Read the previous section!
====
This next section assumes you have followed the instructions in the previous section. As such, we assume you have created an Errai project using the Errai Forge plugin or a copy of the errai-tutorial project, which we'll be importing into your IDE.
====

[[sid-54493220_GettingStartedwithErrai-Prerequisites]]

===== Prerequisites

[[sid-54493220_GettingStartedwithErrai-MavenIntegrationforEclipse%28m2e%29]]

===== Maven Integration for Eclipse (m2e)

This section will walk you through using Maven tooling for running and debugging your app within Eclipse. If you have not already installed m2e in Eclipse, you will want to do so now.

To install the Maven tooling, use the following steps:

1. Go to the _Eclipse Marketplace_ under the _Help_ menu in Eclipse.
+
.Eclipse Marketplace
image::author/download/attachments/54493220/EclipseM2eStep1.PNG[]

2. In the _Find_ dialog enter the phrase _Maven_ and hit enter.
+
.Find Dialog
image::author/download/attachments/54493220/EclipseM2eStep2.PNG[]

3. Find the _Maven Integration for Eclipse_ plugin and click the _Install_ button for that entry.
+
.Maven Integration for Eclipse in Marketplace
image::author/download/attachments/54493220/EclipseM2eStep3.PNG[]

4. Accept the defaults by clicking _Next_, and then accept the User License Agreement to begin the installation.

[[sid-54493220_GettingStartedwithErrai-Importingyourproject]]

===== Importing your project

Once you have completed the installation of the prerequisites from the previous section, you will now be able to go ahead and import the Maven project you created in the first section of this guide. We will use the errai-tutorial project as an example.

Follow these steps to get the project setup:

1. From the _File_ menu, select _Import..._
+
.Import File in Eclipse
image::author/download/attachments/54493220/Import1.PNG[width=650]

2. You will be presented with the Import dialog box. From here you want to select _Maven_ -> _Existing Maven Projects_
+
.Import Existing Maven Project
image::author/download/attachments/54493220/Import2.PNG[width=650]

3. From the _Import Maven Projects_ dialog, you will need to select the directory location of the project you created in the first section of this guide. In the _Root Directory_ field of the dialog, enter the path to the project, or click _Browse..._ to select it from the file chooser dialog.
+
.Select Folder
image::author/download/attachments/54493220/Import3.PNG[width=650]

4. Click _Finish_ to begin the import process.

5. When the import process has finished, you should see your project imported within the Eclipse _Project Explorer_. If you are using errai-tutorial, the [code]+App+ class should be visible within the [code]+client+ package.
+
.App.java
image::author/download/attachments/54493220/Import4.PNG[width=650]

===== Running Development Mode with Eclipse

1. Next you will need to setup a Maven Run Profile for Development Mode. To do so select _Run As..._ > _Run Configurations..._ from the toolbar.
+
.Run Configurations
image::author/download/attachments/54493220/RunConfigurations.PNG[width=650]

2. Select _Maven Build_ from the sidebar and create a new launch configuration by pressing the _New_ button in the top left corner.
+
.New Configuration
image::author/download/attachments/54493220/NewLaunchConfiguration.PNG[width=650]

3. Give the configuration a name, then click _Browse Workspace_ and select the root directory of your new project.
+
.Select Project Root Directory
image::author/download/attachments/54493220/LaunchRootDir.PNG[width=650]

4. In the _Goals_ text box, type "clean gwt:run". Click _Apply_ to save the configuration and then _Close_.
+
.Run Configurations Goals
image::author/download/attachments/54493220/GwtRunGoals.PNG[width=650]

5. You can add this new configuration under the _Run As_ button in your toolbar by selecting _Run As_ > _Organize Favorites_, then clicking _Add_ and selecting the run configuration.
+
.Add Configuration to Favourites
image::author/download/attachments/54493220/OrganizeFavourites.PNG[width=650]

6. At this point, you should try running your new configuration to make sure everything is in working order. To run your app, find the run configuration under the _Run As_ menu in the toolbar.
+
.Run GWT Development Mode from Eclipse
image::author/download/attachments/54493220/UseGwtRunConfiguration.PNG[width=650]

This will start the GWT Development Mode exactly as running `mvn clean gwt:run` from the command line.

===== Debugging in Development Mode with Eclipse

1. To setup a debug run configuration for GWT Development Mode, repeate steps (2) and (3) from the section above, but this time use the _Goals_ "clean gwt:debug".
+
.Configure Maven Debug Configuration
image::author/download/attachments/54493220/ConfigureGwtDebug.PNG[width=650]

2. Next we will need to setup our remote debugger configurations in Eclipse. Because the client and server code run on separate JVMs, we will need to setup two such configurations. To create a debug configuration, select _Debug As..._ > _Debug Configurations..._ from the toolbar.
+
.Create Debug Configuration
image::author/download/attachments/54493220/DebugConfigurations.PNG[width=650]

3. In the sidebar, select _Remote Java Application_ and click the _New_ button in the top right corner.
+
.Create Remote Debug Configuration
image::author/download/attachments/54493220/NewDebugConfig.PNG[width=650]

4. This new configuration will be for remote debugging your client-side code, so give it an appropriate name. If the name of your project is not already in the _Project_ field, click _Browse_ and select it. The _Host_ and _Port_ values should be _localhost_ and _8000_ respectively, such that your configuration looks like this:
+
.Client Debug Configuration
image::author/download/attachments/54493220/ClientDebugConfig.PNG[width=650]
+
If everything is correct, click _Apply_.

5. Create another _Remote Java Application_ run configuration with the steps just described for remote debugging server code. The only differences from the client configuration should be the name and the port, which is _8001_. Thus the server remote debug configuration should look like this:
+
.Server Debug Configuration
image::author/download/attachments/54493220/ServerDebugConfig.PNG[width=650]

6. That's it! You've successfully imported your Errai project into Eclipse. Now, on to <<sid-54493502,coding>>!

==== Running and Debugging in your IDE using GWT tooling

Errai's _EmbeddedWildFlyLauncher_ provides an embedded WildFly instance within Dev Mode to allow users to debug server- and client-side code simultaneously in a single JVM. Here are the instructions for using it in Eclipse and Intellij IDEA Ultimate Edition:

===== Configuring your app to use the Google Plugin for Eclipse

This method requires the Google Plugin for Eclipse (GPE). You can find the instructions to download and install it link:$$https://developers.google.com/eclipse/docs/download$$[here].

Here are the steps to setup a run/debug configuration using the embedded WildFly launcher:

1. Ensure that your app is using the Google Web Toolkit. Right-click on your project in Eclipse, and select Google -> Web Toolkit Settings, and make sure that the "Use Google Web Toolkit" box is checked and the appropriate GWT SDK is selected.
+
.Google Web Toolkit Settings
image::author/download/attachments/gpe/EclipseProjectGWTSettings.png[width=650]

2. Set up a Web Application run/debug configuration as follows: 

+
Create a new Web Application run/debug configuration, select your Errai app in the Project field and set `com.google.gwt.dev.DevMode` as the main class:
+
.Dev Mode Configuration: Main tab
image::author/download/attachments/gpe/EclipseWebAppMain.png[width=650]

3. In the _Server_ tab, check the 'Run built-in server' checkbox, and enter the port number `8888`.
+
.Dev Mode Configuration: Server tab
image::author/download/attachments/gpe/EclipseWebAppServer.png[width=650]

4. Select _Super Development Mode_ in the GWT tab, and add your GWT module under _Available Modules_.
+
.Dev Mode Configuration: GWT tab
image::author/download/attachments/gpe/EclipseWebAppGWT.png[width=650]

5. Under the _Arguments_ tab, there are two fields, _Program arguments_ and _VM arguments_. In the _Program arguments_ field, amend the `server` flag as follows:
+
.Program Arguments
----
-server org.jboss.errai.cdi.server.gwt.EmbeddedWildFlyLauncher 
----
+
Make sure the following VM arguments are set:
+
.VM arguments
----
-Xmx2048m -XX:MaxPermSize=512M -Derrai.jboss.home=/home/ddadlani/errai-tutorial/target/wildfly-8.2.0.Final/
----
+
where `errai.jboss.home` points to your own WildFly installation. This can either be your local WildFly installation directory, or in the _target/_ directory of your app. For the Errai Tutorial app, `errai.jboss.home` points to the WildFly installation within the _target/_ directory, which is redownloaded and installed as part of the build. See <<wildfly-install-eclipse, below>> for information on how to automatically download WildFly into the _target/_ directory prior to running Super Dev Mode.
+
.Dev Mode Configuration: Arguments tab
image::author/download/attachments/gpe/EclipseWebAppArguments.png[width=650]

[[wildfly-install-eclipse]]
[IMPORTANT]
.Copy of WildFly in the target/ directory
====
If you wish to automatically download and install WildFly as part of your build into the _target/_ directory of your web app, you will need to run `mvn process-resources` prior to running or debugging your app. To do this, you can set up a Maven build configuration in Eclipse and specify _Goals_: "process-resources". You can then run the Maven configuration prior to running GWT's Super Dev Mode.
====

That's it! To debug your application within Eclipse, simply select your debug configuration and hit _Debug_. This will start GWT's dev mode as well as the debugger within Eclipse.

====== Debugging client-side JavaScript from within Eclipse

If you wish to debug your client-side JavaScript as Java code from within Eclipse, you will need to use the SDBG plugin for GWT Super Dev Mode. More information can be found http://sdbg.github.io/[here].

===== Configuring your app to use Intellij IDEA's GWT tooling

[NOTE]
.Intellij IDEA Community Edition users
====
The inbuilt GWT tooling for Intellij IDEA is only available in the Ultimate Edition. If you are using the Community Edition, you will not have access to the GWT plugin.
====

The Ultimate Edition for Intellij IDEA comes with a built-in GWT plugin that allows you to run and debug GWT apps specifically. We can configure the plugin to use the embedded WildFly launcher for debugging ease, in order to debug both server and client-side code in one debug session. This section describes how to set up a GWT run/debug configuration within Intellij IDEA:

1. If you have not already done so, add a GWT facet to your main module. Instructions to add a GWT facet to an existing module can be found https://www.jetbrains.com/idea/help/adding-a-gwt-facet-to-a-module.html[here].

2. On the top right hand corner of your Intellij IDEA session, select the dropdown box labeled _Edit Configurations_ to create a new run/debug configuration.
+
.Edit Run/Debug Configuration
image::author/download/attachments/intellij/IntellijEditConfig.png[width=450]

3. Press the `+` button under GWT Configurations to create a new GWT configuration. Check the _Super Dev Mode_ checkbox and select the name of your module. Fill out the following parameters in the corresponding boxes:
+
.VM Options
----
-Xmx2048m -XX:MaxPermSize=512M -Derrai.jboss.home=/home/ddadlani/errai-tutorial/target/wildfly-8.2.0.Final/
----
+
where `errai.jboss.home` points to your WildFly installation directory. This can either be your local WildFly installation directory, or in the _target/_ directory of your app. For the Errai Tutorial app, `errai.jboss.home` points to the WildFly installation within the _target/_ directory, which is redownloaded and installed as part of the build. See <<wildfly-install-intellij, below>> for information on how to automatically download WildFly into the _target/_ directory prior to running Super Dev Mode.
+
.Dev Mode Parameters
----
-server org.jboss.errai.cdi.server.gwt.EmbeddedWildFlyLauncher
----
+
.GWT Run/Debug Configuration for Intellij IDEA
image::author/download/attachments/intellij/IntellijGWTConfig.png[width=650]

4. Select the _Default_ server and make sure the start page is _index.html_. Select your browser and check the _with JavaScript debugger_ box to take advantage of Intellij IDEA's built-in JavaScript tooling.

5. Click on the `+` button under _Before Launch_ and select the _Make_ option. This will tell Intellij to compile your project before launching Dev Mode.

[[wildfly-install-intellij]]
[IMPORTANT]
.Copy of WildFly in the target/ directory
====
If you wish to automatically download and install WildFly as part of your build into the _target/_ directory of your web app, you will need to run `mvn process-resources` prior to running or debugging your app. To do this, you can add a Maven goal to the _Before Launch_ task list. Click the `+` button as before, select _Run Maven Goal_ and in the _Command Line_ field, enter "process-resources". Ensure that the working directory is the same as your project directory before clicking "OK". Intellij IDEA will then run the Maven goal prior to starting Super Dev Mode.
====

To run or debug your app, select this configuration in the top right corner of Intellij IDEA and click the 'Run' or 'Debug' buttons next to it. Your app should start up in Dev Mode within Intellij automatically and you should be able to use Intellij's own debugger to debug your code.

Now that you have everything set up, it's time to move on to coding!


[[sid-54493502]]

==== A Gentle Introduction to CDI

[IMPORTANT]
.This section is based on the previous guide sections
====
The project you created and setup in the previous two sections (ERRAI:Create your Project and ERRAI:Configuring your project for Eclipse) will be used as the basis for this section. So if you have not read them, do so now.
====

Errai CDI as its namesake implies is based on, and is in fact, a partial implementation of the CDI (Contexts and Dependency Injection) specification. Errai CDI covers _most_ of the programming model but omits the CDI SPI, instead replacing it with it a custom set of APIs which are more appropriate for the client programming model of Errai.

These differences aside, using Errai CDI in conjunction with CDI on the server will provide you with a uniform programming model across the client and server code of your application.

This guide does not assume any past experience with CDI. However, you may wish to consider reading the link:$$http://docs.jboss.org/weld/reference/1.1.5.Final/en-US/html/$$[Weld Documentation] in addition to this guide.

[[sid-54493502_AGentleIntroductiontoCDI-YourFirstBean]]

===== Your First Bean

A bean in CDI is merely a POJO (Plain Old Java Object), for the most part. In the context of CDI, any plain, default constructable class is a member of the _dependent scope_. Don't worry too much about what that means for now. Let's just go ahead and make one:

[source, java]
----
public class Foo {
  public String getName() {
    return "Mr. Foo";
  }
}
----

That was an easy, if uninteresting, exercise. But despite this class' worthy distinction as a dependent-scoped bean, it's actually quite a useless dependent scope beaned. Well, maybe not so much useless as it is unused.

Well, how would we use this bean? To answer that question we're going to need to introduce the concept of scopes in more detail.

[[sid-54493502_AGentleIntroductiontoCDI-Scopes]]

===== Scopes

Scopes, put simply, are the context within which beans live. Some scopes are short-lived and some are long-lived. For instance, there are beans which you may only want to create during a request, and beans which you want to live for as long as the application is running.

It turns out that CDI includes a set of default scopes which represent these very things.

We'll start by taking a look at the _application scope_, which is conveniently represented by the annotation [code]+@ApplicationScoped+. An application-scoped bean is a lazily-instantiated bean which will live for the entire duration of the application. In this sense, it is essentially like a singleton. And it's generally okay to think of it in that way.

So let's declare an application-scoped bean:

[source, java]
----
@ApplicationScoped
public class Bar {
  public String getName() {
    return "Mr. Bar";
  }
}
----

So what can we do with [code]+Foo+? Well, let's go ahead and get familiar with dependency injection, shall we?

[source, java]
----
@ApplicationScoped
public class Bar {
  @Inject Foo foo; 

  public String getName() {
    return "Mr. Bar";
  }
}
----

We have added a field of the type [code]+Foo+ which we declared earlier, and we have annotated it with [code]+javax.inject.Inject+. This tells the container to inject an instance of [code]+Foo+ into our bean. Since our [code]+Foo+ bean is of the dependent scope, the bean manager will actually create a _new_ instance of [code]+Foo+ and pass it in.

This scope of the newly instantiated [code]+Foo+ is _dependent_ on the scope that it was injected into. In this case, the application scope. On the other hand, if we were to turn around an inject [code]+Bar+ into [code]+Foo+, the behaviour is quite different.

[source, java]
----
public class Foo {
  @Inject Bar bar; 

  public String getName() {
    return "Mr. Foo";
  }
}
----

Here, every time a new instance of [code]+Foo+ is created, the _same_ instance of [code]+Bar+ will be injected. That is to say: this pseudo-code assertion is now always true:

----
assert fooInstance.bar.foo == fooInstance
----

[IMPORTANT]
.Note
====
This identity check will not _actually_ be true at runtime due to the need to proxy the class in this scenario. But it is true, that [code]+fooInstance+ and [code]+fooInstance.bar.foo+ both point to the same _underlying_ bean instance.
====

In the case of an Errai application, there are a bunch of application scoped beans which come built-in for common services like _ErraiBus_. Thus, in an Errai application which uses the message bus, we can inject a handle to the [code]+MessageBus+ service into any of our beans. Let's go ahead and do that in our [code]+Bar+ class:

[source, java]
----
@ApplicationScoped
public class Bar {
  @Inject Foo foo; 
  @Inject MessageBus bus;

  public String getName() {
    return "Mr. Bar";
  }
}
----

If working with dependency injection is new to you, then this is where you'll start seeing some practical benefit. When you need a common service in your client code, you ask the container for it by _injecting_ it. This frees you from worrying about the proper APIs to use in order to access a service; we need to use the message bus in our [code]+Bar+ bean, and so we inject it.

===== EntryPoints

Now that we're getting the gist of how dependency injection works, let's go back to our sample project.

In the [code]+App+ class that was created you may have noticed that the bean's scope is [code]+@EntryPoint+.

The [code]+@EntryPoint+ annotation is an annotation which provides a an analogue to the GWT EntryPoint concept within the context of CDI in Errai. Basically you want to think of [code]+@EntryPoint+ beans as the Errai CDI-equalivalent of [code]+main()+ methods. But as of Errai 2.2., that might actually be going a little far. In fact, you might be asking what is the real difference between [code]+@ApplicationScoped+ and [code]+@EntryPoint+ in practice. The answer is that beans annotated with [code]+@EntryPoint+ are eagerly instantiated while those annotated with [code]+@ApplicationScoped+ are created when accessed. This makes [code]+@EntryPoint+ useful for bootstrapping your application and [code]+@ApplicationScoped+ useful for creating client-side services.

If you're not convinced, try running this example with the `mvn clean gwt:run` command (described <<sid-54493220_GettingStartedwithErrai-RunningtheappinGWT,above>>).

[NOTE]
.Launching maven the first time
====
Please note, that when launching maven the first time on your machine, it will fetch all dependencies from a central repository. This may take a while, because it includes downloading large binaries like GWT SDK. However, subsequent builds are not required to go through this step and will be much faster.
====

[[sid-5931263]]

== Messaging

This section covers the core messaging concepts of the ErraiBus messaging framework.

ErraiBus provides a straight-forward approach to a complex problem space. Providing common APIs across the client and server, developers will have no trouble working with complex messaging scenarios such as building instant messaging clients, stock tickers, to monitoring instruments. There's no more messing with RPC APIs, or unwieldy AJAX or COMET frameworks. We've built it all in to one concise messaging framework. It's single-paradigm, and it's fun to work with.

[[sid-5931265]]

=== Messaging Overview

It's important to understand the concept of how messaging works in ErraiBus. Here are some important facts you'll need to know:

* Service endpoints are given string-based names that are referenced by message senders.

* There is no difference between sending a message to a client-based service, or sending a message to a server-based service.

* Furthermore, a service of the same name may co-exist on both the client and the server and both will receive all messages bound for that service name, whether they are sent from the client or from the server.

* Services are lightweight in ErraiBus, and can be declared liberally and extensively within your application to provide a message-based infrastructure for your web application.

It can be tempting to think of ErraiBus simply as a client-server communication platform, but there is a plethora of possibilities for using ErraiBus purely within the GWT client context, such as a way to advertise and expose components dynamically, to get around the lack of reflection in GWT.

So keep that in mind when you run up against problems in the client space that could benefit from runtime federation.

[NOTE]
.Manual Setup
====
Checkout the <<Manual-Setup-Section,Manual Setup Section>> for instructions on how to manually add messaging to your project.
====

[[sid-5931280]]

=== Messaging API Basics

The MessageBuilder is the heart of the messaging API in ErraiBus. It provides a fluent / builder API, that is used for constructing messages. All three major message patterns can be constructed from the [code]+MessageBuilder+.

Components that want to receive messages need to implement the [code]+MessageCallback+ interface.

But before we dive into the details, let's look at some use cases.

[[sid-5931280_MessagingAPIBasics-SendingMessageswiththeClientBus]]

==== Sending Messages with the Client Bus

In order to send a message from a client you need to create a [code]+Message+ and send it through an instance of [code]+MessageBus+. In this simple example we send it to the subject 'HelloWorldService'.

[source, java]
----
public class HelloWorld implements EntryPoint {

  // Get an instance of the RequestDispatcher
  private RequestDispatcher dispatcher = ErraiBus.getDispatcher();

  public void onModuleLoad() {
    Button button = new Button("Send message");

    button.addClickHandler(new ClickHandler() {
      public void onClick(ClickEvent event) {
        // Send a message to the 'HelloWorldService'.
        MessageBuilder.createMessage()
          .toSubject("HelloWorldService") // (1)
          .signalling() // (2)
          .noErrorHandling() // (3)
          .sendNowWith(dispatcher); // (4)
        });

        [...]
      }
   }
}

----

In the above example we build and send a message every time the button is clicked. Here's an explanation of what's going on as annotated above:

. We specify the subject we wish to send a message to. In this case, " [code]+HelloWorldService+ ".


. We indicate that we wish to only signal the service, meaning, that we're not sending a qualifying command to the service. For information on this, read the section on <<sid-23036473_WireProtocol%28J.REP%29-BusManagementandHandshakingProtocols,Protocols>>.


. We indicate that we do not want to provide an [code]+ErrorCallback+ to deal with errors for this message.


. We transmit the message by providing an instance to the [code]+RequestDispatcher+


[IMPORTANT]
====
An astute observer will note that access to the [code]+RequestDispatcher+ differs within client code and server code. Because this client code does not run within a container, access to the [code]+RequestDispatcher+ and [code]+MessageBus+ is provided statically using the [code]+ErraiBus.get()+ and [code]+ErraiBus.getDispatcher()+ methods. See the section on Errai IOC and Errai CDI for using ErraiBus from a client-side container.

When using Errai IOC or CDI, you can also use the Sender<T> interface to send messages.
====

[[sid-5931280_MessagingAPIBasics-ReceivingMessagesontheServerBus%2FServerServices]]

==== Receiving Messages on the Server Bus / Server Services

Every message has a sender and at least one receiver. A receiver is as it sounds--it receives the message and does something with it. Implementing a receiver (also referred to as a service) is as simple as implementing our standard MessageCallback interface, which is used pervasively across, both client and server code. Let's begin with server side component that receives messages:


[source, java]
----
@Service
  public class HelloWorldService implements MessageCallback {
    public void callback(Message message) {
      System.out.println("Hello, World!");
    }
  }

----

Here we declare an extremely simple service. The [code]+@Service+ annotation provides a convenient, meta-data based way of having the bus auto-discover and deploy the service.

[[sid-5931280_MessagingAPIBasics-SendingMessageswiththeServerBus]]

==== Sending Messages with the Server Bus

In the following example we extend our server side component to reply with a message when the callback method is invoked. It will create a message and address it to the subject ' [code]+HelloWorldClient+ ':

[source, java]
----
@Service
public class HelloWorldService implements MessageCallback {

  private RequestDispatcher dispatcher;

  @Inject
  public HelloWorldService(RequestDispatcher dispatcher) {
    dispatcher = dispatcher;
  }

  public void callback(CommandMessage message) {
    // Send a message to the 'HelloWorldClient'.
    MessageBuilder.createMessage()
      .toSubject("HelloWorldClient") // (1)
      .signalling()                  // (2)
      .with("text", "Hi There")      // (3)
      .noErrorHandling()             // (4)
      .sendNowWith(dispatcher);      // (5)
    });
  }
}
----

The above example shows a service which sends a message in response to receiving a message. Here's what's going on:

. We specify the subject we wish to send a message to. In this case, " [code]+HelloWorldClient+ ". We are sending this message to all clients which are listening in on this subject. For information on how to communicate with a single client, see Section 2.6.


. We indicate that we wish to only signal the service, meaning that we're not sending a qualifying command to the service. For information on this, read the section on Protocols.


. We add a message part called "text" which contains the value "Hi there".


. We indicate that we do not want to provide an [code]+ErrorCallback+ to deal with errors for this message.


. We transmit the message by providing an instance of the [code]+RequestDispatcher+.


[[sid-5931280_MessagingAPIBasics-ReceivingMessagesontheClientBus%2FClientServices]]

==== Receiving Messages on the Client Bus/ Client Services

Messages can be received asynchronously and arbitriraily by declaring callback services within the client bus. As ErraiBus maintains an open COMET channel at all times, these messages are delivered in real time to the client as they are sent. This provides built-in push messaging for all client services.


[source, java]
----
public class HelloWorld implements EntryPoint {

  private MessageBus bus = ErraiBus.get();

  public void onModuleLoad() {
     [...]

     /*
      * Declare a service to receive messages on the subject
      * "BroadcastReceiver".
      */
     bus.subscribe("BroadcastReceiver", new MessageCallback() {
       public void callback(CommandMessage message) {
         /*
          * When a message arrives, extract the "text" field and
          * do something with it
          */
          String messageText = message.get(String.class, "text");
        }
     });

     [...]
  }
}

----

In the above example, we declare a new client service called [code]+"BroadcastReceiver"+ which can now accept both local messages and remote messages from the server bus. The service will be available in the client to receive messages as long the client bus is and the service is not explicitly de-registered.

[[sid-5931280_MessagingAPIBasics-LocalServices]]

==== Local Services

On the client or the server, you can create a local receiver which only receives messages that originated on the local bus. A local server-side service only receives messages that originate on that server, and a local client-side service only receives messages that originated on that client.

To create a local receiver using the declarative API, use the [code]+@Local+ annotation in conjunction with [code]+@Service+:


[source, java]
----
@Local
@Service
  public class HelloIntrovertService implements MessageCallback {
    public void callback(Message message) {
      System.out.println("Hello, me!");
    }
  }
----

To create a local receiver using through programmatic service registration, use the [code]+subscribeLocal()+ method in place of [code]+subscribe()+:


[source, java]
----
public void registerLocalService(MessageBus bus) {
  bus.subscribeLocal("LocalBroadcastReceiver", new MessageCallback() {
    public void callback(Message message) {
       String messageText = message.get(String.class, "text");
     }
  });
}
----

Both examples above work in client- and server-side code.

[[sid-5931284]]

=== Single-Response Conversations & Pseudo-Synchronous Messaging

It is possible to contruct a message and a default response handler as part of the [code]+MessageBuilder+ API. It should be noted, that multiple replies will not be possible and will result an exception if attempted. Using this aspect of the API is very useful for doing simple psuedo-synchronous conversive things.

You can do this by specifying a [code]+MessageCallback+ using the [code]+repliesTo()+ method in the [code]+MessageBuilder+ API after specifying the error handling of the message.


[source, java]
----
MessageBuilder.createMessage()
  .toSubject("ConversationalService").signalling()
  .with("SomeField", someValue)
  .noErrorHandling()
  .repliesTo(new MessageCallback() {
    public void callback(Message message) {
      System.out.println("I received a response");
    }
   })
----

See the next section on how to build conversational services that can respond to such messages.

[[sid-5931289]]

=== Sender Inferred Subjects

It is possible for the sender to infer, to whatever conversational service it is calling, what subject it would like the reply to go to. This is accomplished by utilizing the standard [code]+MessageParts.ReplyTo+ message part. Using this methodology for building conversations is generally encouraged.

Consider the following client side code:


[source, java]
----
  MessageBuilder.createMessage()
    .toSubject("ObjectService").signalling()
    .with(MessageParts.ReplyTo, "ClientEndpoint")
    .noErrorHandling().sendNowWith(dispatcher);
----

And the conversational code on the server (for service _ObjectService_):


[source, java]
----
  MessageBuilder.createConversation(message)
    .subjectProvided().signalling()
    .with("Records", records)
    .noErrorHandling().reply();
----

In the above examples, assuming that the latter example is inside a service called "[code]+ObjectService+" and is referencing the incoming message that was sent in the former example, the message created will automatically reference the [code]+ReplyTo+ subject that was provided by the sender, and send the message back to the subject desired by the client on the client that sent the message.

[[sid-5931291]]

=== Broadcasting

Broadcasting messages to all clients listening on a specific subject is quite simple and involves nothing more than forgoing use of the reply API. For instance:


[source, java]
----
MessageBuilder.createMessage().
    .toSubject("MessageListener")
    .with("Text", "Hello, from your overlords in the cloud")
    .noErrorHandling().sendGlobalWith(dispatcher);
----

If sent from the server, all clients currently connected, who are listening to the subject [code]+"MessageListener"+ will receive the message. It's as simple as that.

[[sid-5931293]]

=== Client-to-Client Communication

Communication from one client to another client is not directly possible within the bus federation, by design. This isn't to say that it's not possible. But one client cannot see a service within the federation of another client. We institute this limitation as a matter of basic security. But many software engineers will likely find the prospects of such communication appealing, so this section will provide some basic pointers on how to go about accomplishing it.

[[sid-5931293_Client-to-ClientCommunication-RelayServices]]

==== Relay Services

The essential architectural thing you'll need to do is create a relay service that runs on the server. Since a service advertised on the server is visible to all clients and all clients are visible to the server, you might already see where we're going with this.

By creating a service on the server which accepts messages from clients, you can create a simple protocol on-top of the bus to enable quasi peer-to-peer communication. (We say quasi, because it still needs to be routed through the server)

While you can probably imagine simply creating a broadcast-like service which accepts a message from one client and broadcasts it to the rest of the world, it may be less clear how to go about routing from one particular client to another particular client, so we'll focus on that problem. This is covered in <<sid-5931301, the next chapter>>.

[[sid-5931301]]

=== Message Routing Information

Every message that is sent between a local and remote (or server and client) buses contain session routing information. This information is used by the bus to determine what outbound queues to use to deliver the message to, so they will reach their intended recipients. It is possible to manually specify this information to indicate to the bus, where you want a specific message to go.

You can obtain the [code]+SessionID+ directly from a [code]+Message+ by getting the [code]+QueueSession+ resource:


[source, java]
----
   QueueSession sess = message.getResource(QueueSession.class, Resources.Session.name());
   String sessionId = sess.getSessionId();
----

You can extract the [code]+SessionID+ from a message so that you may use it for routing by obtaining the [code]+QueueSession+ resource from the [code]+Message+. For example:


[source, java]
----
...
  public void callback(Message message) {
   QueueSession sess = message.getResource(QueueSession.class, Resources.Session.name());
   String sessionId = sess.getSessionId();

    // Record this sessionId somewhere.
    ...
  }
----

The [code]+SessionID+ can then be stored in a medium, say a Map, to cross-reference specific users or whatever identifier you wish to allow one client to obtain a reference to the specific [code]+SessionID+ of another client. In which case, you can then provide the [code]+SessionID+ as a MessagePart to indicate to the bus where you want the message to go.


[source, java]
----
  MessageBuilder.createMessage()
    .toSubject("ClientMessageListener")
    .signalling()
    .with(MessageParts.SessionID, sessionId)
    .with("Message", "We're relaying a message!")
    .noErrorHandling().sendNowWith(dispatcher);
----

By providing the [code]+SessionID+ part in the message, the bus will see this and use it for routing the message to the relevant queue.

It may be tempting however, to try and include destination [code]+SessionIDs+ at the client level, assuming that this will make the infrastructure simpler. But this will not achieve the desired results, as the bus treats [code]+SessionIDs+ as transient. Meaning, the [code]+SessionID+ information is not ever transmitted from bus-to-bus, and therefore is only directly relevant to the proximate bus.

[[sid-5931306]]

=== Handling Errors

Asynchronous messaging necessitates the need for asynchronous error handling. Luckily, support for handling errors is built directly into the [code]+MessageBuilder+ API, utilizing the [code]+ErrorCallback+ interface. In the examples shown in previous exceptions, error handing has been glossed over with aubiquitous usage of the [code]+noErrorHandling()+ method while building messaging. We chose to require the explicit use of such a method to remind developers of the fact that they are responsible for their own error handling, requiring you to explicitly make the decision to forego handling potential errors.

As a general rule, you should _always handle your errors_. It will lead to faster and quicker identification of problems with your applications if you have error handlers, and generally help you build more robust code.


[source, java]
----
MessageBuilder.createMessage()
    .toSubject("HelloWorldService")
    .signalling()
    .with("msg", "Hi there!")
    .errorsHandledBy(new ErrorCallback() {
      public boolean error(Message message, Throwable throwable) {
        throwable.printStackTrace();
          return true;
      }
    })
    .sendNowWith(dispatcher);
----

The addition of error handling at first may put off developers as it makes code more verbose and less-readable. This is nothing that some good practice can't fix. In fact, you may find cases where the same error handler can appropriately be shared between multiple different calls.


[source, java]
----
ErrorCallback error = new ErrorCallback() {
  public boolean error(Message message, Throwable throwable) {
    throwable.printStackTrace();
    return true;
  }
}

MessageBuilder.createMessage()
  .toSubject("HelloWorldService")
  .signalling()
  .with("msg", "Hi there!")
  .errorsHandledBy(error)
  .sendNowWith(dispatcher);

----

The error handler is required to return a [code]+boolean+ value. This is to indicate whether or not Errai should perform the default error handling actions it would normally take during a failure. You will almost always want to return [code]+true+ here, unless you are trying to explicitly surpress some undesirably activity by Errai, such as automatic subject-termination in conversations. But this is almost never the case.

[[sid-5931306_HandlingErrors-Handlingglobalmessagetransporterrors]]

==== Handling global message transport errors

You may need to detect problems which occur on the bus at runtime. The client bus API provides a facility for doing this in the [code]+org.jboss.errai.bus.client.framework.ClientMessageBus+ using the [code]+addTransportErrorHandler()+ method.

A [code]+TransportErrorHandler+ is an interface which you can use to define error handling behavior in the event of a transport problem.

For example:


[source, java]
----
messageBus.addTransportErrorHandler(new TransportErrorHandler() {
  public void onError(TransportError error) {
    // error handling code.
  }
});

----

The [code]+TransportError+ interface represents the details of an an error from the bus. It contains a set of methods which can be used for determining information on the initial request which triggered the error, if the error occurred over HTTP or WebSockets, status code information, etc. See the JavaDoc for more information.

[[sid-5931309]]

=== Asynchronous Message Tasks

In some applications, it may be necessary or desirable to delay transmission of, or continually stream data to a remote client or group of clients (or from a client to the server). In cases like this, you can utilize the [code]+replyRepeating()+, [code]+replyDelayed()+, [code]+sendRepeating()+ and [code]+sendDelayed()+ methods in the [code]+MessageBuilder+.

Delayed TasksSending a task with a delay is straight forward. Simply utilize the appropriate method (either [code]+replyDelayed()+ or [code]+sendDelayed()+).


[source, java]
----
  MessageBuilder.createConversation(msg)
    .toSubject("FunSubject")
    .signalling()
    .noErrorHandling()
    .replyDelayed(TimeUnit.SECONDS, 5); // sends the message after 5 seconds.
----

or


[source, java]
----
   MessageBuilder.createMessage()
     .toSubject("FunSubject")
     .signalling()
     .noErrorHandling()
     .sendDelayed(requestDispatcher, TimeUnit.SECONDS, 5); // sends the message after 5 seconds.
----

[[sid-5931311]]

=== Repeating Tasks

A repeating task is sent using one of the MessageBuilder's [code]+repeatXXX()+ methods. The task will repeat indefinitely until cancelled (see next section).


[source, java]
----
  MessageBuilder.createMessage()
    .toSubject("FunSubject")
    .signalling()
    .withProvided("time", new ResourceProvider<String>() {
       SimpleDateFormat fmt = new SimpleDateFormat("hh:mm:ss");
     
       public String get() {
         return fmt.format(new Date(System.currentTimeMillis());
       }
     }
     .noErrorHandling()
     .sendRepeatingWith(requestDispatcher, TimeUnit.SECONDS, 1); //sends a message every 1 second
----

The above example sends a message very 1 second with a message part called [code]+"time"+, containing a formatted time string. Note the use of the [code]+withProvided()+ method; a provided message part is calculated at the time of transmission as opposed to when the message is constructed.

Cancelling an Asynchronous TaskA delayed or repeating task can be cancelled by calling the [code]+cancel()+ method of the [code]+AsyncTask+ instance which is returned when creating a task. Reference to the AsyncTask object can be retained and cancelled by any other thread.


[source, java]
----
AsyncTask task = MessageBuilder.createConversation(message)
  .toSubject("TimeChannel").signalling()
  .withProvided(TimeServerParts.TimeString, new ResourceProvider<String>() {
     public String get() {
       return String.valueOf(System.currentTimeMillis());
     }
   }).defaultErrorHandling().replyRepeating(TimeUnit.MILLISECONDS, 100);

    ...

  // cancel the task and interrupt it's thread if necessary.
  task.cancel(true);
----

[[sid-5931315]]

=== Queue Sessions

The ErraiBus maintains it's own seperate session management on-top of the regular HTTP session management. While the queue sessions are tied to, and dependant on HTTP sessions for the most part (meaning they die when HTTP sessions die), they provide extra layers of session tracking to make dealing with complex applications built on Errai easier.

[[sid-5931315_QueueSessions-Lifecycle]]

==== Lifecycle

The lifescyle of a session is bound by the underlying HTTP session. It is also bound by activity thresholds. Clients are required to send heartbeat messages every once in a while to maintain their sessions with the server. If a heartbeat message is not received after a certain period of time, the session is terminated and any resources are deallocated.

[[sid-5931315_QueueSessions-Scopes]]

==== Scopes

One of the things Errai offers is the concept of session and local scopes.

[[sid-5931315_QueueSessions-SessionScope]]

===== Session Scope

A session scope is scoped across all instances of the same session. When a session scope is used, any parameters stored will be accessible and visible by all browser instances and tabs.

The SessionContext helper class is used for accessing the session scope.


[source, java]
----
public class TestService implements MessageCallback {
  public void callback(final Message message) {
    // obtain a reference to the session context by referencing the incoming message.
    SessionContext injectionContext = SessionContext.get(message);

    // set an attribute.
    injectionContext.setAttribute("MyAttribute", "Foo");
  }
}
----

[[sid-5931315_QueueSessions-LocalScope]]

===== Local Scope

A local scope is scoped to a single browser instance. But not to a single session.

In a browser a local scope would be confined to a tab or a window within a browser. You can store parameters inside a local scope just like with a session by using the [code]+LocalContext+ helper class.


[source, java]
----
public class TestService implements MessageCallback {
  public void callback(final Message message) {
    // obtain a reference to the local context by referencing the incoming message.
    LocalContext injectionContext = LocalContext.get(message);

   // set an attribute.
    injectionContext.setAttribute("MyAttribute", "Foo");
  }
}
----

[[sid-23036473]]

=== Wire Protocol (J.REP)

ErraiBus implements a JSON-based wire protocol which is used for the federated communication between different buses. The protocol specification encompasses a standard JSON payload structure, a set of verbs, and an object marshalling protocol. The protocol is named J.REP. Which stands for JSON Rich Event Protocol.

[[sid-23036473_WireProtocol%28J.REP%29-PayloadStructure]]

==== Payload Structure

All wire messages sent across are assumed to be JSON arrays at the outermost element, contained in which, there are _0..n_ messages. An empty array is considered a no-operation, but should be counted as activity against any idle timeout limit between federated buses.

.Example J.REP Payload
====


[source, java]
----
[
  {"ToSubject" : "SomeEndpoint", "Value" : "SomeValue" },
  {"ToSubject" : "SomeOtherEndpoint", "Value" : "SomeOtherValue"}
]
----

====

Here we see an example of a J.REP payload containing two messages. One bound for an endpoint named [code]+"SomeEndpoint"+ and the other bound for the endpoint [code]+"SomeOtherEndpoint"+. They both include a payload element [code]+"Value"+ which contain strings. Let's take a look at the anatomy of an individual message.

.An J.REP Message
====

[source, java]
----
{
  "ToSubject" : "TopicSubscriber",
  "CommandType" : "Subscribe",
  "Value " : "happyTopic",
  "ReplyTo" : "MyTopicSubscriberReplyTo"
}
----

====

The message shows a very vanilla J.REP message. The keys of the JSON Object represent individual _message parts_, with the values representing their corresponding values. The standard J.REP protocol encompasses a set of standard message parts and values, which for the purposes of this specification we'll collectively refer to as the protocol verbs.

The following table describes all of the message parts that a J.REP capable client is expected to understand:

[options="header"]
|===============
|Part|Required|JSON Type|Description
|[code]+ToSubject+|Yes|String|Specifies the subject within the bus, and its federation, which the message should be routed to.
|[code]+CommandType+|No|String|Specifies a command verb to be transmitted to the receiving subject. This is an optional part of a message contract, but is required for using management services
|[code]+ReplyTo+|No|String|Specifies to the receiver what subject it should reply to in response to this message.
|[code]+Value+|No|Any|A recommended but not required standard payload part for sending data to services
|[code]+PriorityProcessing+|No|Number|A processing order salience attribute. Messages which specify priority processing will be processed first if they are competing for resources with other messages in flight. Note: the current version of ErraiBus only supports two salience levels (0 and >1). Any non-zero salience in ErraiBus will be given the same priority relative to 0 salience messages
|[code]+ErrorMessage+|No|String|An accompanying error message with any serialized exception
|[code]+Throwable+|No|Object|If applicable, an encoded object representing any remote exception that was thrown while dispatching the specified service
|===============

[[sid-23036473_WireProtocol%28J.REP%29-BuiltinSubjects]]

===== Built-in Subjects

The table contains a list of reserved subject names used for facilitating things like bus management and error handling. A bus should never allow clients to subscribe to these subjects directly.

[options="header"]
|===============
|Subject|Description
|[code]+ClientBus+|The self-hosted message bus endpoint on the client
|[code]+ServerBus+|The self-hosted message bus endpoint on the server
|[code]+ClientBusErrors+|The standard error receiving service for clients
|===============

As this table indicates, the bus management protocols in J.REP are accomplished using self-hosted services. See the section on _Bus Management and Handshaking Protocols_ for details.

[[sid-23036473_WireProtocol%28J.REP%29-MessageRouting]]

==== Message Routing

There is no real distinction in the J.REP protocol between communication with the server, versus communication with the client. In fact, it assumed from an architectural standpoint that there is no real distinction between a client and a server. Each bus participates in a flat-namespaced federation. Therefore, it is possible that a subject may be observed on both the server and the client.

One in-built assumption of a J.REP-compliant bus however, is that messages are routed within the auspices of session isolation. Consider the following diagram:

.Topology of a J.REP Messaging Federation
image::author/download/attachments/23036473/FederationTopology.png[]

It is possible for _Client A_ to send messages to the subjects _ServiceA_ and _ServiceB_. But it is not possible to address messages to _ServiceC_. Conversely, _Client B_ can address messages to _ServiceC_ and _ServiceB_, but not _ServiceA_.

[[sid-23036473_WireProtocol%28J.REP%29-BusManagementandHandshakingProtocols]]

==== Bus Management and Handshaking Protocols

Federation between buses requires management traffic to negotiate connections and manage visibility of services between buses. This is accomplished through services named [code]+ClientBus+ and [code]+ServerBus+ which both implement the same protocol contracts which are defined in this section.

[[sid-23036473_WireProtocol%28J.REP%29-ServerBusandClientBuscommands]]

===== ServerBus and ClientBus commands

Both bus services share the same management protocols, by implementing verbs (or commands) that perform different actions. These are specified in the protocol with the [code]+CommandType+ message part. The following table describes these commands:

.Message Parts for Bus Commands:
[options="header"]
|===============
|Command / Verb|Message Parts|Description
|[code]+ConnectToQueue+|N/A|The first message sent by a connecting client to begin the handshaking process.
|[code]+CapabilitiesNotice+|[code]+CapabilitiesFlags+|A message sent by one bus to another to notify it of its capabilities during handshake (for instance long polling or websockets)
|[code]+FinishStateSync+|N/A|A message sent from one bus to another to indicate that it has now provided all necessary information to the counter-party bus to establish the federation. When both buses have sent this message to each other, the federation is considered active.
|[code]+RemoteSubscribe+|[code]++Subject++_or_ [code]+SubjectsList+|A message sent to the remote bus to notify it of a service or set of services which it is capable of routing to.
|[code]+RemoteUnsubscribe+|[code]+Subject+|A message sent to the remote bus to notify it that a service is no longer available.
|[code]+Disconnect+|[code]+Reason+|A message sent to a server bus from a client bus to indicate that it wishes to disconnect and defederate. Or, when sent from the client to server, indicates that the session has been terminated.
|[code]+SessionExpired+|N/A|A message sent to a client bus to indicate that its messages are no longer being routed because it no longer has an active session
|[code]+Heartbeat+|N/A|A message sent from one bus to another periodically to indicate it is still active.
|===============

[options="header"]
|===============
|Part|Required|JSON Type|Description
|[code]+CapabilitiesFlags+|Yes|String|A comma delimited string of capabilities the bus is capable of us
|[code]+Subject+|Yes|String|The subject to subscribe or unsubscribe from
|[code]+SubjectsList+|Yes|Array|An array of strings representing a list of subjects to subscribe to
|===============

[[sid-24674472]]

=== Conversations

Conversations are message exchanges which are between a single client and a service. They are a fundmentally important concept in ErraiBus, since by default, a message will be broadcast to all client services listening on a particular channel.

When you create a reply with an incoming message, you ensure that the message you are sending back is received by the same client which sent the incoming message. A simple example:

[source, java]
----
@Service
public class HelloWorldService implements MessageCallback {
  public void callback(CommandMessage message) {
    // Send a message to the 'HelloWorldClient' on the client that sent us the
    // the message.
    MessageBuilder.createConversation(message)
      .toSubject("HelloWorldClient")
      .signalling()
      .with("text", "Hi There! We're having a reply!")
      .noErrorHandling().reply();
    });
  }
}
----

Note that the only difference between the example in the previous section and this is the use of the [code]+createConversation()+ method with [code]+MessageBuilder+.

[[sid-53380177]]

=== WebSockets

ErraiBus has support for WebSocket-based communication. When WebSockets are enabled, capable web browsers will attempt to upgrade their COMET-based communication with the server-side bus to use a WebSocket channel.

There are three different ways the bus can enable WebSockets. The first uses a sideband server, which is a small, lightweight server which runs on a different port from the application server. The second is native JBoss AS 7-based integration and the third is to rely in JSR-356 support in WildFly. Of course, you only need to configure one of these three options!

[[sid-53380177_WebSockets-Configuringthesidebandserver]]

==== Configuring the sideband server

Activating the sideband server is as simple as adding the following to the [code]+ErraiService.properties+ file:

[source, java]
----
errai.bus.enable_web_socket_server=true
----

The default port for the sideband server is [code]+8085+. You can change this by specifying a port with the [code]+errai.bus.web_socket_port+ property in the [code]+ErraiService.properties+ file.

[IMPORTANT]
.Netty Dependencies
====
Make sure to deploy the required Netty dependencies to your server. If you started with one of our demos or our tutorial project it should be enough to *NOT* set [code]+netty-codec-http+ to provided. All required transitive dependencies should then be part of your war file (WEB-INF/lib).
====

[[sid-53380177_WebSockets-DeployingwithJBossAS7]]

==== Deploying with JBoss AS 7.1.2 (or higher)

This is an alternative approach to the sideband server described in the previous chapter. Make sure to *NOT* configure both! It is currently necessary to use the native connector in JBoss AS for WebSockets to work. So the first step is to configure your JBoss AS instance(s) to use the native connector by changing the [code]+domain/configuration/standalone.xml+ or [code]+domain/configuration/domain.xml+ file as follows:

[source, xml]
----
<subsystem xmlns="urn:jboss:domain:web:1.1" default-virtual-server="default-host" native="false">
----

to:

[source, xml]
----
<subsystem xmlns="urn:jboss:domain:web:1.1" default-virtual-server="default-host" native="true">
----

[IMPORTANT]
.Verify that the native APR connector is being used
====
To verify that the native connectors are being used check your console for the following log message:
[code]+INFO [org.apache.coyote.http11.Http11AprProtocol] (MSC service thread 1-6) Starting Coyote HTTP/1.1 on http-/127.0.0.1:8080+

The important part is [code]+org.apache.coyote.http11.Http11AprProtocol+. You should *NOT* be seeing [code]+org.apache.coyote.http11.Http11Protocol+. You might have to install the Tomcat native library if not already available on your system.
====

You will then need to configure the servlet in your application's [code]+web.xml+ which will provide WebSocket upgrade support within AS7.

Add the following to the [code]+web.xml+:

[source, xml]
----
<context-param>
  <param-name>websockets-enabled</param-name>
  <param-value>true</param-value>
</context-param>

<context-param>
  <param-name>websocket-path-element</param-name>
  <param-value>in.erraiBusWS</param-value>
</context-param>
----

This will tell the bus to enable web sockets support. The [code]+websocket-path-element+ specified the path element within a URL which the client bus should request in order to negotiate a websocket connection. For instance, specifying [code]+in.erraiBusWS+ as we have in the snippit above, will result in attempted negotiation at [code]+http://<your_server>:<your_port>/<context_path>/in.erraiBusWS+. For this to have any meaningful result, we must add a servlet mapping that will match this pattern:

[source, xml]
----
<servlet>
  <servlet-name>ErraiWSServlet</servlet-name>
  <servlet-class>org.jboss.errai.bus.server.servlet.JBossAS7WebSocketServlet</servlet-class>
  <load-on-startup>1</load-on-startup>
</servlet>

<servlet-mapping>
  <servlet-name>ErraiWSServlet</servlet-name>
  <url-pattern>*.erraiBusWS</url-pattern>
</servlet-mapping>
----

[IMPORTANT]
.Do not remove the regular ErraiBus servlet mappings!
====
When configuring ErraiBus to use WebSockets on JBoss AS, you _do not_ remove the existing servlet mappings for the bus. The WebSocket servlet is in _addition to_ your current bus servlet. This is because ErraiBus _always_ negotiates WebSocket sessions over the COMET channel.
====

[IMPORTANT]
.Important dependency
====
Also make sure to deploy the required errai-bus-jboss7-websocket.jar to your server. If you're using Maven simply add the following dependency to your pom.xml file:

[source, xml]
----
	<dependency>
  		<groupId>org.jboss.errai</groupId>
  		<artifactId>errai-bus-jboss7-websocket</artifactId>
  		<version>${errai.version}</version>
	</dependency>
----
====

==== JSR-356 WebSocket support (Deploying to WildFly 8.0 or higher)

Errai provides two implementations for this:

. errai-bus-jsr356-websocket: A simple JSR-356 implementation, that does not rely on CDI or Weld.
. errai-bus-jsr356-websocket-weld: Provides the possibility to use the builtin CDI scopes (javax.enterprise.context.RequestScoped, javax.enterprise.context.SessionScoped, javax.enterprise.context.ConversationScoped). This implementation uses WELD and is intended for JBoss WildFly 8 or higher.

Make sure to add the following project dependency:
[source, xml]
----
<!-- For JSR-356 without depending on Weld -->
<dependency>
	<groupId>org.jboss.errai</groupId>
	<artifactId>errai-bus-jsr356-websocket</artifactId>
	<version>${errai.version}</version>
</dependency>

<!-- For JEE environment with Weld-->
<dependency>
	<groupId>org.jboss.errai</groupId>
	<artifactId>errai-bus-jsr356-websocket-weld</artifactId>
	<version>${errai.version}</version>
</dependency>
----

[IMPORTANT]
.Dependency on Weld!
====
The JSR-356 specification is not addressing the integration with builtin CDI scopes which is what the [code]+<artifactId>errai-bus-jsr356-websocket-weld</artifactId>+ module provides. It therefore depends directly to JBoss Weld. If you use a non Weld-based middleware, you can use [code]+<artifactId>errai-bus-jsr356-websocket</artifactId>+ instead.
====

To configure ErraiBus that WebSocket communication should be used, define the following in your [code]+web.xml+
[source, xml]
----
<context-param>
	<param-name>websockets-enabled</param-name>
	<param-value>true</param-value>
</context-param>
----

[IMPORTANT]
.Do not remove the regular ErraiBus servlet mappings!
====
When configuring ErraiBus to use JSR-356 WebSocket, you _do not_ remove the existing servlet mappings for the bus. This is because ErraiBus _always_ negotiates WebSocket sessions over the COMET channel.
====

You can also define filters when using the JSR-356 WebSocket implementation. These filters will be executed for each received ErraiBus message on the server. Your filters need to implement [code]+org.jboss.errai.bus.server.websocket.jsr356.filter.WebSocketFilter+ and must be configured in your appliations's [code]+web.xml+ as an ordered comma separated list:
[source, xml]
----
<context-param>
	<param-name>errai-jsr-356-websocket-filter</param-name>
	<param-value>foo.bar.FooFilter,foo.bar.BarFilter</param-value>
</context-param>
----

Because one of the filter method parameters is the actual WebSocket session, you also have to add the following dependency to your  [code]+pom.xml+:
[source, xml]
----
<dependency>
	<groupId>org.jboss.spec.javax.websocket</groupId>
	<artifactId>jboss-websocket-api_1.0_spec</artifactId>
	<scope>provided</scope>
	<version>1.0.0.Final</version>
</dependency>
----

Please take a look at the JavaDoc of the filter interface for more information about the method parameters.

==== WebSocket Security

Errai supports Websocket security (wss) for two deployment scenarios.

. The servlet container is deployed behind a reverse-proxy or other SSL terminating appliance
. The servlet container is deployed in front and takes care of SSL termination

===== Servlet container is deployed behind a reverse-proxy

All you need to do is configure the following context parameter in your [code]+web.xml+

[source, xml]
----
<context-param>
  <param-name>force-secure-websockets</param-name>
  <param-value>true</param-value>
</context-param>
----

This will work for the sideband-server as well as JBoss AS7 and WildFly based websocket support.

[IMPORTANT]
.Don't forget to configure your reverse-proxy or appliance to handle websocket connections with SSL!
====
To use this kind of configuration you have to configure your reverse-proxy or appliance to use HTTPS (SSL / TLS).
====

===== Servlet container takes care of SSL termination

====== With JBoss AS 7.1.2 (or higher) & JSR-356 WebSocket (WildFly 8 or higher)

If the servlet container is configured to use HTTPS, the Errai WebSocket Servlet for JBoss AS 7 and / or the Errai JSR-356 WebSocket implementation for WildFly will use the WSS scheme automatically. So, there's is nothing else to do!

====== Using the sideband server

To tell the sideband server to use SSL and configure Errai to use the WSS scheme the following properties are mandatory in [code]+ErraiService.properties+:

. errai.bus.secure_web_socket_server=true -> This tells the sideband server and Errai to use SSL / WSS.
. errai.bus.web_socket_keystore=[full qualified path to the JKS or PKCS12 keystore] -> Key store to use
. errai.bus.web_socket_keystore_password=[password for the key store] -> Password for the key store to use

Depending on your configuration and type of PKI container you can the add following addtional properties in the [code]+ErraiService.properties+:

. errai.bus.web_socket_keystore_type=[kind of key store] -> When you want to use the PKCS12 format instead of JKS (default)
. errai.bus.web_socket_key_password=[password of private key] -> When the private key in the container has a different password than the keystore itself.

[IMPORTANT]
.Sidband server needs a keystore.
====
In this deployment case, the sideband server needs a keystore with a server certificate and the corresponding private key.
====

[[sid-59146643]]

=== Bus Lifecycle

[[sid-59146643_BusLifecycle-TurningServerCommunicationOnandOff]]

==== Turning Server Communication On and Off

By default, Errai's client-side message bus attempts to connect to the server as soon as the ErraiBus module has been loaded. The bus will stay connected until a lengthy (about 45 seconds) communication failure occurs, or the web page is unloaded.

The application can affect bus communication through two mechanisms:

. By setting a global JavaScript variable [code]+erraiBusRemoteCommunicationEnabled = false+ before the GWT scripts load, bus communication with the server is permanently disabled


. By calling `((ClientMessageBus) ErraiBus.get()).stop()`, the bus disconnects from the server


To resume server communication after a call to [code]+ClientMessageBus.stop()+ or after communication with the server has exceeded the bus' retry timeout, call `((ClientMessageBus) ErraiBus.get()).init()`. You can use a [code]+BusLifecycleListener+ to monitor the success or failure of this attempt. See the next section for details.

[[sid-59146643_BusLifecycle-ObservingBusLifecycleStateandCommunicationStatus]]

==== Observing Bus Lifecycle State and Communication Status

In a perfect world, the client message bus would always be able to communicate with the server message bus. But in the real world, there's a whole array of reasons why the communication link between the server and the client might be interrupted.

On its own, the client message bus will attempt to reconnect with the server whenever communication has been disrupted. Errai applications can monitor the status of the bus' communication link (whether it is disconnected, attempting to connect, or fully connected) through the [code]+BusLifecycleListener+ interface:

[source, java]
----
class BusStatusLogger implements BusLifecycleListener {

  @Override
  public void busAssociating(BusLifecycleEvent e) {
    GWT.log("Errai Bus trying to connect...");
  }

  @Override
  public void busOnline(BusLifecycleEvent e) {
    GWT.log("Errai Bus connected!");
  }

  @Override
  public void busOffline(BusLifecycleEvent e) {
    GWT.log("Errai Bus trying to connect...");
  }

  @Override
  public void busDisassociating(BusLifecycleEvent e) {
    GWT.log("Errai Bus going into local-only mode.");
  }
}
----

To attach such a listener to the bus, make the following call in client-side code:


[source, java]
----
ClientMessageBus bus = (ClientMessageBus) ErraiBus.get();
bus.addLifecycleListener(new BusStatusLogger());
----

[[sid-68355291]]

=== Shadow Services

Shadow Services is a Service that will get invoked when there is no longer a connection with the server. This is particular helpful when developing an application for mobile. To create a Shadow Service for a specific Services all you have to do is annotate a new client side implementation with the @ShadowService:


[source, java]
----
@ShadowService
public class SignupShadowService implements MessageCallback {
   @Override
   public void callback(Message message) {
   }
}
----

Also when you have a RPC based Service you can just add @ShadowService on a client side implementation to configure it to be the service to get called when there is no network:

[source, java]
----
@ShadowService
public class SignupServiceShadow implements SignupService {
   @Override
   public User register(User newUserObject, String password) throws RegistrationException {
   }
}
----

In this shadow service we can create logic that will deal with the temporary connection loss. For instance you could save the data that needs to get send to the server with JPA on the client and then when the bus get online again sent the data to the server.

[[sid-5931386]]

=== Debugging Messaging Problems

Errai includes a bus monitoring application, which allows you to monitor all of the message exchange activity on the bus in order to help track down any potential problems It allows you to inspect individual messages to examine their state and structure.

To utilize the bus monitor, you'll need to include the _errai-tools _ package as part of your application's dependencies. When you run your application in development mode, you will simply need to add the following JVM options to your run configuration in order to launch the monitor: [code]+-Derrai.tools.bus_monitor_attach=true+

.ErraiBus Monitor
image::author/download/attachments/5931386/MonitorOverview.png[]

The monitor provides you a real-time perspective on what's going on inside the bus. The left side of the main screen lists the services that are currently available, and the right side is the service-explorer, which will show details about the service.

To see what's going on with a specific service, simply double-click on the service or highlight the service, then click "Monitor Service...". This will bring up the service activity monitor.

.ErraiBus Monitor details
image::author/download/attachments/5931386/MonitorOverview2.png[]

The service activity monitor will display a list of all the messages that were transmitted on the bus since the monitor became active. You do not need to actually have each specific monitor window open in order to actively monitor the bus activity. All activity on the bus is recorded.

The monitor allows you select individual messages, an view their individual parts. Clicking on a message part will bring up the object inspector, which will allow you to explore the state of any objects contained within the message, not unlike the object inspectors provided by debuggers in your favorite IDE. This can be a powerful tool for looking under the covers of your application.

[[sid-5931402]]

== Dependency Injection

[NOTE]
.Manual Setup
====
Checkout the <<Manual-Setup-Section,Manual Setup Section>> for instructions on how to manually add Errai IOC to your project.
====

The core Errai IOC module implements the _JSR-330 Dependency Injection_ specification for in-client component wiring.

Dependency injection (DI) allows for cleaner and more modular code, by permitting the implementation of decoupled and type-safe components. By using DI, components do not need to be aware of the implementation of provided services. Instead, they merely declare a contract with the container, which in turn provides instances of the services that component depends on.

[IMPORTANT]
.Classpath Scanning and ErraiApp.properties
====
Errai only scans the contents of classpath locations (JARs and directories) that have <<sid-5931354,
          a file called
          ErraiApp.properties>> at their META-INF directory. If dependency injection is not working for you, double-check that you have an [code]+ErraiApp.properties+ in every JAR and directory that contains classes Errai should know about.
====

A simple example:


[source, java]
----
public class MyLittleClass {
  private final TimeService timeService;

  @Inject
  public MyLittleClass(TimeService timeService) {
    this.timeService = timeService;
  }

  public void printTime() {
    System.out.println(this.timeService.getTime());
  }
}
----

In this example, we create a simple class which declares a dependency using [code]+@Inject+ for the interface [code]+TimeService+. In this particular case, we use constructor injection to establish the contract between the container and the component. We can similarly use field injection to the same effect:


[source, java]
----
public class MyLittleClass {
  @Inject
  private TimeService timeService;

  public void printTime() {
    System.out.println(this.timeService.getTime());
  }
}
----

Below is an example of an [code]+@ApplicationScoped TimeService+, meaning a single instance of [code]+TimeService+ would be provided by the container for all injection sites.

[source, java]
----
@ApplicationScoped
public class TimeService {
}
----

We could also annotate the type [code]+@Dependent+ so that every injection site has its own unique instance.

[source, java]
----
@Dependent
public class TimeService {
}
----

[NOTE]
.Implicitly Dependent Beans
====
Types lacking explicit scopes may also be injected, in which case they will be implicitly [code]+@Dependent+.
====

[TIP]
.Best Practices
====
Although field injection results in less code, a major disadvantage is that you cannot create immutable classes using the pattern, since the container must first call the default, no-argument constructor, and then iterate through its injection tasks, which leaves the potential albeit remote that the object could be left in an partially or improperly initialized state. The advantage of constructor injection is that fields can be immutable (final), and invariance rules applied at construction time, leading to earlier failures, and the guarantee of consistent state.
====

[[sid-5931407]]

=== Container Wiring

In contrast to link:$$http://code.google.com/p/google-gin/$$[Gin], the Errai IOC container does not provide a programmatic way of creating and configuring injectors. Instead, container-level binding rules are defined by implementing a [code]+Provider+, which is scanned for and auto-discovered by the container.

A [code]+Provider+ is essentially a factory which produces type instances within in the container, and defers instantiation responsibility for the provided type to the provider implementation. Top-level providers use the standard [code]+javax.inject.Provider<T>+ interface.

Types made available as _top-level_ providers will be available for injection in any managed component within the container.

Out of the box, Errai IOC implements these default top-level providers, all defined in the [code]+org.jboss.errai.ioc.client.api.builtin+ package:

* [code]+CallerProvider+: Makes RPC [code]+Caller<T>+ objects available for injection.
* [code]+DisposerProvider+: Makes Errai IoC [code]+Disposer<T>+ objects available for injection.
* [code]+InitBallotProvider+: Makes instances of [code]+InitBallot+ available for injection.
* [code]+IOCBeanManagerProvider+: Makes Errai's client-side bean manager, [code]+ClientBeanManager+, available for injection.
* [code]+MessageBusProvider+: Makes Errai's client-side [code]+MessageBus+ singleton available for injection.
* [code]+RequestDispatcherProvider+: Makes an instance of the [code]+RequestDispatcher+ available for injection.
* [code]+RootPanelProvider+: Makes GWT's [code]+RootPanel+ singleton injectable.
* [code]+SenderProvider+: Makes MessageBus [code]+Sender<T>+ objects available for injection.


Implementing a [code]+Provider+ is relatively straight-forward. Consider the following two classes:

_TimeService.java_


[source, java]
----
public interface TimeService {
  public String getTime();
}
----

_TimeServiceProvider.java_


[source, java]
----
@IOCProvider
@Singleton
public class TimeServiceProvider implements Provider<TimeService> {
  @Override
  public TimeService get() {
    return new TimeService() {
      public String getTime() {
        return "It's midnight somewhere!";
      }
    };
  }
}
----

If you are familiar with Guice, this is semantically identical to configuring an injector like so:


[source, java]
----
Guice.createInjector(new AbstractModule() {
  public void configure() {
    bind(TimeService.class).toProvider(TimeServiceProvider.class);
  }
 }).getInstance(MyApp.class);
----

As shown in the above example code, the annotation [code]+@IOCProvider+ is used to denote top-level providers.

The classpath will be searched for all annotated providers at compile time.

[IMPORTANT]
====
Top-level providers are regular beans, so they can inject dependencies particularly from other top-level providers as necessary.
====

[[sid-5931332]]

=== Wiring server side components

By default, Errai uses Google Guice to wire server-side components. When deploying services on the server-side, it is currently possible to obtain references to the [code]+MessageBus+, [code]+RequestDispatcher+, the [code]+ErraiServiceConfigurator+, and [code]+ErraiService+ by declaring them as injection dependencies in Service classes, extension components, and session providers.

Alternatively, supports CDI based wiring of server-side components. See the chapter on Errai CDI for more information.

[[sid-20938792]]

=== Scopes

Out of the box, the IOC container supports three bean scopes, [code]+@Dependent+, [code]+@Singleton+ and [code]+@EntryPoint+. The singleton and entry-point scopes are roughly the same semantics.

[[sid-24674461]]

==== Dependent Scope

In Errai IOC, all client types are valid bean types if they are default constructable or can have construction dependencies satisfied. These unqualified beans belong to the dependent pseudo-scope. See: link:$$http://docs.jboss.org/weld/reference/latest/en-US/html/scopescontexts.html#d0e1997$$[Dependent Psuedo-Scope from CDI Documentation]

Additionally, beans may be qualified as [code]+@ApplicationScoped+, [code]+@Singleton+ or [code]+@EntryPoint+. Although [code]+@ApplicationScoped+ and [code]+@Singleton+ are supported for completeness and conformance, within the client they effectively result in behavior that is identical.

.Example dependent scoped bean
====

[source, java]
----
public void MyDependentScopedBean {
  private final Date createdDate;

  public MyDependentScopedBean {
    createdDate = new Date();
  }  
}
----

====
.Example ApplicationScoped bean
====


[source, java]
----
@ApplicationScoped
public void MyClientBean {
  @Inject MyDependentScopedBean bean;

  // ... //
}
----

====

[IMPORTANT]
.Availability of dependent beans in the client-side BeanManager
====
As is mentioned in the <<sid-21627016_Client-SideBeanManager-AvailabilityOfBeans,bean manager documentation>>, only beans that are _explicitly_ scoped will be made available to the bean manager for lookup. So while it is not necessary for regular injection, you must annotate your dependent scoped beans with [code]+@Dependent+ if you wish to dynamically lookup these beans at runtime.
====

[[sid-20938794]]

=== Built-in Extensions

[[sid-20938797]]

==== Bus Services

As Errai IOC provides a container-based approach to client development, support for Errai services are exposed to the container so they may be injected and used throughout your application where appropriate. This section covers those services.

[[sid-20938797_BusServices-@Service]]

===== @Service

The [code]+org.jboss.errai.bus.server.annotations.Service+ annotation is used for binding service endpoints to the bus. Within the Errai IOC container you can annotate services and have them published to the bus on the client (or on the server) in a very straight-forward manner:

.A simple message receiving service
====

[source, java]
----
@Service
public class MyService implements MessageCallback {
  public void callback(Message message) {
    // ... //
  }
}
----

====

As with server-side use of the annotation, if a service name is not explicitly specified, the underlying class name or field name being annotated will be used as the service name.

[[sid-20938797_BusServices-@Local]]

===== @Local

The [code]+org.jboss.errai.bus.server.api.Local+ annotation is used in conjunction with the [code]+@Service+ annotation to advertise a service only for visibility on the local bus and thus, cannot receive messages across the wire for the service.

.A local only service
====


[source, java]
----
@Service @Local
public class MyLocalService implements MessageCallback {
  public void callback(Message message) {
    // ... //
  }
}
----

====

[[sid-20938797_BusServices-LifecycleImpactofServices]]

===== Lifecycle Impact of Services

Services which are registered with ErraiBus via the bean manager through use of the [code]+@Service+ annotation, have de-registration hooks tied implicitly to the destruction of the bean. Thus, <<sid-22872238,destruction of the bean>> implies that these associated services are to be dereferenced.

[[sid-20938800]]

==== Client Components

The IOC container, by default, provides a set of default injectable bean types. They range from basic services, to injectable proxies for RPC. This section covers the facilities available out-of-the-box.

[[sid-20938800_ClientComponents-MessageBus]]

===== MessageBus

The type [code]+org.jboss.errai.bus.client.framework.MessageBus+ is globally injectable into any bean. Injecting this type will provide the instance of the active message bus running in the client.

.Injecting a MessageBus
====


[source, java]
----
@Inject MessageBus bus;
----

====

[[sid-20938800_ClientComponents-RequestDispatcher]]

===== RequestDispatcher

The type [code]+org.jboss.errai.bus.client.framework.RequestDispatcher+ is globally injectable into any bean. Injecting this type will provide a [code]+RequestDispatcher+ instance capable of delivering any messages provided to it, to the [code]+MessageBus+.

.Injecting a RequestDispatcher
====


[source, java]
----
@Inject RequestDispatcher dispatcher;
----

====

[[sid-20938800_ClientComponents-Caller%3C%3F%3E]]

===== Caller<?>

The type [code]+org.jboss.errai.common.client.api.Caller<?>+ is a globally injectable RPC proxy. RPC proxies may be provided by various components. For example, JAX-RS or Errai RPC. The proxy itself is agnostic to the underlying RPC mechanism and is qualified by it's type parameterization.

For example:

.An example Caller<?> proxy
====


[source, java]
----
public void MyClientBean {
  @Inject
  private Caller<MyRpcInterface> rpcCaller;
 
  // ... ///
  
  @EventHandler("button")
  public void onButtonClick(ClickHandler handler) { 
    rpcCaller.call(new RemoteCallback<Void>() {
      public void callback(Void void) {
        // put code here that should execute after RPC response arrives
      }
    ).callSomeMethod();
  }
}
----

====

The above code shows the injection of a proxy for the RPC remote interface, [code]+MyRpcInterface+. For more information on defining RPC proxies see <<sid-5931313, Remote Procedure Calls (RPC)>>.

[[sid-20938800_ClientComponents-Sender%3C%3F%3E]]

===== Sender<?>

The [code]+org.jboss.errai.ioc.support.bus.client.Sender<?>+ interface is the lower-level counterpart to the [code]+Caller<?>+ interface described above. You can inject a [code]+Sender+ to send low-level ErraiBus messages directly to subscribers on any subject.

For example:


[source, java]
----
  @Inject
  @ToSubject("ListCapitializationService")
  Sender<List<String>> listSender;

  // ... ///

  @EventHandler("button")
  public void onButtonClick(ClickHandler handler) {
    List<String> myListOfStrings = getSelectedCitiesFromForm();
    listSender.send(myListOfStrings, new MessageCallback() {
      public void callback(Message reply) {
        // do stuff with reply
      }
    );
  }
----

The [code]+Sender.send()+ method is overloaded. The variant demonstrated above takes a value and a MessageCallback to reply receive a reply (assuming the subscriber sends a conversational reply). The following variants are available:

* [code]+send(T)+
* [code]+send(T, ErrorCallback)+
* [code]+send(T, MessageCallback)+
* [code]+send(T, MessageCallback, ErrorCallback)+


The reply-to service can also be specified declaratively using the [code]+@ReplyTo+ annotation. This allows the app to receive conversational replies even when using the [code]+send()+ variants that do not take a [code]+MessageCallback+:


[source, java]
----
  @Inject
  @ToSubject("ListCapitializationService")
  @ReplyTo("ClientListService")
  Sender<List<String>> listSender;

  // ... ///

  @EventHandler("button")
  public void onButtonClick(ClickHandler handler) {
    List<String> myListOfStrings = getSelectedCitiesFromForm();
    listSender.send(myListOfStrings);
  }

  @Singleton
  @Service
  public static class ClientListService implements MessageCallback {
    @Override
    public void callback(Message message) {
      // do stuff with message
    }
  }
----

These [code]+Sender<?>+ features are just convenient wrappers around the full-featured programmatic ErraiBus API. See <<sid-5931280, Messaging API Basics>> and <<sid-24674472, Conversations>> for full information about low-level ErraiBus communication.

==== Global Exception Handling

In plain GWT apps you can register your own handler for uncaught exceptions with `GWT.setUncaughtExceptionHandler`. With Errai IOC you can annotate methods in IOC beans as uncaught exception handlers as in the example below.

[source, java]
----
@ApplicationScoped
public class SingletonHandler {
  @UncaughtExceptionHandler
  private void handle(Throwable t) {
    // do something
  }
}
----

In this example, `SingletonHandler` is `@ApplicationScoped` so the `handle` method will be invoked on the same instance for every uncaught exception. If the `SingletonHandler` has not bean instantiated when an uncaught exception occurs, the container will instantiate the instance and invoke the `handle` method.

An `@UncaughtExceptionHandler` method in a `@Dependent` bean will only be invoked for instances that have already been created. If multiple instances of such a bean exist, the `@UncaughtExceptionHandler` method will be invoked for each instance. If none exists the container will not create an instance and no handler methods will be invoked for that type.

[[sid-21758082]]

==== Lifecycle Tools

A problem commonly associated with building large applications in the browser is ensuring that things happen in the proper order when code starts executing. Errai IOC provides you tools which permit you to ensure things happen before initialization, and forcing things to happen after initialization of all of the Errai services.

[[sid-21758082_LifecycleTools-ControllingStartup]]

===== Controlling Startup

In order to prevent initialization of the bus and it's services so that you can do necessary configuration, especially if you are writing extensions to the Errai framework itself, you can create an implicit startup dependency on your bean by injecting an [code]+org.jboss.errai.ioc.client.api.InitBallot<?>+.

.Using an InitBallot to Control Startup
====


[source, java]
----
@Singleton
public class MyClientBean {
  @Inject InitBallot<MyClientBean> ballot;

  @PostConstruct
  public void doStuff() {
    // ... do some work ...
    
    ballot.voteForInit();
  }
}
----

====

[[sid-21758082_LifecycleTools-PerformingTasksAfterInitialization]]

===== Performing Tasks After Initialization

Sending RPC calls to the server from inside constructors and [code]+@PostConstruct+ methods in Errai is not always reliable due to the fact that the bus and RPC proxies initialize asynchronously with the rest of the application. Therefore it is often desirable to have such things happen in a post-initialization task, which is exposed in the [code]+ClientMessageBus+ API. However, it is much cleaner to use the [code]+@AfterInitialization+ annotation on one of your bean methods.

.Using @AfterInitialization to do something after startup
====


[source, java]
----
@Singleton
public class MyClientBean {
  @AfterInitialization
  public void doStuffAfterInit() {
    // ... do some work ...
  }
}
----

====

===== Increase the Initialization Timeout

For some very large applications it is possible for initialization to timeout in Development Mode because of deferred code generation. If you experience this problem, you can adjust the initialization timeout value by setting the `erraiInitTimeout` variable in your GWT Host Page to a value in milliseconds.

[[sid-71467095]]

==== Timed Methods

The [code]+@Timed+ annotation allows scheduling method executions on managed client-side beans. Timers are automatically scoped to the scope of the corresponding managed bean and participate in the same lifecycle (see <<sid-22872238, Bean Lifecycle>> for details).

In the following example the [code]+updateTime+ method is invoked repeatedly every second.


[source, java]
----
@Timed(type = TimerType.REPEATING, interval = 1, timeUnit = TimeUnit.SECONDS)
private void updateTime() {
  timeWidget.setTime(System.currentTimeMillis);
}
----

For delayed one-time execution of methods [code]+type = TimerType.DELAYED+ can be used instead.

[[sid-21627016]]

=== Client-Side Bean Manager

It may be necessary at times to manually obtain instances of beans managed by Errai IOC from outside the container managed scope or creating a hard dependency from your bean. Errai IOC provides a simple client-side bean manager for handling these scenarios: [code]+org.jboss.errai.ioc.client.container.ClientBeanManager+.

As you might expect, you can inject a bean manager instance into any of your managed beans. If you use Errai IOC in its default mode you will need to inject the synchronous bean manager ([code]+org.jboss.errai.ioc.client.container.SyncBeanManager+).

If you have asynchronous IOC mode enabled simply inject the asynchronous bean manager ([code]+org.jboss.errai.ioc.client.container.async.AsyncBeanManager+) instead. Asynchronous IOC brings support for link:$$http://www.gwtproject.org/doc/latest/DevGuideCodeSplitting.html$$[code splitting]. That means that any bean annotated with [code]+@LoadAsync+ can be compiled into a separate JavaScript file that's downloaded when the bean is first needed on the client. [code]+@LoadAsync+ also allows to specify a fragment name using a class literal. Using GWT 2.6.0 or higher, all types with the same fragment name will be part of the same JavaScript file.

.Injecting the client-side bean manager
====


[source, java]
----
public MyManagedBean {
  @Inject SyncBeanManager manager;

  // class body
}
----

====

If you need to access the bean manager outside a managed bean, such as in a unit test, you can access it by calling [code]+org.jboss.errai.ioc.client.container.IOC.getBeanManager()+

[[sid-21627016_Client-SideBeanManager-Lookingupbeans]]

==== Looking up beans

Looking up beans can be done through the use of the [code]+lookupBeans()+ method. Here's a basic example:

.Example lookup of a bean
====


[source, java]
----
public MyManagedBean {
  @Inject SyncBeanManager manager;

  public void lookupBean() {
    IOCBeanDef<SimpleBean> bean = manager.lookupBean(SimpleBean.class);

    if (bean != null) {
      // get the instance of the bean
      SimpleBean inst = bean.getInstance();    
    }    
  }
}
----

====

In this example we lookup a bean class named [code]+SimpleBean+. This example will succeed assuming that [code]+SimpleBean+ is unambiguous. If the bean is ambiguous and requires qualification, you can do a qualified lookup like so:

.Looking up beans with qualifiers
====


[source, java]
----
MyQualifier qual = new MyQualifier() {
  public annotationType() {
    return MyQualifier.class;
  }
}

MyOtherQualifier qual2 = new MyOtherQualifier() {
  public annotationType() {
    return MyOtherQualifier.class;
  }
}

// pass qualifiers to ClientBeanManager.lookupBeans
IOCBeanDef<SimpleBean> bean = beanManager.lookupBean(SimpleBean.class, qual, qual2);
----

====

In this example we manually construct instances of qualifier annotations in order to pass it to the bean manager for lookup. This is a necessary step since there's currently no support for annotation literals in Errai client code.

[[sid-21627016_Client-SideBeanManager-AvailabilityOfBeans]]



[[sid-21627016_Client-SideBeanManager-Availabilityofbeans]]

==== Availability of beans

Not all beans that are available for injection are available for lookup from the bean manager by default. Only beans which are _explicitly_ scoped are available for dynamic lookup. This is an intentional feature to keep the size of the generated code down in the browser.

[[sid-22872133]]

=== Alternatives

It may be desirable to have multiple matching dependencies for a given injection point with the ability to specify which implementation to use at runtime. For instance, you may have different versions of your application which target different browsers or capabilities of the browser. Using alternatives allows you to share common interfaces among your beans, while still using dependency injection, by exporting consideration of what implementation to use to the container's configuration.

Consider the following example:


[source, java]
----
@Singleton @Alternative
public class MobileView implements View {
  // ... //
}
----

and


[source, java]
----
@Singleton @Alternative
public class DesktopView implements View {
  // ... // 
----

In our controller logic we in turn inject the [code]+View+ interface:

[source, java]
----
@EntryPoint
public class MyApp {
  @Inject
  View view;
  
  // ... //
}
----

This code is unaware of the implementation of [code]+View+, which maintains good separation of concerns. However, this of course creates an ambiguous dependency on the [code]+View+ interface as it has two matching subtypes in this case. Thus, we must configure the container to specify which alternative to use. Also note, that the beans in both cases have been annotated with [code]+javax.enterprise.inject.Alternative+.

In your [code]+ErraiApp.properties+ for the module, you can simply specify which active alternative should be used:


[source, ini]
----
errai.ioc.enabled.alternatives=org.foo.MobileView
----

You can specify multiple alternative classes by white space separating them:


[source, ini]
----
errai.ioc.enabled.alternatives=org.foo.MobileView \
                               org.foo.HTML5Orientation \
                               org.foo.MobileStorage 
----

You can only have one enabled alternative for a matching set of alternatives, otherwise you will get ambiguous resolution errors from the container.

[[sid-22872238]]

=== Bean Lifecycle

All beans managed by the Errai IOC container support the [code]+@PostConstruct+ and [code]+@PreDestroy+ annotations.

Beans which have methods annotated with [code]+@PostConstruct+ are guaranteed to have those methods called before the bean is put into service, and only after all dependencies within its graph has been satisfied.

Beans are also guaranteed to have their [code]+@PreDestroy+ annotated methods called before they are destroyed by the bean manager.

[IMPORTANT]
====
This cannot be guaranteed when the browser DOM is destroyed prematurely due to: closing the browser window; closing a tab; refreshing the page, etc.
====

[[sid-22872238_BeanLifecycle-DestructionofBeans]]

==== Destruction of Beans

Beans under management of Errai IOC, of any scope, can be explicitly destroyed through the client bean manager. Destruction of a managed bean is accomplished by passing a reference to the [code]+destroyBean()+ method of the bean manager.

.Destruction of bean
====

[source, java]
----
public MyManagedBean {
  @Inject SyncBeanManager manager;

  public void createABeanThenDestroyIt() {
    // get a new bean.
    SimpleBean bean = manager.lookupBean(SimpleBean.class).getInstance();

    bean.sendMessage("Sorry, I need to dispose of you now");

    // destroy the bean!
    manager.destroyBean(bean);
  }
}
----

====

When the bean manager "destroys" the bean, any pre-destroy methods the bean declares are called, it is taken out of service and no longer tracked by the bean manager. If there are references on the bean by other objects, the bean will continue to be accessible to those objects.

[IMPORTANT]
====
Container managed resources that are dependent on the bean such as bus service endpoints or CDI event observers will also be automatically destroyed when the bean is destroyed.
====

Another important consideration is the rule, "all beans created together are destroyed together." Consider the following example:

.SimpleBean.class
====

[source, java]
----
@Dependent
public class SimpleBean {
   @Inject @New AnotherBean anotherBean;

   public AnotherBean getAnotherBean() {
     return anotherBean;
   }

   @PreDestroy
   private void cleanUp() {
     // do some cleanup tasks
   }
}
----

====

.Destroying bean from subgraph
====

[source, java]
----
public MyManagedBean {
  @Inject SyncBeanManager manager;

  public void createABeanThenDestroyIt() {
    // get a new bean.
    SimpleBean bean = manager.lookupBean(SimpleBean.class).getInstance();

    // destroy the AnotherBean reference from inside the bean
    manager.destroyBean(bean.getAnotherBean());
  }
}
----

====

In this example we pass the instance of [code]+AnotherBean+, created as a dependency of [code]+SimpleBean+, to the bean manager for destruction. Because this bean was created at the same time as its parent, its destruction will also result in the destruction of [code]+SimpleBean+; thus, this action will result in the [code]+@PreDestroy+ [code]+cleanUp()+ method of [code]+SimpleBean+ being invoked.

[[sid-22872238_BeanLifecycle-Disposers]]

===== Disposers

Another way which beans can be destroyed is through the use of the injectable [code]+org.jboss.errai.ioc.client.api.Disposer<T>+ class. The class provides a straight forward way of disposing of bean type.

For instance:

.Destroying bean with disposer
====
[source, java]
----
public MyManagedBean {
  @Inject @New SimpleBean myNewSimpleBean;
  @Inject Disposer<SimpleBean> simpleBeanDisposer;

  public void destroyMyBean() {
    simpleBeanDisposer.dispose(myNewSimpleBean);
  }
}
----
====

[[sid-19398999]]

== Errai CDI

[NOTE]
.Manual Setup
====
Checkout the <<Manual-Setup-Section,Manual Setup Section>> for instructions on how to manually add Errai CDI to your project.
====

CDI (Contexts and Dependency Injection) is the Java EE standard (JSR-299) for handling dependency injection. In addition to dependency injection, the standard encompasses component lifecycle, application configuration, call-interception and a decoupled, type-safe eventing specification.

The Errai CDI extension implements a subset of the specification for use inside of client-side applications within Errai, as well as additional capabilities such as distributed eventing.

Errai CDI does not currently implement all life cycles specified in JSR-299 or interceptors. These deficiencies may be addressed in future versions.

[IMPORTANT]
====
Errai CDI is implemented as an extension on top of the Errai IOC Framework (see <<sid-5931402, Dependency Injection>>), which itself implements JSR-330. Inclusion of the CDI module your GWT project will result in the extensions automatically being loaded and made available to your application.
====

[NOTE]
.Classpath Scanning and ErraiApp.properties
====
Errai CDI only scans the contents of classpath locations (JARs and directories) that have <<sid-5931354,
          a file called
          ErraiApp.properties>> at their META-INF directory. If CDI features such as dependency injection, event observation, and [code]+@PostConstruct+ are not working for your classes, double-check that you have an [code]+ErraiApp.properties+ at the META-INF directory of every JAR and directory tree that contains classes Errai should know about.
====

[[sid-5931498]]

=== Features and Limitations

Beans that are deployed to a CDI container will automatically be registered with Errai and exposed to your GWT client application. So, you can use Errai to communicate between your GWT client components and your CDI backend beans.

Errai CDI based applications use the same annotation-driven programming model as server-side CDI components, with some notable limitations. Many of these limitations will be addressed in future releases.

. There is no support for CDI interceptors in the client.


. Passivating scopes are not supported.


. The JSR-299 SPI is not supported for client side code. Although writing extensions for the client side container is possible via the Errai IOC Extensions API.


. The [code]+@Interceptor+ annotation is unsupported.


. The [code]+@Decorator+ annotation is unsupported.


[[sid-5931498_FeaturesandLimitations-Otherfeatures]]

==== Other features

The CDI container in Errai is built around the <<sid-5931402,Errai IOC module>>, and thus is a superset of the existing functionality in Errai IOC. Thus, all features and APIs documented in Errai IOC are accessible and usable with this Errai CDI programming model.

[[sid-21758054]]

=== Events

Any CDI managed component may produce and consume link:$$http://docs.jboss.org/weld/reference/latest/en-US/html/events.html$$[events]. This allows beans to interact in a completely decoupled fashion. Beans consume events by registering for a particular event type and optional qualifiers. The Errai CDI extension simply extends this concept into the client tier. A GWT client application can simply register an [code]+Observer+ for a particular event type and thus receive events that are produced on the server-side. Likewise and using the same API, GWT clients can produce events that are consumed by a server-side observer.

Let's take a look at an example.

.FraudClient.java
====


[source, java]
----
public class FraudClient extends LayoutPanel {

  @Inject
  private Event<AccountActivity> event; (1)

  private HTML responsePanel;

  public FraudClient() {
    super(new BoxLayout(BoxLayout.Orientation.VERTICAL));
  }

  @PostConstruct
  public void buildUI() {
    Button button = new Button("Create activity", new ClickHandler() {
      public void onClick(ClickEvent clickEvent) {
        event.fire(new AccountActivity());
      }
    });
    responsePanel = new HTML();
    add(button);
    add(responsePanel);
  }

  public void processFraud(@Observes @Detected Fraud fraudEvent) { (2)
    responsePanel.setText("Fraud detected: " + fraudEvent.getTimestamp());
  }
}
----

====

Two things are noteworthy in this example:

. Injection of an [code]+Event+ dispatcher proxy


. Creation of an [code]+Observer+ method for a particular event type


The event dispatcher is responsible for sending events created on the client-side to the server-side event subsystem (CDI container). This means any event that is fired through a dispatcher will eventually be consumed by a CDI managed bean, if there is an corresponding [code]+Observer+ registered for it on the server side.

In order to consume events that are created on the server-side you need to declare an client-side observer method for a particular event type. In case an event is fired on the server this method will be invoked with an event instance of type you declared.

To complete the example, let's look at the corresponding server-side CDI bean:

.AccountService.java
====

[source, java]
----
@ApplicationScoped
public class AccountService {

  @Inject @Detected
  private Event<Fraud> event;

  public void watchActivity(@Observes AccountActivity activity) {
    Fraud fraud = new Fraud(System.currentTimeMillis());
    event.fire(fraud);
 }
}
----

====

[IMPORTANT]
.Dependent-scope observers work differently in Errai
====
When an event is observed in a full CDI implementation (such as Weld), the container:

. Obtains an instance of the bean from the active context

. Invokes the observer method

For dependent-scoped beans, there is no "active-context", so the container *creates a new bean that is destroyed immediately after the observer method is invoked*.

Errai does not behave this way with client-side, dependent-scoped observers. Instead when an event is fired, Errai will invoke the relevant observer method on *every dependent-scoped bean that has already been instantiated* (i.e. zero or more observers can be invoked).

====

[[sid-21758054_Events-Conversationalevents]]

==== Conversational events

A server can address a single client in response to an event annotating event types as [code]+@Conversational+. Consider a service that responds to a subscription event.

.SubscriptionService.java
====


[source, java]
----
@ApplicationScoped
public class SubscriptionService {

  @Inject
  private Event<Documents> welcomeEvent;

  public void onSubscription(@Observes Subscription subscription) {
    Document docs = createWelcomePackage(subscription);
    welcomeEvent.fire(docs);
 }
}
----

====

And the [code]+Document+ class would be annotated like so:

.Document.java
====


[source, java]
----
@Conversational @Portable
public class Document {
   // code here
}
----

====

As such, when [code]+Document+ events are fired, they will be limited in scope to the initiating conversational contents which are implicitly inferred by the caller. So only the client which fired the [code]+Subscription+ event will receive the fired [code]+Document+ event.

==== Local Events

The simplest way to stop a CDI Event from being broadcast over the wire is to avoid annotating the type with `@Portable`. But in some cases you may wish to send a type over the network with Errai RPC or the Message Bus, but only fire it locally as a CDI Event.

This can be accomplished by annotating a type with `@LocalEvent`, as in this example:

[source, java]
----
@Portable @LocalEvent
public DocumentChange {
  private String diff;

  public String getDiff() {
    return diff;
  }

  public void setDiff(String diff) {
    this.diff = diff;
  }
}
----

Because of the `@Portable` annotation instances of `DocumentChange` can be sent over the wire via RPC calls or bus messages, but because of the `@LocalEvent` annotation they will not be sent over the network if fired via a CDI Event.

[[sid-21758054_Events-ClientServerEventExample]]

==== Client-Server Event Example

A key feature of the Errai CDI framework is the ability to federate the CDI eventing bus between the client and the server. This permits the observation of server produced events on the client, and vice-versa.

Example server code:

.MyServerBean.java
====


[source, java]
----
@ApplicationScoped
public class MyServerBean {
  @Inject
  Event<MyResponseEvent> myResponseEvent;

  public void myClientObserver(@Observes MyRequestEvent event) {
    MyResponseEvent response;

    if (event.isThankYou()) {
      // aww, that's nice!
      response = new MyResponseEvent("Well, you're welcome!");
    }
    else {
      // how rude!
      response = new MyResponseEvent("What? Nobody says 'thank you' anymore?");
    }

    myResponseEvent.fire(response);
  }
}
----

====

Domain-model:

.MyRequestEvent.java
====


[source, java]
----
@Portable
public class MyRequestEvent {
  private boolean thankYou;

  public MyRequestEvent(boolean thankYou) {
    setThankYou(thankYou);
  }

  public void setThankYou(boolean thankYou) {
    this.thankYou = thankYou;
  }

  public boolean isThankYou() {
    return thankYou;
  }
}
----

====

.MyResponseEvent.java
====


[source, java]
----
@Portable
public class MyResponseEvent {
  private String message;

  public MyRequestEvent(String message) {
    setMessage(message);
  }

  public void setMessage(String message) {
    this.message = message;
  }

  public String getMessage() {
    return message;
  }
}
----

====

Client application logic:

.MyClientBean.java
====


[source, java]
----
@EntryPoint
public class MyClientBean {
   @Inject
   Event<MyRequestEvent> requestEvent;

   public void myResponseObserver(@Observes MyResponseEvent event) {
     Window.alert("Server replied: " + event.getMessage());
   }

   @PostConstruct
   public void init() {
     Button thankYou = new Button("Say Thank You!");
     thankYou.addClickHandler(new ClickHandler() {
       public void onClick(ClickEvent event) {
         requestEvent.fire(new MyRequestEvent(true));
       }
     }

     Button nothing = new Button("Say nothing!");
     nothing.addClickHandler(new ClickHandler() {
       public void onClick(ClickEvent event) {
         requestEvent.fire(new MyRequestEvent(false));
       }
     }

     VerticalPanel vPanel = new VerticalPanel();
     vPanel.add(thankYou);
     vPanel.add(nothing);

     RootPanel.get().add(vPanel);
   }
}
----

====

[[sid-21758062]]

=== Producers

Producer methods and fields act as sources of objects to be injected. They are useful when additional control over object creation is needed before injections can take place e.g. when you need to make a decision at runtime before an object can be created and injected.

.App.java
====


[source, java]
----
@EntryPoint
public class App {
  ...

  @Produces @Supported
  private MyBaseWidget createWidget() {
    return (Canvas.isSupported()) ? new MyHtml5Widget() : new MyDefaultWidget();
  }
}
----

====

.MyComposite.java
====


[source, java]
----
@ApplicationScoped
public class MyComposite extends Composite {

  @Inject @Supported
  private MyBaseWidget widget;

  ...
}

----

====

Producers can also be scoped themselves. By default, producer methods are dependent-scoped, meaning they get called every time an injection for their provided type is requested. If a producer method is scoped [code]+@Singleton+ for instance, the method will only be called once, and the bean manager will inject the instance from the first invokation of the producer into every matching injection point.

.Singleton producer
====

[source, java]
----
public class App {
  ...

  @Produces @Singleton
  private MyBean produceMyBean() {
    return new MyBean();
  }
}
----

====

For more information on CDI producers, see the link:$$http://docs.jboss.org/cdi/spec/1.0/html/$$[CDI specification] and the link:$$http://seamframework.org/Weld/WeldDocumentation$$[WELD reference documentation].

[[sid-53118110]]

=== Safe dynamic lookup

As an alternative to using the bean manager to dynamically create beans, this can be accomplished in a type-safe way by injecting a [code]+javax.enterprise.inject.Instance<T>+.

For instance, assume you have a dependent-scoped bean [code]+Bar+ and consider the following:

[source, java]
----
public class Foo {
  @Inject Instance<Bar> barInstance;

  public void pingNewBar() {
    Bar bar = barInstance.get();
    bar.ping();
  }
}
----

In this example, calling [code]+barInstance.get()+ returns a new instance of the dependent-scoped bean [code]+Bar+.

[[sid-5931501]]

=== Deploying Errai CDI

The CDI integration is a plugin to the Errai core framework and represents a CDI portable extension. Which means it is discovered automatically by both Errai and the CDI container. In order to use it, you first need to understand the different runtime models involved when working GWT, Errai, and CDI.

Typically a GWT application lifecycle begins in link:$$http://code.google.com/webtoolkit/doc/latest/DevGuideCompilingAndDebugging.html$$[Development Mode] and finally a web application containing the GWT client code will be deployed to a target container (Servlet Engine, Application Server). This is no way different when working with CDI components to back your application.

What's different however is availability of the CDI container across the different runtimes. In GWT development mode and in a pure servlet environment you need to provide and bootstrap the CDI environment on your own. While any Java EE 6 Application Server already provides a preconfigured CDI container. To accomodate these differences, we need to do a little trickery when executing the GWT Development Mode and packaging our application for deployment.

[NOTE]
.Manual Setup
====
Checkout the <<Manual-Setup-Section,Manual Setup Section>> for instructions on how to manually setup Errai CDI in Development Mode.
====

[[sid-5931328]]

== Marshalling

Errai includes a comprehensive marshalling framework which permits the serialization of domain objects between the browser and the server. From the perspective of GWT, this is a complete replacement for the provided GWT serialization facilities and offers a great deal more flexibility. You can use it with your own application-specific domain models as well as preexisting models, including classes from third-party libraries using configuration files or the custom definitions API.

[[sid-5931328_Marshalling-MappingYourDomain]]

=== Mapping Your Domain

All classes that you intend to be marshalled between the client and the server must be exposed to the marshalling framework explicitly. There are several ways to do that, and this section will take you through the different approaches.

[[sid-5931328_Marshalling-@Portableand@NonPortable]]

==== @Portable and @NonPortable

The easiest way to make a Java class eligible for serialization with Errai Marshalling is to mark it with the [code]+org.jboss.errai.common.client.api.annotations.Portable+ annotation. This tells the marshalling system to generate marshalling and demarshalling code for the annotated class and all of its nested classes.

The mapping strategy that will be used depends on how much information you provide about your model up-front. If you simply annotate a domain type with [code]+@Portable+ and do nothing else, the marshalling system will use an exhaustive strategy to determine how to serialize and deserialize instances of that type and its nested types.

The Errai marshalling system works by enumerating all of the Portable types it can find (by any of the three methods discussed in this section of the reference guide), eliminating all the non-portable types it can find (via [code]+@NonPortable+ annotations and entries in [code]+ErraiApp.properties+), then enumerating the marshallable properties that make up each remaining portable entity type. The rules that Errai uses for enumerating the properties of a portable entity type are as follows:

* If an entity type has a field called [code]+foo+, then that entity has a property called [code]+foo+ unless the field is marked [code]+static+ or [code]+transient+.


Note that the existence of methods called [code]+getFoo()+, [code]+setFoo()+, or both, _does not_ mean that the entity has a property called [code]+foo+. Errai Marshalling always works from fields when discovering properties.

When reading a field [code]+foo+, Errai Marshalling will call the method [code]+getFoo()+ in preference to direct field access if the [code]+getFoo()+ method exists.

When writing a field [code]+foo+, Errai Marshalling gives first preference to a parameter of the _mapping constructor_ (defined below) annotated with [code]+@MapsTo("foo")+. Failing this, Errai Marshalling will the method [code]+setFoo()+ if it exists. As a last resort, Errai Marshalling will use direct field access to write the value of [code]+foo+. 

Each field is mapped independently according to the above priority rules. Portable classes can rely on a mix of constructor, setter/getter, and field access.

For de-marshalling a [code]+@Portable+ type, Errai must know how to obtain a new instance of that type. To do this, it selects a _mapping constructor_ (which could literally be a constructor, but could also be a static factory method) using the following rules:

* If the entity has a constructor where every argument is annotated with [code]+@MapsTo+, then this is the mapping constructor. The constructor doesn't have to be public.
* Otherwise, if the entity has a public static method whose return type matches the entity type and every argument is annotated with [code]+@MapsTo+, then it is the mapping constructor. Unlike a constructor, such a method is free to return an instance of a subtype of the marshalled type, or resolve an instance from a cache. In this case, do keep in mind that left-over properties not covered by the method's [code]+@MapsTo+ parameters will still be written by setters and direct field access.
* Otherwise, if the entity has a public no-arguments constructor (including the one the Java compiler provides in the absence of explicit constructors), it is the mapping constructor.

If no suitable mapping constructor can be found on a type marked [code]+@Portable+, it is a compile-time error.
 
Now let's take a look at some common examples of how this works.

[[sid-5931328_Marshalling-Example%3AASimpleEntity]]

===== Example: A Common Mutable Bean

[source, java]
----
@Portable
public class Person {
  private String name;
  private int age;

  public String getName() {
    return name;
  }

  public void setName(String name) {
    this.name = name;
  }

  public int getAge() {
    return age;
  }
  
  public void setAge(int age) {
    this.age = age;
  }
}
----

This class is a straightforward mutable bean. Errai will read and write the name and age properties via the setter and getter methods. It will create new instances of the type using the default no-args public constructor that the Java compiler generated implicitly. 


[[sid-5931328_Marshalling-Example%3AAnImmutableEntitywithaPublicConstructor]]

===== Example: An Immutable Entity with a Public Constructor

It's always good to aim for truly immutabile value types wherever practical, and Errai's marshalling system does not force you to compromise on this ideal.

[source, java]
----
@Portable
public final class Person {
  private final String name;
  private final int age;

  public Person(@MapsTo("name") String name, @MapsTo("age") int age) {
    this.name = name;
    this.age = age;
  }

  public String getName() {
    return name;
  }

  public int getAge() {
    return age;
  }
}
----

Both fields are final, so they cannot be written by setter methods or by direct field access. But that's okay, because we have given Errai a way to set them using the annotated constructor parameters.


[[sid-5931328_Marshalling-Example%3AAnImmutableEntitywithaFactoryMethod]]

===== Example: An Immutable Entity with a Factory Method

Another good practice is to use a factory pattern to enforce invariance. Once again, let's modify our example.


[source, java]
----
@Portable
public class Person {
  private final String name;
  private final int age;

  private Person(String name, int age) {
    this.name = name;
    this.age = age;
  }

  public static Person createPerson(@MapsTo("name") String name, @MapsTo("age") int age) {
    return new Person(name, age);
  }

  public String getName() {
    return name;
  }

  public int getAge() {
    return age;
  }
}
----

Here we have made our only declared constructor private, and created a static factory method. Notice that we've simply used the same [code]+@MapsTo+ annotation in the same way we did on the constructor from our previous example. The marshaller will see this method and know that it should use it to construct the object.

[[sid-5931328_Marshalling-Example%3AAnImmutableEntitywithaBuilder]]

===== Example: An Immutable Entity with a Builder

For types with a large number of optional attributes, a builder is often the best approach.


[source, java]
----
@Portable
public class Person {
  private final String name;
  private final int age;

  private Person(@MapsTo("name") String name, @MapsTo("age") int age) {
    this.name = name;
    this.age = age;
  }

  public String getName() {
    return name;
  }

  public int getAge() {
    return age;
  }

  @NonPortable
  public static class Builder {
    private String name;
    private int age;

    public Builder name(String name) {
      this.name = name;
      return this;
    }

    public Builder age(int age) {
      this.age = age;
      return this;
    }

    public Person build() {
      return new Person(name, age);
    }
  }
}
----

In this example, we have a nested [code]+Builder+ class that implements the Builder Pattern and calls the private [code]+Person+ constructor. Hand-written code will always use the builder to create [code]+Person+ instances, but the [code]+@MapsTo+ annotations on the private [code]+Person+ constructor tell Errai Marshalling to bypass the builder and construct instances of Person directly.

One final note: as a nested type of [code]+Person+ (which is marked [code]+@Portable+), the builder itself would normally be portable. However, we do not intend to move instances of [code]+Person.Builder+ across the network, so we mark [code]+Person.Builder+ as [code]+@NonPortable+.

[[sid-5931328_Marshalling-ManualMapping]]

==== Manual Mapping

Some classes may be out of your control, making it impossible to annotate them for auto-discovery by the marshalling framework. For cases such as this, there are two approaches to include these classes in your application.

The first approach is the easiest, but is contingent on whether or not the class is directly exposed to the GWT compiler. That means, the classes must be part of a GWT module and within the GWT client packages. See the GWT documentation on link:$$http://code.google.com/webtoolkit/doc/latest/DevGuideCodingBasicsClient.html$$[Client-Side Code] for information on this.

[[sid-5931328_Marshalling-MappingExistingClientClasses]]

[[sid-5931328_Marshalling-MappingExistingClientClassesx]]

===== Mapping Existing Client Classes

If you have client-exposed classes that cannot be annotated with the [code]+@Portable+ annotation, you may manually map these classes so that the marshaller framework will comprehend and produce marshallers for them and their nested types.

To do this, specify them in _ErraiApp.properties_, using the [code]+errai.marshalling.serializableTypes+ attribute with a whitespace separated list of classes to make portable.

.Example ErraiApp.properties defining portable classes.
====


[source, ini]
----
errai.marshalling.serializableTypes=org.foo.client.UserEntity \
                                    org.foo.client.GroupEntity \
                                    org.abcinc.model.client.Profile
----

====

If any of the serializable types have nested classes that you wish to make non-portable, you can specify them like this:

.Example ErraiApp.properties defining nonportable classes.
====


[source, ini]
----
errai.marshalling.nonserializableTypes=org.foo.client.UserEntity$Builder \
                                       org.foo.client.GroupEntity$Builder
----

====

[[sid-5931328_Marshalling-AliasedMappingsofExistingInterfaceContracts]]

===== Aliased Mappings of Existing Interface Contracts

The marshalling framework supports and promotes the concept of marshalling by interface contract, where possible. For instance, the framework ships with a marshaller which can marshall data to and from the [code]+java.util.List+ interface. Instead of having custom marshallers for classes such as [code]+ArrayList+ and [code]+LinkedList+, by default, these implementations are merely aliased to the [code]+java.util.List+ marshaller.

There are two distinct ways to go about doing this. The most straightforward is to specify which marshaller to alias when declaring your class is [code]+@Portable+.


[source, java]
----
package org.foo.client;

@Portable(aliasOf = java.util.List.class)
public MyListImpl extends ArrayList {
  // .. //
}
----

In the case of this example, the marshaller will not attempt to comprehend your class. Instead, it will merely rely on the [code]+java.util.List+ marshaller to dematerialize and serialize instances of this type onto the wire.

If for some reason it is not feasible to annotate the class, directly, you may specify the mapping in the _ErraiApp.properties_ file using the [code]+errai.marshalling.mappingAliases+ attribute.


[source, ini]
----
errai.marshalling.mappingAliases=org.foo.client.MyListImpl->java.util.List \
                                 org.foo.client.MyMapImpl->java.util.Map
----

The list of classes is whitespace-separated so that it may be split across lines.

The example above shows the equivalent mapping for the [code]+MyListImpl+ class from the previous example, as well as a mapping of a class to the [code]+java.util.Map+ marshaller.

The syntax of the mapping is as follows: [code]++<class_to_map>++_->_[code]++<contract_to_map_to>++.

[IMPORTANT]
.Aliases do not inherit fields!
====
When you alias a class to another marshalling contract, extended fields of the aliased class will not be available upon deserialization. For this you must provide custom marshallers for those classes.
====

[[sid-5931328_Marshalling-ManualClassMapping]]

==== Manual Class Mapping

Although the default marshalling strategies in Errai Marshalling will suit the vast majority of use cases, there may be situations where it is necessary to manually map your classes into the marshalling framework to teach it how to construct and deconstruct your objects.

This is accomplished by specifying [code]+MappingDefinition+ classes which inform the framework exactly how to read and write state in the process of constructing and deconstructing objects.

[[sid-5931328_Marshalling-MappingDefinition]]

===== MappingDefinition

All manual mappings should extend the [code]+org.jboss.errai.marshalling.rebind.api.model.MappingDefinition+ class. This is base metadata class which contains data on exactly how the marshaller can deconstruct and construct objects.

Consider the following class:


[source, java]
----
public class MySuperCustomEntity {
   private final String mySuperName;
   private String mySuperNickname;

   public MySuperCustomEntity(String mySuperName) {
     this.mySuperName = mySuperName;;
   }

   public String getMySuperName() {
     return this.mySuperName;
   }

   public void setMySuperNickname(String mySuperNickname) {
     this.mySuperNickname = mySuperNickname;
   }

   public String getMySuperNickname() {
     return this.mySuperNickname;
   }
}
----

Let us construct this object like so:

[source, java]
----
  MySuperCustomEntity entity = new MySuperCustomEntity("Coolio");
  entity.setSuperNickname("coo");
----

It is clear that we may rely on this object's two getter methods to extract the totality of its state. But due to the fact that the [code]+mySuperName+ field is final, the only way to properly construct this object is to call its only public constructor and pass in the desired value of [code]+mySuperName+.

Let us consider how we could go about telling the marshalling framework to pull this off:


[source, java]
----
@CustomMapping
public MySuperCustomEntityMapping extends MappingDefinition {
  public MySuperCustomEntityMapping() {
    super(MySuperCustomEntity.class);                                                          // (1)

    SimpleConstructorMapping cnsMapping = new SimpleConstructorMapping();
    cnsMapping.mapParmToIndex("mySuperName", 0, String.class);                                 // (2)

    setInstantiationMapping(cnsMapping);

    addMemberMapping(new WriteMapping("mySuperNickname", String.class, "setMySuperNickname")); // (3)

    addMemberMapping(new ReadMapping("mySuperName", String.class, "getMySuperName"));          // (4)
    addMemberMapping(new ReadMapping("mySuperNickname", String.class, "getMySuperNickname"));  // (5)
  }
}
----

And that's it. This describes to the marshalling framework how it should go about constructing and deconstructing [code]+MySuperCustomEntity+.

Paying attention to our annotating comments, let's describe what we've done here.

. Call the constructor in [code]+MappingDefinition+ passing our reference to the class we are mapping.


. Using the [code]+SimpleConstructorMapping+ class, we have indicated that a custom constructor will be needed to instantiate this class. We have called the [code]+mapParmToIndex+ method with three parameters. The first, [code]+"mySupername"+ describes the class field that we are targeting. The second parameter, the integer [code]+0+ indicates the parameter index of the constructor arguments that we'll be providing the value for the aforementioned field in this case the first and only, and the final parameter [code]+String.class+ tells the marshalling framework which marshalling contract to use in order to de-marshall the value.


. Using the [code]+WriteMapping+ class, we have indicated to the marshaller framework how to write the [code]+"mySuperNickname"+ field, using the [code]+String.class+ marshaller, and using the setter method [code]+setMySuperNickname+.


. Using the [code]+ReadMapping+ class, we have indicated to the marshaller framework how to read the [code]+"mySuperName"+ field, using the [code]+String.class+ marshaller, and using the getter method [code]+getMySuperName+.


. Using the [code]+ReadMapping+ class, we have indicated to the marshaller framework how to read the [code]+"mySuperNickname"+ field, using the [code]+String.class+ marshaller, and using the getter method [code]+getMySuperNickname+.


[[sid-5931328_Marshalling-CustomMarshallers]]

==== Custom Marshallers

There is another approach to extending the marshalling functionality that doesn't involve mapping rules, and that is to implement your own [code]+Marshaller+ class. This gives you complete control over the parsing and emission of the JSON structure.

The implementation of marshallers is made relatively straight forward by the fact that both the server and the client share the same JSON parsing API.

Consider the included [code]+java.util.Date+ marshaller that comes built-in to the marshalling framework:

.DataMarshaller.java from the built-in marshallers
====


[source, java]
----
@ClientMarshaller(Date.class)
@ServerMarshaller(Date.class)
public class DateMarshaller extends AbstractNullableMarshaller<Date> {
  @Override
  public Date[] getEmptyArray() {
    return new Date[0];
  }

  @Override
  public Date doNotNullDemarshall(final EJValue o, final MarshallingSession ctx) {
    if (o.isObject() != null) {
      EJValue qualifiedValue = o.isObject().get(SerializationParts.QUALIFIED_VALUE);
      if (!qualifiedValue.isNull() && qualifiedValue.isString() != null) {
        return new Date(Long.parseLong(qualifiedValue.isString().stringValue()));
      }
      EJValue numericValue = o.isObject().get(SerializationParts.NUMERIC_VALUE);
      if (!numericValue.isNull() && numericValue.isNumber() != null) {
        return new Date(new Double(numericValue.isNumber().doubleValue()).longValue());
      }
      if (!numericValue.isNull() && numericValue.isString() != null) {
        return new Date(Long.parseLong(numericValue.isString().stringValue()));
      }
    }

    return null;
  }

  @Override
  public String doNotNullMarshall(final Date o, final MarshallingSession ctx) {
    return "{\"" + SerializationParts.ENCODED_TYPE + "\":\"" + Date.class.getName() + "\"," +
            "\"" + SerializationParts.OBJECT_ID + "\":\"" + o.hashCode() + "\"," +
            "\"" + SerializationParts.QUALIFIED_VALUE + "\":\"" + o.getTime() + "\"}";
  }
}
----

====

The class is annotated with both [code]+@ClientMarshaller+ and [code]+@ServerMarshaller+ indicating that this class should be used for both marshalling on the client and on the server.

The [code]+doNotNullDemarshall()+ method is responsible for converting the given JSON object (which has already been parsed and verified non-null) into a Java object.

The [code]+doNotNullMarshall()+ method does roughly the inverse: it converts the given Java object into a String (which must be parseable as a JSON object) for transmission on the wire.

[[sid-5931313]]

== Remote Procedure Calls (RPC)

ErraiBus supports a high-level RPC layer to make typical client-server RPC communication easy on top of the bus. While it is possible to use ErraiBus without ever using this API, you may find it to be a more useful and concise approach for exposing services to the clients.

Please note that this API has changed since version 1.0. RPC services provide a way of creating type-safe mechanisms to make client-to-server calls. Currently, this mechanism only support client-to-server calls, and not vice-versa.

[NOTE]
.Manual Setup
====
Checkout the <<Manual-Setup-Section,Manual Setup Section>> for instructions on how to manually add Errai Messaging or Errai CDI to a project.
====

=== Creating an RPC Interface

Creating a service is straight forward. It requires the definition of a remote interface, and a service class which implements it. See the following:


[source, java]
----
@Remote
public interface MyRemoteService {
  public boolean isEveryoneHappy();
}
----

The [code]+@Remote+ annotation tells Errai that we'd like to use this interface as a remote interface. The remote interface must be part of of the GWT client code. It cannot be part of the server-side code, since the interface will need to be referenced from both the client and server side code. That said, the implementation of a service is relatively simple to the point:


[source, java]
----
@Service
public class MyRemoteServiceImpl implements MyRemoteService {

  public boolean isEveryoneHappy() {
    // blatently lie and say everyone's happy.
    return true;
  }
}
----

That's all there is to it. You use the same [code]+@Service+ annotation as described in Section 2.4. The presence of the remote interface tips Errai off as to what you want to do with the class.

[WARNING]
====
Beginning with Errai 2.0.CR1, the default for automatic service discovery has changed in favour of CDI based applications, meaning RPC service discovery must be explicitly turned on in case Errai CDI is not used (the [code]+weld-integration.jar+ is not on the classpath). This can be done using an init-param in the servlet config of your web.xml:
====


[source, xml]
----
<servlet>
  <servlet-name>ErraiServlet</servlet-name>
  <servlet-class>org.jboss.errai.bus.server.servlet.DefaultBlockingServlet</servlet-class>
  <init-param>
    <param-name>auto-discover-services</param-name>
    <param-value>true</param-value>
    </init-param>
    <load-on-startup>1</load-on-startup>
  </servlet>
----

[[sid-5931313_RemoteProcedureCalls%28RPC%29-Makingcalls]]

=== Making calls

Calling a remote service involves use of the [code]+MessageBuilder+ API. Since all messages are asynchronous, the actual code for calling the remote service involves the use of a callback, which we use to receive the response from the remote method. Let's see how it works:


[source, java]
----
MessageBuilder.createCall(new RemoteCallback<Boolean>() {
  public void callback(Boolean isHappy) {
    if (isHappy) Window.alert("Everyone is happy!");
  }
 }, MyRemoteService.class).isEveryoneHappy();

----

In the above example, we declare a remote callback that receives a Boolean, to correspond to the return value of the method on the server. We also reference the remote interface we are calling, and directly call the method. However, _don't be tempted to write code like this_:


[source, java]
----
 boolean bool = MessageBuilder.createCall(..., MyRemoteService.class).isEveryoneHappy();
----

The above code will never return a valid result. In fact, it will always return null, false, or 0 depending on the type. This is due to the fact that the method is dispatched asynchronously, as in, it does not wait for a server response before returning control. The reason we chose to do this, as opposed to emulate the native GWT-approach, which requires the implementation of remote and async interfaces, was purely a function of a tradeoff for simplicity.

[[sid-5931313_RemoteProcedureCalls%28RPC%29-ProxyInjection]]

==== Proxy Injection

An alternative to using the [code]+MessageBuilder+ API is to have a proxy of the service injected.


[source, java]
----
@Inject
private Caller<MyRemoteService> remoteService;
----

For calling the remote service, the callback objects need to be provided to the [code]+call+ method before the corresponding interface method is invoked.


[source, java]
----
remoteService.call(callback).isEveryoneHappy();
----

The Errai IOC GWT module needs to be inherited to make use of caller injection. To do this, the following line needs to be added to the application's [code]+*.gwt.xml+ file. It is important that this line comes [code]+after+ the Errai Bus module:

[source, xml]
----
  <inherits name="org.jboss.errai.ioc.Container"/>
----

[[sid-5931313_RemoteProcedureCalls%28RPC%29-Handlingexceptions]]

=== Handling exceptions

Handling remote exceptions can be done by providing an [code]+ErrorCallback+ on the client:


[source, java]
----
MessageBuilder.createCall(
  new RemoteCallback<Boolean>() {
    public void callback(Boolean isHappy) {
      if (isHappy) Window.alert("Everyone is happy!");
    }
  },
  new ErrorCallback() {
    public boolean error(Message message, Throwable caught) {
      try {
        throw caught;
      }
      catch (NobodyIsHappyException e) {
        Window.alert("OK, that's sad!");
      }
      catch (Throwable t) {
        GWT.log("An unexpected error has occurred", t);
      }
      return false;
    }
  },
  MyRemoteService.class).isEveryoneHappy();
----

As remote exceptions need to be serialized to be sent to the client, the [code]+@Portable+ annotation needs to be present on the corresponding exception class (see <<sid-5931328, Marshalling>>). Further the exception class needs to be part of the client-side code. For more details on [code]+ErrorCallbacks+ see <<sid-5931306, Handling Errors>>.

[[sid-5931313_RemoteProcedureCalls%28RPC%29-GlobalRPCexceptionhandler]]

==== Global RPC exception handler

In a scenario where many different remote calls potentially throw the same exception types (e.g. exceptions related to authentication or authorization) it can be easier to register a global exception handler instead of providing error callbacks at each RPC invocation. This global exception handler is called in case an exception occurs in the process of a remote call that has no error callback associated with it. So, it will handle an otherwise uncaught exception.


[source, java]
----
@UncaughtExceptionHandler
private void onUncaughtException(Throwable caught) {
  try {
    throw caught;
  }
  catch (UserNotLoggedInException e) {
    // navigate to login dialog
  }
  catch (Throwable t) {
    GWT.log("An unexpected error has occurred", t);
  }
}
----

==== Logging RPC exceptions on the server

Errai logs all exceptions thrown by RPC endpoints on the server at the DEBUG level. To show these messages in your server logs, set the logger "org.jboss.errai.bus.server.io.AbstractRPCMethodCallback" to the DEBUG level. Errai uses SLF4J, so how you go about setting this logger to debug will depend on what logging backend you use.

[[sid-5931313_RemoteProcedureCalls%28RPC%29-ClientsideInterceptors]]

=== Client-side Interceptors

Client-side remote call interceptors provide the ability to manipulate or bypass the remote call before it's being sent. This is useful for implementing crosscutting concerns like caching, for example when the remote call should be avoided if the data is already cached locally.

==== Annotating the Remote Interface

To have a remote call intercepted, either an interface method or the remote interface type has to be annotated with [code]+@InterceptedCall+. If the type is annotated, all interface methods will be intercepted.


[source, java]
----
@Remote
public interface CustomerService {

  @InterceptedCall(MyCacheInterceptor.class)
  public Customer retrieveCustomerById(long id);
}
----

Note that an ordered list of interceptors can be used for specifying an interceptor chain e.g.


[source, java]
----
@InterceptedCall({MyCacheInterceptor.class, MySecurityInterceptor.class})
public Customer retrieveCustomerById(long id);

----

==== Implementing an Interceptor

Implementing an interceptor is easy:


[source, java]
----
public class MyCacheInterceptor implements RpcInterceptor {

  @Override
  public void aroundInvoke(final RemoteCallContext context) {
    // e.g check if the result is cached and carry out the actual call only in case it's not.
    context.proceed() // executes the next interceptor in the chain or the actual remote call.
    // context.setResult() // sets the result directly without carrying out the remote call.
  }
}
----

The [code]+RemoteCallContext+ passed to the [code]+aroundInvoke+ method provides access to the intercepted method's name and read/write access to the parameter values provided at the call site.

Calling [code]+proceed+ executes the next interceptor in the chain or the actual remote call if all interceptors have already been executed. If access to the result of the (asynchronous) remote call is needed in the interceptor, one of the overloaded versions of [code]+proceed+ accepting a [code]+RemoteCallback+ has to be used instead.

The result of the remote call can be manipulated by calling [code]+RemoteCallContext.setResult()+.

Not calling [code]+proceed+ in the interceptor bypasses the actual remote call, passing [code]+RestCallContext.getResult()+ to the [code]+RemoteCallBack+ provided at the call site.


==== Annotating the Interceptor (alternative)

If you cannot (or do not wish to) annotate the remote interface you may instead define remote call interceptors by annotating the interceptor class itself with [code]+@InterceptsRemoteCall+.  This annotation requires the developer to specify the remote interface that should be intercepted.  The interceptor will then be applied to all methods in that interface.  If the interface method is annotated with [code]+InterceptedCall+, that annotation will win out.

[source, java]
----
@InterceptsRemoteCall({ MyRemoteInterface.class, MyOtherRemoteInterface.class })
public class CustomRpcInterceptor implements RpcInterceptor {

  @Override
  public void aroundInvoke(final RemoteCallContext context) {
    // interceptor logic goes here
  }
}
----

This approach sacrifices granularity (you cannot intercept individual methods on the remote interface).  However, it does allow method interception without modification to the remote interface (which is particularly useful when the developer is not in control of the remote interface).


==== Interceptors and IOC

It is worth noting that interceptors *may* be defined as managed beans using the [code]+@Dependent+, [code]+@Singleton+, or [code]+@ApplicationScoped+ annotations.  If the Errai application is using IOC (i.e. imports the IOC Errai module) *and* the interceptor is annotated as a managed bean, then the IOC container will be used to get/create the interceptor instance.  This allows developers to [code]+@Inject+ dependencies into interceptors.  If IOC is not being used, or else the interceptor is not properly annotated, then the interceptor class will simply be instantiated via *new*.


[[sid-5931313_RemoteProcedureCalls%28RPC%29-SessionandrequestobjectsinRPCendpoints]]

=== Session and request objects in RPC endpoints

Before invoking an endpoint method Errai sets up an [code]+RpcContext+ that provides access to message resources that are otherwise not visible to RPC endpoints.


[source, java]
----
@Service
public class MyRemoteServiceImpl implements MyRemoteService {

  public boolean isEveryoneHappy() {
    HttpSession session = RpcContext.getHttpSession();
    ServletRequest request = RpcContext.getServletRequest();
    ...
    return true;
  }
}
----

[[sid-5931313_RemoteProcedureCalls%28RPC%29-Batchingremotecalls]]

=== Batching remote calls

Some use cases require multiple interactions with the server to complete. Errai's RPC mechanism allows for batched invocations of remote methods that will be executed using a single server round-trip. This is useful for reducing the number of simultaneous HTTP connections and at the same time allows for reusing and combining fine-grained remote services.

Injecting a BatchCaller instead of a Caller<T> is all it takes to make use of batched remote procedure calls.


[source, java]
----
@EntryPoint
public class MyBean {
 
 @Inject
 private BatchCaller batchCaller;
 
 private void someMethod() {
    // ...
    batchCaller.call(remoteCallback1, RemoteService1.class).method1();
    batchCaller.call(remoteCallback2, RemoteService2.class).method2();
    
    // Invokes the accumulated remote requests using a single server round-trip.
    batchCaller.sendBatch();
 }
 
}
----

The remote methods will get executed only after [code]+sendBatch()+ was called. The method [code]+sendBatch+ accepts an additional [code]+RemoteCallback+ instance as a parameter which will we invoked when all remote calls have completed in success. Consequently, an [code]+ErrorCallback+ can also be provided which will get executed for all remote calls that have completed in failure.

=== Asynchronous handling of RPCs on the server

If computing the result of an RPC call takes a significant amount of time (i.e. because a third party service needs to be contacted or a long running query needs to be executed) it might be preferable to release the request-processing thread so it can perform other work and provide the result in a different execution context farther in the future. So, the RPC endpoint method can return immediately and the thread handling the incoming request doesn't need to stay active until the result is available. Computing and setting the result can be done in a different thread (i.e. from a smaller thread pool provided by a library).

Errai provides a special return type [code]+CallableFuture+ to indicate to the RPC system that the result of the remote method call will be provided asynchronously (after the remote method call has returned).

Here's an example returning a result of type String:

[source, java]
----
@Remote
public interface LongRunningService {
  public CallableFuture<String> someLongRunningTask();
}
----

[source, java]
----
@Service
public class LongRunningServiceImpl implements LongRunningService {
  @Override
  public CallableFuture<String> someLongRunningTask() {
    final CallableFuture<String> future = CallableFutureFactory.get().createFuture(String.class);

    final ExecutorService executorService = Executors.newSingleThreadExecutor();
    executorService.submit(new Runnable() {
      @Override
      public void run() {
        try {
          Thread.sleep(5000);
          future.setValue("result");
        }
        catch (Throwable t) {
          t.printStackTrace();
        }
      }
    });
    executorService.shutdown();
    return future;
  }
}
----

Note that the client-side code does not change when using this feature and will work exactly as described in <<sid-5931313_RemoteProcedureCalls%28RPC%29-Makingcalls>> i.e.: 

[source, java]
----
MessageBuilder.createCall(new RemoteCallback<String>() {
  @Override
  public void callback(String response) {
    assertEquals("foobar", response);
    finishTest();
  }
}, LongRunningService.class).someLongRunningTask();
----

[[sid-19398997]]

== Errai JAX-RS

JAX-RS (Java API for RESTful Web Services) is a Java EE standard (JSR-311) for implementing REST-based Web services in Java. Errai JAX-RS brings this standard to the browser and simplifies the integration of REST-based services in GWT client applications. Errai can generate proxies based on JAX-RS interfaces which will handle all the underlying communication and serialization logic. All that's left to do is to invoke a Java method.

Errai's JAX-RS support consists of the following:

* A client-side API to communicate with JAX-RS endpoints
* A code generator that runs at your project's build time, providing proxy implementations for each JAX-RS resource interfaces visible within the GWT module
* Errai IoC and CDI providers that allow you to [code]+@Inject+ instances of [code]+Caller<T>+ (the same API used in Errai RPC)
* Integration with either Errai Marshalling or Jackson to translate request and response data between Java object and a string-based wire format

[NOTE]
.Manual Setup
====
Checkout the <<Manual-Setup-Section,Manual Setup Section>> for instructions on how to manually add JAX-RS to your project. You can also go to the link:$$https://github.com/errai/errai-tutorial/archive/master.zip$$[Errai tutorial project] or the link:$$https://github.com/errai/errai/tree/master/errai-demos$$[demo collection] for an example of JAX-RS.
====

[[sid-19398997_ErraiJAX-RS-ServerSideJAXRSImplementation]]

=== Server-Side JAX-RS Implementation

Errai's JAX-RS support consists mostly of features that make the client side easier and more reliable to maintain. You will need to use an existing third-party JAX-RS implementation on the server side. All Java EE 6 application servers include such a module out-of-the-box. If you are developing an application that you intend to deploy on a plain servlet container, you will have to choose a JAX-RS implementation (for example, RestEasy) and configure it properly in your web.xml.

Alternatively, you could keep your REST resource layer in a completely separate web application hosted on the same server (perhaps build an Errai JAX-RS client against an existing REST service you developed previously). In this case, you could factor out the shared JAX-RS interface into a shared library, leaving the implementation in the non-Errai application.

Finally, you can take advantage of the cross-origin resource sharing (CoRS) feature in modern browsers and use Errai JAX-RS to send requests to a third-party server. The third-party server would have to be configured to allow cross-domain requests. In this case, you would write a JAX-RS-Annotated interface describing the remote REST resources, but you would not create an implementation of that interface.

[[sid-19398997_ErraiJAX-RS-SharedJAXRSInterface]]

=== Shared JAX-RS Interface

Errai JAX-RS works by leveraging standard Java interfaces that bear JAX-RS annotations. You will also want these interfaces visible to server-side code so that your JAX-RS resource classes can implement them (and inherit the annotations). This keeps the whole setup typesafe, and reduces duplication to the bare minimum. The natural solution, then is to put the JAX-RS interfaces under the client.shared package within your GWT module:

* project
** src/main/java
*** com.mycompany.myapp
**** MyApp.gwt.xml _[the app's GWT module]_
*** com.mycompany.myapp.client.local
**** MyAppClientStuff.java _[code that @Injects Caller<MyAppRestResource>]_
*** com.mycompany.myapp.client.shared
**** CustomerService.java _[the JAX-RS interface]_
*** com.mycompany.myapp.server
**** CustomerServiceImpl.java _[the server-side JAX-RS resource implementation]_

The contents of the server-side files would be as follows:

.CustomerService.java
====

[source, java]
----
@Path("customers")
public interface CustomerService {
  @GET
  @Produces("application/json")
  public List<Customer> listAllCustomers();

  @POST
  @Consumes("application/json")
  @Produces("text/plain")
  public long createCustomer(Customer customer);
}
----

====

The above interface is visible both to server-side code and to client-side code. It is used by client-side code to describe the available operations, their parameter types, and their return types. If you use your IDE's refactoring tools to modify this interface, both the server-side and client-side code will be updated automatically.

.CustomerServiceImpl.java
====


[source, java]
----
public class CustomerServiceImpl implements CustomerService {

  @Override
  public List<Customer> listAllCustomers() {
    // Use a database API to look up all customers in back-end data store
    // Return the resulting list
  }

  @Override
  public long createCustomer(Customer customer) {
    // Store new Customer instance in back-end data store
  }
}
----

====

The above class implements the shared interface. Since it performs database and/or filesystem operations to manipulate the persistent data store, it is not GWT translatable, and it's therefore kept in a package that is not part of the GWT module.

[IMPORTANT]
.Save typing and reduce duplication
====
Note that all JAX-RS annotations ([code]+@Path+, [code]+@GET+, [code]+@Consumes+, and so on) can be inherited from the interface. You do not need to repeat these annotations in your resource implementation classes.
====

[[sid-19398997_ErraiJAX-RS-CreatingRequests]]

=== Creating Requests

This section assumes you have already set up the CustomerService JAX-RS endpoint as described in the previous section.

To create a request on the client, all that needs to be done is to invoke [code]+RestClient.create()+, thereby providing the JAX-RS interface, a response callback and to invoke the corresponding interface method:

.App.java
====

[source, java]
----
...
Button create = new Button("Create", new ClickHandler() {
  public void onClick(ClickEvent clickEvent) {
    Customer customer = new Customer(firstName, lastName, postalCode);
    RestClient.create(CustomerService.class, callback).createCustomer(customer);
  }
});
...
----

====

For details on the callback mechanism see <<sid-19398997_ErraiJAX-RS-HandlingResponses,Handling Responses>>.

[[sid-19398997_ErraiJAX-RS-ProxyInjection]]

==== Proxy Injection

Injectable proxies can be used as an alternative to calling [code]+RestClient.create()+.


[source, java]
----
@Inject
private Caller<CustomerService> customerService; 
----

To create a request, the callback objects need to be provided to the [code]+call+ method before the corresponding interface method is invoked.


[source, java]
----
customerService.call(callback).listAllCustomers();
----

To use caller injection, your application needs to inherit the Errai IOC GWT module. To do this, just add this line to your application's [code]+*.gwt.xml+ file and make sure it comes [code]+after+ the Errai JAX-RS module (see <<sid-19398997_ErraiJAX-RS-GettingStarted,Getting Started>>):


[source, xml]
----
  <inherits name="org.jboss.errai.ioc.Container"/>
----

[NOTE]
====
The JAX-RS interfaces need to be visible to the GWT compiler and must therefore reside within the client packages (e.g. client.shared).
====

[[sid-19398997_ErraiJAX-RS-HandlingResponses]]

=== Handling Responses

An instance of Errai's [code]+RemoteCallback<T>+ has to be passed to the [code]+RestClient.create()+ call, which will provide access to the JAX-RS resource method's result. [code]+T+ is the return type of the JAX-RS resource method. In the example below it's just a [code]+Long+ representing a customer ID, but it can be any serializable type (see <<sid-5931328, Marshalling>>).

[source, java]
----
RemoteCallback<Long> callback = new RemoteCallback<Long>() {
  public void callback(Long id) {
    Window.alert("Customer created with ID: " + id);
  }
};
----

One special use case for the [code]+RemoteCallback+ is for JAX-RS interface methods that return a [code]+javax.ws.rs.core.Response+ type. Errai does not provide a client implementation of the [code]+javax.ws.rs.core.Response+ class. Instead calls to methods returning a [code]+javax.ws.rs.core.Response+ should use a [code]+RemoteCallback<com.google.gwt.http.client.Response>+. The [code]+MarshallingWrapper+ class can be used to manually deserialize an entity from the body of a response.


[source, java]
----
RemoteCallback<Response> callback = new RemoteCallback<Response>() {
  public void callback(Response response) {
    Window.alert("HTTP status code: " + response.getStatusCode());
    Window.alert("HTTP response body: " + response.getText());
    Window.alert("Demarshalled entity: " + MasrhallingWrapper.fromJSON(response.getText()));
  }
};
----

[[sid-19398997_ErraiJAX-RS-HandlingErrors]]

==== Handling Errors

For handling errors, Errai's error callback mechanism can be reused and an instance of [code]+ErrorCallback+ can optionally be passed to the [code]+RestClient.create()+ call. In case of an HTTP error, the [code]+ResponseException+ provides access to the [code]+Response+ object. All other [code]+Throwables+ indicate a communication problem.


[source, java]
----
ErrorCallback errorCallback = new RestErrorCallback() {
  public boolean error(Request request, Throwable throwable) {
    try {
      throw throwable;
    }
    catch (ResponseException e) {
      Response response = e.getResponse();
      // process unexpected response
      response.getStatusCode();
    }
    catch (Throwable t) {
      // process unexpected error (e.g. a network problem)
    }
    return false;
  }
};
----

To provide more customized error handling, Errai also defines client side exception handling via the [code]+ClientExceptionMapper+ interface.  The client exception mapper allows developers to process a REST [code]+Response+ into a [code]+Throwable+ prior to the error being delivered to the [code]+ErrorCallback+ described above.  The exception mapper class must be annotated with [code]+javax.ws.rs.ext.Provider+ as well as implement the [code]+ClientExceptionMapper+ interface.

[source, java]
----
@Provider
public class MyAppExceptionMapper implements ClientExceptionMapper {
  
  /**
   * @see org.jboss.errai.enterprise.client.jaxrs.ClientExceptionMapper#fromResponse(com.google.gwt.http.client.Response)
   */
  @Override
  public Throwable fromResponse(Response response) {
    if (response.getStatusCode() == 404)
      return new MyAppNotFoundException();
    else
      return new MyAppServerError(response.getStatusText());
  }

}

----

[IMPORTANT]
.Must be used in conjunction with [code]+RestErrorCallback+
====
It is important to note that the [code]+ClientExceptionMapper+ will only be invoked when the callback passed to the [code]+Caller+ is an instance of [code]+RestErrorCallback+.
====

The [code]+ClientExceptionMapper+ will, by default, be invoked for every error response.  However, Errai also provides the [code]+org.jboss.errai.enterprise.shared.api.annotations.MapsFrom+ annotation which provides for additional granularity.  An exception mapper can be annotated so that it is only invoked for methods on specific REST interfaces.

[source, java]
----
@Provider
@MapsFrom({ SomeRestInterface.class })
public class SpecificClientExceptionMapper implements ClientExceptionMapper {

  /**
   * @see org.jboss.errai.enterprise.client.jaxrs.ClientExceptionMapper#fromResponse(com.google.gwt.http.client.Response)
   */
  @Override
  public Throwable fromResponse(Response response) {
     ... // Do something specific here
  }

}
----

[[sid-19398997_ErraiJAX-RS-AbortingRequests]]

=== Accesssing and aborting requests

An instance of Errai's [code]+RequestCallback+ can optionally be passed to the [code]+RestClient.create()+ call, which will
provide access to the underlying HTTP request. The callback is invoked synchronously after the HTTP request has been initiated.
This means that you will have access to the request immediately after the call.

[source, java]
----
RequestCallback requestCallback = new RequestCallback() {
  @Override
  public void callback(Request request) {
    this.request = request;
  }
};

RestClient.create(SearchService.class, callback, requestCallback).find(query);
----

This allows you to cancel a pending request. Alternatively, a [code]+RequestHolder+ can be used instead.

[source, java]
----
RequestHolder searchRequestHolder = new RequestHolder();
RestClient.create(SearchService.class, callback, searchRequestHolder).find(query);
...
if (searchRequestHolder.isAlive()) {
  searchRequestHolder.getRequest().cancel();
}
----

[[sid-19398997_ErraiJAX-RS-ClientsideInterceptors]]

=== Client-side Interceptors

Client-side remote call interceptors provide the ability to manipulate or bypass the request before it's being sent. This is useful for implementing crosscutting concerns like caching or security features e.g:

* avoiding the request when the data is cached locally
* adding special HTTP headers or parameters to the request

==== Annotating the JAX-RS Interface

To have a JAX-RS remote call intercepted, either an interface method or the JAX-RS implementation class method has to be annotated with [code]+@InterceptedCall+. If the type is annotated, all interface methods will be intercepted.


[source, java]
----
@Path("customers")
public interface CustomerService {

  @GET
  @Path("/{id}")
  @Produces("application/json")
  @InterceptedCall(MyCacheInterceptor.class)
  public Customer retrieveCustomerById(@PathParam("id") long id);
}
----

Note that an ordered list of interceptors can be used for specifying an interceptor chain e.g.


[source, java]
----
@InterceptedCall({MyCacheInterceptor.class, MySecurityInterceptor.class})
public Customer retrieveCustomerById(@PathParam("id") long id);
----

==== Implementing an Interceptor

Implementing an interceptor is easy:


[source, java]
----
public class MyCacheInterceptor implements RestClientInterceptor {

  @Override
  public void aroundInvoke(final RestCallContext context) {
    RequestBuilder builder = context.getRequestBuilder();
    builder.setHeader("headerName", "value");
    context.proceed();
  }
}
----

The [code]+RestCallContext+ passed to the [code]+aroundInvoke+ method provides access to the context of the intercepted JAX-RS (REST) remote call. It allows to read and write the parameter values provided at the call site and provides read/write access to the [code]+RequestBuilder+ instance which has the URL, HTTP headers and parameters set.

Calling [code]+proceed+ executes the next interceptor in the chain or the actual remote call if all interceptors have already been executed. If access to the result of the (asynchronous) remote call is needed in the interceptor, one of the overloaded versions of [code]+proceed+ accepting a [code]+RemoteCallback+ has to be used instead.

The result of the remote call can be manipulated by calling [code]+RestCallContext.setResult()+.

Not calling [code]+proceed+ in the interceptor bypasses the actual remote call, passing [code]+RestCallContext.getResult()+ to the [code]+RemoteCallBack+ provided at the call site.


==== Annotating the Interceptor (alternative)

If you cannot (or do not wish to) annotate the JAX-RS interface you may instead define remote call interceptors by annotating the interceptor class itself with [code]+@InterceptsRemoteCall+. This annotation requires the developer to specify the JAX-RS interface that should be intercepted. The interceptor will then be applied to all methods in that interface.  If the interface method is annotated with [code]+InterceptedCall+, that annotation will win out.

[source, java]
----
@InterceptsRemoteCall({ MyJaxrsInterface.class, MyOtherJaxrsInterface.class })
public class MyCacheInterceptor implements RestClientInterceptor {

  @Override
  public void aroundInvoke(final RestCallContext context) {
    // Do interceptor logic here
    context.proceed();
  }
}
----

This approach sacrifices granularity (you cannot intercept individual methods on the JAX-RS interface). However, it does allow method interception without modification to the JAX-RS interface (which is particularly useful when the developer is not in control of the JAX-RS interface).


==== Interceptors and IOC

It is worth noting that interceptors *may* be defined as managed beans using the [code]+@Dependent+, [code]+@Singleton+, or [code]+@ApplicationScoped+ annotations. If the Errai application is using IOC (i.e. imports the IOC Errai module) *and* the interceptor is annotated as a managed bean, then the IOC container will be used to get/create the interceptor instance. This allows developers to [code]+@Inject+ dependencies into interceptors.  If IOC is not being used, or else the interceptor is not properly annotated, then the interceptor class will simply be instantiated via *new*.


[[sid-19398997_ErraiJAX-RS-WireFormat]]

=== Wire Format

Errai's JSON format will be used to serialize/deserialize your custom types. See <<sid-5931328, Marshalling>> for details.

Alternatively, a Jackson compatible JSON format can be used on the wire. See <<sid-19398997_ErraiJAX-RS-Configuration,Configuration>> for details on how to enable Jackson marshalling.

=== Path

All paths specified using the [code]+@Path+ annotation on JAX-RS interfaces are by definition relative paths. Therefore, by default, it is assumed that the JAX-RS endpoints can be found at the specified paths relative to the GWT client application's context path.

[IMPORTANT]
.Configuring the Path
====
To learn more about configuring the path, checkout <<sid-19398997_ErraiJAX-RS-Configuration,the JAX-RS Configuration Section>>.
====

=== CSRF Protection

Errai provides a filter for protecting REST endpoints from Cross Site Request Forgery (CSRF) attacks. The filter `org.jboss.errai.bus.server.servlet.CSRFTokenFilter` generates a CSRF token for every HTTP session that is required as an HTTP header for all POST, PUT, and DELETE requests. Requests made with an Errai `Caller<T>` will automatically negotiate for a CSRF token, or the same filter can be added to the host page, where it will inject the token onto the page as a JavaScript variable.

[[sid-54493688]]

== Errai JPA

[WARNING]
.Deprecated
====
Errai JPA is deprecated. These features are no longer being updated and will be removed in a future release.
====

Starting with Errai 2.1, Errai implements a subset of JPA 2.0. With Errai JPA, you can store and retrieve entity objects on the client side, in the browser's local storage. This allows the reuse of JPA-related code (both entity class definitions and procedural logic that uses the EntityManager) between client and server.

Errai JPA implements the following subset of JPA 2.0:

* Annotation-based configuration
* Entity Types with
* Identifiers of any numeric type (int, long, short, etc.)
* Generated identifiers


* Regular attributes of any JPA Basic type (Java primitive types, boxed primitives, enums, BigInteger, BigDecimal, String, Date, Time, and Timestamp)
* Singular and Plural (collection-valued) attributes of other entity types
* All association types (one-to-one, one-to-many, many-to-one, many-to-many)
* All association cascade rules (ALL, PERSIST, MERGE, REMOVE, REFRESH, DETACH)
* Circular and self references work properly
* Polymorphic queries and collections (queries for a base entity type can result in instances of its subtypes)


* Property access by field or get/set methods


* Named, typed JPQL queries that select exactly one entity type
* With cascading fetch of related entities
* With or without [code]+WHERE+ clause
* All boolean, arithmetic, and string operators supported
* All String manipulation functions supported


* With or without [code]+ORDER BY+ clause


* Lifecycle events and entity lifecycle listeners
* Much of the Metamodel API ([code]+Metamodel+, [code]+EntityType+, [code]+SingularAttribute+, [code]+PluralAttribute+, etc.)


[IMPORTANT]
.It's all client-side
====
Errai JPA is a declarative, typesafe interface to the web browser's [code]+localStorage+ object. As such it is a _client-side implementation_ of JPA. Objects are stored and fetched from the browser's local storage, _not_ from the JPA provider on the server side.
====

[[sid-54493688_ErraiJPA-GettingStarted]]

=== Getting Started

[NOTE]
.Manual Setup
====
Checkout the <<Manual-Setup-Section,Manual Setup Section>> for instructions on how to manually add Errai JPA to your project.
====

==== META-INF/persistence.xml

Errai ignores META-INF/persistence.xml for purposes of client-side JPA. Instead, Errai scans all Java packages that are part of your GWT modules for classes annotated with [code]+@Entity+. This allows you the freedom of defining a persistence.xml that includes both shared entity classes that you use on the client and the server, plus server-only entities that are defined in a server-only package.

[[sid-54493688_ErraiJPA-DeclaringanEntityClass]]

==== Declaring an Entity Class

Classes whose instances can be stored and retrieved by JPA are called _entities_. To declare a class as a JPA entity, annotate it with [code]+@Entity+.

JPA requires that entity classes conform to a set of rules. These are:

* The class must have an ID attribute
* The class must have a public or protected constructor that takes no arguments
* The class must be public and nonfinal
* No methods or persistent fields of the class may be final
* The class must be a top-level type (not a nested or inner class)


Here is an example of a valid entity class with an ID attribute ([code]+id+) and a String-valued persistent attribute ([code]+name+):


[source, java]
----
@Entity
public class Genre {

  @Id @GeneratedValue
  private int id;

  private String name;

  // This constructor is used by JPA
  public Genre() {}

  // This constructor is not used by JPA
  public Genre(String name) {
    this();
    this.name = name;
  }


  // These getter and Setter methods are optional:

  public int getId() { return id; }
  public void setId(int id) { this.id = id; }

  public String getName() { return name; }
  public void setName(String name) { this.name = name; }
}
----

[[sid-54493688_ErraiJPA-EntityAttributes]]

===== Entity Attributes

The state of fields and JavaBeans properties of entities are generally persisted with the entity instance. These persistent things are called _attributes_.

JPA Attributes are subdivided into two main types: _singular_ and _plural_. Singular attributes are scalar types like [code]+Integer+ or [code]+String+. Plural attributes are collection values, such as [code]+List<Integer>+ or [code]+Set<String>+.

The values of singular attributes (and the elements of plural attributes) can be of any application-defined entity type or a JPA Basic type. The JPA basic types are all of the Java primitive types, all boxed primitives, enums, BigInteger, BigDecimal, String, Date ([code]+java.util.Date+ or [code]+java.sql.Date+), Time, and Timestamp.

You can direct JPA to read and write your entity's attributes by direct field access or via JavaBeans property access methods (that is, "getters and setters"). Direct field access is the default. To request property access, annotate the class with [code]+@Access(AccessType.PROPERTY)+. If using direct field access, attribute-specific JPA annotations should be on the fields themselves; when using property access, the attribute-specific annotations should be on the getter method for that property.

[[sid-54493688_ErraiJPA-IDAttributesandAutoGeneratedIdentifiers]]

===== ID Attributes and Auto-Generated Identifiers

Each entity class must have exactly one ID attribute. The value of this attribute together with the fully-qualified class name uniquely identifies an instance to the entity manager.

ID values can be assigned by the application, or they can be generated by the JPA entity manager. To declare a generated identifier, annotate the field with [code]+@GeneratedValue+. To declare an application-assigned identifier, leave off the [code]+@GeneratedValue+ annotation.

Generated identifier fields must not be initialized or modified by application code. Application-assigned identifier fields must be initialized to a unique value before the entity is persisted by the entity manager, but must not be modified afterward.

[[sid-54493688_ErraiJPA-SinglevaluedAttributes]]

===== Single-valued Attributes

By default, every field of a JPA basic type is a persistent attribute. If a basic type field should not be presistent, mark it with [code]+transient+ or annotate it with [code]+@Transient+.

Single-valued attributes of entity types must be annotated with [code]+@OneToOne+ or [code]+@ManyToOne+.

Single-valued types that are neither entity types nor JPA Basic types are not presently supported by Errai JPA. Such attributes must be marked transient.

Here is an example of an entity with single-valued basic attributes and a single-valued relation to another entity type:


[source, java]
----
@Entity
public class Album {

  @GeneratedValue
  @Id
  private Long id;

  private String name;

  @ManyToOne
  private Artist artist;

  private Date releaseDate;

  private Format format;

  public Long getId() { return id; }
  public void setId(Long id) { this.id = id; }

  public String getName() { return name; }
  public void setName(String name) { this.name = name; }

  public Artist getArtist() { return artist; }
  public void setArtist(Artist artist) { this.artist = artist; }

  public Date getReleaseDate() { return releaseDate; }
  public void setReleaseDate(Date releaseDate) { this.releaseDate = releaseDate; }

  public Format getFormat() { return format; }
  public void setFormat(Format format) { this.format = format; }
}
----

[[sid-54493688_ErraiJPA-Plural%28collectionvalued%29Attributes]]

===== Plural (collection-valued) Attributes

Collection-valued types [code]+Collection<T>+, [code]+Set<T>+, and [code]+List<T>+ are supported. JPA rules require that all access to the collections are done through the collection interface method; never by specific methods on an implementation.

The element type of a collection attribute can be a JPA basic type or an entity type. If it is an entity type, the attribute must be annotated with [code]+@OneToMany+ or [code]+@ManyToMany+.

Here is an example of an entity with two plural attributes:


[source, java]
----
@Entity
public class Artist {

  @Id
  private Long id;

  private String name;

  // a two-way relationship (albums refer back to artists)
  @OneToMany(mappedBy="artist", cascade=CascadeType.ALL)
  private Set<Album> albums = new HashSet<Album>();

  // a one-way relationship (genres don't reference artists)
  @OneToMany(cascade={CascadeType.PERSIST, CascadeType.MERGE})
  private Set<Genre> genres = new HashSet<Genre>();

  public Long getId() { return id; }
  public void setId(Long id) { this.id = id; }

  public String getName() { return name; }
  public void setName(String name) { this.name = name; }

  public Set<Album> getAlbums() { return albums; }
  public void setAlbums(Set<Album> albums) { this.albums = albums; }

  public Set<Genre> getGenres() { return genres; }
  public void setGenres(Set<Genre> genres) { this.genres = genres; }
}
----

[[sid-54493688_ErraiJPA-EntityLifecycleStates]]

==== Entity Lifecycle States

[[sid-54493688_ErraiJPA-CascadeRules]]

===== Cascade Rules

When an entity changes state (more on this later), that state change can be cascaded automatically to related entity instances. By default, no state changes are cascaded to related entities. To request cascading of entity state changes, use the [code]+cascade+ attribute on any of the relationship quantifiers [code]+@OneToOne+, [code]+@ManyToOne+, [code]+@OneToMany+, and [code]+@ManyToMany+.

[options="header"]
|===============
|CascadeType value|Description
|[code]+PERSIST+|Persist the related entity object(s) when this entity is persisted
|[code]+MERGE+|Merge the attributes of the related entity object(s) when this entity is merged
|[code]+REMOVE+|Remove the related entity object(s) from persistent storage when this one is removed
|[code]+REFRESH+|Not applicable in Errai JPA
|[code]+DETACH+|Detach the related entity object(s) from the entity manager when this object is detached
|[code]+ALL+|Equivalent to specifying all of the above
|===============

For an example of specifying cascade rules, refer to the [code]+Artist+ example above. In that example, the cascade type on [code]+albums+ is [code]+ALL+. When a particular [code]+Artist+ is persisted or removed, detached, etc., all of that artist's albums will also be persisted or removed, or detached correspondingly. However, the cascade rules for [code]+genres+ are different: we only specify [code]+PERSIST+ and [code]+MERGE+. Because a [code]+Genre+ instance is reusable and potentially shared between many artists, we do not want to remove or detach these when one artist that references them is removed or detached. However, we still want the convenience of automatic cascading persistence in case we persist an [code]+Artist+ which references a new, unmanaged [code]+Genre+.

[[sid-54493688_ErraiJPA-ObtaininganinstanceofEntityManager]]

==== Obtaining an instance of EntityManager

The entity manager provides the means for storing, retrieving, removing, and otherwise affecting the lifecycle state of entity instances.

To obtain an instance of EntityManager on the client side, use Errai IoC (or CDI) to inject it into any client-side bean:


[source, java]
----
@EntryPoint
public class Main {
  @Inject EntityManager em;
}
----

[[sid-54493688_ErraiJPA-StoringandUpdatingEntities]]

===== Storing and Updating Entities

To store an entity object in persistent storage, pass that object to the [code]+EntityManager.persist()+ method. Once this is done, the entity instance transitions from the _new_ state to the _managed_ state.

If the entity references any related entities, these entities must be in the managed state already, or have cascade-on-persist enabled. If neither of these criteria are met, an [code]+IllegalStateException+ will be thrown.

See an example in the following section.

[[sid-54493688_ErraiJPA-FetchingEntitiesbyID]]

===== Fetching Entities by ID

If you know the unique ID of an entity object, you can use the [code]+EntityManager.find()+ method to retrieve it from persistent storage. The object returned from the [code]+find()+ method will be in the managed state.

Example:


[source, java]
----
    // make it
    Album album = new Album();
    album.setArtist(null);
    album.setName("Abbey Road");
    album.setReleaseDate(new Date(-8366400000L));

    // store it
    EntityManager em = getEntityManager();
    em.persist(album);
    em.flush();
    em.detach(album);
    assertNotNull(album.getId());

    // fetch it
    Album fetchedAlbum = em.find(Album.class, album.getId());
    assertNotSame(album, fetchedAlbum);
    assertEquals(album.toString(), fetchedAlbum.toString());
----

[[sid-54493688_ErraiJPA-RemovingEntitiesfromPersistentStorage]]

===== Removing Entities from Persistent Storage

To remove a persistent managed entity, pass it to the [code]+EntityManager.remove()+ method. As the cascade rules specify, related entities will also be removed recursively.

Once an entity has been removed and the entity manager's state has been flushed, the entity object is unmanaged and back in the _new_ state.

[[sid-54493688_ErraiJPA-ClearingallLocalStorage]]

====== Clearing all Local Storage

Errai's EntityManager class provides a [code]+removeAll()+ method which removes everything from the browser's persistent store for the domain of the current webpage.

This method is not part of the JPA standard, so you must down-cast your client-side [code]+EntityManager+ instance to [code]+ErraiEntityManager+. Example:


[source, java]
----
@EntryPoint
public class Main {

  @Inject EntityManager em;

  void resetJpaStorage() {
    ((ErraiEntityManager) em).removeAll();
  }
}
----

[[sid-54493688_ErraiJPA-DetachingEntityInstancesfromtheEntityManager]]

===== Detaching Entity Instances from the Entity Manager

For every entity instance in the managed state, changes to the attribute values of that entity are persisted to local storage whenever the entity manager is flushed. To prevent this automatic updating from happening, you can _detach_ an entity from the entity manager. When an instance is detached, it is not deleted. All information about it remains in persistent storage. The next time that entity is retrieved, the entity manager will create a new and separate managed instance for it.

To detach one particular object along with all related objects whose cascade rules say so, call [code]+EntityManager.detach()+ and pass in that object.

To detach all objects from the entity manager at once, call [code]+EntityManager.detachAll()+.

[[sid-54493688_ErraiJPA-TestingifanEntityisintheManagedState]]

===== Testing if an Entity is in the Managed State

To check if a given object is presently managed by the entity manager, call [code]+EntityManager.contains()+ and pass in the object of interest.

[[sid-54493688_ErraiJPA-NamedQueries]]

==== Named Queries

To retrieve one or more entities that match a set of criteria, Errai JPA allows the use of JPA _named queries_. Named queries are declared in annotations on entity classes.

[[sid-54493688_ErraiJPA-DeclaringNamedQueries]]

===== Declaring Named Queries

Queries in JPA are written in the JPQL language. As of Errai 2.1, Errai JPA does not support all JPQL features. Most importantly, implicit and explicit joins in queries are not yet supported. Queries of the following form generally work:


[source, java]
----
SELECT et FROM EntityType et WHERE [expression with constants, named parameters and attributes of et] ORDER BY et.attr1 [ASC|DESC], et.attr2 [ASC|DESC]
----

Here is how to declare a JPQL query on an entity:


[source, java]
----
@NamedQuery(name="selectAlbumByName", query="SELECT a FROM Album a WHERE a.name=:name")
@Entity
public class Album {
  ... same as before ...
}
----

To declare more than one query on the same entity, wrap the [code]+@NamedQuery+ annotations in [code]+@NamedQueries+ like this:


[source, java]
----
@NamedQueries({
  @NamedQuery(name="selectAlbumByName", query="SELECT a FROM Album a WHERE a.name = :name"),
  @NamedQuery(name="selectAlbumsAfter", query="SELECT a FROM Album a WHERE a.releaseDate >= :startDate")
})
@Entity
public class Album {
  ... same as before ...
}
----

[[sid-54493688_ErraiJPA-ExecutingNamedQueries]]

===== Executing Named Queries

To execute a named query, retrieve it by name and result type from the entity manager, set the values of its parameters (if any), and then call one of the execution methods [code]+getSingleResult()+ or [code]+getResultList()+.

Example:


[source, java]
----
    TypedQuery<Album> q = em.createNamedQuery("selectAlbumByName", Album.class);
    q.setParameter("name", "Let It Be");
    List<Album> fetchedAlbums = q.getResultList();
----

[[sid-54493688_ErraiJPA-EntityLifecycleEvents]]

==== Entity Lifecycle Events

To receive a notification when an entity instance transitions from one lifecycle state to another, use an entity lifecycle listener.

These annotations can be applied to methods in order to receive notifications at certain points in an entity's lifecycle. These events are delivered for direct operations initiated on the EntityManager as well as operations that happen due to cascade rules.

[options="header"]
|===============
|Annotation|Meaning
|[code]+@PrePersist+|The entity is about to be persisted or merged into the entity manager.
|[code]+@PostPersist+|The entity has just been persisted or merged into the entity manager.
|[code]+@PreUpdate+|The entity's state is about to be captured into the browser's localStorage.
|[code]+@PostUpdate+|The entity's state has just been captured into the browser's localStorage.
|[code]+@PreRemove+|The entity is about to be removed from persistent storage.
|[code]+@PostRemove+|The entity has just been removed from persistent storage.
|[code]+@PostLoad+|The entity's state has just been retrieved from the browser's localStorage.
|===============

JPA lifecycle event annotations can be placed on methods in the entity type itself, or on a method of any type with a public no-args constructor.

To receive lifecycle event notifications directly on the affected entity instance, create a no-args method on the entity class and annotate it with one or more of the lifecycle annotations in the above table.

For example, here is a variant of the Album class where instances receive notification right after they are loaded from persistent storage:


[source, java]
----
@Entity
public class Album {

  ... same as before ...

  @PostLoad
  public void postLoad() {
    System.out.println("Album " + getName() + " was just loaded into the entity manager");
  }
}
----

To receive lifecycle methods in a different class, declare a method that takes one parameter of the entity type and annotate it with the desired lifecycle annotations. Then name that class in the [code]+@EntityListeners+ annotation on the entity type.

The following example produces the same results as the previous example:


[source, java]
----
@Entity
@EntityListeners(StandaloneLifecycleListener.class)
public class Album {

  ... same as always ...

}

public class StandaloneLifecycleListener {

  @PostLoad
  public void albumLoaded(Album a) {
  public void postLoad() {
    System.out.println("Album " + a.getName() + " was just loaded into the entity manager");
  }
}
----

[[sid-54493688_ErraiJPA-JPAMetamodel]]

==== JPA Metamodel

Errai captures structural information about entity types at compile time and makes them available in the GWT runtime environment. The JPA metamodel includes methods for enumerating all known entity types and enumerating the singular and plural attributes of those types. Errai extends the JPA 2.0 Metamodel by providing methods that can create new instances of entity classes, and read and write attribute values of existing entity instances.

As an example of what is possible, this functionality could be used to create a reusable UI widget that can present an editable table of any JPA entity type.

To access the JPA Metamodel, call the [code]+EntityManager.getMetamodel()+ method. For details on what can be done with the stock JPA metamodel, see the API's javadoc or consult the JPA specification.

[[sid-54493688_ErraiJPA-ErraiExtensionstoJPAMetamodelAPI]]

===== Errai Extensions to JPA Metamodel API

Wherever you obtain an instance of [code]+SingularAttribute+ from the metamodel API, you can down-cast it to [code]+ErraiSingularAttribute+. Likewise, you can down-cast any [code]+PluralAttribute+ to [code]+ErraiPluralAttribute+.

In either case, you can read the value of an arbitrary attribute by calling [code]+ErraiAttribute.get()+ and passing in the entity instance. You can set any attribute's value by calling [code]+ErraiAttribute.set()+, passing in the entity instance and the new value.

In addition to [code]+get()+ and [code]+set()+, [code]+ErraiPluralAttribute+ also has the [code]+createEmptyCollection()+ method, which creates an empty collection of the correct interface type for the given attribute.

[[sid-54493688_ErraiJPA-JPAFeaturesNotImplementedinErrai2.4]]

==== JPA Features Not Implemented in Errai 2.4

The following features are not yet implemented, but could conceivably be implemented in a future Errai JPA release:

* Flush modes other than immediate
* Transactions, including EntityManager.getTransaction()
* In named queries:
* Joins and nested attribute paths ([code]+a.b.c+) do not yet work, although single-step attribute paths ([code]+a.b+) do.
* The [code]+SELECT+ clause must specify exactly one entity type. Selection of individual attributes is not yet implemented.
* Embedded collections
* Compound identifiers (presently, only basic types are supported for entity IDs)
* [code]+EntityManager.refresh()+ to pick up changes made in localStorage from a different browser window/tab.
* Criteria Queries
* The generated static Metamodel
* The [code]+@PersistenceContext+ annotation currently has no effect in client-side code (use [code]+@Inject+ instead)


The following may never be implemented due to limitations and restrictions in the GWT client-side environment:

* [code]+EntityManager.createQuery(String, ...)+ (that is, unnamed queries) are impractical because JPQL queries are parsed at compile time, not in the browser.
* [code]+EntityManager.createNativeQuery(String, ...)+ don't make sense because the underlying database is just a hash table. It does not have a query language.
* Persistent attributes of type [code]+java.util.Calendar+ because the [code]+Calendar+ class is not in GWT's JRE emulation library.


[[sid-54493688_ErraiJPA-OtherCaveatsforErrai2.1JPA]]

==== Other Caveats for Errai 2.1 JPA

We hope to remedy these shortcomings in a future release.

* In Dev Mode, changes to entity classes are not discovered on page refresh. You need to restart Dev Mode.
* The local data stored in the browser is not encrypted


[[sid-71467090]]

=== Errai JPA Data Sync

Traditional JPA implementations allow you to store and retrieve entity objects on the server side. Errai's JPA implementation allows you to store and retrieve entity objects in the web browser using the same APIs. All that's missing is the ability to synchronize the stored data between the server side and the client side.

This is where Errai JPA Data Sync comes in: it provides an easy mechanism for two-way synchronization of data sets between the client and the server.

[[sid-71467090_ErraiJPADataSync-HowToUseIt]]

==== How To Use It

[NOTE]
.Manual Setup
====
Checkout the <<Manual-Setup-Section,Manual Setup Section>> for instructions on how to manually add Errai JPA Datasync to your project.
====

[[sid-71467090_ErraiJPADataSync-ARunningExample]]

===== A Running Example

For the rest of this chapter, we will refer to the following Entity classes, which are defined in a [code]+shared+ package that's visible to client and server code:


[source, java]
----
@Portable
@Entity
@NamedQuery(name = "allUsers", query = "SELECT u FROM User u")
public class User {

  @Id
  @GeneratedValue
  private long id;

  private String name;

  // getters and setters omitted
}
----

[source, java]
----
@Portable
@Entity
@NamedQuery(name = "groceryListsForUser", query = "SELECT gl FROM GroceryList gl WHERE gl.owner=:user")
public class GroceryList {

  @Id
  @GeneratedValue
  private long id;

  @ManyToOne
  private User owner;

  @OneToMany(cascade = { CascadeType.PERSIST, CascadeType.MERGE, CascadeType.REFRESH })
  private List<Item> items = new ArrayList<Item>();

  // getters and setters omitted
}
----

[source, java]
----
@Portable
@Entity
@NamedQuery(name = "allItems", query = "SELECT i FROM Item i")
public class Item {

  @Id
  @GeneratedValue
  private long id;

  private String name;
  private String department;
  private String comment;
  private Date addedOn;

  @ManyToOne(cascade = { CascadeType.PERSIST, CascadeType.MERGE, CascadeType.REFRESH })
  private User addedBy;

  // getters and setters omitted
}
----

To summarize: there are three entity types: [code]+User+, [code]+GroceryList+, and [code]+Item+. Each [code]+GroceryList+ belongs to a [code]+User+ and has a list of [code]+Item+ objects.

[NOTE]
====
All the entities involved in the data synchronization request must be marshallable via Errai Marshalling. This is normally accomplished by adding the [code]+@Portable+ annotation to each JPA entity class, but it is also acceptable to list them in [code]+ErraiApp.properties+. See the <<sid-5931328, Marshalling>> section for more details.
====

Now let's say we want to synchronize the data for all of a user's grocery lists. This will make them available for offline use through Errai JPA, and at the same time it will update the server with the latest changes made on the client. Ultimately, the sync operation is accomplished via an annotated method or an asynchronous call into `ClientSyncManager`, but first we have to prepare a few things on the client and the server.

[[sid-71467090_ErraiJPADataSync-ServerSide%E2%80%93DataSyncServiceImpl]]

===== Server Side DataSyncServiceImpl

A data sync operation begins when the client-side sync manager sends an <<sid-5931313,Errai RPC>> request to the server. Although a server-side implementation of the remote interface is provided, you are responsible for implementing a thin wrapper around it. This wrapper serves two purposes:

. It allows you to determine how to obtain a reference to the JPA EntityManager (and to choose which persistence context the server-side data sync will operate on)
. It allows you to inspect the contents of each sync request and make security decisions about access to particular entities

If you are deploying to a container that supports CDI and EJB 3, you can use this DataSyncServiceImpl as a template for your own:

[source, java]
----
@Stateless @org.jboss.errai.bus.server.annotations.Service
public class DataSyncServiceImpl implements DataSyncService {

  @PersistenceContext
  private EntityManager em;

  private final JpaAttributeAccessor attributeAccessor = new JavaReflectionAttributeAccessor();

  @Inject private LoginService loginService;

  @Override
  public <X> List<SyncResponse<X>> coldSync(SyncableDataSet<X> dataSet, List<SyncRequestOperation<X>> remoteResults) {

    // Ensure a user is logged in
    User currentUser = loginService.whoAmI();
    if (currentUser == null) {
      throw new IllegalStateException("Nobody is logged in!");
    }

    // Ensure user is accessing their own data!
    if (dataSet.getQueryName().equals("groceryListsForUser")) {
      User requestedUser = (User) dataSet.getParameters().get("user");
      if (!currentUser.getId().equals(requestedUser.getId())) {
        throw new AccessDeniedException("You don't have permission to sync user " + requestedUser.getId());
      }
    }
    else {
      throw new IllegalArgumentException("You don't have permission to sync dataset " + dataSet.getQueryName());
    }

    DataSyncService dss = new org.jboss.errai.jpa.sync.server.DataSyncServiceImpl(em, attributeAccessor);
    return dss.coldSync(dataSet, remoteResults);
  }
}
----

If you are not using EJB 3, you will not be able to use the [code]+@PersistenceContext+ annotation. In this case, obtain a reference to your EntityManager the same way you would anywhere else in your application.

[[ErraiJPADataSync-ClientSide-Declarative]]

===== Client Side -- Declarative

Like many Errai features, Errai JPA DataSync provides an annotation-driven programming model and a programmatic API.
You can choose which to use based on your needs and preferences.

The declarative data sync API is driven by the `@Sync` annotation. Consider the following example client-side class:

[source, java]
----
  // This injected User object could have been set up in a @PostConstruct method instead of being injected.
  @Inject
  private User syncThisUser;

  @Sync(query = "groceryListsForUser", params = { @SyncParam(name = "user", val = "{syncThisUser}") })
  private void onDataSyncComplete(SyncResponses<GroceryList> responses) {
    Window.alert("Data Sync Complete!");
  }
----

By placing the above code snippet in a client-side bean, you tell Errai JPA Data Sync that, as long as a managed
instance of the bean containing the `@Sync` method exists, the Data Sync system should keep all grocery lists
belonging to the `syncThisUser` user in sync between the client-side JPA EntityManager and the server-side EntityManager.
Right now, the data sets are kept in sync using a sync request every 5 seconds. In the future, this may be optimised
to an incremental approach that pushes changes as they occur.

The annotated method needs to have exactly one parameter of type `SyncResponses` and will
be called each time a data sync operation has completed. All sync operations passed to the
method will have already been applied to the local EntityManager, with conflicts resolved in
favour of the server's version of the data. The original client values are available in the
`SyncResponses` object, which gives you a chance to implement a different conflict
resolution policy.

The `query` attribute on the `@Sync` annotation must refer to an existing JPA Named Query that is defined on a shared
JPA entity class.

The `params` attribute is an array of `@SyncParam` annotations. There must be exactly one `@SyncParam` for each named
parameter in the JPA query (positional parameters are not supported). If the `val` argument is surrounded with brace
brackets (as it is in the example aboce) then it is interpreted as a reference to a declared or inherited field in
the containing class. Otherwise, it is interpreted as a literal String value.

[NOTE]
====
Field-reference sync params are captured just after the bean's `@PostConstruct` method is invoked. This means that
values of referenced fields can be provided using `@Inject` (which in turn could come from a CDI Producer method)
or by code in the `@PostConstruct` method.
====

Transport (network) errors are logged to the slf4j logger channel `org.jboss.errai.jpa.sync.client.local.ClientSyncWorker`.
As of Errai 3.0.0.M4, it is not possible to specify a custom error handler using the declarative API. See the next
section for information about the programmatic API.


[[ErraiJPADataSync-ClientSide-Programmatic]]

===== Client Side -- Programmatic

[source, java]
----
  @Inject private ClientSyncManager syncManager;
  @Inject private EntityManager em;

  public void syncGroceryLists(User forUser) {
    RemoteCallback<List<SyncResponse<GroceryList>>> onCompletion = new RemoteCallback<List<SyncResponse<GroceryList>>>() {
      @Override
      public void callback(List<SyncResponse<GroceryList>> response) {
        Window.alert("Data Sync Complete!");
      }
    };

    ErrorCallback<?> onError = new BusErrorCallback() {

      @Override
      public boolean error(Message message, Throwable throwable) {
        Window.alert("Data Sync failed!");
        return false;
      }
    };

    Map<String, Object> queryParams = new HashMap<String, Object>();
    queryParams.put("user", forUser);

    syncManager.coldSync("groceryListsForUser", GroceryList.class, queryParams, onCompletion, onError);
  }
----

[IMPORTANT]
====
The [code]+onCompletion+ and [code]+onError+ callbacks are optional. In the unlikely case that your application doesn't
care if a data sync request completed successfully, you can pass [code]+null+ for either callback.
====

Once your [code]+onCompletion+ callback has been notified, the server and client will have the same entities stored in
their respective databases for all entities reachable from the given query result.

[[sid-71467090_ErraiJPADataSync-DealingWithConflicts]]

===== Dealing With Conflicts

When the client sends the sync request to the server, it includes information about the state it expects each entity to be in. If an entity's state on the server does not match this expected state on the client, the server ignores the client's change request and includes a [code]+ConflictResponse+ object in the sync reply.

When the client processes the sync responses from the server, it applies the new state from the server to the local data store. This overwrites the change that was initially requested from the client. In short, you could call this the "server wins" conflict resolution policy.

In some cases, your application may be able to do something smarter: apply domain-specific knowledge to merge the conflict automatically, or prompt the user to perform a manual merge. In order to do this, you will have to examine the server response from inside the [code]+onCompletion+ callback you provided to the [code]+coldSync()+ method:

[source, java]
----
    RemoteCallback<List<SyncResponse<GroceryList>>> onCompletion = new RemoteCallback<List<SyncResponse<GroceryList>>>() {
      @Override
      public void callback(List<SyncResponse<GroceryList>> responses) {
        for (SyncResponse<GroceryList> response : responses) {
          if (response instanceof ConflictResponse) {
            ConflictResponse<GroceryList> cr = (ConflictResponse<GroceryList>) response;
            List<Item> expectedItems = cr.getExpected().getItems();
            List<Item> serverItems = cr.getActualNew().getItems();
            List<Item> clientItems = cr.getRequestedNew().getItems();

            // merge the list of items by comparing each to expectedItems
            List<Item> merged = ...;

            // update local storage with the merged list
            em.find(GroceryList.class, cr.getActualNew().getId()).setItems(merged);
            em.flush();
          }
        }
      }
    };
----

Remember, because of Errai's default "server wins" resolution policy, the call to [code]+em.find(GroceryList.class, cr.getActualNew().getId())+ will return a GroceryList object that has already been updated to match the state present in [code]+serverItems+.

[NOTE]
====
Searching for ConflictResponse objects in the [code]+onCompletion+ callback is the only way to recover client data that was clobbered in a conflict. If you do not merge this data back into local storage, or at least retain a reference to the [code]+cr.getRequestedNew()+ object, this conflicting client data will be lost forever.

In a future release of Errai JPA, we plan to provide a client-side callback mechanism for custom conflict handling. If such a callback is registered, it will override the default behaviour.
====

[[sid-51282340]]

== Data Binding

Errai's data binding module provides the ability to bind model objects to UI components. The bound properties of the model and the UI components will automatically be kept in sync for as long as they are bound. With Errai Data Binding there is no need to write code for UI updates in response to model changes and no need to register listeners to update the model in response to UI changes.

[[sid-51282340_DataBinding-GettingStarted]]

=== Getting Started

The data binding module is directly integrated with <<sid-51806600, Errai UI>> and <<sid-54493688, Errai JPA>> but can also be used as a standalone project in any GWT client application:

[NOTE]
.Manual Setup
====
Checkout the <<Manual-Setup-Section,Manual Setup Section>> for instructions on how to manually add Errai Data Binding to your project.
====

[[sid-51282340_DataBinding-BindableObjects]]

==== Bindable Objects

Objects that should participate in data bindings have to be marked as [code]+@Bindable+ and must follow Java bean conventions. All editable properties of these objects are then bindable to UI widgets.

.Customer.java
====

[source, java]
----
@Bindable
public class Customer {
  ...
  private String name;

  public String getName() {
    return name;
  }

  public void setName(String name) {
    this.name = name;
  }
  ...
}
----

====

[IMPORTANT]
====
If you cannot or prefer not to annotate your classes with [code]+@Bindable+, you can alternatively specify bindable types in your ErraiApp.properties using a whitespace-separated list of fully qualified class names: [code]+errai.ui.bindableTypes=org.example.Model1 org.example.Model2+
====

[[sid-51282340_DataBinding-InitializingaDataBinder]]

==== Initializing a DataBinder

An instance of [code]+DataBinder+ is required to create bindings. It can either be

injected into a client-side bean:


[source, java]
----
public class CustomerView {
  @Inject
  private DataBinder<Customer> dataBinder;
}
----

or created manually:

[source, java]
----
DataBinder<Customer> dataBinder = DataBinder.forType(Customer.class);
----

In both cases above, the [code]+DataBinder+ instance is associated with a new instance of the model (e.g. a new [code]+Customer+ object). A [code]+DataBinder+ can also be associated with an already existing object:


[source, java]
----
DataBinder<Customer> dataBinder = DataBinder.forModel(existingCustomerObject);
----

In case there is existing state in either the model object or the UI components before the they are bound, initial state synchronization can be carried out to align the model and the corresponding UI fields.

For using the model object's state to set the initial values in the UI:


[source, java]
----
DataBinder<Customer> dataBinder = DataBinder.forModel(existingCustomerObject, InitialState.FROM_MODEL);
----

For using the UI values to set the initial state in the model object:


[source, java]
----
DataBinder<Customer> dataBinder = DataBinder.forModel(existingCustomerObject, InitialState.FROM_UI);
----

[[sid-51282340_DataBinding-CreatingBindings]]

=== Creating Bindings

Bindings can be created by calling the [code]+bind+ method on a [code]+DataBinder+ instance, thereby specifying which widgets should be bound to which properties of the model. It is possible to use property chains for bindings, given that all nested properties are of bindable types. When binding to [code]+customer.address.streetName+, for example, both [code]+customer+ and [code]+address+ have to be of a type annotated with [code]+@Bindable+.

[source, java]
----
import elemental2.dom.HTMLInputElement;
...

public class CustomerView {
  @Inject private DataBinder<Customer> dataBinder;

  @Inject private HTMLInputElement nameInput; <1>
  @Inject private HTMLInputElement ageInput; <2>
  // more fields...

  @PostConstruct
  private void init() {

    nameInput.type = "text";
    ageInput.type = "number";

    Customer customer = dataBinder
        .bind(nameInput, "name") <1>
        .bind(ageInput, "age") <2>
        .getModel();
  }
}
----

[NOTE]
.Elemental 2 API
====
`nameInput` and `ageInput` are of type `HTMLInputElement`, which is provided by Elemental 2 [1] as a representation of the actual DOM. Every Elemental 2 class or interface is  `@JsType(isNative=true)`. More on this later.

[1] https://github.com/google/elemental2
====

[NOTE]
.Errai DOM wrappers at `org.jboss.errai.common.client.dom` are still supported.
====
Since Elemental 2 API became the standard DOM API in Errai, using Errai DOM wrappers became deprecated, but their use is still supported, **though not recommended**.
====

<1> As `nameInput` is an `input[type='text']` element, Errai will correctly infer that it stores a String.
<2> `ageInput` is an `input[type='number']` element. Errai will also be able to infer that this stores a number.

After the call to [code]+dataBinder.bind()+ in the example above, the customer object's name property and the [code]+nameInput+ are kept in sync until either the [code]+dataBinder.unbind()+ method is called or the [code]+CustomerView+ bean is destroyed.

That means that a call to [code]+customer.setName()+ will automatically update the value of the HTMLInputElement and any change to the `nameInput` value in the browser will update the customer object's name property. So, [code]+customer.getName()+ will always reflect the currently displayed value of the [code]+nameInput+.

[NOTE]
====
It's important to retrieve the model instance using dataBinder.getModel() before making changes to it as the data binder will provide a proxy to the model to ensure that changes will update the corresponding UI components.
====

[TIP]
====
Errai also provides a <<sid-51282340_DataBinding-DeclarativeBinding,declarative binding API>> that can be used to create bindings automatically based on matching field and model property names.
====

[[sid-51282340_DataBinding-SpecifyingConverters]]

=== Specifying Converters

Errai has built-in conversion support for all Number types as well as Boolean and Date to java.lang.String and vice versa. However, in some cases it will be necessary to provide custom converters (e.g. if a custom date format is desired). This can be done on two levels.

[[sid-51282340_DataBinding-Registeringaglobaldefaultconverter]]

==== Registering a global default converter

[source, java]
----
@DefaultConverter
public class MyCustomDateConverter implements Converter<Date, String> {

  private static final String DATE_FORMAT = "YY_DD_MM";

  @Override
  public Class<Date> getModelType() {
    return Date.class;
  }

  @Override
  public Date toModelValue(String widgetValue) {
    return DateTimeFormat.getFormat(DATE_FORMAT).parse(widgetValue);
  }

  @Override
  public Class<String> getComponentType() {
    return String.class;
  }

  @Override
  public String toWidgetValue(Date modelValue) {
    return DateTimeFormat.getFormat(DATE_FORMAT).format((Date) modelValue);
  }
}
----

All converters annotated with [code]+@DefaultConverter+ will be registered as global defaults calling [code]+Convert.registerDefaultConverter()+. Note that the [code]+Converter+ interface specifies two type parameters. The first one represents the type of the model field, the second one the type held by the widget (e.g. [code]+String+ for widgets implementing [code]+HasValue<String>+). These default converters will be used for all bindings with matching model and widget types.

[[sid-51282340_DataBinding-Providingabindingspecificconverter]]

==== Providing a binding-specific converter

Alternatively, converter instances can be passed to the [code]+dataBinder.bind()+ calls.


[source, java]
----
dataBinder.bind(textBox, "name", customConverter);
----

Converters specified on the binding level take precedence over global default converters with matching types. Errai will validate that the converter model type matches the actual type of the bound property. If Errai is able to infer the value type in the bound UI component, it will also validate that it matches the component type of the converter.

==== Errai UI Value Inference

For many kinds of DOM elements and Widgets Errai can correctly infer the type of value stored. When Errai cannot infer the component type, it will fallback to the component type of any specified converters. If no converters are specified, Errai assumes the UI component stores a String.

==== UI Component Values

Originally, Errai only supported binding with Widgets implementing `com.google.gwt.user.client.TakesValue`. Now that Errai supports binding with DOM elements directly here are all the binding rules:

* As before, if a component implements `com.google.gwt.user.client.TakesValue` or `com.google.gwt.user.client.ui.HasValue`, it is bound using that interface. The type can only be inferred at runtime for Widgets in gwt-user.

* If a component implements `com.google.gwt.user.client.ui.HasText` it is bound using that interface. The value type can only be `String`.

* If a component is a native DOM element (via JS interop or a `JavaScriptObject`), it is bound by the following rules:

** An `InputElement` stores the bound value in its `value` attribute. The type of the value is determined by the element's `type` attribute (`text` has type `String`, `number` has type `Double`, `checkbox` has type `Boolean`, etc.).

** All other elements store bound values as text content (i.e. the value between the HTML tags). The content is presumed to be a strings.

* If a component implements `org.jboss.errai.common.client.api.IsElement`, binding is performed on the DOM element returned by `IsElement.getElement()` with the above specified rules.

* If a component implements `org.jboss.errai.common.client.api.elemental2.IsElement`, binding is performed on the DOM element returned by `IsElement.getElement()` with the above specified rules.

[NOTE]
.Inference at Run-Time versus Inference at Compile-Time
====
The above rules for inferring values are those used when you directly use the data-binding API. Using the declarative API it is possible create custom JS interop interfaces for DOM elements where you can specify how values are bound to the element (see <<Customizing-Element-Binding-Behaviour,Customizing Element Binding Behaviour>>).
====

[[sid-51282340_DataBinding-PropertyChangeHandlers]]

=== Property Change Handlers

In some cases keeping the model and the UI in sync is not enough. Errai's [code]+DataBinder+ allows for the registration of [code]+PropertyChangeHandlers+ for specific properties, property expressions or all properties of a bound model. A property expression can be a property chain such as customer.address.street. It can end in a wildcard to indicate that changes of any property of the corresponding bean should be observed (e.g [code]+"customer.address.\*"+). A double wildcard can be used at the end of a property expression to register a cascading change handler for any nested property (e.g [code]+"customer.\**"+ or just [code]+"**"+).

This provides a uniform notification mechanism for model and UI value changes. [code]+PropertyChangeHandlers+ can be used to carry out any additional logic that might be necessary after a model or UI value has changed.


[source, java]
----
dataBinder.addPropertyChangeHandler(new PropertyChangeHandler() {
  @Override
  public void onPropertyChange(PropertyChangeEvent event) {
    Window.alert(event.getPropertyName() + " changed to:" + event.getNewValue());
  }
});
----


[source, java]
----
dataBinder.addPropertyChangeHandler("name", new PropertyChangeHandler() {
  @Override
  public void onPropertyChange(PropertyChangeEvent event) {
    Window.alert("name changed to:" + event.getNewValue());
  }
});
----

[[sid-51282340_DataBinding-DeclarativeBinding]]

=== Declarative Binding

Programmatic binding as described above (see <<sid-51282340_DataBinding-CreatingBindings,Creating Bindings>>) can be tedious when working with UI components that contain a large number of input fields. Errai provides an annotation-driven binding API that can be used to create bindings automatically which cuts a lot of boilerplate code. Additionally the declarative API also supports binding properties to native jsinterop types or [code]+JavaScriptObjects+ that wrap DOM elements. The declarative API will work in any <<sid-5931402,Errai IOC>> managed bean (including <<sid-51806600, Errai UI>> templates). Simply inject a data binder or model object and declare the bindings using [code]+@Bound+.

Here is a simple example using an injected model object provided by the [code]+@Model+ annotation (field injection is used here, but constructor and method injection are supported as well):

[source, java]
----
@Dependent
public class CustomerView {
  @Inject @Model
  private Customer customer;

  @Inject @Bound
  private HTMLInputElement name;

  @Bound
  private Label id = new Label();

  ....
}
----

Here is the same example injecting a [code]+DataBinder+ instead of the model object. This is useful when more control is needed (e.g. the ability to register property change handlers). The [code]+@AutoBound+ annotation specifies that this [code]+DataBinder+ should be used to bind the model to all enclosing widgets annotated with [code]+@Bound+. This example uses field injection again but constructor and method injection are supported as well.

[source, java]
----
import static elemental2.dom.DomGlobal.document;
...

@Dependent
public class CustomerView {

  @Inject @AutoBound
  private DataBinder<Customer> customerBinder;

  @Inject @Bound
  private HTMLInputElement name;

  @Bound
  private HTMLLabelElement id = (HTMLLabelElement) document.createElement("label"); (1)

  ...
}
----
. Casting is necessary here. That is the Elemental 2's recommended way to create `HTMLElement` instances without injection. Using `@Inject` would have the exact same effect.

In both examples above an instance of the [code]+Customer+ model is automatically bound to the corresponding UI components based on matching field names. The model object and the UI fields will automatically be kept in sync. UI components from all enclosing fields and methods annotated with [code]+@Bound+, of the class that defines the [code]+@AutoBound DataBinder+ or [code]+@Model+ and all its super classes, are used.

[[Customizing-Element-Binding-Behaviour]]

==== Customizing Element Binding Behaviour

Since Widget bindings can use the `HasValue` or `TakesValue` interfaces at runtime, these can obviously be used to add customized binding behaviour. But you might well be wondering how this is done when binding directly to elements.

Custom element binding behaviour can be achieved by creating your own element wrappers with JS interop.

[source, java]
----
@JsType(isNative=true, name="HTMLLabelElement", namespace = JsPackage.GLOBAL) <1>
public class IntegerLabel extends elemental2.dom.HTMLLabelElement <2>
                          implements org.jboss.errai.common.client.ui.HasValue<Integer> <3>
{
  @JsOverlay <4>
  public Integer getValue() {
    return Integer.valueOf(textContent);
  }

  @JsOverlay <4>
  public void setValue(Integer content) {
    textContent = content.toString();
  }
}
----

<1> In the JS interop API, native JS types are thin wrappers around JavaScript objects.
<2> The type inherits Elemental 2 API's `HTMLLabelElement`.
<3> This `HasValue` interface is analogous to the on in gwt-user, but it is *only meant for native JS types*.
<4> The overridden methods of `HasValue` are `@JsOverlay` methods. Even though `IntegerLabel` wil be a native JavaScript object at runtime, we can add `@JsOverlay` methods to add some behaviour on top of the JavaScript API.

Using declarative binding, you can bind an integer value to this `IntegerLabel`, and Errai will use the `@JsOverlay` implementations of `getValue`/`setValue` to manipulate the value in the underlying label element.

[NOTE]
.HasValue and other JS interop mappings
====
At `@JsOverlay` is the most powerful way to define custom binding behaviour, but in some cases it can be more convenient to use `@JsProperty` or `@JsMethod` to map the `HasValue` methods to properties or member functions on the underlying JavaScript object.
====

[WARNING]
.Only supported via declarative API
====
Because of limitations on native JS types, this approach using the native `HasValue` interface only works with declarative binding.
====

[[sid-51282340_DataBinding-Default%2CSimple%2CandChainedPropertyBindings]]

==== Default, Simple, and Chained Property Bindings

By default, bindings are determined by matching field names to property names on the model object. In the examples above, the field [code]+name+ was automatically bound to the JavaBeans property [code]+name+ of the model ([code]+user+ object). If the field name does not match the model property name, you can use the [code]+property+ attribute of the [code]+@Bound+ annotation to specify the name of the property. The property can be a simple name (for example, "name") or a property chain (for example, [code]+user.address.streetName+). When binding to a property chain, all properties but the last in the chain must refer to @Bindable values.

The following example illustrates all three scenarios:

[source, java]
----
@Bindable
public class Address {
  private String line1;
  private String line2;
  private String city;
  private String stateProv;
  private String country;

  // getters and setters
}

@Bindable
public class User {
  private String name;
  private String password;
  private Date dob;
  private Address address;
  private List<Role> roles;

  // getters and setters
}

@Templated
public class UserWidget {
  @Inject @AutoBound DataBinder<User> user;
  @Inject @Bound HTMLInputElement name;
  @Inject @Bound(property="dob") DatePicker dateOfBirth;
  @Inject @Bound(property="address.city") TextBox city;
}
----

In [code]+UserWidget+ above, the [code]+name+ text box is bound to [code]+user.name+ using the default name matching; the [code]+dateOfBirth+ date picker is bound to [code]+user.dob+ using a simple property name mapping; finally, the [code]+city+ text box is bound to [code]+user.address.city+ using a property chain. Note that the [code]+Address+ class is required to be [code]+@Bindable+ in this case.

[[sid-51282340_DataBinding-DataConverters]]

==== Data Converters

The [code]+@Bound+ annotation further allows to specify a converter to use for the binding (see <<sid-51282340_DataBinding-SpecifyingConverters,Specifying Converters>> for details). This is how a binding specific converter can be specified on a data field:

[source, java]
----
@Inject
@Bound(converter=MyDateConverter.class)
@DataField
private HTMLInputElement date;
----

==== Updating model values on UI text changes

By default, Errai DataBinding updates model values when the corresponding Widget fires a ValueChangeEvent. For text-based widgets, this means that the model values are updated only once the widget loses focus. However in some cases, you may also need to update a model's value as soon as the text changes in the Widget.

Errai allows you to do this by setting the [code]+onKeyUp+ flag in the [code]+@Bound+ annotation. *_Note that this parameter can only be used on Widgets that extend GWT's ValueBoxBase widget, DOM wrappers backed by input elements and any class or interface of the Elemental 2 API_*. Setting this parameter to [code]+true+ will cause the model value to update on a KeyUpEvent as well as the default ValueChangeEvent. This will result in the model object being updated as soon as any text is entered/removed from the Widget. You can specify this as follows:

[source, java]
----
@Inject
@Bound(onKeyUp = true)
private HTMLInputElement name;
----

You can also achieve the same effect using programmatic bindings. To do this, you can use the method [code]+DataBinder.bind(Widget widget, String property, Converter converter, boolean bindOnKeyUp)+. As an example, take a look at the following code snippet:

[source, java]
----
@Inject
DataBinder<Model> binder;

@Inject
private HTMLInputElement nameTextBox;

...

@PostConstruct
public void onLoad() {
  binder.bind(nameTextBox, "name", converter, true);
}

----

[IMPORTANT]
.Text Based Widgets
====
Binding on key events is only valid for text-based Widgets, i.e. those that extend ValueBoxBase. Errai DataBinding will throw an exception if the onKeyUp parameter is set on any non-ValueBoxBased Widgets.
====

[[sid-51282340_DataBinding-Replacingamodelobject]]

==== Replacing a model object

The injected model objects in the examples above are always proxies to the actual model since method invocations on these objects need to trigger additional logic for updating the UI. Special care needs to be taken in case a model object should be replaced.

When working with an [code]+@AutoBound DataBinder+, simply calling [code]+setModel()+ on the [code]+DataBinder+ will be enough to replace the underlying model instance. However, when working with [code]+@Model+ the instance cannot be replaced directly. Errai provides a special method level annotation [code]+@ModelSetter+ that will allow replacing the model instance. Here's an example:

[source, java]
----
@Dependent
public class CustomerView {
  @Inject @Model
  private Customer customer;

  @Inject @Bound
  private HTMLInputElement name;

  @Bound
  private HTMLLabelElement id = (HTMLLabelElement) document.createElement("label");

  @ModelSetter
  public void setModel(Customer customer) {
    this.customer = customer;
  }
}
----

The [code]+@ModelSetter+ method is required to have a single parameter. The parameter type needs to correspond to the type of the managed model.

[[sid-51282340_DataBinding-Beanvalidation]]

=== Bean validation

Java bean validation (JSR 303) provides a declarative programming model for validating entities. More details and examples can be found link:$$http://docs.jboss.org/hibernate/validator/4.3/reference/en-US/html_single/$$[here]. Errai provides a bean validation module that makes [code]+Validator+ instances injectable and work well with Errai's data binding module. The following line needs to be added to the GWT module descriptor to inherit Errai's bean validation module:

.App.gwt.xml
====


[source, xml]
----
<inherits name="org.jboss.errai.validation.Validation" />

<inherits name="org.hibernate.validator.HibernateValidator" />
----

====

To use Errai's bean validation module, you must add the module, the javax.validation API and an implementation such as hibernate validator to your classpath. If you are using Maven for your build, add these dependencies:


[source, xml]
----
    <dependency>
      <groupId>org.jboss.errai</groupId>
      <artifactId>errai-validation</artifactId>
      <version>${errai.version}</version>
    </dependency>

    <dependency>
      <groupId>javax.validation</groupId>
      <artifactId>validation-api</artifactId>
      <scope>provided</scope>
    </dependency>

    <dependency>
      <groupId>javax.validation</groupId>
      <artifactId>validation-api</artifactId>
      <classifier>sources</classifier>
      <scope>provided</scope>
    </dependency>

    <dependency>
      <groupId>org.hibernate</groupId>
      <artifactId>hibernate-validator</artifactId>
      <version>4.2.0.Final</version>
      <scope>provided</scope>
    </dependency>

    <dependency>
      <groupId>org.hibernate</groupId>
      <artifactId>hibernate-validator</artifactId>
      <version>4.2.0.Final</version>
      <scope>provided</scope>
      <classifier>sources</classifier>
    </dependency>
----

Now it is as simple as injecting a [code]+Validator+ instance into an <<sid-5931402,Errai IOC>> managed bean and calling the [code]+validate+ method.


[source, java]
----
@Inject
private Validator validator;
----


[source, java]
----
Set<ConstraintViolation<Customer>> violations  = validator.validate(customer);
// display violations
----

[[sid-51282340_DataBinding-ExcludingClassesfromValidation]]

==== Excluding Classes from Validation

By default, Errai scans the entire classpath for classes with constraints. But sometimes it is necessary or desirable to exclude some shared classes from being validated on the client side. This can be done by adding a list of classes and package masks to the ErraiApp.properties file like so:


[source, ini]
----
# The following blacklists the class some.fully.qualified.ClassName and all classes
# in some.package.mask (and subpackages thereof).
errai.validation.blacklist = some.fully.qualified.ClassName \
                             some.package.mask.*
----

[[sid-51806600]]

== Errai UI

One of the primary complaints of GWT to date has been that it is difficult to use "pure HTML" when building and skinning components. Inevitably one must turn to Java-based configuration in order to finish the job. In contrast, Errai strives to remove the need for Java styling. HTML template files are placed in the project source tree and referenced from custom Errai UI components in Java. Since Errai UI depends on Errai IOC and Errai CDI, dependency injection is supported in all custom components. Errai UI provides rapid prototyping and HTML5 templating for GWT.

[[sid-51806600_ErraiUI-Getstarted]]

=== Get started

The Errai UI module is directly integrated with <<sid-51282340, Data Binding>> and Errai JPA but can also be used as a standalone project in any GWT client application by simply inheriting the Errai UI GWT module, and ensuring that you have properly using <<sid-19398999,Errai CDI's @Inject>> to instantiate your components:

[[sid-51806600_ErraiUI-WorkingDemo]]

[NOTE]
.Manual Setup
====
Checkout the <<Manual-Setup-Section,Manual Setup Section>> for instructions on how to manually add Errai UI to your project. If you work better by playing with a finished product, you can see a simple client-server project link:$$https://github.com/errai/summit-demo-2013$$[implemented using Errai UI here].
====

[WARNING]
.Widget-based Components
====
Since Errai 4.0, Errai UI components are no longer required to extend [code]+Composite+. In fact, extending [code]+Composite+ is deprecated.
Though components can still be built with and as widgets, we encourage users to build components using purely native HTML elements.
====

=== Use Errai UI Components

==== Parts of an Errai UI component
An Errai UI component consists of a Java class (the _templated bean_), an HTML file (the _template_), and an optional CSS file (the _template stylesheet_).
The template and template stylesheet describe the look of your component. The templated bean uses the `@org.jboss.errai.ui.shared.api.annotations.DataField` annotation
to declare mappings between fields in the templated bean and elements in the template.

=== Creating a component

As previously mentioned, Errai UI components are built from a Java class (the _templated bean_), an HTML file (the _template_),
and an optional CSS file (the _template stylesheet_). A Java class is a templated bean if the class is annotated with +@Templated+.

==== Basic templated bean

Here is a basic templated bean with no Java fields mapped to UI elements.

* LoginForm.java

+

[source, java]
----
@Templated
public class LoginForm implements IsElement {
}
----

Annotating the type with +@Templated+ and no argument declares that this bean should have a template file +LoginForm.html+
and optionally a stylesheet +LoginForm.css+ in the same package as +LoginForm.java+.

[NOTE]
.Optionally implement IsElement for easy access to the component root
====
Implementing `org.jboss.errai.ui.client.local.api.elemental2.IsElement` is optional, but we will use it in all of our examples. The interface contains a single default method, `getElement`, that returns the root element of the template, allowing us to programmatically attach a component to the DOM. Later on we will discuss alternative methods of accessing a component's root element.
====

==== Custom template names

When no argument is provided to +@Templated+, Errai UI looks in the current package for a template file having
the simple class name of the templated bean, suffixed with +.html+.
But +@Templated+ accepts an argument to define an alternatively named or located template, as in the proceeding example.


[source, java]
----
@Templated("my-template.html")
public class LoginForm implements IsElement {
   /* Looks for my-template.html in LoginForm's package */
}
----

Fully qualified template paths are also supported, but must begin with a leading '/':


[source, java]
----
@Templated("/org/example/my-template.html")
public class LoginForm implements IsElement {
   /* Looks for my-template.html in package org.example */
}
----

==== Template providers

The previous examples specify template files at compile time, but it is possible to use templates provided at runtime using a `TemplateProvider`. These providers run asynchronously so that it is possible to fetch templates via HTTP requests. In fact Errai UI contains an implementation, `ServerTemplateProvider`, that fetches templates using the `@Templated` value as a url.

[source, java]
----
@Templated(value="home.html", provider=ServerTemplateProvider.class)
public class LoginForm implements IsElement {
  /* Makes an HTTP request for the relative path "home.html" */
}
----

Custom implementations can also be used.

[source, java]
----
@Templated(provider=MyTemplateProvider.class)
public class LoginForm implements IsElement {
  /* Makes an HTTP request for the relative path "home.html" */
}

@Dependent
public class MyTemplateProvider implements TemplateProvider {

  @Override
  public void provideTemplate(String location, TemplateRenderingCallback renderingCallback) {
    String template;

    /*
     * Generate the template String.
     * Note: The location parameter is the value from the @Templated annotation.
     */
    
    renderingCallback.renderTemplate(template);
  }
}
----

[[sid-51806600_ErraiUI-CreateanHTMLtemplate]]

=== Create an HTML template

Templates in Errai UI may be designed either as an HTML snippet or as a full HTML document. You can even take an existing HTML page and use it as a template. With either approach, the [code]+id+, [code]+class+, and [code]+data-field+ attributes in the template identify elements by name. These elements and their children are used in the component to add behavior, and use additional components to add functionality to the template. There is no limit to how many templated beans may share a given HTML template.

==== Using an HTML fragment as a template
Here is a simple HTML fragment for a login form to accompany our [code]+@Templated LoginForm+ bean.

[source, xml]
----
<form>
  <legend>Log in to your account</legend>

  <label for="username">Username</label>
  <input id="username" type="text" placeholder="Username">

  <label for="password">Password</label>
  <input id="password" type="password" placeholder="Password">

  <button>Log in</button>
  <button>Cancel</button>
</form>
----

This fragment can be used with our previous +@Templated LoginForm+ declaration as is.

==== Select a fragment from a larger HTML template
You can also use a full HTML document that is more easily previewed during design. When doing this you must specify the location of the component's root DOM Element within the template file using a [code]+"data-field"+, [code]+id+, or [code]+class+ attribute matching the value of the @Templated annotation. There is no limit to how many templated beans may share a single HTML template.

* LoginForm.java

+

[source, java]
----
@Templated("my-template.html#login-form")
public class LoginForm implements IsElement {
   /* Specifies that <... id="login-form"> be used as the root Element of this component */
}
----

* my-template.html

+

[source, xml]
----
<!DOCTYPE html>
<html lang="en">
<head>
    <title>A full HTML document</title>
</head>
<body>
    <div>
        <form id="login-form"> # <1>
          <legend>Log in to your account</legend>

          <label for="username">Username</label>
          <input id="username" type="text" placeholder="Username">

          <label for="username">Password</label>
          <input id="password" type="password" placeholder="Password">

          <button>Log in</button>
          <button>Cancel</button>
        </form>
    </div>

    <hr>
    <footer id="theme-footer">
        <p>(c) Company 2012</p>
    </footer>
</body>
</html>
----

+

<1> The HTML [code]+id+ value of this form Element matches the +#login-from+ part from the +@Templated("my-template.html#login-from")+ declaration.
That means that this element will be used as the root of the component defined by +LoginForm.java+. Note that we could also have used
+class="login-form"+ or +data-field="login-form"+ to the same effect.

Multiple components may use the same template, specifying any elements as a their root elements.
In particular, note that two or more components may declare the same DOM element of this template file as their root elements;
there is no conflict because are each components instantiated with a unique copy of the template DOM rooted at the specified element at runtime
(or from the root element if a fragment is not specified.)

For example, the component below also uses the same template file by referencing the template name, and specifying a fragment.


[source, java]
----
@Templated("my-template.html#theme-footer")
public class Footer implements IsElement {
   /* Specifies that <... id="theme-footer"> be used as the root Element of this Widget */
}
----

==== Using a single component instance
As with most other features of Errai, dependency injection with CDI is the programming model of choice, so when interacting with components defined using Errai UI,
you should always [code]+@Inject+ references to your components.

In this example we use a single Errai UI component by injecting it and adding it to the DOM using Errai's DOM wrappers.

[source, java]
----
@EntryPoint
public class Application {
   @Inject
   private Document document; <1>

   @Inject
   private TemplatedBean component;

   @PostConstruct
   public void init() {
     document.getBody().appendChild(component.getElement()); <2>
   }
}
----

<1> `org.jboss.errai.common.client.dom.Document` is a thin wrapper around the DOM document provided by Errai. More on this later.
<2> This line assumes that `TemplatedBean` implements `org.jboss.errai.ui.client.local.api.elemental2.IsElement`. The default implementation of `IsElement.getElement` returns the root element of the component as an Errai DOM wrapper, which is compatible with the injected `Document`.

==== Using multiple instances (for iteration)

In some cases you may need to display multiple instances of a component.
Here we create and add many components to the DOM using an injected [code]+org.jboss.errai.ioc.client.api.ManagedInstance<T>+.

[source, java]
----
import static elemental2.dom.DomGlobal.document;

@EntryPoint
public class Application {
   private String[] colors = new String[]{"Blue", "Yellow", "Red"};

   @Inject
   private ManagedInstance<ColorComponent> provider;

   @Inject
   private Document document;

   @PostConstruct
   public void init() {
      for(String color: colors) {
        ColorComponent component = provider.get(); <1>
        component.setColor(c);
        document.appendChild(component.getElement()); <1>
      }
   }
}
----

<1> Again, we assume `ColorComponent` implements `org.jboss.errai.ui.client.local.api.elemental2.IsElement`, where `getElement` is defined.

=== Adding behaviour to your components

Now that we know how to create a +@Templated+ bean and an HTML template, we can start wiring in functionality and behavior;
this is done by annotating fields and methods to replace specific sub-elements of the template DOM.
We can even replace portions of the template with other Errai UI components!

==== Annotate Elements in the template with @DataField

In order to substitute elements into the template DOM you must annotate fields in your templated bean with +@DataField+
and mark the HTML template element with a correspondingly named [code]+data-field+, [code]+id+, or [code]+class+ attribute.
All replacements happen while the component is being constructed; thus, fields annotated with +@DataField+ must either be [code]++@Inject++ed
or manually initialized when the templated bean is instantiated.

[NOTE]
.Uses Elemental 2 API
====
The +@DataField+ types used in this example are provided by Elemental 2 in the +elemental2.dom+ package. Using Errai DOM wrappers found in the +org.jboss.errai.common.client.dom+ package of errai-common or widgets in a +@DataField+ is still possible, but this approach is not recommended.
====


[source, java]
----
/*
* Here the template file is implicitly LoginForm.html.
* The root element has id, class, or data-field "form".
*/
@Dependent
@Templated("#form")
public class LoginForm implements IsElement {
   // This is the root element of the template, for adding this component to the DOM.
   @Inject
   @DataField
   private HTMLFormElement form;

   // If not otherwise specified, the name to match in the HTML template defaults
   // to the name of the field; in this case, the name would be "username"
   @Inject
   @DataField
   private HTMLInputElement username;

   // The name to reference in the template can also be specified manually
   @Inject
   @DataField("pass")
   private HTMLInputElement password;

   // We can also choose to instantiate our own data fields. Injection is not required.
   @DataField
   private HTMLButtonElement submit = (HTMLButtonElement) document.createElement("button");

   @PostConstruct
   public void init() {
       password.type = "password";
   }
}
----

[NOTE]
====
Field, method, and constructor injection are all supported by @DataField.
====

==== Allowed DataField types

The previous [code]+LoginForm+ example uses HTML wrapper elements from Elemental 2, but there are other types that can be used as [code]+@DataFields+.
Here is a full list:

. Any native [code]+@JsType+ that is a wrapper for a DOM element (including those provided in errai-common). (_This approach is no longer recommended!_).

. Any Errai UI component.

. Any [code]+com.google.gwt.dom.client.Element+ type. (_This approach is no longer recommended!_).

. Any type implementing [code]+org.jboss.errai.common.client.api.IsElement+. (_This approach is no longer recommended!_).

. Any type implementing [code]+org.jboss.errai.common.client.api.elemental2.IsElement+.

. Any [code]+com.google.gwt.user.client.ui.Widget+ type. (_This approach is no longer recommended!_).

==== Accessing the root element of a component

When programmatically adding components to the DOM, it is necessary to access their HTMLElement roots. Errai UI provides two ways of doing this.

===== Inject the root element as a DataField

Errai UI supports injecting any element in a template html file as a DataField in the templated bean, including the root element. Below is a simple example.

====== MyBean.html
[source, html]
----
<div class="root">
  <h1>Hello World!</h1>
</div>
----

====== MyBean.java
[source, java]
----
@Templated
public class MyBean {
  @Inject @DataField HTMLDivElement root;
}
----

This method has the advantage that any valid @DataField type can be used (for example, you can expose your root element as a `com.google.gwt.dom.client.Element` or your own handwritten `@JsType` element wrapper).

===== Implement org.jboss.errai.ui.client.local.api.elemental2.IsElement

The interface [code]+org.jboss.errai.common.client.api.elemental2.IsElement+ is analogous to `IsWidget`. It declares a single method `getElement` for accessing a type that is a UI component with a root element.

The interface [code]+org.jboss.errai.ui.client.local.api.elemental2.IsElement+ provides a default implementation of [code]+org.jboss.errai.common.client.api.elemental2.IsElement+ that works for any templated bean. For example:

[NOTE]
====
Although using [code]+org.jboss.errai.ui.client.local.api.elemental2.IsElement+ is the recomended approach, [code]+org.jboss.errai.ui.client.local.api.IsElement+ is still supported.
====

====== MyBean.html
[source, html]
----
<div class="root">
  <h1>Hello World!</h1>
</div>
----

====== MyBean.java
[source, java]
----
import org.jboss.errai.ui.client.local.api.elemental2.IsElement;

@Templated
public class MyBean implements IsElement {
}
----

====== Usage
[source, java]
----
@EntryPoint
public class Setup {
  @Inject MyBean component;

  @PostConstruct
  public void attachBean() {
    // The default implementation automatically returns
    // the correct root element.
    HTMLElement rootElement = component.getElement();
    document.body.appendChild(rootElement);
  }
}
----

[NOTE]
====
The `getElement` call in the usage above returns the element as the [code]+org.jboss.errai.common.client.dom.HTMLElement+ type from errai-common.
====

==== Using JsType element wrappers

[WARNING]
.Jsinterop ahead
====
This section assumes basic familiarity with JS interop in GWT 2.8+.
====

Since 4.0, Errai UI supports working with JS interop wrappers of DOM elements.
Additionally, Errai provides a concise way of allowing your custom JS interop wrappers to be injected into components.

===== LoginForm with a jsinterop element

Let's redo our previous login form, but with a new, custom JS interop form element as the root. First we need our element wrapper.

[source, java]
----
@JsType(isNative = true)
@Element("form")
public interface NativeForm {
  // Element methods and properties go here
}
----

Here we have a defined a JS interop interface that will be backed by a FormElement javascript object at runtime.
The [code]+org.jboss.errai.ui.shared.api.annotation.Element+ annotation declares this type as injectable with Errai IOC;
at the container will call `document.createElement("form")` in javascript to satisfy injection sites for this type.

Once you've defined your element wrapper, using it as a [code]+@DataField+ works exactly as in previous examples.

[source, java]
----
/*
* Like the component from the previous example, but with a custom element wrapper as its root.
*/
@Templated("#form")
public class LoginForm {

   // Now the root element is our custom JsType
   @Inject
   @DataField
   private NativeForm form;

   @Inject
   @DataField
   private HTMLInputElement username;

   @Inject
   @DataField("pass")
   private HTMLInputElement password;

   @DataField
   private HTMLButtonElement submit = (HTMLButtonElement) document.createElement("button");

   @PostConstruct
   public void init() {
      password.type = "password";
   }
}
----

==== Injecting JsTypes and Elements that have multiple tag names

In our previous examples injecting [code]+Elements+ or native [code]+JsTypes+, we did so with types that had a single possible tag name.
But consider the heading tags (h1, h2, ..., h6). In Elemental 2, these are all represented by [code]+HTMLHeadingElement+. In gwt-user and errai-common these are all represented by [code]+HeadingElement+.
We might also wish to make our own [code]+@JsType+ wrapper to represent these tags:

[source, java]
----
@JsType(isNative = true)
@Element({ "h1", "h2", "h3", "h4", "h5", "h6" })
public interface NativeHeading {
  // Heading element methods and properties go here
}
----

With the above definition, injecting a +NativeHeading+ is ambiguous. Fortunately for both [code]+Elements+ and native [code]+JsTypes+ we can use the
[code]+javax.inject.Named+ annotation to remove this ambgiuity by specifying a tag name at a injection site.

[source, java]
----
@Templated
public class Component {
  // Injects a Elemental 2 HTMLHeadingElement with tag name "h1"
  @Inject
  @Named("h1")
  @DataField
  private HTMLHeadingElement h1;

  // Injects a gwt-user HeadingElement with tag name "h2"
  @Inject
  @Named("h2")
  @DataField
  private HeadingElement h2;

  // Injects a NativeHeading wrapper for an "h6" element
  @Inject
  @Named("h6")
  @DataField
  private NativeHeading h6;
}
----

[[sid-51806600_ErraiUI-AddcorrespondingattributestotheHTMLtemplate]]

==== Add corresponding attributes to the HTML template

Each +@DataField+ reference in the Java class must match an element in the HTML template. The matching of Java references to HTML elements is performed as follows:

. A _name_ for the Java reference is determined. If the [code]+@DataField+ annotation has a value argument, that is used as the reference name. For fields, the default reference name is the field name. Method and constructor parameters have no default name, so they must always specify a value.


. If there is an element in the HTML template with attribute [code]+data-field=name+, the Java reference will point to this element. If there is more than one such element, the Java reference points to the first.


. Otherwise, if there is an element in the HTML template with attribute [code]+id=name+, the Java reference will point to this element. If there is more than one such element, the Java reference points to the first.


. Otherwise, if there is an element in the HTML template with a CSS style class [code]+name+, the Java reference will point to this element. If there is more than one such element, the Java reference points to the first. For elements with more than one CSS style, each style name is considered individually. For example:
+
[source, java]
----
   <div class="eat drink be-merry">
----
+
matches Java references named [code]+eat+, [code]+drink+, or [code]+be-merry+.


. If no matching element is found by this point, it is an error.


If more than one Java reference matches the same HTML element in the template, it is an error. For example, given a template containing the element [code]+<div class="eat drink be-merry">+, the following Java code is in error:


[source, java]
----
@Templated
public class ErroneousTemplate {
   @Inject @DataField
   private HTMLDivElement eat;

   @Inject @DataField
   private HTMLDivElement drink;
}
----

because both fields [code]+eat+ and [code]+drink+ refer to the same HTML [code]+div+ element.

So now we must ensure there are [code]+data-field+, [code]+id+, or [code]+class+ attributes in the right places in our template HTML file. This, combined with the @DataField annotation in our component allows Errai UI to determine where and what should be composited when creating component instances.


[source, xml]
----
<form id="form">
  <legend>Log in to your account</legend>

  <label for="username">Username</label>
  <input id="username" type="text" placeholder="Username">

  <label for="password">Password</label>
  <input data-field="pass" id="password" type="password" placeholder="Password">

  <button id="submit">Log in</button>
  <button>Cancel</button>
</form>
----

Now, when we run our application, we will be able to interact with these fields in our component.

[[sid-51806600_ErraiUI-HowHTMLtemplatesaremergedwithComponents]]

=== How HTML templates are merged with Components

Three things are merged or modified when Errai UI creates a new component instance:

. By default, element attributes are merged from the template to the templated bean +@DataFields+ (this behaviour can be configured with attributes of the `@DataField` annotation -- see the javadoc for details).

. Template element inner text and inner HTML are preserved when the given [code]+@DataField+ is a [code]+Widget+ that implements [code]+HasText+ or [code]+HasHTML+
or if it is a DOM element that has no children.

. If (2) is not applicable then child DOM Elements are merged from the templated bean +@DataField+ to the template.


==== Example

===== Templated bean:

[source, java]
----
@Templated
public class StyledComponent implements IsElement {

    @Inject
    @DataField("field-1")
    private HTMLDivElement div;

    public StyledComponent() {
      div.style.setProperty("position", "fixed");
      div.style.setProperty("top", "0");
      div.style.setProperty("left", "0");
      this.getElement().id = "outer-id";
    }
}
----

===== Template:

[source, xml]
----
<form>
  <span data-field="field-1" style="display:inline;"> This element will become a div </span>
</form>

This text will be ignored.
----

===== Output / result:


[source, xml]
----
<form id="outer-id">
   <div data-field="field-1" style="display:inline;"> This element will become a div </div>
</form>
----

But why does the output look the way it does? Some things happened that may be unsettling at first,
but once you understand why these things occur you will find these mechanisms extremely powerful.

==== Element attributes (template wins)

When styling your templates, you should keep in mind that, by default, all attributes defined in the template file will take precedence over any preset attributes in your [code]+@DataFields+.
This "attribute merge" occurs only when the components are instantiated; subsequent changes to any attributes after construction will function normally.
In the example we defined a component that applied several styles to a child Widget in its constructor, but we can see from the output that the styles from the template have overridden them.

If styles must be applied in Java instead of in the template, there are two options:

* Programmatically update the component in a `@PostConstruct` method.

* Change the attribute merging strategy with attributes of the `@DataField` annotation (see javadoc for details).

==== DOM Elements (templated bean field wins)

Element composition, however, functions inversely from the attribute merging default behaviour, and the [code]+<span>+ defined in our template is actually replaced by the [code]+<div>+
because of the `HTMLDivElement` in our component field. This does not, however, change the behavior of the attribute merge - the new [code]+<div>+ was still be rendered inline,
because we have specified this style in our template, and the template always wins in competition with attributes set programatically before composition occurs.
It is this rule that allows nesting of Errai UI components, since the markup of an Errai UI component +A+ used as a +@DataField+ in component +B+ will override
the markup in the +B+ template.
In short, whatever is inside the [code]+@DataField+ in your class will replace the children of the corresponding element in your template.

==== Inner text and inner HTML (preserved when component implements HasText or HasHTML)

Additionally, because [code]+HTMLDivElement+ is a thin Element wrapper, the contents of the <span> "field-1" Element in the template were preserved;
however, this would not have been the case if the [code]+@DataField+ specified for the element was not an element wrapper (for example if it was another Errai UI component).
In short, if you wish to preserve text or HTML contents of an element in your template, you can do one of two things: do not composite that Element with a [code]+@DataField+ reference,
or ensure that the UI component being composited implements is a a DOM element with no children.

=== Event handlers

Dealing with User and DOM Events is a reality in rich web development, and Errai UI provides several approaches for dealing with all types of browser events using its "quick handler" functionality. It is possible to handle:

. JS interop Elemental 2 or wrapped DOM events on Widgets and Elements

. GWT events on Widgets (Deprecated)

. GWT events on DOM Elements (Deprecated)

. Native DOM events on Elements (Deprecated)



[IMPORTANT]
====
It is not possible to handle Native DOM events on Widgets because GWT overrides native event handlers when Widgets are added to the DOM. You must programatically configure such handlers after the Widget has been added to the DOM.
====

[[sid-51806600_ErraiUI-Concepts]]

==== Concepts

Each of the scenarios mentioned above use the same basic programming model for event handling: Errai UI wires methods annotated with [code]+@EventHandler("my-data-field")+ (_event handler methods_) to handle events on the corresponding [code]+@DataField("my-data-field")+ in the same component. Event handler methods annotated with a bare [code]+@EventHandler+ annotation (no annotation parameter) are wired to receive events on the @Templated component itself.

A JS interop wrapped event is a type annotated with `@JsType(isNative=true)` and `@BrowserEvent` and provides an interface to the API of a browser DOM event.

[[sid-51806600_ErraiUI-GWTeventsonWidgets]]

==== JS Interop wrapped events on Elements and Widgets

This approach can be used to handle events on any kind of `@DataField` or on a `data-field` element in the HTML template.  Since many browser event types share interfaces a quick handler with a JS interop event parameter must sometimes specify the browser event type (i.e. "click", "blur", "focus", etc.).

Here is an example of a quick handler for "click" events on an element `@DataField` where the `Event` parameter is a JS interop wrapped event type `org.jboss.errai.common.client.dom.Event`. The `Event` interfaces is annotated with `@BrowserEvent`, but does not specify a value of usable browser event types, so the quick handler must specify the event type is listens to with the `@ForEvent` annotation.

[source, java]
----
@Templated
public class ElementHandlerComponent {

   @Inject
   @DataField("b1")
   private HTMLButtonElement button;

   @EventHandler("b1")
   public void doSomething(@ForEvent("click") Event e) {
     // do something
   }
}
----

For `@BrowserEvent` wrappers that specify event types, `@ForEvent` may be omitted. In this case the quick handler is registered for all supported event types. In the example below, `FocusEvent` is annotated with `@BrowserEvent({"blur", "focus", "focusin", "focusout"})`, so the quick handler is registered for all four event: blur, focus, focusin, and focusout.


[source, java]
----
@Templated
public class ElementHandlerComponent {

   @Inject
   @DataField
   private HTMLAnchorElement link;

   @EventHandler("link")
   public void doSomething(FocusEvent e) {
     // do something
   }
}
----

This approach can also be used with GWT Widget `@DataFields` and template `data-fields` that do not have a `@DataField`.

[source, java]
----
@Templated
public class WidgetAndElementHandlerComponent {

   @Inject
   @DataField
   private HTMLInputElement input;

   // Handles focus-related events on the
   // underlying HTML element of the HTMLInputElement field.
   @EventHandler("input")
   public void doSomething(FocusEvent e) {
     // do something
   }

   // Handles dblclick events for the element in the
   // template with id/class/data-field="button".
   @EventHandler("button")
   public void onClick(@ForEvent("dblclick") MouseEvent e) {
     // do something
   }
}
----

==== GWT events on Widgets

This approach handles GWT Event classes for Widgets that explicitly handle the given event type. If a Widget does not handle the Event type given in the [code]+@EventHandler+ method's signature, the application will fail to compile and appropriate errors will be displayed.

[source, java]
----
@Templated
public class WidgetHandlerComponent extends Composite {

   @Inject
   @DataField("b1")
   private Button button;

   @EventHandler("b1")
   public void doSomethingC1(ClickEvent e) {
     // do something
   }
}
----

[[sid-51806600_ErraiUI-GWTeventsonDOMElements]]

==== GWT events on DOM Elements

Errai UI also makes it possible to handle GWT events on native Elements which are specified as a [code]+@DataField+ in the component class. This is useful when a full GWT Widget is not available for a given Element, or for GWT events that might not normally be available on a given Element type. This could occur, for instance, when clicking on a [code]+<div>+, which would normally not have the ability to receive the GWT [code]+ClickEvent+, and would otherwise require creating a custom DIV Widget to handle such an event.

[source, java]
----
@Templated
public class ElementHandlerComponent extends Composite {

   @DataField("div-1")
   private DivElement button = DOM.createDiv();

   @EventHandler("div-1")
   public void doSomethingC1(ClickEvent e) {
     // do something
   }
}
----

[NOTE]
.Events with native JsTypes
====
As with previous features, the [code]+DivElement+ above could be replaced with a native [code]+JsType+ (for example, +Div+ from errai-common).
====

[[sid-51806600_ErraiUI-NativeDOMeventsonElements]]

==== Native DOM events on Elements

The last approach is handles the case where native DOM events must be handled, but no such GWT event handler exists for the given event type. Alternatively, it can also be used for situations where Elements in the template should receive events, but no handle to the Element the component class is necessary (aside from the event handling itself.) Native DOM events do not require a corresponding [code]+@DataField+ be configured in the class; only the HTML [code]+data-field+, [code]+id+, or [code]+class+ template attribute is required.


[source, xml]
----
<div>
   <a id="link" href="/page">this is a hyperlink</a>
   <div data-field="div"> Some content </div>
</div>
----

The [code]+@SinkNative+ annotation specifies (as a bit mask) which native events the method should handle; this sink behaves the same in Errai UI as it would with [code]+DOM.sinkEvents(Element e, int bits)+. Note that a [code]+@DataField+ reference in the component class is optional.

[IMPORTANT]
====
Only one @EventHandler may be specified for a given template element when @SinkNative is used to handle native DOM events.
====

[source, java]
----
@Templated
public class QuickHandlerComponent extends Composite {

  @DataField
  private AnchorElement link = DOM.createAnchor().cast();

  @EventHandler("link")
  @SinkNative(Event.ONCLICK | Event.ONMOUSEOVER)
  public void doSomething(Event e) {
    // do something
  }

  @EventHandler("div")
  @SinkNative(Event.ONMOUSEOVER)
  public void doSomethingElse(Event e) {
    // do something else
  }
}
----

=== HTML Form Support

Using asynchronous Javascript calls often make realizing the benefits of modern browsers difficult when it comes to form submission. But there is now a base class in Errai UI for creating `@Templated` form widgets that are perfect for tasks such as creating a login form.

==== A Login Form that Triggers Browsers' "Remember Password" Feature

Here is a sample `@Templated` login form class. This form has:

* a `username` text field
* a `password` field
* a button that with a click handler that attempts to login asynchronously

[source, java]
----
@Dependent
@Templated
public class LoginForm extends AbstractForm { <1>
  
  @Inject
  private Caller<AuthenticationService> authenticationServiceCaller;

  @Inject
  @DataField
  private TextBox username;
  
  @Inject
  @DataField
  private PasswordTextBox password;

  @DataField
  private final FormElement form = DOM.createForm(); <2>

  @Inject
  @DataField
  private Button login; <3>
  
  @Override
  protected FormElement getFormElement() {
    return form; <4>
  }

  @EventHandler("login")
  private void loginClicked(ClickEvent event) {
    authenticationServiceCaller.call(new RemoteCallback<User>() {

      @Override
      public void callback(User response) {
        // Now that we're logged in, submit the form
        submit(); <5>
      }
    }).login(username.getText(), password.getText());
  }

}
----

The key things that you should take from this example:

<1> The class extends `org.jboss.errai.ui.client.widget.AbstractForm`.
<2> The `form` field is a `@DataField` but it is not injected.
<3> The login button is a regular button widget, with a click handling method below.
<4> The `getFormElement` method inherited from `AbstractForm` must return the `FormElement` that will be submitted.
<5> After the user has successfully logged in asynchronously we call `submit()`. This causes form submission to happen in a way that will not cause the page to refresh, but will still properly notify the browser of a form submission.

When a user successfully logs in via this example, the web browser should prompt them to remember the username and password (assuming this is a feature of the browser being used).

==== Using the Correct Elements in the Template

The most likely way to go wrong is to accidentally use the wrong types of elements in your template. It is very important that you use a proper `from` element with `input` elements *with the exception of the submit button*. Here is an html template that could accompany the `LoginForm.java` example above:

[source, html]
----
<div>
  <form data-field="form">
    <input type="text" name="username" data-field="username">
    <input type="password" name="password" data-field="password">
    <button data-field="login">Sign In</button>
  </form>
</div>
----

To reiterate, notice that the `username` and `password` fields are legitimate `input` elements. This is because we want these values to be submitted when `AbstractForm.submit()` is called (so that the browser notices them). However, we do not want there to be any way to submit the form other than calling `AbstractForm.submit()`, so the `button` element is notably missing the `type="submit"` attribute pair.

[[sid-51806600_ErraiUI-DataBinding]]

=== Data Binding

A recurring implementation task in rich web development is writing event handler code for updating model objects to reflect input field changes in the user interface. The requirement to update user interface fields in response to changed model values is just as common. These tasks require a significant amount of boilerplate code which can be alleviated by Errai. Errai's <<sid-51282340,data binding module>> provides the ability to bind model objects to user interface fields, so they will automatically be kept in sync. While the module can be used on its own, it can cut even more boilerplate when used together with Errai UI.

In the following example, all [code]+@DataFields+ annotated with [code]+@Bound+ have their contents bound to properties of the data model (a [code]+User+ object). The model object is injected and annotated with [code]+@Model+, which indicates automatic binding should be carried out. Alternatively, the model object could be provided by an injected [code]+DataBinder+ instance annotated with [code]+@AutoBound+, see <<sid-51282340_DataBinding-DeclarativeBinding,Declarative Binding>> for details.


[source, java]
----
@Templated
public class LoginForm {

   @Inject
   @Model
   private User user;

   @Inject
   @Bound
   @DataField
   private InputElement name;

   @Inject
   @Bound
   @DataField
   private PasswordTextBox password;

   @DataField
   private Button submit = new Button();
}
----

Now the user object and the [code]+username+ and [code]+password+ fields in the UI are automatically kept in sync. No event handling code needs to be written to update the user object in response to input field changes and no code needs to be written to update the UI fields when the model object changes. So, with the above annotations in place, it will always be true that [code]+user.getUsername().equals(username.getText())+ and [code]+user.getPassword().equals(password.getText())+.

[[sid-51806600_ErraiUI-Default%2CSimple%2CandChainedPropertyBindings]]

==== Default, Simple, and Chained Property Bindings

By default, bindings are determined by matching field names to property names on the model object. In the example above, the field [code]+name+ was automatically bound to the JavaBeans property [code]+name+ of the model ([code]+user+ object). If the field name does not match the model property name, you can use the [code]+property+ attribute of the [code]+@Bound+ annotation to specify the name of the property. The property can be a simple name (for example, "name") or a property chain (for example, [code]+user.address.streetName+). When binding to a property chain, all properties but the last in the chain must refer to @Bindable values.

The following example illustrates all three scenarios:


[source, java]
----
@Bindable
public class Address {
  private String line1;
  private String line2;
  private String city;
  private String stateProv;
  private String country;

  // getters and setters
}

@Bindable
public class User {
  private String name;
  private String password;
  private Date dob;
  private Address address;
  private List<Role> roles;

  // getters and setters
}

@Templated
public class UserComponent {
  @Inject @AutoBound DataBinder<User> user;
  @Inject @Bound InputElement name;
  @Inject @Bound(property="dob") DatePicker dateOfBirth;
  @Inject @Bound(property="address.city") TextBox city;
}
----

In [code]+UserComponent+ above, the [code]+name+ input element is bound to [code]+user.name+ using the default name matching; the [code]+dateOfBirth+ date picker is bound to [code]+user.dob+ using a simple property name mapping; finally, the [code]+city+ text box is bound to [code]+user.address.city+ using a property chain. Note that the [code]+Address+ class is required to be [code]+@Bindable+ in this case.

[[sid-51806600_ErraiUI-BindingofLists]]

==== Binding of Lists

Often you will need to bind a list of model objects so that every object in the list is bound to a corresponding component. This task can be accomplished using Errai UI's [code]+ListWidget+ class. Here's an example of binding a list of users using the [code]+UserComponent+ class from the previous example. First, we need to enhance [code]+UserComponent+ to implement [code]+HasModel+.


[source, java]
----
@Templated
public class UserWidget implements HasModel<User> {
  @Inject @AutoBound DataBinder<User> userBinder;
  @Inject @Bound InputElement name;
  @Inject @Bound(property="dob") DatePicker dateOfBirth;
  @Inject @Bound(property="address.city") TextBox city;

  public User getModel() {
    userBinder.getModel();
  }

  public void setModel(User user) {
    userBinder.setModel(user);
  }
}
----

Now we can use [code]+UserComponent+ to display items in a list.

[source, java]
----
@Templated
public class MyComponent {

  @Inject @DataField ListWidget<User, UserComponent> userListWidget;

  @PostConstruct
  public void init() {
    List<User> users = .....
    userListWidget.setItems(users);
  }
}
----

Calling [code]+setItems+ on the [code]+userListWidget+ causes an instance of [code]+UserComponent+ to be displayed for each user in the list. The [code]+UserComponent+ is then bound to the corresponding user object. By default, the widgets are arranged in a vertical panel. However, [code]+ListWidget+ can also be subclassed to provide alternative behaviour. In the following example, we use a horizontal panel to display the widgets.


[source, java]
----
public class UserListWidget extends ListWidget<User, UserWidget> {

  public UserList() {
    super(new HorizontalPanel());
  }

  @PostConstruct
  public void init() {
    List<User> users = .....
    setItems(users);
  }

  @Override
  public Class<UserWidget> getItemWidgetType() {
    return UserWidget.class;
  }
}
----

[[sid-51806600_ErraiUI-Bindinglistswith@Bound]]

===== Binding lists with @Bound

An instance of [code]+ListWidget+ can also participate in automatic bindings using [code]+@Bound+. In this case, [code]+setItems+ never needs to be called manually. The bound list property and displayed items will automatically be kept in sync. In the example below a list of user roles is bound to a [code]+ListWidget+ that displays and manages a [code]+RoleWidget+ for each role in the list. Every change to the list returned by [code]+user.getRoles()+ will now trigger a corresponding update in the UI.


[source, java]
----
@Templated
public class UserDetailView {

   @Inject
   @Bound
   @DataField
   private InputElement name;

   @Inject
   @Bound
   @DataField
   private PasswordTextBox password;

   @Inject
   @Bound
   @DataField
   private ListWidget<Role, RoleWidget> roles;

   @DataField
   private Button submit = new Button();

   @Inject @Model
   private User user;
}
----

[[sid-51806600_ErraiUI-DataConverters]]

==== Data Converters

The [code]+@Bound+ annotation further allows to specify a converter to use for the binding (see <<sid-51282340_DataBinding-SpecifyingConverters,Specifying Converters>> for details). This is how a binding specific converter can be specified on a data field:

[source, java]
----
@Inject
@Bound(converter=MyDateConverter.class)
@DataField
private TextBox date;
----

Errai's [code]+DataBinder+ also allows to register [code]+PropertyChangeHandlers+ for the cases where keeping the model and UI in sync is not enough and additional logic needs to be executed (see <<sid-51282340_DataBinding-PropertyChangeHandlers,Property Change Handlers>> for details).

[[sid-51806600_ErraiUI-NestCompositecomponents]]

=== Nest components

Using components to build up a hierarchy of UI componenets functions exactly the same as when building hierarchies of GWT widgets or DOM elements. The only distinction might be that with Errai UI, [code]+@Inject+ is preferred to manual instantiation.


[source, java]
----
@Templated
public class ComponentOne {

   @Inject
   @DataField("other-comp")
   private ComponentTwo two;
}
----

[NOTE]
====
This example works whether [code]+ComponentTwo+ is a composite or non-composite component.
====

[[sid-51806600_ErraiUI-ExtendCompositecomponents]]

=== Extend components

Templating would not be complete without the ability to inherit from parent templates, and Errai UI also makes this possible using simple Java inheritance. The only additional requirement is that components extending from a parent component must also be annotated with @Templated, and the path to the template file must also be specified in the child component's annotation. Child components may specify [code]+@DataField+ references that were omitted in the parent class, and they may also override [code]+@DataField+ references (by using the same [code]+data-field+ name) that were already specified in the parent component.

==== Template

Extension templating is particularly useful for creating reusable page layouts with some shared content (navigation menus, side-bars, footers, etc.) where certain sections will be filled with unique content for each page that extends from the base template; this is commonly seen when combined with the MVP design pattern traditionally used in GWT applications.


[source, html]
----
<div class="container">
   <div id="header"> Default header </div>
   <div id="content"> Default content </div>
   <div id="footer"> Default footer </div>
</div>
----

[[sid-51806600_ErraiUI-Parentcomponent]]

==== Parent component

This component provides the common features of our page layout, including header and footer, but does not specify any content. The missing @DataField "content" will be provided by the individual page components extending from this parent component.


[source, java]
----
@Templated
public class PageLayout {

   @Inject
   @DataField
   private HeaderComponent header;

   @Inject
   @DataField
   private FooterComponent footer;

   @PostConstruct
   public final void init() {
      // do some setup
   }
}
----

[[sid-51806600_ErraiUI-Childcomponent]]

==== Child component

We are free to fill in the missing "content" @DataField with a component of our choosing. Note that it is not required to fill in all omitted @DataField references.


[source, java]
----
@Templated("PageLayout.html")
public class LoginLayout extends PageLayout {

   @Inject
   @DataField
   private LoginForm content;

}
----

We could also have chosen to override one or more [code]+@DataField+ references defined in the parent component, simply by specifying a [code]+@DataField+ with the same name in the child component, as is done with the "footer" data field below.


[source, java]
----
@Templated("PageLayout.html")
public class LoginLayout extends PageLayout {

   @Inject
   @DataField
   private LoginForm content;

   /* Override footer defined in PageLayout */
   @Inject
   @DataField
   private CustomFooter footer;

}
----

Be aware that templates shouldn't all be [code]+@Singleton+. Singleton templates will be shared, so you can't attach the same template component twice. Duplicated template components should be dependent-scoped, so several instances will be created when they are injected.

[[sid-51806600_ErraiUI-Stylesheetbinding]]

=== Stylesheet binding

When developing moderately-complex web applications with Errai, you may find yourself needing to do quite a bit of programmatic style changes. One common case is showing or enabling controls only if a user has the necessary permissions to use them. One part of the problem is securing those features from being used, and the other part which is an important usability consideration is communicating that state to the user.

.RestrictedAccess in Errai Security
[TIP]
====
Errai Security contains a `RestrictedAccess` annotation that uses style sheet binding to implement a feature similar in nature to this example.
====

Let's start with the example case I just described. We have a control that we only want to be visible if the user is an admin. So the first thing we do is create a style binding annotation.


[source, java]
----
@StyleBinding
@Retention(RetentionPolicy.RUNTIME)
public @interface Admin {
}
----

This defines [code]+Admin+ as a stylebinding now we can use it like this:


[source, java]
----
@EntryPoint
@Templated
public class HelloWorldForm {
  @Inject @Admin @DataField ButtonElement deleteButton;
  @Inject SessionManager sessionManager;


  @EventHandler("deleteButton")
  private void handleSendClick(ClickEvent event) {
    // do some deleting!
  }

  @Admin
  private void applyAdminStyling(Style style) {
    if (!sessionManager.isAdmin()) {
      style.setVisibility(Style.Visibility.HIDDEN);
    }
  }
}
----

Now before the form is shown to the user the [code]+applyAdminStyling+ method will be executed where the [code]+sessionManager+ is queried to see if the user is an admin if not the delete button that is also annotated with [code]+@Admin+ will be hidden from the view.

The above example took at `Style` object as a parameter, but it is also possible to use an `Element`. So the `applyAdminStyling` method above could have also been written like this:

[source, java]
----
  @Admin
  private void applyAdminStyling(Element element) {
    if (!sessionManager.isAdmin()) {
      element.addClassName("disabled");
    }
  }
----

The CSS class "disabled" could apply the same style as before ("visibility: hidden") or it could have more complex behaviour that is dependent on the element type.

==== Usage with Data Binding

In addition when using this in conjunction with Errai Databinding. Any Errai UI component which uses @AutoBound, will get live updating of the style rules for free, anytime the model changes. Allowing dynamic styling based on user input and other state changes.

[[sid-51806600_ErraiUI-Internationalization%28i18n%29]]

=== Internationalization (i18n)

User interfaces often need to be available in different languages. Errai's i18n support makes it easier for you to publish your web app in multiple languages. This section explains how to use this feature in your application.

==== HTML Template Translation

To get started with Errai's internationalization support, simply put [code]+@Bundle("bundle.json")+ or [code]+@Bundle("bundle.properties")+ annotation on your entry point and add an empty [code]+bundle.json+ or [code]+bundle.properties+ file to your classpath (e.g. to src/main/java or src/main/resources). Of course, you can name it differently provided the file extension is `.json` or `.properties`.

Errai will scan your HTML templates and process all text elements to generate key/value pairs for translation. It will generate a file called [code]+errai-bundle-all.json+ and put it in your [code]+.errai+ directory. If you used a JSON file in you [code]+@Bundle+ annotation, you can copy this generated file and use it as a starting point for your custom translation bundles. If the text value is longer than 128 characters the key will get cut off and a hash appended at the end.

The translation bundle files use the same naming scheme as Java (e.g. [code]+bundle_nl_BE.json+ or [code]+bundel_nl_BE.properties+ for Belgian Dutch, and [code]+bundle_nl.json+ or [code]+bundle_nl.properties+ for plain Dutch). Errai will also generate a file called [code]+errai-bundle-missing.json+ in the [code]+.errai+ folder containing all template values for which no translations have been defined. You can copy the key/value pairs out of this file to create our own translations when you use a JSON file:


[source, javascript]
----
{
"StoresPage.Stores!" : "Stores!",
"WelcomePage.As_you_move_toward_a_more_and_more_declarative_style,_you_allow_the_compiler_and_the_framework_to_catch_more_mistakes_up_front._-734987445" : "As you move toward a more and more declarative style, you allow the compiler and the framework to catch more mistakes up front. Broken links? A thing of the past!"
}
----

Here are the same translations as specified by a properties file:

[source]
----
StoresPage.Stores! = Stores!
WelcomePage.As_you_move_toward_a_more_and_more_declarative_style,_you_allow_the_compiler_and_the_framework_to_catch_more_mistakes_up_front._-734987445 = As you move toward a more and more declarative style, you allow the compiler and the framework to catch more mistakes up front. Broken links? A thing of the past!
----

If you want to use your own keys instead of these generated ones you can specify them in your templates using the [code]+data-i18n-key+ attribute:


[source, xml]
----
<html>
<body>
  <div id="content">
  <p data-i18n-key="welcome">Welcome to errai-ui i18n.</p>
<div>
...
----

By adding this attribute in the template you can translate it with the following:


[source, javascript]
----
{
    "TemplatedClassName.welcome": "Willkommen bei Errai-ui i18n."
}
----

or

[source]
----
TemplatedClassName.welcome=Willkommen bei Errai-ui i18n.
----

These keys are prefixed with the name of the `@Templated` class to which they belong, and as such will only applied to the element with `data-i18n-key="welcome"` in that classes template. You may also declare translations without the prefix that can apply to any template, like so:

[source, javascript]
----
{
    "welcome": "Willkommen bei Errai-ui i18n."
}
----

or

[source]
----
welcome=Willkommen bei Errai-ui i18n.
----

Either of these translations will apply to elements with `data-i18n-key="welcome"` in any template.


Because your templates are designer templates and can contain some mock data that doesn't need to be translated, Errai has the ability to indicate that with an attribute [code]+data-role=dummy+:


[source, xml]
----
<div id=navbar data-role=dummy>
  <div class="navbar navbar-fixed-top">
    <div class=navbar-inner>
      <div class=container>
        <span class=brand>Example Navbar</span>
        <ul class=nav>
          <li><a>Item</a>
          <li><a>Item</a>
        </ul>
      </div>
    </div>
  </div>
</div>
----

Here the template fills out a navbar with dummy elements, useful for creating a design, adding [code]+data-role=dummy+ will not only exclude it form being translated it will also strip the children nodes from the template that will be used by the application.

When you have setup a translation of your application Errai will look at the browser locale and select the locale, if it's available, if not it will use the default ([code]+bundle.json+). If the users of your application need to be able to switch the language manually, Errai offers a pre build component you can easily add to your page: [code]+LocaleListBox+ will render a Listbox with all available languages. If you want more control of what this language selector looks like there is also a [code]+LocaleSelector+ that you can use to query and select the locale for example:


[source, java]
----
@Templated
public class NavBar {

  @Inject
  private LocaleSelector selector;

  @Inject @DataField @OrderedList
  ListWidget<Locale, LanguageItem> language;

  @AfterInitialization
  public void buildLanguageList() {
    language.setItems(new ArrayList<Locale>(selector.getSupportedLocales()));
  }

...
// in LanguageItem we add a click handler on a link

  @Inject
  Navigation navigation;

  @Inject
  private LocaleSelector selector;

  link.addClickHandler(new ClickHandler() {
      @Override
      public void onClick(ClickEvent event) {
        selector.select(model.getLocale());
        navigation.goTo(navigation.getCurrentPage().name());
      }
    });
----

==== TranslationKey and TranslationService

The [code]+@TranslationKey+ annotation and [code]+TranslationService+ class extend Errai's i18n support to Java code. They provide a mechanism for developers to declare translation strings from within their GWT application code (as opposed to the HTML templates).

To do this, developers must annotate a field which represents the translation key with [code]+@TranslationKey+ annotation. This key will then map to a value in the translation bundle file. Once the field is annotated appropriately, the developer must directly invoke the TranslationService's format() method. This method call will perform a lookup in the translation service of the value mapped to the provided key. Note that value substitution using the +\{N\}+ format is supported.

As an example, consider the following code:


[source, java]
----
package org.example.ui.client.local;

public class AppMessages {

   @TranslationKey(defaultValue = "I guess something happened!")
   public static final String CUSTOM_MESSAGE = "app.custom-message";
   
   @TranslationKey(defaultValue = "Hey {0}, I just told you something happened!")
   public static final String CUSTOM_MESSAGE_WITH_NAME = "app.custom-message-with-name";
}
----


[source, java]
----
package org.example.ui.client.local;

@Dependent
@Templated
public class CustomComponent extends Composite {
      
   @Inject
   private TranslationService translationService;

   @Inject
   @DataField
   private Button someAction;

   @EventHandler("someAction")
   private void doLogin(ClickEvent event) {
     
      // do some action that may require a notification sent to the user
     
      String messageToUser = translationService.format(AppMessages.CUSTOM_MESSAGE);
      Window.alert(messageToUser);
     
      String username = getCurrentUserName();
      String messageToUserWithName = translationService.format(AppMessages.CUSTOM_MESSAGE_WITH_NAME, username);
      Window.alert(messageToUserWithName);
   }
}
----

[[sid-51806600_ErraiUI-ExtendedstylingwithLESS]]

=== Extended styling with LESS

Errai also supports link:$$http://lesscss.org$$[LESS] stylesheets for `@Templated`. You can specify a CSS or LESS stylesheet path for a component with the `stylesheet` attribute of `@Templated`, as in the example below:

[source, java]
----
package org.jboss.errai.example;

@Templated(stylesheet = "main.less")
public class StyledComponent {
}
----

For the above example, during GWT compilation Errai will load the LESS stylesheet from the classpath (in this case with the path `org/jboss/errai/example/main.less`) and compile it. At runtime the compiled CSS will be loaded.

You can omit the `stylesheet` attribute if your LESS stylsheet follows the standard Errai UI naming conventions. For example:

[source, java]
----
package org.jboss.errai.example;

@Templated
public class StyledComponent {
}
----

Errai will automatically find and compile a LESS stylesheet for this template if it exists on the classpath at this path: `org/jboss/errai/example/StyledComponent.less`

[NOTE]
.Precedence of CSS and LESS
====
When the `stylesheet` attribute is not specified, Errai will only find a LESS stylesheet as described above if no CSS stylesheet exists at the default path.
====


[[sid-54493676]]

== Errai UI Navigation

Starting in version 2.1, Errai offers a system for creating applications that have multiple bookmarkable pages. This navigation system has the following features:

* Declarative, statically-analyzable configuration of pages and links
* Compile time referential safety (i.e. &ldquo;no broken links&rdquo;)
* Generates a storyboard of the application&rsquo;s navigation flow at compile time


* Decentralized configuration
* Create a new page by creating a new annotated class. No need to edit a second file.
* Make navigational changes in the natural place in the code


* Integrates cleanly with Errai UI templates, but also works well with other view technologies
* Builds on Errai IoC & CDI

* Provides support for HTML5 pushState and path-parameter based URLs


[[sid-54493676_ErraiUINavigation-GettingStarted]]

=== Getting Started

[NOTE]
.Manual Setup
====
Checkout the <<Manual-Setup-Section,Manual Setup Section>> for instructions on how to manually add Errai Navigation to your project.
====

[[sid-54493676_ErraiUINavigation-HowitWorks]]

=== How it Works

Errai Navigation has these main parts:

* The [code]+@Page+ annotation marks any widget or Errai UI component as a page.
* The [code]+TransitionTo<P>+, [code]+TransitionAnchor<P>+, and [code]+TransitionToRole<R>+ classes are injectable types that provide links to other pages.
* The [code]+Navigation+ singleton offers control over the navigation system as a whole.

The [code]+Navigation+ singleton owns a GWT Panel called the _navigation panel_. This panel always contains a widget or component corresponding to the fragment ID (the part after the # symbol) in the browser's location bar. Whenever the fragment ID changes for any reason (for example, because the user pressed the back button, navigated to a bookmarked URL, or simply typed a fragment ID by hand), the widget in the navigation panel is replaced by the widget associated with that fragment ID. Likewise, when the application asks the navigation system to follow a link, the fragment ID in the browser's location bar is updated to reflect the new current page.

[[sid-54493676_ErraiUINavigation-DeclaringaPage]]

==== Declaring a Page

To declare a page, annotate any subclass of Widget or Errai UI templated component with the [code]+@Page+ annotation:


[source, java]
----
@Page
public class ItemListPage extends Composite {
  // Anything goes...
}
----

[source, java]
----
@Page
@Templated
public class ComponentPage {
  // Anything goes...
}
----

By default, the name of a page is the simple name of the class that declares it. In the above examples, the [code]+ItemListPage+ will fill the navigation panel whenever the browser's location bar ends with [code]+#ItemListPage+ and similarly [code]+ComponentPage+ will be displayed when the location bar ends with [code]+#ComponentPage+. If you prefer a different page name, use the [code]+@Page+ annotation's [code]+path+ attribute:


[source, java]
----
@Page(path="items")
public class ItemListPage extends Composite {
  // Anything goes...
}
----

[[sid-54493676_ErraiUINavigation-TheStartingPage]]

===== The Default (Starting) Page

Each application must have exactly one _default page_. This requirement is enforced at compile time. This default page is displayed when there is no fragment ID present in the browser's location bar.

Use the [code]+role = DefaultPage.class+ attribute to declare the default starting page, like this:

[source, java]
----
@Page(role = DefaultPage.class)
public class WelcomePage extends Composite {
  // Anything goes...
}
----

Pages are looked up as CDI beans, so you can inject other CDI beans into fields or a constructor. Pages can also have [code]+@PostConstruct+ and [code]+@PreDestroy+ CDI methods.

===== Page Roles

`DefaultPage` is just one example of a page role. A page role is simply an interface used to mark `@Page` types. The main uses for page roles:

* Using the `Navigation` singleton, you can look up all pages that have a specific role.
* If a role is unique (as is the case with `DefaultPage`) then it should extend `UniquePageRole`, making it possible to navigate to the page by its role.

[[sid-54493676_ErraiUINavigation-PageLifecycle]]

==== Page Lifecycle

There are four annotations related to page lifecycle events: [code]+@PageShowing+, [code]+@PageShown+, [code]+@PageHiding+, and [code]+@PageHidden+. These annotations designate methods so a page widget can be notified when it is displayed or hidden:


[source, java]
----
@Page
public class ItemPage extends VerticalPanel {

  @PageShowing
  private void preparePage() {
  }

  @PageHiding
  private void unpreparePage() {
  }

  // Anything goes...
}
----

===== Lifecycle Phases

. The fragment identifier in the URL changes

. The [code]+@PageHiding+ method on the current (about-to-be-navigated-away-from) page is invoked


. The current page is removed from the browser's DOM


. The [code]+@PageHidden+ method on the just-removed page is invoked


. The navigation system looks up the corresponding [code]+@Page+ bean in the client-side bean manager (we'll call this bean "the new page")


. The navigation system writes to all [code]+@PageState+ fields in the new page bean (more on this in the next section)


. The [code]+@PageShowing+ method of the new page is invoked


. The new page widget is added to the DOM (as a direct child of the navigation content panel)


. The [code]+@PageShown+ method of the new page is invoked.

===== Optional Parameters

The [code]+@PageShowing+ and [code]+@PageShown+ methods are permitted one optional parameter of type [code]+HistoryToken+ -- more on this in the next section.

The [code]+@PageHiding+ and [code]+PageShowing+ methods are also permitted one optional parameter of type [code]+NavigationControl+. If the parameter is present, the page navigation will not be carried out until `NavigationControl.proceed()` is invoked, or `NavigationControl.redirect(Class)` may be called to redirect to another page with the given class. In [code]+PageHiding+ methods this is useful for interrupting page navigations and then resuming at a later time (for example, to prompt the user to save their work before transitioning to a new page). In [code]+PageShowing+ methods, this is useful for redirecting a user before a page is shown based on business logic.

===== Page Instance Lifespan

The lifespan of a Page instance is governed by CDI scope: Dependent and implict-scoped page beans are instantiated each time the user navigates to them, whereas Singleton and ApplicationScoped beans are created only once over the lifetime of the application. If a particular page is slow to appear because its UI takes a lot of effort to build, try marking it as a singleton.

[[sid-54493676_ErraiUINavigation-PageStateParameters]]

==== Page State Parameters

A page widget will often represent a view on on instance of a class of things. For example, there might be an ItemPage that displays a particular item available at a store. In cases like this, it's important that the bookmarkable navigation URL includes not only the name of the page but also an identifier for the particular item being displayed.

This is where page state parameters come in. Consider the following page widget:


[source, java]
----
@Page
public class ItemPage extends VerticalPanel {

  @PageState
  private int itemId;

  // Anything goes...
}
----

This page would be reachable at a URL like `http://www.company.com/store/#ItemPage;itemId=4`, assuming `www.company.com` was the host address and `store` was the application context. Before the page was displayed, the Errai UI Navigation framework would write the [code]+int+ value [code]+4+ into the [code]+itemId+ field.

Page state parameters can also be accessed using URLs with path parameters. In this case, you have to declare the template of the page's path in the [code]+path+ field of the [code]+@Page+ annotation. As an example, consider the following code:

[source, java]
----
@Page(path="item/{itemID}/{customerID}")
public class ItemPage extends VerticalPanel {

  @PageState
  private int itemID;

  @PageState
  private String customerID;

  // Anything goes...
}
----

In the above example, the [code]+{itemID}+ and [code]+{customerID}+ fields represent path parameters. Any combination of path strings and path parameters that are separated by slashes is considered valid. The URL `http://www.company.com/store/#item/5042/cust1234` would redirect the user to the ItemPage, with the state values set as [code]+int itemId = 4+ and [code]+String customerID = "cust1234"+.

There are three ways to pass state information to a page: by passing a Multimap to [code]+TransitionTo.go()+; by passing a Multimap to [code]+Navigation.goTo()+; or by including the state information in the path parameter or fragment identifier of a hyperlink as illustrated in the previous paragraph (use the [code]+HistoryToken+ class to construct such a URL properly.)

A page widget can have any number of [code]+@PageState+ fields. The fields can be of any primitive or boxed primitive type (except [code]+char+ or [code]+Character+), [code]+String+, or a [code]+Collection+, [code]+List+, or [code]+Set+ of the allowable scalar types. Nested collections are not supported.

[code]+@PageState+ fields can be private, protected, default access, or public. They are always updated by direct field access; never via a setter method. The updates occur just before the [code]+@PageShowing+ method is invoked.

In addition to receiving page state information via direct writes to [code]+@PageState+ fields, you can also receive the whole Multimap in the [code]+@PageShowing+ and [code]+@PageShown+ methods through a parameter of type [code]+HistoryToken+. Whether or not a lifecycle method has such a parameter, the [code]+@PageState+ fields will still be written as usual.

Page state values are represented in the URL in place of the corresponding parameter variables declared in the URL template (the [code]+path+ field of the [code]+@Page+ annotation. See <<sid-54493676_ErraiUINavigation-DeclaringaPage, Declaring a Page>>). If a parameter variable is declared in the URL template and is missing from the actual typed URL, it will cause a navigation error as Errai will not be able to match the typed URL to any template. 

Any additional path parameters not found in the URL template are appended as key=value pairs separated by the ampersand ([code]+&+) character. Multi-valued page state fields are represented by repeated occurrences of the same key. If a key corresponding to a [code]+@PageState+ field is absent from the state information passed to the page, the framework writes a default value: [code]+null+ for scalar Object fields, the JVM default (0 or false) for primitives, and an empty collection for collection-valued fields. To construct and parse state tokens programmatically, use the [code]+HistoryToken+ class.

To illustrate this further, consider the following example:

[source, java]
----
@Page(path="item/{itemID}/{customerID}")
public class ItemPage extends VerticalPanel {

  @PageState
  private int itemID;

  @PageState
  private String customerID;

  @PageState
  private int storeID;

  // Anything goes...
}
----

Given the host [code]+"www.company.com"+, the context `store`, and a state map with the values [code]+itemID=4231+, [code]+customerID=9364+, and [code]+storeID=0032+, the following URL will be generated:
[code]+www.company.com/store/#item/4231/9364;storeID=0032+

If the value for storeID is undefined, the URL will be `www.company.com/store/#item/4231/9364;storeID=0`.

If the URL typed into the browser is `www.company.com/store/#item/4231;storeID=0032`, it will cause a navigation error (assuming there is no other page by this url) because there is a missing path parameter.

==== PushState Functionality

Errai now comes with support for pushState and path-parameter-based URLs. If HTML5 pushState is enabled Errai Navigation urls will not use the fragment-identifier (#). Thus the non-pushState url from the previous section, `www.company.com/store/#item/4231/9364`, would become `www.company.com/store/item/4231/9364`. 

HTML5 pushState can be enabled by adding the following lines to your GWT host page:

[source, xml]
----
<script type="text/javascript">
    var erraiPushStateEnabled = true;
</script>
----

The application context must be the same as the application's servlet web context deployed on the server. Errai attempts to infer the application context upon the first page load, but it can also be set manually. To explicitly declare the application context, you can use the [code]+setApplicationContext+ method in the Navigation class, or set the [code]+erraiApplicationWebContext+ variable in your GWT host page as follows:

[source, xml]
----
<script type="text/javascript">
    var erraiApplicationWebContext = "store";
</script>
----

In the event that the browser does not support HTML5, Errai automatically disables pushState functionality and reverts to a '#'-based URL format. That is, Errai uses fragment identifiers to refer to particular resources.

If the page that the user is trying to navigate to cannot be found, a 404 - Not Found page is displayed. You can override this functionality and display a custom page in the case of a page not found error. For example, to navigate to the GWT host page by default, add the following lines to your web.xml file:

[source, xml]
----
<error-page>
    <error-code>404</error-code>
    <location>/</location>
</error-page>
----

[[sid-54493676_ErraiUINavigation-DeclaringaLinkwithTransitionAnchor]]

==== Declaring a Link with TransitionAnchor

The easiest way to declare a link between pages is to inject an instance of [code]+TransitionAnchor<P>+, where [code]+P+ is the class of the target page.

Here is an example declaring an anchor link from the templated welcome page to the item list page. The first code sample would go in WelcomePage.java while the second would go in the WelcomePage.html, the associated html template.

[source, java]
----
@Page(role = DefaultPage.class)
@Templated
public class WelcomePage {

  @Inject @DataField TransitionAnchor<ItemListPage> itemLink;

}
----

[source, xml]
----
<div>
  <a data-field="itemLink">Go to Item List Page</a>
</div>
----

You can inject any number of links into a page. The only restriction is that the target of the link must be a Widget type or Errai UI component that is annotated with [code]+@Page+. When the user clicks the link Errai will transition to the item list page.

[[sid-54493676_ErraiUINavigation-DeclaringaManualLink]]

==== Declaring a Manual Link

Sometimes it is necessary to manually transition between pages (such as in response to an event being fired). To declare a manual link from one page to another, inject an instance of [code]+TransitionTo<P>+, where [code]+P+ is the class of the target page.

This code declares a manual transition from the welcome page to the item list page:

[source, java]
----
@Page(role = DefaultPage.class)
public class WelcomePage extends Composite {

  @Inject TransitionTo<ItemListPage> startButtonClicked;

}
----

You do not need to implement the [code]+TransitionTo+ interface yourself; the framework creates the appropriate instance for you.

As with [code]+TransitionAnchor+, the only restriction is that the target of the link must be a Widget type or Errai UI component that is annotated with [code]+@Page+.

[[sid-54493676_ErraiUINavigation-FollowingaManualLink]]

==== Following a Manual Link

To follow a manual link, simply call the [code]+go()+ method on an injected [code]+TransitionTo+ object. For example:


[source, java]
----
@Page(role = DefaultPage.class)
public class WelcomePage extends Composite {

  @Inject TransitionTo<ItemListPage> startButtonClicked;

  public void onStartButtonPressed(ClickEvent e) {
    startButtonClicked.go();
  }
}
----

==== Declaring a Link By UniquePageRole

For convenience, it is also possible to transition to a page by its role using an injected `TransitionToRole<R>` where `R` is an interface extending `UniquePageRole`. This type is used exactly as the `TransitionTo`: just inject a parameterized instance and invoke the `go()` method.

By injecting a `TransitionToRole` into a `@Page`, Errai will verify the existence of a single page with this role at compile-time.

[[sid-54493676_ErraiUINavigation-InstallingtheNavigationPanelintotheUserInterface]]

==== Installing the Navigation Panel into the User Interface

Beginning in version 2.4, Errai will automatically attach the Navigation Panel to the Root Panel, but it is possible to override this behaviour by simply adding the Navigation Panel to another component manually. The best time to do this is during application startup, for example in the [code]+@PostConstruct+ method of your [code]+@EntryPoint+ class. By using the default behaviour you can allow Errai Navigation to control the full contents of the page, or you can opt to keep some parts of the page (headers, footers, and sidebars, for example) away from Errai Navigation by choosing an alternate location for the Navigation Panel.

The following example reserves space for header and footer content that is not affected by the navigation system:


[source, java]
----
@EntryPoint
public class Bootstrap {

  @Inject
  private Navigation navigation;

  @PostConstruct
  public void clientMain() {
    VerticalPanel vp = new VerticalPanel();
    vp.add(new HeaderWidget());
    vp.add(navigation.getContentPanel());
    vp.add(new FooterWidget());

    RootPanel.get().add(vp);
  }
}
----

This last example demonstrates a simple approach to defining the page structure with an Errai UI template. The final product is identical to the above example, but in this case the overall page structure is declared in an HTML template rather than being defined programmatically in procedural logic:


[source, java]
----
@Templated("#root")
@EntryPoint
public class OverallPageStructure {

  @Inject
  private Navigation navigation;

  @Inject @DataField
  private DivElement root;

  @Inject @DataField
  private Header header;

  @Inject @DataField
  private SimplePanel content;

  @Inject @DataField
  private Footer footer;

  @PostConstruct
  public void clientMain() {

    // give over the contents of this.content to the navigation panel
    content.add(navigation.getContentPanel());

    // add this whole component to the DOM
    Document.get().getBody().appendChild(root);
  }

}
----

[[sid-54493676_ErraiUINavigation-OverridingthedefaultNavigatingPaneltype]]

==== Overriding the default Navigating Panel type

By default Errai uses [code]+com.google.gwt.user.client.ui.SimplePanel+ as a container for navigation panel. Sometimes this is not sufficient and users would prefer using another implementation. For example a [code]+com.google.gwt.user.client.ui.SimpleLayoutPanel+ that manages child size state.

To provide your own implementation of the navigation panel you must implement [code]+org.jboss.errai.ui.nav.client.local.NavigatingContainer+. For example:


[source, java]
----
public class NavigatingPanel implements NavigatingContainer {

  SimplePanel panel = new SimpleLayoutPanel();

  public void clear() {
    this.panel.clear();
  }

  public Widget asWidget() {
    return panel.asWidget();
  }

  public Widget getWidget() {
    return panel.getWidget();
  }

  public void setWidget(Widget childWidget) {
    panel.add(childWidget);
  }

  public void setWidget(IsWidget childWidget) {
    panel.add(childWidget);
  }

}
----

Then in your GWT module descriptor you need to override the default navigation panel ([code]+org.jboss.errai.ui.nav.client.local.NavigatingContainer+) by adding:


[source, xml]
----
<replace-with class="com.company.application.client.NavigatingPanel">
  <when-type-is class="org.jboss.errai.ui.nav.client.local.NavigatingContainer"/>
</replace-with>
----

==== Handling Navigation Errors

When a user enters a url for an Errai page that does not exist an error is logged and the app navigates to the `DefaultPage`. It is possible to override this behaviour by setting an error handler on `Navigation`.

Here is an example of a class that registers a navigation error handler that redirects the user to a special `PageNotFound` page:

[source, java]
----
@ApplicationScoped
public class NavigationErrorHandlerSetter {

  @Inject
  private Navigation navigation;

  @PostConstruct
  public void setErrorHandler() {
    navigation.setErrorHandler(new PageNavigationErrorHandler() {

      @Override
      public void handleError(Exception exception, String pageName) {
        navigation.goTo("PageNotFound");
      }

      @Override
      public void handleError(Exception exception, Class<? extends PageRole> pageRole) { <1>
        navigation.goTo("PageNotFound");
      }
    });
  }

}
----

<1> Note that this method signature is for errors that occur from calls to `Navigation.goToWithRole(Class<? extends UniquePageRole>)`. These kinds of errors can be avoided at compile-time by injecting `TransitionToRole` instances into your `@Page` classes instead of directly calling that method.


[[sid-54493676_ErraiUINavigation-ViewingtheGeneratedNavigationGraph]]

==== Viewing the Generated Navigation Graph

Because the pages and links in an Errai Navigation application are declared structurally, the framework gets a complete picture of the app's navigation structure at compile time. This knowledge is saved out during compilation (and at page reload when in Dev Mode) to the file [code]+.errai/navgraph.gv+. You can view the navigation graph using any tool that understands the GraphViz (also known as DOT) file format.

One popular open source tool that can display GraphViz/DOT files is link:$$http://www.graphviz.org/$$[GraphViz]. Free downloads are available for all major operating systems.

When rendered, a navigation graph looks like this:

.Navigation Graph
image::author/download/attachments/54493676/example_errai_nav_graph.png[]


In the rendered graph, the pages are nodes (text surrounded by an ellipse). The starting page is drawn with a heavier stroke. The links are drawn as arrows from one page to another. The labels on these arrows come from the Java field names the TransitionTo objects were injected into.

== Errai Security

Errai Security provides a lightweight security API for declaring RPC services and client-side UI elements which require authentication or authorization.

[WARNING]
.PicketLink support deprecated
====
The Errai Security support for Picket Link is deprecated. Users should use Keycloak with Errai or provide their own implementations for Errai's AuthenticationService.
====

[NOTE]
.Manual Setup
====
Checkout the <<Manual-Setup-Section,Manual Setup Section>> for instructions on how to manually add Errai Security to your project.
====

=== Basic Model

Errai Security provides two main concepts:

* *Users*
** A User corresponds to a single person.
** It is usually associated with a username, full name, and email address.

* *Roles*
** A Role represents a priveleged group within your system.
** A User can have several roles, and a role can be had by many users.
** Roles are the primary way of defining authorization in Errai Security.

By default the server-side Errai Security module uses link:$$http://www.picketlink.org/$$[PicketLink] for authentication. Later on we will explain how to use an alternative backend.

=== Getting Started

==== Making Users

The simplest way to begin experimenting with Errai Security is to add Users and Roles to PicketLink programmatically. Here is some sample server-side code from the link:$$https://github.com/errai/errai/blob/master/errai-demos/errai-security-demo/src/main/java/org/jboss/errai/security/demo/server/PicketLinkDefaultUsers.java$$[Errai Security Demo].

[source,java,numbered]
----
@Singleton
@Startup
public class PicketLinkDefaultUsers {

  @Inject
  private PartitionManager partitionManager; <1>

  /**
   * <p>Loads some users during the first construction.</p>
   */
  @PostConstruct
  public void create() {
    final IdentityManager identityManager = partitionManager.createIdentityManager();
    final RelationshipManager relationshipManager = partitionManager.createRelationshipManager();

    User john = new User("john");

    john.setEmail("john@doe.com");
    john.setFirstName("John");
    john.setLastName("Doe");

    User hacker = new User("hacker");

    hacker.setEmail("hacker@illegal.ru");
    hacker.setFirstName("Hacker");
    hacker.setLastName("anonymous");
    
    identityManager.add(john); <2>
    identityManager.add(hacker);
    final Password defaultPassword = new Password("123");
    identityManager.updateCredential(john, defaultPassword);
    identityManager.updateCredential(hacker, defaultPassword);

    Role roleDeveloper = new Role("simple");
    Role roleAdmin = new Role("admin");

    identityManager.add(roleDeveloper);
    identityManager.add(roleAdmin);

    relationshipManager.add(new Grant(john, roleDeveloper)); <3>
    relationshipManager.add(new Grant(john, roleAdmin));
  }

}
----

Here are the important things that are happening here:

<1> PicketLink uses the concept of partitions, which are sections that can contain different users and roles. What we really need to make users and roles are the `IdentityManager` and `RelationshipManager`, but these objects are `@RequestScoped` so in order to access them when the application starts we must `@Inject` the `PartitionManager`.

<2> Here we add are new users to the `IdentityManager`. It is also used below to give passwords to the new users, and to add the _simple_ and _admin_ roles.

<3> The `RelationshipManager` defines relationships between entities. In this case, it is used to specify that a user belongs to a role.

==== Authentication from the Client

Once you've created some users and roles, you're ready to write some client-side code. Authentication is performed with the `org.jboss.errai.security.shared.service.AuthenticationService` via Errai RPC.

Here is some sample code involving the user _john_ from the previous Security Demo excerpt.

* Injecting the `Caller<AuthenticationService>`:
+
[source,java]
----
@Inject Caller<AuthenticationService> authServiceCaller;
----

* Logging in:
+
[source,java]
----
authServiceCaller.call(new RemoteCallback<User>() {

    @Override
    public void callback(User user) {
      // handle successful login
    }
  }, new ErrorCallback<Message>() {

    @Override
    public boolean error(Message message, Throwable t) {
      if (t instanceof AuthenticationException) {
        // handle authentication failure
      }

      // Returning true causes the error to propogate to top-level handlers
      return true;
    }
  }).login("john", "123");
----

* Getting the currently authenticated User:
+
[source,java]
----
authServiceCaller.call(new RemoteCallback<User>() {

    @Override
    public void callback(User user) {
      if (!user.equals(User.ANONYMOUS)) {
        // Do something because we're logged in.
      }
      else {
        // Do something else because we're not logged in.
      }
    }
  }).getUser();
----

* Logging out:
+
[source,java]
----
authServiceCaller.call().logout();
----

[NOTE]
.AuthenticationService Caching
====
Client-side interceptors are used for caching so that generally only calls to `login` and `logout` must be sent over the wire. The cache is automatically invalidated when a service throws an `UnauthenticatedException`, but it can also be invalidated manually via the `SecurityContext`.
====

=== RestrictedAccess

The annotation `@RestrictedAccess` is the only annotation necessary to secure a resource or UI element. In general, `@RestrictedAccess` blocks a resource from users who are either not logged in or who lack required roles. Roles are defined through the `@RestrictedAccess` annotation in one of the following two ways.

==== Simple Roles as Strings

Simple roles are roles that can be directly mapped to Strings (the String value being the role name). Simple roles are defined by defining an array of Strings in the `roles` parameter of `@RestrictedAccess`. Two simple roles are equivalent if they have the same name.

Here is an example usage of `@RestrictedAccess` with two simple roles, "user" and "admin":

[source,java]
----
@RestrictedAccess(roles = { "user", "admin" })
----

==== Provided Roles

Conceptually, a provided can be used to implement a more complex security system. In practice, a provided role is some concrete type that implements the `Role` interface and overrides `Object.equals(Object)`. Provided roles are declared on a resource by creating a `RequiredRolesProvider` that produces these roles and assigning the type to the `providers` parameter of `@RestrictedAccess`.

Here is an sample of a `RequireRolesProvider` and its usage with `@RestrictedAccess`. This example defines equivalent roles to the above example using simple roles.

[source,java]
----
@Dependent <1>
public class AdminRolesProvider implements RequiredRolesProvider {

  @Override
  public Set<Role> getRoles() {
    return new HashSet<Role>(Arrays.asList(
      new RoleImpl("user"), <2>
      new RoleImpl("admin")
    ));
  }
}
----

[source,java]
----
@RestrictedAccess(providers = { AdminRolesProvider.class })
----

<1> The role provider implementation must be a CDI bean so that it can be looked up dynamically on the client and server.

<2> `RoleImpl` is the internal implementation used for simple roles. A `RoleImpl` equals another role if they are both instances of `RoleImpl` and have matching names.

==== RPC Services

To secure an Errai RPC service, simply annotate the RPC interface (either the entire type or just a method) with one of the security annotations.

For example:

* All methods on this interface require an authenticated user to access:
+
[source,java]
----
@Remote
@RestrictedAccess
public interface UserOnlyStuff {
  public void someMethod();
  public void otherMethod();
}
----

* Here the first method requires an authenticated user, and the second requires a user with the _admin_ role:
+
[source,java]
----
@Remote
public interface MixedService {

  @RestrictedAccess
  public void userService();

  @RestrictedAccess(roles = {"admin"})
  public void adminService();
}
----

.Using Role Providers with RPC Services
[NOTE]
====
If a `RequiredRolesProvider` is used on an RPC interface, the provider type must be located in a shared package. Security checks for RPCs are performed on the client and the server, so placing the type in a client- or server-only package will result in run-time errors.
====

===== Error Callbacks

When access to a secured RPC service is denied an `UnauthenticatedException` or `UnauthorizedException` is thrown. This error is then transmitted back to the client, where it can be caught with an `ErrorCallback` (provided when the RPC is invoked).

Here is how we would invoke the previous `MixedService` example with error handling:

[source,java]
----
MessageBuilder.createCall(new RemoteCallback<Void>() {

    @Override
    public void callback(Void response) {
      // ...
    }
  }, new ErrorCallback<Message>() { <1>

    @Override
    public boolean error(Message message, Throwable t) {
      if (t instanceof UnauthenticatedException) {
        // User is not logged in.
        return false;
      }
      else if (t instanceof UnauthorizedException) {
        // User is logged in but lacked sufficient roles.
        return false;
      }
      else {
        // Some other error has happened. Let it propogate.
        return true;
      }
    }
  }, MixedService.class).adminService();
----

<1> This `ErrorCallback` is parameterized with the type `Message` because it is an Errai Bus RPC. In the next section we will demonstrate the use of a JAX-RS RPC.

[IMPORTANT]
.DefaultBusSecurityErrorCallback
====
Errai Security provides a default global Bus RPC handler that catches any thrown `UnauthenticatedException` or `UnauthorizedException` and navigates to the page with the `LoginPage` or `SecurityError` role respectively.
====

===== JAX-RS RPC

JAX-RS RPCs are secured exactly as bus RPCs. Here is the first example from the previous section, but converted to use JAX-RS instead of the Errai Bus.

[source,java]
----
@Path("/rest-endpoint")
@RestrictedAccess
public interface UserOnlyStuff {

  @Path("/some-method")
  @GET
  public void someMethod();

  @Path("/other-method")
  @GET
  public void otherMethod();
}
----

There are two important differences when calling a secured JAX-RS RPC (in contrast to an Errai Bus RPC):

* JAX-RS RPC calls use the `RestErrorCallback` (an interface extending `ErrorCallback<Request>`).

* There is now global error-handling for JAX-RS.

Because there is no global error-handling, you should always pass a `RestErrorCallback` when using a JAX-RS RPC. Errai provides the `DefaultRestSecurityErrorCallback` that provides the same default behaviour as the `DefaultBusSecurityErrorCallback` mentioned above. It can also optionally wrap a provided callback as demonstrated below:

* Injecting a callback `Instance`:
+
[source,java]
----
@Inject
private Instance<DefaultRestSecurityErrorCallback> defaultCallbackInstance;
----

* Wrapping a custom callback in a default callback:
+
[source,java]
----
void callSomeService() {
  userOnlyStuffService.call(new RemoteCallback<Void>() {

    @Override
    public void callback(Void response) {
      // Handle success...
    }
  }, defaultCallbackInstance.get()
        .setWrappedErrorCallback(new RestErrorCallback() {

          @Override
          public boolean error(Request request, Throwable t) {
            // Handle error...

            // Returning true means the default navigation behaviour will occur
            return true;
          }
        }
  )).someMethod();
}
----

* Using the default callback without a wrapped callback:
+
[source,java]
----
void callSomeService() {
  userOnlyStuffService.call(new RemoteCallback<Void>() {

    @Override
    public void callback(Void response) {
      // Handle success...
    }
  }, defaultCallbackInstance.get()).someMethod();
}
----

==== Page Navigation

Any class annotated with `@Page` can also be marked with `@RestrictedAccess`. By doing so, users will be prevented from navigating to the given page if they are not logged in or lack authorization.

Here are two simple examples:

* This page is only for logged in users:
+
[source,java]
----
@Page
@RestrictedAccess
public class UserProfilePage extends SimplePanel {

  @Inject private Caller<AuthenticationService> authServiceCaller;
  private User user;

  @PageShowing
  private void setupPage() {
    authServiceCaller.call(new RemoteCallback<User>() {
        @Override
        public void callback(User response) {
          // We don't have to check if this is a valid user, since the page requires authentication.
          user = response;
          // do setup...
        }
    }).getUser();
  }

}
----

* This page requires the _user_ and _admin_ roles:
+
[source,java]
----
@Page
@RestrictedAccess(roles = {"admin", "user"})
public class AdminManagementPage extends SimplePanel {
}
----

[IMPORTANT]
.Redirection
====
When a user is denied access to a page they will be redirected to a `LoginPage (@Page(role = LoginPage.class))` or `SecurityError (@Page(role = SecurityError.class))` page. To direct a user to the page they were trying to reach after successful login, `@Inject` the `SecurityContext` and invoke the `navigateBackOrHome` method.
====

===== Page Redirection and Caching

Security checks performed before page navigation do not use any RPC calls, but are instead performed from a cached (in-memory) instance of the `org.jboss.errai.security.shared.api.identity.User`. This prevents the possibility of lengthy delays between page navigation while waiting for RPC return values.

But the drawback is that any attempts to navigate to a secured `@Page` before the cache is populated will result in redirection to the `LoginPage` -- even if the user is in fact logged in.

In practice, this is only likely to happen if a user starts an Errai app with a URL to a secure page while still logged in on the server from a previous session.

One option offered by Errai is to persist the `org.jboss.errai.security.shared.api.identity.User` object on the GWT host page using a servlet filter. In errai-security-server there is `org.jboss.errai.security.server.servlet.UserHostPageFilter` that uses the `AuthenticationService` to do this. The `UserHostPageFilter` works in a CDI container. Enable the filter by setting `errai.security.user_on_hostpage_enabled=true` in ErraiApp.properties and ensuring the filter is active for your hostpage URL (filters index.html and index.jsp by default).

With this option enabled the `User` will be persisted to a JavaScript variable on the GWT host page, which is loaded quickly enough to avoid the described navigation issue. This feature can also be used to allow an application to work offline, or allow the server to log in a user on an initial page request.

If you do not wish to use this feature you will likely want to handle this case in the `@PageShowing` method of your `LoginPage`. Here is an outline of what you might want to do:

[source,java]
----
@Page(role = LoginPage.class)
@Templated
public class ExampleLoginPage extends Composite {

  @Inject
  private SecurityContext securityContext;

  @Inject
  private Caller<AuthenticationService> authService;

  @Inject
  @DataField
  private Label status;

  @PageShowing
  public void checkForPendingCache() {    
    // Check if cache is invalid.
    if (!securityContext.isUserCacheValid()) {
      // Update the status.
      status.setText("loading...");

      // Force cache to update by calling getUser
      authService.call(new RemoteCallback<User> {
        @Override
        public void callback(User user) {
          /* An interceptor will have updated the cache by now.
             So check if we are logged in and redirect if necessary.
          */
          if (!user.equals(User.ANONYMOUS)) {
            /* This is a special transition that takes us back to
               a secure page from which we were redirected. */
            securityContext.navigateBackOrHome();
          }
          else {
            status.setText("You are not logged in.");
          }
        }
      }).getUser();
    }
  }

}
----

==== Hiding UI Elements

Errai Security annotations can also be used to hide Errai UI template fields. When a user is not logged in or lacks required roles the annotated field will have the CSS class "errai-restricted-access-style" added to it. By defining this style (for example with `visibility: none`) you can hide or otherwise modify the display of the element for unautorized users.

Here is an example of an Errai UI templated class using this feature:

[source,java]
----
@Templated
public class NavBar extends Composite {

  @Inject
  @DataField
  @RestrictedAccess
  private Button logoutButton;

  @Inject
  @DataField
  @RestrictedAccess(roles = {"admin"})
  private Button dropAllTablesButton;

}
----

=== Form Based Login

[[ErraiUserHostPageFilter]]
==== Errai User Host Page Filter

The `errai-security-server` jar contains a servlet filter for encoding the currently authenticated user in an html page. By configuring this filter for your GWT host page, a user will be logged-in as soon as your Errai app loads. Here are the steps for setting this up:

. Add the following to your ErraiApp.properties: `errai.security.user_on_hostpage_enabled=true`

. Create a login page using an html form that posts to a servlet-filter. If you are using Errai Security with PicketLink you will want to use the `org.picketlink.authentication.web.AuthenticationFilter` servlet-filter. Otherwise, you will need to implement one yourself that authenticates the user by calling the `AuthenticationService.login(String, String)` method.

. Add this filter-mapping.
+
[source,xml]
----
  <filter-mapping>
    <filter-name>ErraiUserHostPageFilter</filter-name>
    <url-mapping>/gwt-host-page.html</url-mapping>
  </filter-mapping>
----
+
The mapped URL should be that of your GWT Host Page.

=== Using an Alternative to PicketLink

All Errai Security authentication is implemented with Errai Remote Procedure Calls to the `AuthenticationService`. A default implementation of this interface using PicketLink is provided in the `errai-security-picketlink` jar. But it is possible to use a different sever-side security framework by providing your own custom implementation of `AuthenticationService` and annotating it with `@Service`. In that case your project should not depend on `errai-security-picketlink`.

=== Using Keycloak for Authentication

link:$$http://keycloak.jboss.org/$$[Keycloak] is is a new project that provides integrated SSO and IDM for browser apps and RESTful web services. By using Keycloak it is possible to outsource the responsibility of authentication and account management from your application entirely. Errai Security provides an optional `errai-security-keycloak` jar that provides an implementation of the `AuthenticationService` that works with Keycloak.

==== How It Works (Overview)

From the perspective of a visitor, here is what happens when she attempts to log in:

* The visitor is redirected to a Keycloak login page.

* The visitor submits her credentials through the Keycloak login page.

* Assuming the credentials are valid, the visitor is redirected back to the web app, where she is now logged in.

===== Keycloak Token

Behind the scenes, when the visitor successfully submits credentials she is redirected back to the web app with a Keycloak Access Token, which contains information that is configurable from within Keycloak. A servlet filter is used to extract the token from the request and assign it to the `AuthenticationService` implementation. At this point the User is now logged in to your application.

==== Setup

[NOTE]
.Make sure to check out the Errai Security Demo. 
====
This demo can be configured to work with Keycloak in just a few simple steps as outlined in the link:$$https://github.com/errai/errai/tree/master/errai-demos/errai-security-demo$$[README file]!
====

To start from scratch and add Keycloak integration to your application:

* Setup a Keycloak server. Please consult the link:$$http://keycloak.jboss.org/docs.html$$[Keycloak documentation] for details on how this is achieved.

* Start the Keycloak server.

* Go to the link:$$https://github.com/errai/errai/tree/master/errai-demos/errai-security-demo$$[Keycloak Administrative Console] (i.e. http://localhost:8080/auth/admin/) (the username and password are both *admin* on first use).

* Click *Add Realm* and create a custom realm for your application.

* Select the *Clients* tab and click *Create*, then fill in the following to add the client application to this realm:
  ** `Client ID`: the name of your client application (i.e. errai-security-demo)
  ** `Access Type`: public
  ** `Redirect URI`: the url of your application (i.e. `http://localhost:8080/[your-application]/*`)
  
* After saving your application, choose the new application in the menu and make sure the following are set:
  ** In the *Roles* tab add your custom roles.
  ** In the *Installation* tab choose the format option `keycloak.json` and copy the contents in your `WEB-INF/keycloak.json` file. 

* Click on *Users* on the side-panel to add a user:
  ** Fill out the `Username`, `Email`, `First Name`, and `Last Name` with any values.
  ** After saving go to the *Credentials* tab and set a password.
  ** Go to the *Role Mappings* tab. Add `at least one` role to the `Assigned Roles` for your application (scroll down to `Application Roles` and select your application to do this).

* Add the `errai-security-keycloak` jar to your project and make sure it's being deployed to the server. In maven, the dependency is `org.jboss.errai:errai-security-keycloak`.

* Configure the `ErraiUserCookieFilter` in your `web.xml`. All that is necessary is adding a filter-mapping for your GWT host page like so:
+
[source,xml]
----
  <filter-mapping>
    <filter-name>ErraiUserCookieFilter</filter-name>
    <url-pattern>/index.html</url-pattern>
  </filter-mapping>
----

* Configure the `ErraiLoginRedirectFilter` in your `web.xml`.
  ** Create a filter-mapping of this filter onto a path that will act as a url to the Keycloak login page. For example, if your deployed app is called `my-app` and you wanted `<server-uri>/my-app/app-login` as your login url then you would add the following:
+
[source,xml]
----
  <filter-mapping>
    <filter-name>ErraiLoginRedirectFilter</filter-name>
    <url-pattern>/app-login</url-pattern>
  </filter-mapping>
----

  ** Add a security-constraint to login url. This is what actually causes the redirection to Keycloak. All the filter does is redirect back to your app (which happens after the login completes). For the previous example, the constraint would look like this:
+
[source,xml]
----
  <security-constraint>
    <web-resource-collection>
      <web-resource-name>Login</web-resource-name>
      <url-pattern>/app-login</url-pattern>
    </web-resource-collection>
    <auth-constraint>
      <role-name>*</role-name>
    </auth-constraint>
  </security-constraint>
----

  ** Optionally configure the URL that the `ErraiLoginRedirectFilter` redirects to. You can do this with the `redirectLocation` param, which takes a path relative to the app context:
+
[source,xml]
----
  <filter>
    <filter-name>ErraiLoginRedirectFilter</filter-name>
    <init-param>
      <param-name>redirectLocation</param-name>
      <param-value>/index.jsp</param-value>
    </init-param>
  </filter>
----

* Set the login method to use Keycloak in you `web.xml`:
+
[source,xml]
----
  <login-config>
    <auth-method>KEYCLOAK</auth-method>
    <realm-name>[your-realm-name]</realm-name>
  </login-config>
----

* Add roles available to users in your application to the `web.xml`. Here is an example declaration of a "user" role:
+
[source,xml]
----
  <security-role>
    <role-name>user</role-name>
  </security-role>
----

.All users must have at least one role
[IMPORTANT]
====
With this configuration all users must have at least a single role, or else they will not be redirected propertly. Unfortunately, there is no way to define a security-constraint that only requires authentication. The simplest solution is to add a default role to your realm.
====

[[sid-74908675]]

== Logging

Errai now supports using the link:$$http://www.slf4j.org/$$[slf4j] logging api on the server and client. This gives you the flexibility of choosing your own logging back-end for your server-side code, while still allowing a uniform logging interface that can be used in shared packages.

[[sid-74908675_Logging-Whatisslf4j%3F]]

=== What is slf4j?

sl4j is logging abstraction. Using the slf4j api, you can add log statements to your code using a fixed api while maintaining the ability to switch the logging implementation at run-time. For example, the slf4j api can be used with java.util.logging (JUL) as the back-end.

[[sid-74908675_Logging-ClientSideSetup]]

=== Client-Side Setup

The client-side slf4j code uses the link:$$http://www.gwtproject.org/doc/latest/DevGuideLogging.html$$[GWT Logging] as the back-end. Using slf4j in client-side code has three steps:

* Add the errai-common artifact as a maven dependency to your project

* Inherit the GWT module [code]+org.jboss.errai.common.ErraiCommon+
+
[source,xml]
----
  <inherits name="org.jboss.errai.common.ErraiCommon" />
----
* Enable logging and configure the log level in your gwt.xml module descriptor:
+
[source,xml]
----
  <set-property name="gwt.logging.enabled" value="TRUE"/>
  <set-property name="gwt.logging.logLevel" value="ALL"/>    
----

[[sid-74908675_Logging-ErraiClientSideLogHandlers]]

==== Errai Client-Side Log Handlers

In the ErraiCommon module, we have disabled the built-in GWT log handlers and provided four handlers of our own:

* _ErraiSystemLogHandler_: prints log statements to the terminal in Development Mode
* _ErraiConsoleLogHandler_: prints statements to the web console in the browser
* _ErraiDevelopmentModeLogHandler_: prints statements in the Development Mode window
* _ErraiFirebugLogHandler_: prints statements to the console in Firefox These loggers are all enabled by default and set to handle all log levels.

[[sid-74908675_Logging-ConfiguringErraiClientSideLogHandlers]]

==== Configuring Errai Client-Side Log Handlers

Log handler levels can be changed at run-time through Java or Javascript. To do so through Java, use the [code]+LoggingHandlerConfigurator+ in Errai Common. Here's an example:

.HandlerLevelAdjuster.java
====

[source, java]
----
import org.jboss.errai.common.client.logging.LoggingHandlerConfigurator;
import org.jboss.errai.common.client.logging.handlers.ErraiSystemLogHandler;
import java.util.logging.Level;

public class HandlerLevelAdjuster {

  public static void logAll() {
    LoggingHandlerConfigurator config = LoggingHandlerConfigurator.get();
    ErraiSystemLogHandler handler = config.getHandler(ErraiSystemLogHandler.class);
    handler.setLevel(Level.ALL);
  }

  public static void disableLogging() {
    LoggingHandlerConfigurator config = LoggingHandlerConfigurator.get();
    ErraiSystemLogHandler handler = config.getHandler(ErraiSystemLogHandler.class);
    handler.setLevel(Level.OFF);
  }

}
----

====

Each handler has a native Javascript variable associated with its log level:

[options="header"]
|===============
|Handler|Variable Name
|ErraiSystemLogHandler|erraiSystemLogHandlerLevel
|ErraiConsoleLogHandler|erraiConsoleLogHandlerLevel
|ErraiDevelopmentModeLogHandler|erraiDevelopmentModeLogHandlerLevel
|ErraiFirebugLogHandler|erraiFirebugLogHandlerLevel
|===============

Since these are native Javascript variables, they can easily be set in a script tag on your host page:


[source, xml]
----
<script type="text/javascript">
  erraiSystemLoghandlerLevel = "INFO";
</script>
----

The possible log levels correspond to those in [code]+java.util.logging.Level+.

.Logging Levels
[IMPORTANT]
====
If you are increasing the logging level of an Errai log handler, you will also need to increase the `gwt.logging.logLevel` (set in your `*.gwt.xml`). Handlers will not receive log records that are lower than the GWT log level, which is set to **INFO** in `ErraiCommon.gwt.xml`.
==== 

[[sid-74908675_Logging-FormatString]]

==== Format String

The Errai log handlers use [code]+ErraiSimpleFormatter+ to format log output. The format string is similar to that used in by [code]+java.util.SimpleFormatter+ (for precise differences please see the javadocs for [code]+ErraiSimpleFormatter+ and [code]+StringFormat+).

As with handler settings, these can be configured in Java or Javascript. To do so in Java, use [code]+ErraiSimpleFormmater.setSimpleFormatString(String)+. In Javascript, just set the variable [code]+erraiSimpleFormatString+ to the desired value.

[[sid-74908675_Logging-ServerSideSetup]]

=== Server-Side Setup

On the server you are free to use any logging back-end that has slf4j bindings (or to make your own). Just make sure to add dependencies for the slf4j-api artifact and the slf4j binding you choose. _Note:_ Some application servers provide their own slf4j bindings (such as JBoss AS), in which case you should add your binding dependency as provided scope.

To learn more about how to setup slf4j for your server-side code, see link:$$http://www.slf4j.org/$$[their website].

[[sid-74908675_Logging-ExampleUsage]]

=== Example Usage

Here is sample usage of the slf4j code (which with the above setup can be run on the client or server):

.LogExample.java
====

[source, java]
----
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import javax.inject.Inject;

public class LogExample {

  public void logStuff() {
    // Get a logger for this class
    @Inject Logger logger;

    // Logging going from most to least detailed
    logger.trace("this is extremely specific!");
    logger.debug("this is still pretty specific");
    logger.info("this is an average log message");
    logger.warn("there might be something fishy here...");
    logger.error("uh oh... abandon ship!", new Exception("I am a logged exception"));
  }
}
----

====

[[sid-74908675_Logging-LoggerNames]]

=== Logger Names

By default, the above example with provide a logger with the fully qualified class name of the enclosing class. To inject a logger with an alternate name, use the [code]+NamedLogger+ annotation:

.NamedLogExample.java
====


[source, java]
----
import org.slf4j.Logger;
import javax.inject.Inject;
import org.jboss.errai.common.client.api.NamedLogger;

public class NamedLogExample {

  // Get a logger with the name "Logger!"
  @Inject @NamedLogger("Logger!") logger;
  
  // Get the root logger
  @Inject @NamedLogger rootLogger;

}
----

====

[[sid-5931334]]

[[Manual-Setup-Section]]

== Configuration

This section contains information on manually setting up Errai and describes additional configurations and settings which may be adjusted.

=== Errai Development Mode Configuration

[[sid-5931501_DeployingErraiCDI-DeploymentinDevelopmentMode]]

==== Deployment in Development Mode

In development mode we need to bootstrap the CDI environment on our own and make both Errai and CDI available through JNDI (common denominator across all runtimes). GWT by default uses Jetty, that only supports read only JNDI. The current solution for this is to use a custom launcher to control a JBoss AS 7 or Wildfly 8 instance instead of GWT's built-in Jetty.

To do this, requires the following configurations in the gwt-maven-plugin configuration:

[source, xml]
----
<plugin>
  <groupId>org.codehaus.mojo</groupId>
  <artifactId>gwt-maven-plugin</artifactId>
  <version>${gwt.version}</version>

  <configuration>
  ...
    <extraJvmArgs>-Derrai.jboss.home=$JBOSS_HOME</extraJvmArgs>
    <noServer>false</noServer>
    <server>org.jboss.errai.cdi.server.gwt.EmbeddedWildFlyLauncher</server>
  </configuration>
  <executions>
  ...
  </executions> 
</plugin>
----

What does all this mean?

* `<noServer>false</noServer>`: Tells GWT to lauch a server for us.

* `<server>org.jboss.errai.cdi.server.gwt.EmbeddedWildFlyLauncher</server>`: Tells GWT to use a custom launcher instead of it's default JettyLauncher.

* `<extraJvmArgs>-Derrai.jboss.home=$JBOSS_HOME</extraJvmArgs>`: Tells the launcher the location of the Wildfly instance to use. Note that `$JBOSS_HOME` should be replaced with a literal path (or pom property) to a Wildfly instance you have installed.

==== Additional Launcher Arguments

Here are some additional JVM arguments that can be passed to the JBossLauncher:

* `errai.dev.context`: Sets the context under which your app will be deployed (defaults to "webapp").

* `errai.jboss.args`: For supplying any command arguments for the WildFly instance being launched.

[[sid-5931501_DeployingErraiCDI-DeploymenttoanApplicationServer]]

==== Deployment to an Application Server

We provide integration with the link:$$http://jboss.org/jbossas$$[JBoss Application Server], but the requirements are basically the same for other vendors. When running a GWT client app that leverages CDI beans on a Java EE 6 application server, CDI is already part of the container and accessible through JNDI ([code]+java:/BeanManager+).

=== Server-Side Class Generation

Errai Marshalling and Errai CDI generate class files that should be packaged in your server-side war (usually in WEB-INF/classes). Errai will attempt to discover where these files should be written, but in some project configurations you may need to specify this manually. You can add this system property to your gwt-maven-plugin configuration to explicitly set the target folder to `src/main/webapp/WEB-INF/classes`:

[source]
----
-Derrai.server.classOutput=src/main/webapp/WEB-INF/classes
----


[[Offline-Mode]]

=== Errai Offline Mode Configuration

Errai provides special support for HTML5's application caching mechanism that enables applications to work offline. If you're 
not familiar with the HTML5 application cache you can find all the details link:$$https://developer.mozilla.org/en-US/docs/Web/HTML/Using_the_application_cache$$[here].

As GWT compiles separate browser-specific JavaScript permutations for your application, it is not enough to manually create a cache manifest file and simply list all generated JavaScript files. This would cause every browser to download and cache JavaScript files that it doesn't need in the first place (i.e. Safari would download and cache JavaScript files that were generated for Internet Explorer only). Errai solves this problem by using a custom linker to generate user-agent specific cache manifest files.

The following steps are necessary to activate this linker:

* Define the linker in your gwt.xml module descriptor:

[source, xml]
----
<define-linker name="offline" class="org.jboss.errai.offline.linker.DefaultCacheManifestLinker" />
<add-linker name="offline" />
----

* Add the manifest (`your_module_name`/errai.appcache) to the `html` tag in your host page:

[source, xml]
----
<html manifest="your_module_name/errai.appcache">  
----

* Add a mime-mapping to your web.xml file (you can skip this step if you deploy the errai-javaee-all.jar as part of your application):

[source, xml]
----
<mime-mapping>
  <extension>manifest</extension>
  <mime-type>text/cache-manifest</mime-type>
</mime-mapping>
----
  
* Make sure the `errai-common.jar` file is deployed as part of your application. It contains a servlet that will provide the correct user-agent specific manifest file in response to requests to your_module_name/errai.appcache

* To obtain manifests that contain other files in addition to those generated by the `DefaultCacheManifestLinker`, create a subclass that overrides `otherCachedFiles()`, and use this subclass as a linker instead:

[source, java]
----
@Shardable
@LinkerOrder(Order.POST)
public class MyCacheManifestLinker extends DefaultCacheManifestLinker {
  @Override
  protected String[] otherCachedFiles() {
    return new String[] {"/my-app/index.html","/my-app/css/application.css"};
  }
}
----

[[sid-5931354]]

=== ErraiApp.properties

ErraiApp.properties acts both as a marker file for JARs that contain Errai-enabled GWT modules, and as a place to put configuration settings for those modules in the rare case that non-default configuration is necessary.

[[sid-5931354_ErraiApp.properties-AsaMarkerFile]]

==== As a Marker File

_An_ [code]++ErraiApp.properties++ _file must appear at the META-INF directory of each classpath location that contains an Errai module._ The contents of JAR and directory classpath entries that do not contain an [code]+ErraiApp.properties+ are effectively invisible to Errai's classpath scanner. . (Placing ErraiApp.properties in the root of the classpath is still supported for compatibility reasons but may not be in future versions.)

[[sid-5931354_ErraiApp.properties-AsaConfigurationFile]]

==== As a Configuration File

ErraiApp.properties is usually left empty, but it can contain configuration settings for both the core of Errai and any of its extensions. Configuration properties defined and used by Errai components have keys that start with " [code]+errai.+ ". Third party extensions should each choose their own prefix for keys in ErraiApp.properties.

[[sid-5931354_ErraiApp.properties-ConfigurationMerging]]

===== Configuration Merging

In a non-trivial application, there will be several instances of ErraiApp.properties on the classpath (one per JAR file that contains Errai modules, beans, or portable classes).

Before using the configuration information from ErraiApp.properties, Errai reads the contents of every ErraiApp.properties on the classpath. The configuration information in all these files is merged together to form one set of key=value pairs.

If the same key appears in more than one ErraiApp.properties file, only one of the values will be associated with that key. The other values will be ignored. In future versions of Errai, this condition may be made into an error. It's best to avoid specifying the same configuration key in multiple ErraiApp.properties files.

[[sid-5931354_ErraiApp.properties-ErraiMarshallingConfiguration]]

===== Errai Marshalling Configuration

* _$$errai.marshalling.use_static_marshallers$$_ when set to [code]+false+, Errai will not use the precompiled server-side marshallers even if the generated [code]+ServerMarshallingFactoryImpl+ class is found on the classpath. This is useful when using Dev Mode in conjunction with an external server such as JBoss AS 7 or EAP 6.
* _$$errai.marshalling.force_static_marshallers$$_ when set to [code]+true+, Errai will not use dynamic marshallers. If the generated [code]+ServerMarshallingFactoryImpl+ cannot be loaded (possibly after an attempt to generate it on-the-fly), the Errai web app will fail to start.
* _$$errai.marshalling.short_names$$_ when set to true (the default value), Errai will shorten the names of generated marshaller classes (rather than using the long names which encode the fully qualified class names of the types being marshalled). This was added to avoid issues with path length limitations on certain platforms.
* _$$errai.marshalling.very_short_names$$_ when set to true, Errai will shorten the names of generated marshaller classes to a 7 character long hash. This was added to avoid issues with path length limitations on certain platforms.

Errai also supports configuring portable types in [code]+ErraiApp.properties+ as an alternative to the [code]+@Portable+ annotation. See <<sid-5931328_Marshalling-ManualMapping,the Errai Marshalling section on Manual Mapping>> for details.

[[sid-5931354_ErraiApp.properties-ErraiIoCConfiguration]]

===== Errai IoC Configuration

* _errai.ioc.QualifyingMetaDataFactory_ specifies the fully-qualified class name of the QualifyingMetadataFactory implementation to use with Errai IoC.

* _errai.ioc.enabled.alternatives_ specifies a whitespace-separated list of fully-qualified class names for _alternative beans_. See <<sid-22872133, Alternatives and Mocks>> for details.

* _errai.ioc.async_bean_manager_ a boolean property that when set to true (defaults to false) will activate asynchronous IOC to allow for link:$$http://www.gwtproject.org/doc/latest/DevGuideCodeSplitting.html$$[code splitting]. The code of types annotated with [code]+@LoadAsync+ will be downloaded the first time it is needed. [code]+@LoadAsync+ also allows to specify a fragment name using a class literal. Using GWT 2.6.0 or higher, all types with the same fragment name will be part of the same split point.

* _errai.ioc.blacklist_ specifies a whitespace-separated list of classes that should be hidden from Errai IOC and that will be excluded when generating the bean graph and wiring components. Wildcards are supported to exclude all types underneath a package e.g. org.jboss.myapp.exclude.* (all types under the exclude package will be hidden from ERRAI IOC).

* _errai.ioc.whitelist_ when this property is present all types in your application are hidden from Errai IOC by default. It specifies a whitespace-separated list of classes that should be visible to IOC and that will be included when generating the bean graph and wiring components. Wildcards are supported to include all types underneath a package e.g. org.jboss.myapp.include.* (all types under the include package will be visible to ERRAI IOC).

===== Errai JPA Configuration
* _errai.jpa.whitelist_ specifies a whitespace-separated list of fully-qualified class names that should be included in Errai JPA's scanning and in the Entity Manager. Any entities that are not part of the whitelist are ignored by Errai JPA. This property supports wildcards to exclude everything within a package (e.g. org.jboss.myapp.exclude.*). 

* _errai.jpa.blacklist_ specifies a whitespace-separated list of fully-qualified class names that should be excluded from Errai JPA's scanning. This can be used for client-side entities that do not use Errai JPA. This property supports wildcards to exclude everything within a package (e.g. org.jboss.myapp.exclude.*). The blacklist has priority over the whitelist. This means that if a class is part of both the blacklist and the whitelist, the class will be blacklisted, i.e. ignored by Errai JPA.

[[sid-5931338]]

=== Messaging (Errai Bus) Configuration

==== Compile-time Dependencies

The following compile-time dependency is required for Errai Messaging:

[source, xml]
----
  <dependency>
    <groupId>org.jboss.errai</groupId>
    <artifactId>errai-bus</artifactId>
    <version>${errai.version}</version>
  </dependency>
----

Or if you are not using Maven, have [code]+errai-bus-${errai.version}.jar+ on the classpath.

If you are also using Errai IOC or Errai CDI and wish to use inject Errai Messaging dependencies, you will also want this dependency:

[source, xml]
----
  <dependency>
    <groupId>org.jboss.errai</groupId>
    <artifactId>errai-ioc-bus-support</artifactId>
    <version>${errai.version}</version>
  </dependency>
----

Or if you are not using Maven, have [code]+errai-ioc-bus-support-${errai.version}.jar+ on the classpath.

[[sid-5931338_Messaging%28ErraiBus%29Configuration-Disablingremotecommunication]]

==== Disabling remote communication

In some cases it might be desirable to prevent the client bus from communicating with the server. One use case for this is when all communication with the server is handled using JAX-RS and the constant long polling requests for message exchange are not needed.

To turn off remote communication in the client bus the following JavaScript variable can be set in the HTML host page:


[source, xml]
----
<script type="text/javascript">
  erraiBusRemoteCommunicationEnabled = false;
</script>
----

[[sid-5931338_Messaging%28ErraiBus%29Configuration-Configuringanalternativeremoteremotebusendpoint]]

==== Configuring an alternative remote remote bus endpoint

By default the remote bus is expected at the GWT web application's context path. In case the remote bus is part of a different web application or deployed on a different server, the following configuration can be used in the HTML host page to configure the remote bus endpoint used on the client.

[source, xml]
----
<script type="text/javascript">
  erraiBusApplicationRoot = "/MyRemoteMessageBusEnpoint";
</script>
----

[[sid-5931338_Messaging%28ErraiBus%29Configuration-ErraiService.properties]]

==== ErraiService.properties

The ErraiService.properties file contains basic configuration for the bus itself. Unlike ErraiApp.properties, there should be at most one ErraiService.properties file on the classpath of a deployed application. If you do not need to set any properties to their non-default values, this file can be omitted from the deployment entirely.

[[sid-5931338_Messaging%28ErraiBus%29Configuration-MessageDispatching]]

===== Message Dispatching

Dispatchers encapsulate the strategy for taking messages that need to be delivered somewhere and seeing that they are delivered to where they need to go. There are two primary implementations that are provided with Errai, depending on your needs.

[[sid-5931338_Messaging%28ErraiBus%29Configuration-SimpleDispatcher]]

SimpleDispatcher:

SimpleDispatcher is basic implementation that provides no asychronous delivery mechanism. Rather, when you configure the Errai to use this implementation, messages are delivered to their endpoints synchronously. The incoming HTTP thread will be held open until the messages are delivered.

While this sounds like it has almost no advantages, especially in terms of scalablity. Using the SimpleDispatcher can be far preferable when you're developing your application, as any errors and stack traces will be far more easily traced and some cloud services may not permit the use of threads in any case.

[[sid-5931338_Messaging%28ErraiBus%29Configuration-AsyncDispatcher]]

AsyncDispatcher:

The AsyncDispatcher provides full asynchronous delivery of messages. When this dispatcher is used, HTTP threads will have control immediately returned upon dispatch of the message. This dispatcher provides far more efficient use of resources in high-load applications, and will significantly decrease memory and thread usage overall.

* _errai.dispatcher.implementation_ specifies the dispatcher implementation to be used by the bus. There are two implementations which come with Errai out of the box: the [code]+SimpleDispatcher+ and the [code]+AsyncDispatcher+. See ERRAI:Dispatcher Implementations for more information about the differences between the two.


[[sid-5931338_Messaging%28ErraiBus%29Configuration-Threading]]

===== Threading

* _$$errai.async_thread_pool_size$$_ specifies the total number of worker threads in the worker pool for handling and delivering messages. Adjusting this value does not have any effect if you are using the SimpleDispatcher.


* _$$errai.async.worker_timeout$$_ specifies the total amount of time (in seconds) that a service is given to finish processing an incoming message before the pool interrupts the thread and returns an error. Adjusting this value has no effect if you are using the SimpleDispatcher.


[[sid-5931338_Messaging%28ErraiBus%29Configuration-Buffering]]

===== Buffering

* _$$errai.bus.buffer_size$$_ The total size of the transmission buffer, in megabytes. If this attribute is specified along with [code]+errai.bus.buffer_segment_count+, then the segment count is inferred by the calculation [code]+buffer_segment_count / buffer_size+. If [code]+errai.bus.buffer_segment_count+ is also defined, it will be ignored in the presence of this property. Default value: 32.


* _$$errai.bus.buffer_segment_size$$_ The transmission buffer segment size in bytes. This is the minimum amount of memory each message will consume while stored within the buffer. Defualt value: 8.


* _$$errai.bus.buffer_segment_count$$_ The number of segments in absolute terms. If this attribute is specified in the absence of [code]+errai.bus.buffer_size+, the buffer size is inferred by the calculation [code]+buffer_segment_size / buffer_segment_count+.


* _$$errai.bus.buffer_allocation_mode$$_ Buffer allocation mode. Allowed values are [code]+direct+ and [code]+heap+. Direct allocation puts buffer memory outside of the JVM heap, while heap allocation uses buffer memory inside the Java heap. For most situations, heap allocation is preferable. However, if the application is data intensive and requires a substantially large buffer, it is preferable to use a direct buffer. From a throughput perspective, current JVM implementations pay about a 20% performance penalty for direct-allocated memory access. However, your application may show better scaling characteristics with direct buffers. Benchmarking under real load conditions is the only way to know the optimal setting for your use case and expected load. Default value: [code]+direct+.

[[sid-5931338_Messaging%28ErraiBus%29Configuration-Clustering]]

===== Clustering

* _$$errai.bus.enable_clustering$$_ A boolean indicating whether or not Errai's server side bus should attempt to orchestrate with its peers. The orchestration mechanism is dependent on the configured clustering provider (e.g. UDP based multicast discovery in case of the default JGroups provider). The default value is [code]+false+.


* _$$errai.bus.clustering_provider$$_ The fully qualified class name of the clustering provider implementation. A class that implements [code]+org.jboss.errai.bus.server.cluster.ClusteringProvider+. Currently the only build-in provider is the [code]+org.jboss.errai.bus.server.cluster.jgroups.JGroupsClusteringProvider+.

===== CSRF Protection

* _$$errai.bus.enable_csrf_token$$_ A boolean indicating whether or not a Cross Site Request Forgery (CSRF) protection is enabled. When enabled, the Errai Bus servlet generates a CSRF token for every HTTP session; all bus requests for a session must include the token in an HTTP header. The client-bus can negotiate with the server for a token when connecting, or else the `org.jboss.errai.bus.server.servlet.CSRFTokenFilter` can be configured to inject it into the host page as a JavaScript variable. The default value is [code]+false+.

[[sid-5931338_Messaging%28ErraiBus%29Configuration-StartupConfiguration]]

===== Startup Configuration

* _$$errai.auto_discover_services$$_ A boolean indicating whether or not the Errai bootstrapper should automatically scan for services. _This property must be set to true if and only if Errai CDI is not on the classpath_. The default value is [code]+false+.

* _$$errai.auto_load_extensions$$_ A boolean indicating whether or not the Errai bootstrapper should automatically scan for extensions. The default value is [code]+true+.

[[sid-5931338_Messaging%28ErraiBus%29Configuration-ExampleConfiguration]]

===== Example Configuration

[source, ini]
----
##
## Request dispatcher implementation (default is SimpleDispatcher)
##
#errai.dispatcher_implementation=org.jboss.errai.bus.server.SimpleDispatcher
errai.dispatcher_implementation=org.jboss.errai.bus.server.AsyncDispatcher

##
## Worker pool size. This is the number of threads the asynchronous worker pool should
## provide for processing incoming messages. This option is only valid when using
## the AsyncDispatcher implementation.
##
errai.async.thread_pool_size=5

##
## Worker timeout (in seconds). This defines the time that a single asychronous process
## may run, before the worker pool terminates it and reclaims the thread. This option
## is only valid when using the AsyncDispatcher implementation.
##
errai.async.worker.timeout=5
----

[[sid-5931338_Messaging%28ErraiBus%29Configuration-ServletConfiguration]]

==== Servlet Configuration

Errai has several different implementations for HTTP traffic to and from the bus. We provide a universally-compatible blocking implementation that provides fully synchronous communication to/from the server-side bus. Where this introduces scalability problems, we have implemented many webserver-specific implementations that take advantage of the various proprietary APIs to provide true asynchrony.

These included implementations are packaged at: [code]+org.jboss.errai.bus.server.servlet+.

[IMPORTANT]
.One is Enough!
====
You should use just one of the options below. Configuring multiple ErraiServlet implementations in the same application will lead to unpredictable behaviour!

Remember that all Errai demos and archetypes are preconfigured with DefaultBlockingServlet as a servlet. You will need to remove this default setup if you choose to use a different ErraiServlet implementation in your app.
====

[NOTE]
.Rolling your own security? Beware!
====
All of the following examples use a wildcard mapping for [code]+*.erraiBus+ with no path prefix. This allows Errai Bus to communicate from any point in your application's URI hierarchy, which allows bus communication to work properly no matter where you choose to put your GWT host page.

For example, all of the following are equivalent from Errai's point of view:

* /in.erraiBus
* /foo/bar/in.erraiBus
* /long/path/to/get/to.erraiBus

If you rely on your own security rules or a custom security filter to control access to Errai Bus (rather than the security framework within Errai Bus,) ensure you use the same mapping pattern for that [code]+filter-mapping+ or [code]+security-constraint+ as you do for the Errai Servlet itself.
====

[[sid-5931338_Messaging%28ErraiBus%29Configuration-DefaultBlockingServlet]]

===== DefaultBlockingServlet

This ErraiServlet implementation should work in virtually any servlet container that supports Java Servlets 2.0 or higher. It provides purely synchronous request handling. The one scenario where this servlet will not work is in servers that put restrictions on putting threads into sleep states.

The default DefaultBlockingServlet which provides the HTTP-protocol gateway between the server bus and the client buses.

As its name suggests, DefaultBlockingServlet is normally configured as an HTTP Servlet in the [code]+web.xml+ file:

[source, xml]
----
<servlet>
  <servlet-name>ErraiServlet</servlet-name>
  <servlet-class>org.jboss.errai.bus.server.servlet.DefaultBlockingServlet</servlet-class>
  <load-on-startup>1</load-on-startup>
</servlet>
                                                                                                     
<servlet-mapping>
  <servlet-name>ErraiServlet</servlet-name>
  <url-pattern>*.erraiBus</url-pattern>
</servlet-mapping>
----

[[sid-5931338_Messaging%28ErraiBus%29Configuration-DefaultBlockingServletconfiguredasFilter]]

===== DefaultBlockingServlet configured as Filter

Alternatively, the DefaultBlockingServlet can be deployed as a Servlet Filter. This may be necessary in cases where an existing filter is configured in the web application, and that filter interferes with the Errai Bus requests. In this case, configuring DefaultBlockingServlet to handle [code]+*.erraiBus+ requests ahead of other filters in web.xml will solve the problem:

[source, xml]
----
<filter>
  <filter-name>ErraiServlet</filter-name>
  <filter-class>org.jboss.errai.bus.server.servlet.DefaultBlockingServlet</filter-class>
</filter>

<filter-mapping>
  <filter-name>ErraiServlet</filter-name>
  <url-pattern>*.erraiBus</url-pattern>
</filter-mapping>
----

[[sid-5931338_Messaging%28ErraiBus%29Configuration-JettyContinuationsServlet]]

===== JettyContinuationsServlet

The Jetty implementation leverages Jetty's continuations support, which allows for threadless pausing of port connections. This servlet implementation should work without any special configuration of Jetty.

[source, xml]
----
<servlet>
  <servlet-name>ErraiServlet</servlet-name>
  <servlet-class>org.jboss.errai.bus.server.servlet.JettyContinuationsServlet</servlet-class>
  <load-on-startup>1</load-on-startup>
</servlet>
                                                                                                     
<servlet-mapping>
  <servlet-name>ErraiServlet</servlet-name>
  <url-pattern>*.erraiBus</url-pattern>
</servlet-mapping>
----

[[sid-5931338_Messaging%28ErraiBus%29Configuration-StandardAsyncServlet]]

===== StandardAsyncServlet

This implementation leverages asynchronous support in Servlet 3.0 to allow for threadless pausing of port connections. Note that [code]+<async-supported>true</async-supported>+ has to be added to the servlet definition in [code]+web.xml+.

[source, xml]
----
<servlet>
  <servlet-name>ErraiServlet</servlet-name>
  <servlet-class>org.jboss.errai.bus.server.servlet.StandardAsyncServlet</servlet-class>
  <load-on-startup>1</load-on-startup>
  <async-supported>true</async-supported>
</servlet>
                                                                                                     
<servlet-mapping>
  <servlet-name>ErraiServlet</servlet-name>
  <url-pattern>*.erraiBus</url-pattern>
</servlet-mapping>
----

===== Automatic Service Discovery

By default Errai relies on a provided CDI container to do server-side service discovery. But if you intend to use Errai Messaging without a CDI container, Errai can scan for services on its own if the following initialization parameter is added to the servlet configuration:

[source, xml]
----
    <init-param>
      <param-name>auto-discover-services</param-name>
      <param-value>true</param-value>
    </init-param>
----

[WARNING]
====
This configuration will cause issues (such as duplicate services) if it is set to true _and_ a server-side CDI container is available.
====

[[sid-19398997_ErraiJAX-RS-GettingStarted]]

=== Errai JAX-RS Setup

[[sid-19398997_ErraiJAX-RS-Dependencies]]

==== Compile-time dependency

To use Errai JAX-RS, you must include it on the compile-time classpath. If you are using Maven for your build, add this dependency:

[source, xml]
----
<dependency>
  <groupId>org.jboss.errai</groupId>
  <artifactId>errai-jaxrs-client</artifactId>
  <version>${errai.version}</version>
  <scope>provided</scope>
</dependency>
----

Or if you are not using Maven for dependency management, add [code]+errai-jaxrs-client-${errai.version}.jar+ to your classpath.

If you intend to use Errai's JSON format on the wire you will need to add Errai's JAX-RS JSON provider to your classpath and make sure it gets deployed to the server.


[source, xml]
----
<dependency>
  <groupId>org.jboss.errai</groupId>
  <artifactId>errai-jaxrs-provider</artifactId>
  <version>${errai.version}</version>
</dependency>
----

Or manually add [code]+errai-jaxrs-provider-${errai.version}.jar+ in case you're not using Maven. If your REST service returns Jackson generated JSON you do not need the errai-jaxrs-provider (see <<sid-19398997_ErraiJAX-RS-Configuration,Configuration>>).

[[sid-19398997_ErraiJAX-RS-GWTModule]]

==== GWT Module

Once you have Errai JAX-RS on your classpath, ensure your application inherits the GWT module as well. Add this line to your application's [code]+*.gwt.xml+ file:

[source, xml]
----
<inherits name="org.jboss.errai.enterprise.Jaxrs"/>
----

[[sid-19398997_ErraiJAX-RS-Configuration]]

==== Configuration

[[sid-19398997_ErraiJAX-RS-ConfiguringthedefaultrootpathofJAXRSendpoints]]

===== Configuring the default root path of JAX-RS endpoints

All paths specified using the [code]+@Path+ annotation on JAX-RS interfaces are by definition relative paths. Therefore, by default, it is assumed that the JAX-RS endpoints can be found at the specified paths relative to the GWT client application's context path.

To configure a relative or absolute root path, the following JavaScript variable can be set in either:

* The host HTML page;
+
[source, xml]
----
<script type="text/javascript">
  erraiJaxRsApplicationRoot = "/MyJaxRsEndpointPath";
</script>
----

* By using a JSNI method;
+
[source, java]
----
private native void setMyJaxRsAppRoot(String path) /*-{
  $wnd.erraiJaxRsApplicationRoot = path;
}-*/;
----

* Or by simply invoking.
+
[source, java]
----
RestClient.setApplicationRoot("/MyJaxRsEndpointPath");
----

The root path will be prepended to all paths specified on the JAX-RS interfaces. It serves as the base URL for all requests sent from the client.

[[sid-19398997_ErraiJAX-RS-EnablingJacksonmarshalling]]

===== Enabling Jackson marshalling

The following options are available for activating Jackson marshalling on the client. Note that this is a client-side configuration, the JAX-RS endpoint is assumed to already return a Jackson representation (Jackson is supported by all JAX-RS implementations). The [code]+errai-jaxrs-provider-${errai.version}.jar+ does not have to be deployed on the server in this case!

To use the Jackson marshaller add on of these configurations:

* Set a Javascript variable in the GWT Host Page;
+
[source, xml]
----
<script type="text/javascript">
  erraiJaxRsJacksonMarshallingActive = true;
</script>
----

* Use a JSNI method;
+
[source, java]
----
private native void setJacksonMarshallingActive(boolean active) /*-{
  $wnd.erraiJaxRsJacksonMarshallingActive = active;
}-*/;
----

* Or invoke a method in RestClient.
+
[source, java]
----
RestClient.setJacksonMarshallingActive(true);
----

=== Errai JPA

[[sid-54493688_ErraiJPA-Compiletimedependency]]

==== Compile-time Dependencies

To use Errai JPA, you must include it on the compile-time classpath. If you are using Maven for your build, add this dependency:


[source, xml]
----
<dependency>
  <groupId>org.jboss.errai</groupId>
  <artifactId>errai-jpa-client</artifactId>
  <version>${errai.version}</version>
</dependency>
----

If you are not using Maven for dependency management, add [code]+errai-jpa-client-${errai.version}.jar+, Hibernate 4.1.1, and Google Guava for GWT 12.0 to your compile-time classpath.

[[sid-54493688_ErraiJPA-GWTModuleDescriptor]]

==== GWT Module Descriptor

Once you have Errai JPA on your classpath, ensure your application inherits the GWT module as well. Add this line to your application's [code]+*.gwt.xml+ file:

[source, xml]
----
 <inherits name="org.jboss.errai.jpa.JPA"/>
----

[[sid-54493688_ErraiJPA-METAINF%2Fpersistence.xml]]

=== Errai JPA Data Sync

[[sid-71467090_ErraiJPADataSync-Dependencies]]

==== Compile-time Dependencies

First, ensure your [code]+pom.xml+ includes a dependency on the Data Sync module. This module must be packaged in your application's WAR file, so include it with the default scope (compile):

[source, xml]
----
<dependency>
  <groupId>org.jboss.errai</groupId>
  <artifactId>errai-jpa-datasync</artifactId>
  <version>${errai.version}</version>
</dependency>
----

==== GWT Module Descriptor

Then, ensure your project's [code]+*.gwt.xml+ module descriptor includes a dependency on the Data Sync GWT module:

[source, xml]
----
<inherits name="org.jboss.errai.jpa.sync.DataSync"/>
----

=== Errai Data Binding

[[sid-51282340_DataBinding-Compiletimedependency]]

==== Compile-time Dependencies

To use Errai's data binding module, you must include it on the compile-time classpath. If you are using Maven for your build, add this dependency:


[source, xml]
----
<dependency>
  <groupId>org.jboss.errai</groupId>
  <artifactId>errai-data-binding</artifactId>
  <version>${errai.version}</version>
</dependency>
----

If you are not using Maven for dependency management, add [code]+errai-data-binding-${errai.version}.jar+ to your classpath.

[[sid-51282340_DataBinding-GWTmoduledescriptor]]

==== GWT module descriptor

You must also inherit the Errai data binding module by adding the following line to your GWT module descriptor (gwt.xml).

.App.gwt.xml
====

[source, xml]
----
<inherits name="org.jboss.errai.databinding.DataBinding" />
----

====

==== Bootstrapping Data Binding without Errai IOC

In case you don't want to or cannot use Errai's IOC container you will have to manually bootstrap Errai Data Binding and inherit the Errai Common GWT module:

[source, java]
----
BindableProxyLoader proxyLoader = GWT.create(BindableProxyLoader.class);
proxyLoader.loadBindableProxies();
----

[source, xml]
----
<inherits name="org.jboss.errai.common.ErraiCommon"/>
----

=== Errai UI

[[sid-51806600_ErraiUI-pom.xml]]

==== Compile-time dependency

The easiest way to get Errai UI on your classpath is to depend on the special [code]+errai-javaee-all+ artifact, which brings in most Errai modules:


[source, xml]
----
<dependency>
  <groupId>org.jboss.errai</groupId>
  <artifactId>errai-javaee-all</artifactId>
  <version>${errai.version}</version>
</dependency>
----

Or if you prefer to manage your project's dependency in a finer-grained way, you can depend on [code]+errai-ui+ directly:


[source, xml]
----
<dependency>
  <groupId>org.jboss.errai</groupId>
  <artifactId>errai-ui</artifactId>
  <version>${errai.version}</version>
</dependency>
----

[[sid-51806600_ErraiUI-App.gwt.xml]]

==== GWT Module Descriptor

Once you have Errai UI on your classpath, ensure your application inherits the GWT module as well. Add this line to your application's [code]+*.gwt.xml+ file:

[source, xml]
----
<inherits name="org.jboss.errai.ui.UI" />
----
=== Errai UI Navigation

[[sid-54493676_ErraiUINavigation-Compiletimedependency]]

==== Compile-time Dependencies

To use Errai UI Navigation, you must include it on the compile-time classpath. If you are using Maven for your build, add these dependencies:

[source, xml]
----
<dependency>
  <groupId>org.jboss.errai</groupId>
  <artifactId>errai-navigation</artifactId>
  <version>${errai.version}</version>
  <scope>provided</scope>
</dependency>
<dependency>
  <groupId>org.jboss.errai</groupId>
  <artifactId>errai-cdi-client</artifactId>
  <version>${errai.version}</version>
  <scope>provided</scope>
</dependency>
----

If you are not using Maven for dependency management, add [code]+errai-navigation-${errai.version}.jar+ to the compile-time classpath of a project that's already set up for Errai UI templating.

[[sid-54493676_ErraiUINavigation-GWTModuleDescriptor]]

==== GWT Module Descriptor

Once you have Errai UI Navigation on your classpath, ensure your application inherits the GWT module as well. Add this line to your application's [code]+*.gwt.xml+ file:

[source, xml]
----
<inherits name="org.jboss.errai.ui.nav.Navigation"/>
----

=== Errai Security

==== Compile-time dependency

Errai Security requires to modules to be included in a project:

[source, xml]
----
<dependency>
  <groupId>org.jboss.errai</groupId>
  <artifactId>errai-security-server</artifactId>
  <version>${errai.version}</version>
</dependency>
<dependency>
  <groupId>org.jboss.errai</groupId>
  <artifactId>errai-security-client</artifactId>
  <scope>provided</scope>
  <version>${errai.version}</version>
</dependency>
----

If you are using picketlink for authentication, you should also include this:
[source, xml]
----
<dependency>
  <groupId>org.jboss.errai</groupId>
  <artifactId>errai-security-picketlink</artifactId>
  <version>${errai.version}</version>
</dependency>
----

==== GWT Module Descriptor

Once you have Errai Security Client on your classpath, ensure your application inherits the GWT module as well. Add this line to your application's [code]+*.gwt.xml+ file:

[source, xml]
----
<inherits name="org.jboss.errai.security.Security" />
----

==== CDI and Interceptor Bindings

Errai security requires a CDI container to intercept calls to remote services. In particular, the following interceptor must be added to your application's `beans.xml`:

[source,xml]
----
<interceptors>
  <class>org.jboss.errai.security.server.ServerSecurityRoleInterceptor</class>
</interceptors>
----

[[sid-32473113]]

== Troubleshooting & FAQ

This section explains the cause of and solution to some common problems that people encounter when building applications with Errai.

Of course, when lots of people trip over the same problem, it's probably because there is a deficiency in the framework! A FAQ list like this is just a band-aid solution. If you have suggestions for permanent fixes to these problems, please get in touch with us: file an issue in our issue tracker, chat with us on IRC, or post a suggestion on our forum.

But for now, on to the FAQ:

[[sid-32473113_Troubleshooting%26FAQ-WhydoesitseemthatErraican%27tseemyclassatcompiletime%3F]]

=== Why does it seem that Errai can't see my class at compile time?

Possible symptoms:

* uncaught exception: java.lang.RuntimeException: No proxy provider found for type: _my.fully.qualified.ServiceName_

_Answer:_ Make sure the <<sid-5931354, ErraiApp.properties>> file is actually making it into your runtime classpath.

One common cause of this problem is a <resources> section in pom.xml that includes src/main/java (to expose .java sources to the GWT compiler) that does not also include src/main/resources as a resource path. You must include both explicitly:

[source, xml]
----
<resources>
  <resource>
    <directory>src/main/java</directory>
  </resource>
  <resource>
    <directory>src/main/resources</directory>
  </resource>
</resources>
----

[[sid-32473113_Troubleshooting%26FAQ-WhyamIgetting%22java.lang.ClassFormatError%3AIllegalmethodname%22%3Cinit%3E%24%22inclassorg%2Fxyz%2Fpackage%2FMyClass%22%3F]]

=== Why am I getting "java.lang.ClassFormatError: Illegal method name "<init>$" in class org/xyz/package/MyClass"?

_Answer:_ This error message means that your project has a (direct or indirect) subclass of JavaScriptObject that lacks a protected no-args constructor. All subtypes of JavaScriptObject (also known as _overlay types_) must declare a protected no-args constructor, but the error message could be much clearer. There is an issue filed in the GWT project's bug tracker for improving the error message: link:$$http://code.google.com/p/google-web-toolkit/issues/detail?id=3383$$[GWT issue 3383].

[[sid-32473113_Troubleshooting%26FAQ-I%27mgetting%22java.lang.RuntimeException%3ATherearenoproxyprovidersregisteredyet.%22inmy@PostConstructmethod%21]]

=== I'm getting "java.lang.RuntimeException: There are no proxy providers registered yet." in my @PostConstruct method!

_Answer:_ You can't invoke RPC methods via [code]+Caller<?>+ or by other means until after the Errai Bus has finished its initial handshake. Try changing your [code]+@PostConstruct+ annotation to [code]+@AfterInitialization+. This will cause your method to be invoked later after the bus handshake has completed.

If this doesn't help, it is also possible that the proxies were never generated in the first place. Check in [code]+.errai/RpcProxyLoaderImpl.java+ to see if proxy code exists for the [code]+@Remote+ and/or [code]+@Path+ interface in question. If not, your [code]+@Remote+ interfaces were not present on the GWT compiler's classpath when your application module was compiled. Double-check your GWT compilation classpath: all [code]+@Remote+ interfaces must be visible to (in or inherited by) the GWT module that contains the [code]+Caller<?>+ types. Pay special attention that your [code]+@Remote+ and [code]+@Path+ interfaces are not in a package excluded from the GWT module (by default, every subpackage other than [code]+client+ and [code]+shared+ is invisible to the GWT compiler).

=== Why do I get a "404 - Not Found" page if I try to navigate to my web page by typing in the URL or refreshing the page?

_Answer:_ There are two reasons that could cause this behaviour:
 
You may not have declared a default page for Errai pushState to navigate to in the case of a page not found error. For example, to navigate to the GWT host page by default, add the following lines to your web.xml file. See <<sid-54493676_ErraiUINavigation-HowitWorks, Errai UI Navigation - How it Works -> PushState Functionality>>.

If that doesn't work, check to see if you have explicitly declared the application web context in your GWT host page. See <<sid-54493676, Errai UI Navigation - How it Works -> PushState Functionality>>.

[[sid-21758202]]

== Upgrade Guide

This chapter contains important information for migrating to newer versions of Errai. If you experience any problems, don't hesitate to get in touch with us. See <<sid-5833089, Reporting problems>>.

[[sid-21758204]]

=== Upgrading from 1.* to 2.0

The first issues that will arise after replacing the jars or after changing the version numbers in the [code]+pom.xml+ are unresolved package imports. This is due to refactorings that became necessary when the project grew. Most of these import problems can be resolved automatically by modern IDEs (Organize Imports). So, this should replace [code]+org.jboss.errai.bus.client.protocols.\*+ with [code]+org.jboss.errai.common.client.protocols.*+ for example.

The following is a list of manual steps that have to be carried out when upgrading:

* @ExposedEntity became @Portable ([code]+org.jboss.errai.common.client.api.annotations.Portable+). See <<sid-5931328, Marshalling>> for details.


* The @Conversational annotation must now target the event objects themselves, not the observer methods of the events. So an _event type_ is either conversational or not; you no longer specify that listeners receive arbitrary events in a conversational context. See the <<sid-21758054_Events-Conversationalevents,Conversational Events>> section of the CDI chapter for details.


* Errai CDI projects must now use the [code]+SimpleDispatcher+ instead of the [code]+AsynDispatcher+. This has to be configured in <<sid-5931338, Messaging (Errai Bus) Configuration>>.


* The bootstrap listener (configured in [code]+WEB-INF/web.xml+) for Errai CDI has changed ([code]+org.jboss.errai.container.DevModeCDIBootstrap+ is now [code]+org.jboss.errai.container.CDIServletStateListener+).


* gwt 2.3.0 or newer must be used and replace older versions.


* mvel2 2.1.Beta8 or newer must be used and replace older versions.


* weld 1.1.5.Final or newer must be used and replace older versions.


* slf4j 1.6.1 or newer must be used and replace older versions.


* This step can be skipped if Maven is used to build the project. If the project is NOT built using Maven, the following jar files have to be added manually to project's build/class path: errai-common-2.x.jar, errai-marshalling-2.x.jar, errai-codegen-2.x.jar, netty-4.0.0.Alpha1.errai.r1.jar.


* If the project was built using an early version of an Errai archetype the configuration of the maven-gwt-plugin has to be modified to contain the [code]+<hostedWebapp>path-to-your-standard-webapp-folder</hostedWebapp>+. This is usually either [code]+war+ or [code]+src/main/webapp+.


[[sid-24838246]]

=== Upgrading from 2.0.Beta to 2.0.*.Final

The following is a list of manual steps that have to be carried out when upgrading from a 2.0.Beta version to 2.0.CR1 or 2.0.Final:

* Starting with 2.0.CR1 the default for automatic service discovery has been changed in favour of CDI based applications. That means it has to be explicitly turned on for plain bus applications (Errai applications that do not use Errai-CDI). Not doing so will result in [code]+NoSubscribersToDeliverTo+ exceptions. The snippet below shows how to activate automatic service discovery:

.web.xml
====

[source, xml]
----
<servlet>
  <servlet-name>ErraiServlet</servlet-name>
  <servlet-class>org.jboss.errai.bus.server.servlet.DefaultBlockingServlet</servlet-class>
  <init-param>
    <param-name>auto-discover-services</param-name>
    <param-value>true</param-value>
  </init-param>
  <load-on-startup>1</load-on-startup>
</servlet>
----
====

* The [code]+jboss7-support+ module was deleted and is no longer needed as a dependency.

[[sid-59146804]]

=== Upgrading from Errai 2.2.x to 2.4 or 3.0

There are some breaking API changes in the update from Errai 2.2.x to Errai 2.4.x and 3.0.x.

Here are the steps you'll need to take to get your project compiling after you update:

* Starting with Errai 2.3.0, GWT 2.5.0 or higher is required.


* Use your IDE to organize imports at the top level. In eclipse, you'd click in the Project Explorer, press Ctrl-A (select all) and then Ctrl-O (Organize Imports). Other IDEs have similar features.


* The [code]+ErrorCallback+ interface has been made more general so the same type can be shared between Errai modules. This allows you reuse your own generic error handler class for, eg, Errai JAX-RS and ErraiBus callbacks. If you want to use a generic error handler throughout your app, change your [code]+ErrorCallback+ implementations to [code]+ErrorCallback<?>+ and change the first argument type of your error() method to Object. Otherwise, if you have use-case-specific error callbacks, implement the interfaces [code]+RestErrorCallback+ or [code]+BusErrorCallback+ as appropriate.


* [code]+IOCBeanManager+ was replaced by two new types [code]+SyncBeanManager+ and [code]+AsyncBeanManager+ that need to be used instead. See <<sid-21627016, Client-side Bean Manager>> for details.


Note: Errai 3 is still changing rapidly, so this section is a work in progress. Please add any additional steps you had to take in upgrading your own codebase.

[[sid-77234301]]

=== Upgrading to Errai 3.0

Here are the steps you'll need to take to get your project running after you update:

* Errai's custom jetty launcher (org.jboss.errai.cdi.erver.gwt.JettyLauncher) is no longer needed and has been deleted. Simply remove the corresponding -server parameter from your GWT launch configuration if you still use it.

* The whole artifact errai-cdi-jetty has been deleted and is no longer required. Delete the JAR file from your project or remove the corresponding dependency in your pom.xml.

=== Upgrading to Errai 3.1 from 3.0

Here are the steps you'll need to take to get your project running after you update:

* If you are using Errai to compile LESS/CSS files you will need to declare a `StyleDescriptor` listing the resources to compile in the desired order. This change was made to provide a deterministic and configurable order of styles in the generated CSS.

* Errai 3.1+ targets CDI 1.1 containers by default (i.e. WildFly 8+). If you wish to deploy to a CDI 1.0 container (i.e AS7, EAP6) you will have to downgrade the errai-weld-integration.jar to 3.0.4.Final. You can still use all of Errai's latest features and use the 3.1+ versions of all other Errai jars.

=== Upgrading to Errai 3.2 from 3.1

Starting from Errai 3.2.0.Final, Errai Security only supports Keycloak 1.2.0.Final and higher. Errai Security is no longer compatible with earlier versions of Keycloak. 

=== Upgrading to Errai 4.0 from 3.2

Here are the steps you'll need to take to get your project running after you update:

* Rename dependencies on `errai-weld-integration` to `errai-cdi-server`.

* Upgrade to GWT 2.8, the supported GWT version for Errai 4.0.

* Fix ambigious dependencies on pseudo-dependent beans. For example in the past the following code would correctly compile and execute in Errai:
+
[source,java]
---------------
public class SuperType {
}
---------------
+
[source,java]
---------------
public class SubType extends SuperType {
}
---------------
+
[source,java]
---------------
public class Usage {
  @Inject
  private SuperType bean;
}
---------------
+
In Errai 4.0 this is ambiguous because both the `SubType` and `SuperType` classes satisfy this injection site, as is the case in CDI. Some ways to fix this problem:

** Make the base class abstract or @Alternative if you are not also using it.
** Use different qualifiers on each type (or at least make only one type @Default).

* Make any `@ApplicationScoped` or `@Singleton` beans proxiable. To be proxiable a bean class must:
** Be non-final.
** Have a public, no-argument constructor.

* Remove package-private methods from `@ApplicationScoped` and `@Singleton` beans. Because these beans are proxied, the container must be able to override any non-private methods. Private methods are fine as they do not require proxying.

* Explicitly enable any `@Alternative` beans used by your application in ErraiApp.properties.

* Add explicit scopes to beans that are only looked up through the bean manager. If a type is not injected anywhere and does not have an explicit scope, it will not be available for lookup by the bean manager at runtime.

* Replace usages of `@TestMock` with `@Alternative`. Whenever this is done, you will also have to explicitly activate the bean in the ErraiApp.properties for your test.

* Remove usages of the `@New` qualifier. This has been removed from Errai and deprecated in CDI. Instead, consider making your bean `@Dependent` scoped.

* Remove injection sites of `@LoadAsync` inside types that are no async. In Errai 4.0, it is only possible to inject async types into eachother.

* Check your usages of the bean manager. There have been some changes to the `SyncBeanManager` and `SyncBeanDef` interfaces (and their async counter-parts).

* Add an explicit converter for `@Bound` fileds where there is conversion between `java.util.Date` and `String`.

* Remove any usage of the `@StyleDescriptor`. LESS and CSS files can be declared in Java code via the `@Templated` annotation.

[[sid-5833087]]

== Downloads

The distribution packages can be downloaded from jboss.org http://jboss.org/errai/Downloads.html.

[[sid-5833088]]

== Sources

Errai is currently managed using GitHub. You can clone our repositories from http://github.com/errai.

[[sid-5833089]]

== Reporting problems

If you run into trouble don't hesitate to get in touch with us:

* JIRA Issue Tracking: https://jira.jboss.org/jira/browse/ERRAI
* User Forum: http://community.jboss.org/en/errai?view=discussions
* Mailing List: http://jboss.org/errai/MailingLists.html
* IRC: irc://irc.freenode.net/errai

[[sid-5833086]]

== Errai License

Errai is distributed under the terms of the Apache License, Version 2.0. See link:$$http://www.apache.org/licenses/LICENSE-2.0$$[the full Apache license text].
