The Role of Eclipse RCP Application Advisors

---

Introduction
When you create a new Eclipse RCP application, the wizard will create an Application class that implements IApplication and the following advisor classes:

ApplicationWorkbenchAdvisor, which extends WorkbenchAdvisor and will be responsible for loading the initial perspective

ApplicationWorkbenchWindowAdvisor, which extends WorkbenchWindowAdvisor and is responsible for configuring the application window

ApplicationActionBarAdvisor, which extends ActionBarAdvisor and will be responsible for populating the action bar

The Application class that the wizard creates has a start method and a stop method. I’ve never had the need to make changes to this Application class. How is this Application class used? In essence, the application class in RCP will have a role similar to a main class in a standard executable jar file. In a standard jar file the JVM will search the jar manifest to determine which class has the main method where the program begins. In RCP, the Eclipse platform checks the plugin.xml file to determine the run class that implements IApplication.

So the RCP application will execute under a Run Configuration. Within that configuration, there will be a reference to the plug-in that you are developing. The plugin.xml file will show the Application class as the run class:

      <application
            icon="icons/branding/branding16.gif"
            visible="true">
         <run
              class="com.oxbsystems.client.application.Application">
         </run>
      </application>

In short, the sequence of events for application start-up is:

The Eclipse platform loads and determines the plug-in that should be executed

Eclipse inspects the plugin.xml file for the plug-in to resolve the run class name.

Eclipse calls the start method in the run class (which implements IApplication)

The start method in the run class will create an instance of ApplicationWorkbenchAdvisor

ApplicationWorkbenchAdvisor will instantiate an ApplicationWorkbenchWindowAdvisor, which in turn will instantiate ApplicationActionBarAdvisor.

---

ApplicationWorkbenchAdvisor
The ApplicationWorkbenchAdvisor does two things: it instantiates an ApplicationWorkbenchWindowAdvisor (explained below) and will set the initial perspective.

public class ApplicationWorkbenchAdvisor extends WorkbenchAdvisor {
	private static final String PERSPECTIVE_ID = "com.oxbsystems.client.perspective.login.LoginPerspective";

	public WorkbenchWindowAdvisor createWorkbenchWindowAdvisor(IWorkbenchWindowConfigurer configurer) {
		return new ApplicationWorkbenchWindowAdvisor(configurer);
	}

	public String getInitialWindowPerspectiveId() {
		return PERSPECTIVE_ID;
	}
}

---

ApplicationWorkbenchWindowAdvisor
ApplicationWorkbenchWindowAdvisor will have a constructor that takes an IWorkbenchWindowConfigurer that will be supplied by the platform. This class will typically have the following methods:

createActionBarAdvisor will instantiate and return an ApplicationActionBarAdvisor.

preWindowOpen will modify the IWorkbenchWindowConfigurer. Screen size will be calculated in this method as shown in the next snippet.

postWindowOpen will modify the configurer after the application window opens.

public class ApplicationWorkbenchWindowAdvisor extends WorkbenchWindowAdvisor {

	public ApplicationWorkbenchWindowAdvisor(IWorkbenchWindowConfigurer configurer) {
		super(configurer);
	}

	public ActionBarAdvisor createActionBarAdvisor(IActionBarConfigurer configurer) {
		return new ApplicationActionBarAdvisor(configurer);
	}

	public void preWindowOpen() {
		IWorkbenchWindowConfigurer configurer = getWindowConfigurer();
		Rectangle r = GraphicsEnvironment.getLocalGraphicsEnvironment().getMaximumWindowBounds();
		configurer.setInitialSize(new Point(r.width, r.height));
		configurer.setShowCoolBar(true);
		configurer.setShowStatusLine(false);
		PlatformUI.getPreferenceStore().setValue(
				IWorkbenchPreferenceConstants.SHOW_TRADITIONAL_STYLE_TABS, false);
	}

	@Override
	public void postWindowOpen() {
		super.postWindowOpen();
		IWorkbenchWindowConfigurer configurer = getWindowConfigurer();
		configurer.getWindow().getShell().setMaximized(true);

	}

}

---

ApplicationActionBarAdvisor
The ApplicationActionBarAdvisor creates actions and adds them to the toolbar. In the following example this class also listens for changes in a Session object to enable or disable items in the toolbar.

public class ApplicationActionBarAdvisor extends ActionBarAdvisor implements SessionListener{
	private OpenCompanyCatalogPerspectiveAction openCompanyPerspectiveAction;
	private OpenServiceCatalogPerspectiveAction openServicePerspectiveAction;
	private Session session;
	private IWorkbenchAction quitAction;
	private ToolBarManager toolBarManager;

    public ApplicationActionBarAdvisor(IActionBarConfigurer configurer) {
		super(configurer);
		session = Session.getInstance();
		session.register(this);
    }

    protected void makeActions(IWorkbenchWindow window) {
		quitAction = ActionFactory.QUIT.create(window);
		quitAction.setImageDescriptor(	Activator.getImageDescriptor( "icons/action/perspective/exit.png"));
		register(quitAction);

		openCompanyPerspectiveAction = new OpenCompanyCatalogPerspectiveAction(window);
		register(openCompanyPerspectiveAction);

		openServicePerspectiveAction = new OpenServiceCatalogPerspectiveAction(window);
		register(openServicePerspectiveAction);
    }

	protected void fillMenuBar(IMenuManager menuBar) {
	}

	protected void fillCoolBar(ICoolBarManager coolBar) {
		toolBarManager = new ToolBarManager(SWT.FLAT);
		coolBar.add(toolBarManager);
		this.populateToolbar();
	}

	private void populateToolbar() {
		this.toolBarManager.removeAll();
		if(session.isValid()){
			this.toolBarManager.add(openConfigurationPerspectiveAction);
			this.toolBarManager.add(openCompanyPerspectiveAction);
		}
		this.toolBarManager.add(quitAction);
	}

	/* (non-Javadoc)
	 * @see com.oxbsystems.client.service.jaas.SessionListener#sessionChanged()
	 */
	@Override
	public void sessionChanged() {
		this.populateToolbar();
		this.toolBarManager.update(true);
	}
}