<?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>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.</para>
      <section id="sid-5931354_ErraiApp.properties-AsaMarkerFile">
         <title>As a Marker File</title>
         <para>
            <emphasis role="strong">
            An
            <code>ErraiApp.properties</code>
            file must appear at the root of each classpath location that contains an Errai module.
          </emphasis>
          The contents of JAR and directory classpath entries that do not contain an
          <code>ErraiApp.properties</code>
          are effectively invisible to Errai's classpath scanner.
        </para>
      </section>
      <section id="sid-5931354_ErraiApp.properties-AsaConfigurationFile">
         <title>As a Configuration File</title>
         <para>
          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.</code>
          ". Third party extensions should each choose their own prefix for keys in ErraiApp.properties.
        </para>
         <section id="sid-5931354_ErraiApp.properties-ConfigurationMerging">
            <title>Configuration Merging</title>
            <para>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).</para>
            <para>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.</para>
            <para>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.</para>
         </section>
         <section id="sid-5931354_ErraiApp.properties-ErraiMarshallingConfiguration">
            <title>Errai Marshalling Configuration</title>
            <para>
            Configuration properties related to marshalling are documented in
            <link linkend="sid-5931328_Marshalling-ManualMapping">the Errai Marshalling section on Manual Mapping</link>
            .
          </para>
         </section>
         <section id="sid-5931354_ErraiApp.properties-ErraiIoCConfiguration">
            <title>Errai IoC Configuration</title>
            <itemizedlist>
               <listitem>
                  <para>
                     <emphasis role="strong">errai.ioc.QualifyingMetaDataFactory</emphasis>
                specifies the fully-qualified class name of the QualifyingMetadataFactory implementation to use with Errai IoC.
              </para>
               </listitem>
            </itemizedlist>
            <itemizedlist>
               <listitem>
                  <para>
                     <emphasis role="strong">errai.ioc.enabled.alternatives</emphasis>
                specifies a whitespace-separated list of fully-qualified class names for
                <emphasis role="italics">alternative beans</emphasis>
                . See
                <xref linkend="sid-22872133"/>
                for details.
              </para>
               </listitem>
            </itemizedlist>
         </section>
      </section>
   </section>
   <section id="sid-5931338">
      <title>ErraiService.properties</title>
      <para>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.</para>
      <section id="sid-5931338_ErraiService.properties-ConfigurationProperties">
         <title>Configuration Properties</title>
         <section id="sid-5931338_ErraiService.properties-MessageDispatching">
            <title>Message Dispatching</title>
            <itemizedlist>
               <listitem>
                  <para>
                     <emphasis role="strong">errai.dispatcher.implementation</emphasis>
                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</code>
                and the
                <code>AsyncDispatcher</code>
                . See
                <xref linkend="sid-5931357"/>
                for more information about the differences between the two.
              </para>
               </listitem>
            </itemizedlist>
            <itemizedlist>
               <listitem>
                  <para>
                     <emphasis role="strong">errai.async_thread_pool_size</emphasis>
                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>
               </listitem>
            </itemizedlist>
            <itemizedlist>
               <listitem>
                  <para>
                     <emphasis role="strong">errai.async.worker_timeout</emphasis>
                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.
              </para>
               </listitem>
            </itemizedlist>
            <itemizedlist>
               <listitem>
                  <para>
                     <emphasis role="strong">errai.bus.buffer_size</emphasis>
                The total size of the transmission buffer, in megabytes. If this attribute is specified along with
                <code>errai.bus.buffer_segment_count</code>
                , then the segment count is inferred by the calculation
                <code>buffer_segment_count / buffer_size}. If {{errai.bus.buffer_segment_count</code>
                is also defined, it will be ignored in the presence of this property. Default value: 32.
              </para>
               </listitem>
            </itemizedlist>
            <itemizedlist>
               <listitem>
                  <para>
                     <emphasis role="strong">errai.bus.buffer_segment_size</emphasis>
                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.
              </para>
               </listitem>
            </itemizedlist>
            <itemizedlist>
               <listitem>
                  <para>
                     <emphasis role="strong">errai.bus.buffer_segment_count</emphasis>
                The number of segments in absolute terms. If this attribute is specified in the absence of
                <code>errai.bus.buffer_size</code>
                , the buffer size is inferred by the calculation
                <code>buffer_segment_size / buffer_segment_count</code>
                .
              </para>
               </listitem>
            </itemizedlist>
            <itemizedlist>
               <listitem>
                  <para>
                     <emphasis role="strong">errai.bus.buffer_allocation_mode</emphasis>
                Buffer allocation mode. Allowed values are
                <code>direct</code>
                and
                <code>heap</code>
                . 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</code>
                .
              </para>
               </listitem>
            </itemizedlist>
         </section>
         <section id="sid-5931338_ErraiService.properties-Security">
            <title>Security</title>
            <itemizedlist>
               <listitem>
                  <para>
                     <emphasis role="strong">errai.authentication_adapter</emphasis>
                specifies the authentication modelAdapter the bus should use for determining whether calls should be serviced based on authentication and security principals.
              </para>
               </listitem>
            </itemizedlist>
            <itemizedlist>
               <listitem>
                  <para>
                     <emphasis role="strong">errai.require_authentication_for_all</emphasis>
                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>
               </listitem>
            </itemizedlist>
         </section>
         <section id="sid-5931338_ErraiService.properties-StartupConfiguration">
            <title>Startup Configuration</title>
            <itemizedlist>
               <listitem>
                  <para>
                     <emphasis role="strong">errai.auto_discover_services</emphasis>
                A boolean indicating whether or not the Errai bootstrapper should automatically scan for services.
                <emphasis role="strong">
                  This property must be set to
                  <code>true</code>
                  if and only if Errai CDI is not on the classpath
                </emphasis>
                . The default value is
                <code>false</code>
                .
              </para>
               </listitem>
            </itemizedlist>
            <itemizedlist>
               <listitem>
                  <para>
                     <emphasis role="strong">errai.auto_load_extensions</emphasis>
                A boolean indicating whether or not the Errai bootstrapper should automatically scan for extensions. The default value is
                <code>true</code>
                .
              </para>
               </listitem>
            </itemizedlist>
         </section>
      </section>
      <section id="sid-5931338_ErraiService.properties-ExampleConfiguration">
         <title>Example Configuration</title>
         <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>
   </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>