<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <meta name="copyright" content="Copyright (c) 2012, 2021 EclipseSource. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page."/>
  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
  <title> Application Configuration </title>
  <link rel="stylesheet" href="../../../PRODUCT_PLUGIN/book.css" type="text/css"/>
</head>
<body>

  <h1>Application Configuration</h1>
  <p>
    This article explains how to configure a RAP application in an <em>OSGi</em> or in an
    <em>RWT Standalone</em> <a href="application-setup.html#summary">setup</a> without the
    extension registry.
    This approach does not apply for workbench-based applications, which are configured using
    extensions (see <a href="branding.html">Branding</a>).
  </p>

  <h2>
    Implementing an ApplicationConfiguration
  </h2>
  <p>
    A RAP application consists of various parts, such as entry points, URL mappings, themes,
    service handlers, etc.
    All these parts constitute an <em>application configuration</em>,
    which is used by the framework to create and start an application instance.
    There can be more than one application instance at runtime, e.g. running on different network
    ports or in different servlet contexts.
  </p>
  <p>
    An application configuration is an implementation of the interface
    <em><a href="../reference/api/org/eclipse/rap/rwt/application/ApplicationConfiguration.html">ApplicationConfiguration</a></em>.
    RAP uses a callback approach to configure applications before they are started.
    The method <em><a href="../reference/api/org/eclipse/rap/rwt/application/ApplicationConfiguration.html#configure-org.eclipse.rap.rwt.application.Application-">configure( Application )</a></em>
    is invoked with a reference to the created
    <em><a href="../reference/api/org/eclipse/rap/rwt/application/Application.html">Application</a></em>
    as the sole argument.
    A minimal implementation must register at least one implementation of the
    <em><a href="../reference/api/org/eclipse/rap/rwt/application/EntryPoint.html">EntryPoint</a></em>
    interface
    (<a href="hello-world.html#entrypoint">it's recommended</a> to extend
    <em><a href="../reference/api/org/eclipse/rap/rwt/application/AbstractEntryPoint.html">AbstractEntryPoint</a></em>).
  </p>
<pre class="lang-java">
public class SimpleConfiguration implements ApplicationConfiguration {

  public void configure( Application application ) {
    application.addEntryPoint( "/simple", SimpleEntryPoint.class, null );
  }

}
</pre>
  <p>
    An application may have any number of entry points, each mapped to a separate servlet path.
    In case of the example above, the entry point would be available at the URL
    <code>http://{rapserver}:{port}/simple</code>.
  </p>
  <p id="entrypointconfig">
    The third argument of <em>addEntryPoint</em> is an optional map to configure visual aspects
    of the entry point.
    These may be client-specific, and therefore the
    <a href="client.html">Client</a> implementation
    (e.g. <em><a href="../reference/api/org/eclipse/rap/rwt/client/WebClient.html">WebClient</a></em>)
    provides constants to be used with the map.
    For example, it's possible to specify
    <a href="theming.html#rwt">a theme to use</a>, native HTML document
    <a href="../reference/api/org/eclipse/rap/rwt/client/WebClient.html#PAGE_OVERFLOW">overflow</a> behaviour,
    and an <a href="../reference/api/org/eclipse/rap/rwt/client/WebClient.html#FAVICON">icon</a>
    and <a href="../reference/api/org/eclipse/rap/rwt/client/WebClient.html#PAGE_TITLE">title</a>
    to be displayed in the browser title bar.
    It's also possible to add static HTML to the client documents
    <em><a href="../reference/api/org/eclipse/rap/rwt/client/WebClient.html#HEAD_HTML">head</a></em>
    or <em><a href="../reference/api/org/eclipse/rap/rwt/client/WebClient.html#BODY_HTML">body</a></em>,
    e.g. to implement a simple splash screen.
  </p>
<pre class="lang-java">
Map&lt;String, String&gt; properties = new HashMap&lt;String, String&gt;();
properties.put( WebClient.PAGE_TITLE, "RAP Example" );
properties.put( WebClient.PAGE_OVERFLOW, "scrollY" );
properties.put( WebClient.BODY_HTML, "&lt;big&gt;Loading Application&lt;big&gt;" );
properties.put( WebClient.FAVICON, "icons/favicon.png" );
properties.put( WebClient.THEME_ID, "MyCustomTheme" );
application.addEntryPoint( "/example", Example.class, properties );
</pre>
  <p>
    Note that the favicon and any images you might use in the additional HTML must be registered
    as a static resource. This can also be done in the application configuration with the
    method <em><a href="../reference/api/org/eclipse/rap/rwt/application/Application.html#addResource-java.lang.String-org.eclipse.rap.rwt.service.ResourceLoader-">Application#addResource</a></em>.
    Learn more about static resources <a href="resources.html">here</a>.
  </p>
  <p>
    The theme-id (<em><a href="../reference/api/org/eclipse/rap/rwt/client/WebClient.html#THEME_ID">WebClient.THEME_ID</a></em>)
    is the same that is used in the method <em><a href="../reference/api/org/eclipse/rap/rwt/application/Application.html#addStyleSheet-java.lang.String-java.lang.String, org.eclipse.rap.rwt.service.ResourceLoader-">Application#addStyleSheet</a></em>.
    Learn more about custom themes and theme contributions <a href="theming.html">here</a>.
  </p>
  <p>
    Moreover, the application instance provides methods to set the
    <a href="application-setup.html#compat">operation mode</a>
    and to register a
    <a  href="../reference/api/org/eclipse/rap/rwt/application/Application.html#addServiceHandler-java.lang.String, org.eclipse.rap.rwt.service.ServiceHandler-">service handler</a>.
  </p>

  <h3>Exception Handlers</h3>
  <p>
    By default, any exception that occurs during the event handling in a RAP application
    will lead to an HTTP 500 response (“Internal Server Error”).
    As an effect, the current UISession can not be continued.
    In a production environment, this is not always an appropriate response to an error.
  </p>
  <p>
    Since RAP 2.1, a custom exception handler can be registered in an application configuration
    to process exceptions that happen in event handling code.
    When an exception handler is registered, all exceptions that occur while running the event
    loop will be forwarded to this handler.
    The exception handler can then decide to ignore the exception, to write it to a log,
    display a message to the user, or to gracefully terminate the UISession.
  </p>

