JBoss.orgCommunity Documentation
This section contains information on manually setting up Errai and describes additional configurations and settings which may be adjusted.
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:
<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.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.We provide integration with the 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 (java:/BeanManager).
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:
-Derrai.server.classOutput=src/main/webapp/WEB-INF/classes
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 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-linker name="offline" class="org.jboss.errai.offline.linker.DefaultCacheManifestLinker" />
<add-linker name="offline" />
your_module_name/errai.appcache) to the html tag in your host page:<html manifest="your_module_name/errai.appcache">
<mime-mapping>
<extension>manifest</extension>
<mime-type>text/cache-manifest</mime-type>
</mime-mapping>
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.appcacheDefaultCacheManifestLinker, create a subclass that overrides otherCachedFiles(), and use this subclass as a linker instead:@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"};
}
}
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.
An 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 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.)
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 " errai. ". Third party extensions should each choose their own prefix for keys in ErraiApp.properties.
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.
Errai also supports configuring portable types in ErraiApp.properties as an alternative to the @Portable annotation. See the Errai Marshalling section on Manual Mapping for details.
The following compile-time dependency is required for Errai Messaging:
<dependency>
<groupId>org.jboss.errai</groupId>
<artifactId>errai-bus</artifactId>
<version>${errai.version}</version>
</dependency>
Or if you are not using Maven, have 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:
<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 errai-ioc-bus-support-${errai.version}.jar on the classpath.
[[sid-5931338_Messaging%28ErraiBus%29Configuration-Disablingremotecommunication]]
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:
<script type="text/javascript">
erraiBusRemoteCommunicationEnabled = false;
</script>
[[sid-5931338_Messaging%28ErraiBus%29Configuration-Configuringanalternativeremoteremotebusendpoint]]
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.
<script type="text/javascript">
erraiBusApplicationRoot = "/MyRemoteMessageBusEnpoint";
</script>
[[sid-5931338_Messaging%28ErraiBus%29Configuration-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]]
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.
[[sid-5931338_Messaging%28ErraiBus%29Configuration-Threading]]
[[sid-5931338_Messaging%28ErraiBus%29Configuration-Buffering]]
[[sid-5931338_Messaging%28ErraiBus%29Configuration-Clustering]]
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 false.[[sid-5931338_Messaging%28ErraiBus%29Configuration-StartupConfiguration]]
[[sid-5931338_Messaging%28ErraiBus%29Configuration-ExampleConfiguration]]
## ## 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]]
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: org.jboss.errai.bus.server.servlet.
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.
All of the following examples use a wildcard mapping for *.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:
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 filter-mapping or security-constraint as you do for the Errai Servlet itself.
[[sid-5931338_Messaging%28ErraiBus%29Configuration-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 web.xml file:
<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]]
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 *.erraiBus requests ahead of other filters in web.xml will solve the problem:
<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]]
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.
<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]]
This implementation leverages asynchronous support in Servlet 3.0 to allow for threadless pausing of port connections. Note that <async-supported>true</async-supported> has to be added to the servlet definition in web.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>
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:
<init-param>
<param-name>auto-discover-services</param-name>
<param-value>true</param-value>
</init-param>
This configuration will cause issues (such as duplicate services) if it is set to true and a server-side CDI container is available.
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:
<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 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.
<dependency>
<groupId>org.jboss.errai</groupId>
<artifactId>errai-jaxrs-provider</artifactId>
<version>${errai.version}</version>
</dependency>
Or manually add 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 Configuration).
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 *.gwt.xml file:
<inherits name="org.jboss.errai.enterprise.Jaxrs"/>
All paths specified using the @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;
<script type="text/javascript">
erraiJaxRsApplicationRoot = "/MyJaxRsEndpointPath";
</script>
By using a JSNI method;
private native void setMyJaxRsAppRoot(String path) /*-{
$wnd.erraiJaxRsApplicationRoot = path;
}-*/;
Or by simply invoking.
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.
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 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;
<script type="text/javascript">
erraiJaxRsJacksonMarshallingActive = true;
</script>
Use a JSNI method;
private native void setJacksonMarshallingActive(boolean active) /*-{
$wnd.erraiJaxRsJacksonMarshallingActive = active;
}-*/;
Or invoke a method in RestClient.
RestClient.setJacksonMarshallingActive(true);
To use Errai JPA, you must include it on the compile-time classpath. If you are using Maven for your build, add this dependency:
<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 errai-jpa-client-${errai.version}.jar, Hibernate 4.1.1, and Google Guava for GWT 12.0 to your compile-time classpath.
First, ensure your 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):
<dependency>
<groupId>org.jboss.errai</groupId>
<artifactId>errai-jpa-datasync</artifactId>
<version>${errai.version}</version>
</dependency>
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:
<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 errai-data-binding-${errai.version}.jar to your classpath.
You must also inherit the Errai data binding module by adding the following line to your GWT module descriptor (gwt.xml).
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:
BindableProxyLoader proxyLoader = GWT.create(BindableProxyLoader.class);
proxyLoader.loadBindableProxies();
<inherits name="org.jboss.errai.common.ErraiCommon"/>
The easiest way to get Errai UI on your classpath is to depend on the special errai-javaee-all artifact, which brings in most Errai modules:
<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 errai-ui directly:
<dependency>
<groupId>org.jboss.errai</groupId>
<artifactId>errai-ui</artifactId>
<version>${errai.version}</version>
</dependency>
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:
<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 errai-navigation-${errai.version}.jar to the compile-time classpath of a project that’s already set up for Errai UI templating.
Errai Security requires to modules to be included in a project:
<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:
<dependency>
<groupId>org.jboss.errai</groupId>
<artifactId>errai-security-picketlink</artifactId>
<version>${errai.version}</version>
</dependency>
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 *.gwt.xml file:
<inherits name="org.jboss.errai.security.Security" />
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:
<interceptors>
<class>org.jboss.errai.security.server.ServerSecurityRoleInterceptor</class>
</interceptors>