# Launching RAP Applications from the IDE

The RAP Tools provide two dedicated launchers to start RAP applications directly from the IDE: the RWT Launcher, used for snippets and stand-alone applications, and the RAP Launcher, used for applications based on OSGi. The latter you can also be started without the RAP Tools, using the plain OSGi Launcher.

Contents:

- Using the RWT Launcher
- Using the RAP Launcher
- Using the OSGi Launcher
- TroubleShooting

## Using the RWT Launcher

The RWT Launcher is the simplest way to start a RAP application. It requires no OSGi, application configuration or Branding, only an entry point. Consequentially, this method does not allow multiple entry points or any customization of the application (e.g. using a custom theme).

1. Select the Java class that contains the entry point you want to launch (e.g. in the Package Explorer).
2. Select Run > Run As > RWT Application in the menu bar, or Run As > RWT Application in the context menu of the file.
3. The application will be launched and opened in a browser view.

Before the RWT launcher starts the application, it terminates any possibly running instance of the same application. After a successful start, you should see a message like this one in the Console view:
`INFO: Started SocketListener on 0.0.0.0:<port>`.

### Further launch configuration options

Whenever you start an application as described above, a launch configuration is created and added to the Run > Run History menu. The created launch configuration is based on your Java project and your IDE preferences. It can later be edited and refined with custom or additional parameters.

To create a new launch configuration or to alter an existing one, select Run > Run Configurations… or Run > Debug Configurations…. This opens a dialog that lets you create, modify, and delete launch configurations of different types. To create a new RWT Application launch configuration, select RWT Application from the list of launch configuration types on the left, and press the New button in the toolbar. The tabs on the right allow you control specific aspects of the launch.

On the Main tab you can control the following aspects of the launch:

- The Project field denotes the project that contains the entry point to launch. You do not have to specify a project, but doing so allows a default classpath, source lookup path, and JRE to be chosen.
- The Application entry point lets you specify what should be launched. For simple use cases, choose Run entry point class and specify the class that implements the EntryPoint interface in the class name field.
  If you need more control or even would like to run an arbitrary web application, select Run from web.xml and enter the path to the web.xml in the location field.
- The Open in Browser group lets you control whether the application should be opened in a browser after a successful start. The application can be opened either in an internal browser, i.e. embedded in the Eclipse IDE, or in an external browser. The external browser application can be configured in the Web Browser preferences of your IDE. The link Configure browsers… lets you jump right there. The Servlet Path is used to construct the URL which will be opened in the browser. If you're launching an entry point, you are free to choose an arbitrary path. When launching an application from a web.xml, it must point to one of the servlets defined in the web.xml.
- In the Server Settings, you can select a fixed network port to start your application at, a session timeout and a context path.

  Use a fixed port configuration lets you select a fixed network port to start your application at. If you don't configure a port, the launcher will choose a free port, which may be different on every launch.

  Session Timeout specifies the servlet session timeout in minutes. If the checkbox is unselected, the session will never expire.

  Context Path selects an optional context path for the web application. The context path is part of a web application's URL, e.g. `http://<server>:<port>/contextPath/servletPath`. In a servlet container, every web app is available at its own context path. This setting lets you simulate the same context path that your application will be accessible at in the production environment.

- The option Start in development mode selects the variant of the RWT JavaScript library that will be delivered to the client. If development mode is on, the client maintains the JavaScript code in its original, human-readable form. If it is off, the client is optimized for speed and size by compressing the JavaScript code. It will also print non-critical JavaScript errors to the browsers console instead of crashing the entire client.

For an explanation of the other tabs see the topic Creating a Java application launch configuration

## Using the RAP Launcher

The RAP Launcher is based on the OSGi Launcher and adds a Main tab page to it. Please note that the RAP Launcher only works when the Equinox OSGi Framework is selected, which is the default setting on page Bundles.

### Open in Browser

This setting lets you control whether the application should be opened in a browser after a successful start. The application can be opened either in an internal browser, i.e. embedded in the Eclipse IDE, or in an external browser. The external browser application can be configured in the Web Browser preference of your IDE, the link Configure browsers… lets you jump right there.

The Servlet Path field lets you configure the URL that will be opened in the browser. Which path is mapped to which entry point is configured in the application configuration.

### Server Settings

Use a fixed port configuration lets you select a fixed network port to start your application at. If you don't configure a port, the launcher will choose a free port, which may be different on every launch.

Session Timeout specifies the servlet session timeout in seconds. If the checkbox is unselected, the session will never expire.

Context Path selects an optional context path for the web application. The context path is part of a web application's URL, e.g. `http://<server>:<port>/contextPath/servletPath`. In a servlet container, every webapp is available at its own context path. This setting lets you simulate the same context path that your application will be accessible at in the production environment.

The option Start in development mode selects the variant of the RWT JavaScript library that will be delivered to the client. If development mode is on, the client maintains the JavaScript code in its original, human-readable form. If it is off, the client is optimized for speed and size by compressing the JavaScript code. It will also print non-critical JavaScript errors to the browsers console instead of crashing the entire client.

