Skip to end of metadata
Go to start of metadata

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:

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.

The file contains basic configuration for the bus itself. Unlike, there should be at most one 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.

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.


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.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 [ERRAI: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.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 false.
  • errai.bus.clustering_provider The fully qualified class name of the clustering provider implementation. A class that implements org.jboss.errai.bus.server.cluster.ClusteringProvider. Currently the only build-in provider is the org.jboss.errai.bus.server.cluster.jgroups.JGroupsClusteringProvider.

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 false.
  • errai.auto_load_extensions A boolean indicating whether or not the Errai bootstrapper should automatically scan for extensions. The default value is true.

Example Configuration

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: org.jboss.errai.bus.server.servlet.

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.

Rolling your own security? Beware!
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:

  • /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 filter-mapping or security-constraint as you do for the Errai Servlet itself.


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:

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 *.erraiBus requests ahead of other filters in web.xml will solve the problem:


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.


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.

Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.