<?xml version="1.0" encoding="UTF-8"?>
<chapter id="sid-5931334">
   <title>Configuration</title>
   <para>This section contains information on configuring Errai.</para>
   <section id="sid-5931336">
      <title>Appserver Configuration</title>
      <para>
        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
        <xref linkend="sid-5931364"/>
        for information on the available servlet implementations.
      </para>
      <para>Here's a sample web.xml file:</para>
      <informalexample>
         <programlisting language="xml">&lt;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"&gt;

  &lt;servlet&gt;
    &lt;servlet-name&gt;ErraiServlet&lt;/servlet-name&gt;
    &lt;servlet-class&gt;org.jboss.errai.bus.server.servlet.DefaultBlockingServlet&lt;/servlet-class&gt;
    &lt;load-on-startup&gt;1&lt;/load-on-startup&gt;
  &lt;/servlet&gt;

  &lt;servlet-mapping&gt;
    &lt;servlet-name&gt;ErraiServlet&lt;/servlet-name&gt;
    &lt;url-pattern&gt;*.erraiBus&lt;/url-pattern&gt;
  &lt;/servlet-mapping&gt;

  &lt;context-param&gt;
    &lt;param-name&gt;errai.properties&lt;/param-name&gt;
    &lt;param-value&gt;/WEB-INF/errai.properties&lt;/param-value&gt;
  &lt;/context-param&gt;

  &lt;context-param&gt;
    &lt;param-name&gt;login.config&lt;/param-name&gt;
    &lt;param-value&gt;/WEB-INF/login.config&lt;/param-value&gt;
  &lt;/context-param&gt;

  &lt;context-param&gt;
    &lt;param-name&gt;users.properties&lt;/param-name&gt;
    &lt;param-value&gt;/WEB-INF/users.properties&lt;/param-value&gt;
  &lt;/context-param&gt;

&lt;/web-app&gt;</programlisting>
      </informalexample>
   </section>
   <section id="sid-23036402">
      <title>Client Configuration</title>
      <para>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.</para>
      <para>To turn off remote communication in the client bus the following JavaScript variable can be set in the HTML host page:</para>
      <informalexample>
         <programlisting language="xml">&lt;script type="text/javascript"&gt;
  erraiBusRemoteCommunicationEnabled = false;
&lt;/script&gt;</programlisting>
      </informalexample>
   </section>
   <section id="sid-5931354">
      <title>ErraiApp.properties</title>
      <para>The ErraiApp.properties acts as a marker file. When it is detected inside a JAR or at the top of any classpath, the subdirectories are scanned for deployable components. As such, all Errai application modules in a project should contain an ErraiApp.properties at the root of all classpaths that you wish to be scanned.</para>
   </section>
   <section id="sid-5931338">
      <title>ErraiService.properties</title>
      <para>he ErraiService.properties file contains basic configuration for the bus itself.</para>
      <para>Example Configuration:</para>
      <informalexample>
         <programlisting language="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

##
## 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</programlisting>
      </informalexample>
      <section id="sid-5931338_ErraiService.properties-errai.dispatcher.implementation">
         <title>errai.dispatcher.implementation</title>
         <para>
          The
          <code>errai.dispatcher_implementation</code>
          defines, as it's name quite succinctly implies, the dispatcher implementation to be used by the bus. There are two implementations which come with Errai out of the box: the
          <code>SimpleDispatcher</code>
          and the
          <code>AsyncDispatcher</code>
          . See
          <xref linkend="sid-5931357"/>
          for more information about the differences between the two.
        </para>
      </section>
      <section id="sid-5931338_ErraiService.properties-errai.asyncthreadpoolsize">
         <title>errai.async_thread_pool_size</title>
         <para>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.</para>
      </section>
      <section id="sid-5931338_ErraiService.properties-errai.async.workertimeout">
         <title>errai.async.worker_timeout</title>
         <para>Specifies the total amount of a time (in seconds) a service has to finish processing an incoming message before the pool interrupts the thread and returns an error. Adjusting this value does not have an effect if you are using the SimpleDispatcher.</para>
      </section>
      <section id="sid-5931338_ErraiService.properties-errai.authenticationadapter">
         <title>errai.authentication_adapter</title>
         <para>Specifies the authentication modelAdapter the bus should use for determining whether calls should be serviced based on authentication and security principles.</para>
      </section>
      <section id="sid-5931338_ErraiService.properties-errai.requireauthenticationforall">
         <title>errai.require_authentication_for_all</title>
         <para>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.</para>
      </section>
      <section id="sid-5931338_ErraiService.properties-errai.autodiscoverservices">
         <title>errai.auto_discover_services</title>
         <para>A boolean indicating whether or not the Errai bootstrapper should automatically scan for services.</para>
      </section>
      <section id="sid-5931338_ErraiService.properties-errai.autoloadextensions">
         <title>errai.auto_load_extensions</title>
         <para>A boolean indicating whether or not the Errai bootstrapper should automatically scan for extensions.</para>
      </section>
   </section>
   <section id="sid-5931357">
      <title>Dispatcher Implementations</title>
      <para>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.</para>
      <section id="sid-5931357_DispatcherImplementations-SimpleDispatcher">
         <title>SimpleDispatcher</title>
         <para>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.</para>
         <para>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.</para>
      </section>
      <section id="sid-5931357_DispatcherImplementations-AsyncDispatcher">
         <title>AsyncDispatcher</title>
         <para>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.</para>
      </section>
   </section>
   <section id="sid-5931364">
      <title>Servlet Implementations</title>
      <para>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.</para>
      <para>
        These included implementations are packaged at:
        <code>org.jboss.errai.bus.server.servlet</code>
        .
      </para>
      <section id="sid-5931364_ServletImplementations-DefaultBlockingServlet">
         <title>DefaultBlockingServlet</title>
         <para>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.</para>
      </section>
      <section id="sid-5931364_ServletImplementations-JBossCometServlet">
         <title>JBossCometServlet</title>
         <para>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).</para>
      </section>
      <section id="sid-5931364_ServletImplementations-JettyContinuationsServlet">
         <title>JettyContinuationsServlet</title>
         <para>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.</para>
      </section>
      <section id="sid-5931364_ServletImplementations-StandardAsyncServlet">
         <title>StandardAsyncServlet</title>
         <para>
          This implementation leverages asynchronous support in Servlet 3.0 to allow for threadless pausing of port connections. Note that
          <code>&lt;async-supported&gt;true&lt;/async-supported&gt;</code>
          has to be added to the servlet definition in
          <code>web.xml</code>
          .
        </para>
      </section>
   </section>
</chapter>