JBoss.orgCommunity Documentation
This section contains information on configuring Errai.
Depending on what application server you are deploying on, you must provide an appropriate servlet implementation if you wish to use true, asynchronous I/O. See Section 12.6, “Servlet Implementations” for information on the available servlet implementations.
Here's a sample web.xml file:
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
version="2.5">
<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>
<context-param>
<param-name>errai.properties</param-name>
<param-value>/WEB-INF/errai.properties</param-value>
</context-param>
<context-param>
<param-name>login.config</param-name>
<param-value>/WEB-INF/login.config</param-value>
</context-param>
<context-param>
<param-name>users.properties</param-name>
<param-value>/WEB-INF/users.properties</param-value>
</context-param>
</web-app>
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>
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>
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 root 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.
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.
Configuration properties related to marshalling are documented in the Errai Marshalling section on Manual Mapping .
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 Section 3.6, “Alternatives and Mocks” for details.
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.
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
SimpleDispatcher
and the
AsyncDispatcher
. See
Section 12.5, “Dispatcher Implementations”
for more information about the differences between the two.
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.
errai.bus.buffer_size
The total size of the transmission buffer, in megabytes. If this attribute is specified along with
errai.bus.buffer_segment_count
, then the segment count is inferred by the calculation
buffer_segment_count / buffer_size}. If {{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
errai.bus.buffer_size
, the buffer size is inferred by the calculation
buffer_segment_size / buffer_segment_count
.
errai.bus.buffer_allocation_mode
Buffer allocation mode. Allowed values are
direct
and
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:
direct
.
errai.authentication_adapter specifies the authentication modelAdapter the bus should use for determining whether calls should be serviced based on authentication and security principals.
errai.require_authentication_for_all indicates whether or not the bus should always require the use of authentication for all requests inbound for the bus. If this is turned on, an authentication model adapter must be defined, and any user must be authenticated before the bus will deliver any messages from the client to any service.
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
false
.
errai.auto_load_extensions
A boolean indicating whether or not the Errai bootstrapper should automatically scan for extensions. The default value is
true
.
## ## 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 ## ## Specify the Authentication/Authorization Adapter to use ## #errai.authentication_adapter=org.jboss.errai.persistence.server.security.HibernateAuthenticationAdapter #errai.authentication_adapter=org.jboss.errai.bus.server.security.auth.JAASAdapter ## ## This property indicates whether or not authentication is required for all communication with the bus. Set this ## to 'true' if all access to your application should be secure. ## #errai.require_authentication_for_all=true
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.
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.
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 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
.
This is a universal, completely servlet spec (2.0) compliant, Servlet implementation. It provides purely synchronous request handling and should work in virtually any servlet container, unless there are restrictions on putting threads into sleep states.
The JBoss Comet support utilizes the JBoss Web AIO APIs (AS 5.0 and AS 6.0) to improve scalability and reduce thread usage. The HTTP, NIO, and AJP connectors are not supported. Use of this implementation requires use of the APR (Apache Portable Runtime).
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.