<pre class="lang-java">
application.setExceptionHandler( new ExceptionHandler() {
  @Override
  public void handleException( Throwable exception ) {
    // display error dialog, redirect to error page,
    // write exception to log, ...
  }
});
</pre>

  <p>
    To allow an exception handler to log all kinds of errors, it is even called for instances of
    <code>Error</code>.
    However, since errors must not be swallowed, they will be re-thrown after the handler was
    called.
  </p>

  <h2>Registering the Application Configuration</h2>
  <p>
    The application configuration needs to be registered in order to be found by the framework.
    When using OSGi, it can be registered as a service.
    This can be done either programmatically in a bundle activator or in a declarative way.
    Declarative services (DS) are the preferred way to register services in Equinox.
    For applications that don't use OSGi, the application configuration must be provided in a
    context parameter (see below).
  </p>

  <h3>Using OSGi Declarative Services (DS)</h3>
  <p>
    Using OSGi <a href="http://wiki.osgi.org/wiki/Declarative_Services">Declarative Services</a>,
    a service component can be declared in an XML file inside the bundle.
    Here's an example that registers an application configuration:
  </p>
<pre class="lang-xml">
&lt;scr:component xmlns:scr="http://www.osgi.org/xmlns/scr/v1.1.0"&gt;
  &lt;implementation class="com.example.ExampleConfiguration"/&gt;
  &lt;service&gt;
     &lt;provide interface="org.eclipse.rap.rwt.application.ApplicationConfiguration"/&gt;
  &lt;/service&gt;
&lt;/scr:component&gt;
</pre>
  <p>
    Adjust the element <em>implementation</em> to point to your application configuration.
    A common convention is to put this file in a directory named <em>OSGI-INF</em> in the bundle
    root.
    The file must be referenced in the bundle manifest (<em>MANIFEST.MF</em>) as follows:
  </p>
<pre>
Service-Component: OSGI-INF/configuration.xml
</pre>
  <p>
    The Plug-in development tools in Eclipse include a wizard for creating service declarations:
    <em class="UILabel">New &gt; Plug-in Development &gt; Component Definition</em>.
  </p>

  <h4>Custom context path</h4>
  <p>
    By default, a RAP application is available directly at the servlet container's root.
    For example, the servlet path “<code>/simple</code>” will be mapped to a URL like
    <code>http://example.com:8080/simple</code>.
    When using the servlet bridge, an additional path segment will be included that represents
    the web application.
  </p>
  <p>
    It is possible to specify a custom <em>context path</em> to be included in the URL.
    To do so, the application configuration service must be registered with a service parameter
    <em>contextName</em>.
    When using declarative services, a line like the following would be added to the component
    declaration:
  </p>
<pre class="lang-xml">
  &lt;property name=&quot;contextName&quot; type=&quot;String&quot; value=&quot;example&quot;/&gt;
</pre>
  <p>
    With this configuration, the same entry point will be available at
    <code>http://example.com:8080/example/simple</code>.
  </p>

  <h3>RWT stand-alone</h3>
  <p>
    When using <a href="rwt-standalone.html">RWT as a library</a> in a traditional web application
    (i.e. without OSGi) the application configuration must be registered using a context parameter.
    This can be done by adding a <code>context-param</code> element to the <code>web.xml</code>:
  </p>
<pre class="lang-xml">
&lt;context-param&gt;
  &lt;param-name&gt;org.eclipse.rap.applicationConfiguration&lt;/param-name&gt;
  &lt;param-value&gt;com.example.ExampleConfiguration&lt;/param-value&gt;
&lt;/context-param&gt;
</pre>
  <p>
    Replace the parameter value with the fully qualified class name of your application
    configuration.
    The parameter name is also contained in the constant
    <em><a href="../reference/api/org/eclipse/rap/rwt/application/ApplicationConfiguration.html#CONFIGURATION_PARAM">ApplicationConfiguration#CONFIGURATION_PARAM</a></em>
    as a reference.
  </p>

  <h2>
    Starting the Application
  </h2>
  <p>
    When an application configuration has been registered as a service in OSGi, the bundle
    <em>org.eclipse.rap.rwt.osgi</em> will automatically start this application on any available
    HttpService.
    When using Equinox, don’t forget to also include the <em>org.eclipse.equinox.ds</em> bundle.
  </p>
  <p>
    Please also ensure that the bundle <em>org.eclipse.rap.ui.workbench</em> is
    <strong>not</strong> included in your configuration. The workbench bundle automatically starts
    an application in the default context that clashes with the registered application unless the
    application is registered with a custom context.
  </p>
  <p>
    As an alternative to letting the framework start the application automatically, applications
    can also be started explicitly using an
    <em><a href="../reference/api/org/eclipse/rap/rwt/application/ApplicationRunner.html">ApplicationRunner</a></em>:
  </p>
<pre class="lang-java">
ApplicationConfiguration configuration = new SimpleConfiguration();
ApplicationRunner runner = new ApplicationRunner( configuration, servletContext );
runner.start();
</pre>

</body>
</html>