This document provides information on the Run > Run on Server menu item, including how it works, and how to make it appear or disappear on a given object.

The Run, Debug, and Profile menu items are contributed by the Eclipse debug component. These menus appear on all objects in the UI that are adaptable to org.eclipse.debug.ui.actions.ILaunchable. Enabling these menus (by adapting objects to ILaunchable) is a prerequisite to enabling Run on Server.

If the Run menu appears on something that is not runnable, one solution is to try to remove the ILaunchable adapter to remove the menu entirely.

To determine when the Run on Server submenu appears in the Run menu, the org.eclipse.wst.server.ui.moduleArtifactAdapters extension point is used. This extension point provides an enablement expression that allows other plugins to enable the Run on Server submenu for specific objects. The Run on Server menu item appears on all objects that are accepted by at least one moduleArtifactAdapters expression.

Once the Run on Server menu item is selected, the selected object is adapted to IModuleArtifact. If the object cannot be adapted, an error message will be displayed (this should never happen unless an external plugin provides enablement but not adapting for an object). If the object can be adapted, Run on Server will proceed to try to find an available server to run on.

The most common problems with Run on Server are it not appearing on objects that should be runnable, or appearing on objects that aren't runnable:

This problem occurs when the selected object cannot be adapted (either directly or via an adapter factory) to ILaunchable. The owner of the object should provide an adapter to make the menu appear.

This problem occurs when the selected object is incorrectly adaptable to ILaunchable. The owner of the object should remove the ILaunchable interface or the adapter factory that supports the object.

Is Run on Server not appearing on an object that you think is runnable? Contact the development team responsible for the artifact (e.g. J2EE team for Servlet) and ask them to add support.

This problem can only occur when some plugin is using the moduleArtifactAdapter extension point to enable for an object that it shouldn't. Use the steps below to figure out which plugin is causing the problem and open a defect up against them.

Using a development environment, turn on tracing for org.eclipse.wst.server.ui and launch a workbench. When you right click on the object and hover over the Run menu, the following line of trace will be output as Run on Server appears: "Run On Server for XX is enabled by YY." XX is the object that you have selected, and YY is the extension point id for the plugin that is doing the enablement. Track down the id and open a defect against this component.

This problem can only occur when a plugin provides enablement for an object but does not allow the object to adapt to IModuleArtifact. Use the tracing steps above to identify the plugin and open a defect to get the object adapted.

The appendix contains some useful hints and tips.

Enablement expressions allow you to create arbitrarily complex expressions using ands, ors, nots, and Java code. For performance reasons, it's always better to use the expression support instead of using Java code, which is slower or may be in plugins that aren't loaded yet. However, simple Java tests can provide much better flexibility and do not need to cause large delays.

The best practice is to use enablement expressions as much as possible to filter down the number and types of objects that are applicable. As a final check, a property tester can then be used. However, it is still important to use expressions first, even if you know you'll be using a property tester for the last check - this will keep the performance up for all the objects that are filtered out.

To add a property tester to an enablement expression, try using the following example. In your plugin.xml, add the propertyTesters extension point:

<extension point="org.eclipse.core.expressions.propertyTesters">
   <propertyTester
      id="org.eclipse.myplugin.propertyTester"
      namespace="org.eclipse.myplugin"
      properties="someProperty"
      type="java.lang.Object"
      class="org.eclipse.myplugin.internal.MyPropertyTester">
   </propertyTester>
</extension>

package org.eclipse.myplugin.internal;
import org.eclipse.core.expressions.PropertyTester;

public class MyPropertyTester extends PropertyTester {
	public boolean test(Object receiver, String property, Object[] args, Object expectedValue) {
		// cast receiver and/or expectedValue
		// if (xx) // check some dynamic property
			return true;
		// else
		//return false;
	}
}

<test property="org.eclipse.myplugin.someProperty" value="true"/>