# 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 (see Choosing an Application Setup for these different types of applications). OSGi applications 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 simplest way to launch an RWT application is to run it using an RWT Application launch configuration. This launch configuration type uses information derived from the workbench preferences and your applications's Java project to launch the program.

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 workbench menu (or Run As > RWT Application in the context menu of this file).
3. The application will be launched and opened in a browser view.

Before the RWT launcher starts an 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 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 workbench 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 `IEntryPoint` 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.
- In the Runtime Settings, you can select a fixed network port to start your application at. If you don't configure a port, the launcher will choose a free port.
- The 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 preference settings, the link Configure browsers… lets you jump right there.
- The servlet path is used to construct the URL to be opened with 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.

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.

### Run 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 settings, the link Configure browsers… lets you jump right there.

The Servlet Path and Startup Parameter fields let you configure the URL that will be opened in the browser. The startup parameter is considered obsolete. The entrypoint to start is normally configured using the servlet name.

### Runtime Settings

Manual Port configuration lets you can select a fixed network port to start your application at. If you don't configure a port, the launcher will choose a free port.

When the option Terminate possible running previous launch is selected, the launcher automatically stops an application with the same name that is currently running. This helps to restart applications quickly without having to stop the application before.

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 Client-side Library Variant selects the variant of the RWT JavaScript library that will be delivered to the client. The Standard version is optimized for speed and size by compressing the JavaScript code. The Debug version maintains the JavaScript code in its original form. We recommend to use the Debug variant when developing custom widgets for RAP.

### 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

Additional 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 a once created 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 least, you have to specify the HTTP port for the server with the VM argument

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

Tu run RAP in debug mode, add this system property, too:

    -Dorg.eclipse.rwt.clientLibraryVariant=DEBUG

### Servlet engine log

By default the servlet engine (namely Jetty) is configured to suppress most logging information. This can be changed by adding the VM argument `-Dorg.eclipse.equinox.http.jetty.log.stderr.threshold=<log level>` to the launch configuration. 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 block must be removed:

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