### Instance Area

The instance area location sets the Program Arguments to define the osgi.instance.area. Bundles use this location to store their state location data.

### Required plug-ins

In the Bundles tab, the following bundles need to be activated:

Basic RAP bundles

- org.eclipse.rap.rwt
- org.eclipse.rap.rwt.osgi

Basic Equinox OSGi platform

- org.eclipse.osgi
- org.eclipse.osgi.services
- org.eclipse.equinox.console (the OSGi console)
  - org.apache.felix.gogo.command (required by equinox.console)
  - org.apache.felix.gogo.shell (required by equinox.console)
  - org.apache.felix.gogo.runtime (required by equinox.console)
- org.eclipse.equinox.http.jetty
- org.eclipse.equinox.http.servlet
- org.eclipse.equinox.ds (to enable declarative services)
  - org.eclipse.equinox.util (required by equinox.ds)

The Jetty servlet container

- org.eclipse.jetty.continuation
- org.eclipse.jetty.http
- org.eclipse.jetty.io
- org.eclipse.jetty.security
- org.eclipse.jetty.server
- org.eclipse.jetty.servlet
- org.eclipse.jetty.util

Servlet API (remove when deploying to a servlet container)

- javax.servlet

Optional RAP bundles (require additional platform bundles - see below)

- org.eclipse.rap.jface
- org.eclipse.rap.jface.databinding
- org.eclipse.rap.ui
- org.eclipse.rap.ui.forms
- org.eclipse.rap.ui.views
- org.eclipse.rap.ui.workbench

Eclipse platform bundles required by applications using JFace or the Workbench (only a subset may be required, please check for the actual dependencies)

- com.ibm.icu.base
- org.eclipse.core.commands
- org.eclipse.core.contenttype
- org.eclipse.core.databinding
- org.eclipse.core.databinding.beans
- org.eclipse.core.databinding.observable
- org.eclipse.core.databinding.property
- org.eclipse.core.expressions
- org.eclipse.core.jobs
- org.eclipse.core.runtime
- org.eclipse.equinox.app
- org.eclipse.equinox.common
- org.eclipse.equinox.registry
- org.eclipse.equinox.preferences
- org.eclipse.equinox.http.registry

To launch an existing launch configuration you may use the launch shortcut keys Alt+Shift+X, R (run) and Alt+Shift+D, R (debug).

## Using the OSGi Launcher

Alternatively, you can also use the plain OSGi Launcher to start RAP applications. In this case, you have to set the necessary system properties and program arguments on your own. At minimum, you have to specify the HTTP port for the server with this VM argument:

    -Dorg.osgi.service.http.port=<PORT>

To run RAP in development mode, add this system property, too:

    -Dorg.eclipse.rap.rwt.developmentMode=true

### Context path

To simulate the production environment, you can start your application with a context path, e.g. http://localhost:8080/contextPath/servletName.

    -Dorg.eclipse.equinox.http.jetty.context.path=<context path>

Valid context paths start with a slash and do not end with a slash. In the example above, the context path would be `/contextPath`. The default is the root context, i.e. the URL does not contain a contextPath segment.

### Servlet engine log

By default the servlet engine (namely Jetty) is configured to suppress most logging information. This can be changed by adding this VM argument to the launch configuration:

    -Dorg.eclipse.equinox.http.jetty.log.stderr.threshold=<log level>

Valid log levels are debug, info, warn, error, and off. The default value is warn.

## TroubleShooting

- Unsupported JRE version

  `java.lang.UnsupportedClassVersionError: Bad version number in .class file`

  The launcher requires JavaSE 1.6 or higher. If your project is configured with a JRE < 1.6, the launcher will try to start with a matching JRE. If you have a 1.5 JRE configured in your IDE, it will fail with an exception like the one shown above. In this case, edit the launch configuration and set the JRE to a Java 6 or higher.

- Unsupported Operation mode

  `java.lang.UnsupportedOperationException: The SimpleLifeCycle does not support Display#sleep()`

  The RWT launcher starts applications in the JEE compatibility mode. This mode does not support `Display.sleep()`, specifically, it does not support the SWT main loop. When starting an SWT snippet, this code may not be used:

      while( !shell.isDisposed() ) {
        if( !display.readAndDispatch() )
          display.sleep();
      }
      display.dispose();

  It is recommended to extend AbstractEntryPoint instead of implementing the EntryPoint interface directly. With AbstractEntryPoint no main loop is required, no matter which operation mode is used.

- UI does not react to user input

  This happens if the application starts in SWT compatibility mode and no SWT main loop is present. Basically the reverse of the above issue. Either add a main loop, or extend AbstractEntryPoint instead of implementing the EntryPoint interface.

- 404 Error Page

  There are two reasons a 404 page may be displayed in the browser. Either the URL is incorrect (check the servlet path), or the browser opened faster than the application could start. In that case, simply hit F5 (refresh).