| <?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, 2020 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<String, String> properties = new HashMap<String, String>(); |
| properties.put( WebClient.PAGE_TITLE, "RAP Example" ); |
| properties.put( WebClient.PAGE_OVERFLOW, "scrollY" ); |
| properties.put( WebClient.BODY_HTML, "<big>Loading Application<big>" ); |
| 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"> |
| <scr:component xmlns:scr="http://www.osgi.org/xmlns/scr/v1.1.0"> |
| <implementation class="com.example.ExampleConfiguration"/> |
| <service> |
| <provide interface="org.eclipse.rap.rwt.application.ApplicationConfiguration"/> |
| </service> |
| </scr:component> |
| </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 > Plug-in Development > 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"> |
| <property name="contextName" type="String" value="example"/> |
| </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"> |
| <context-param> |
| <param-name>org.eclipse.rap.applicationConfiguration</param-name> |
| <param-value>com.example.ExampleConfiguration</param-value> |
| </context-param> |
| </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> |