Using JViews products in Eclipse RCP applications

Installing the JViews runtime plug-in

JViews provides an IlvSwingControl class that encapsulates a Swing JComponent in an SWT widget. It allows you to use IlpNetwork, IlpEquipment, IlpTree, and IlpTable objects in an SWT window, together with other SWT or JFace controls. In this way, it provides a bridge between the AWT/Swing windowing system and the SWT windowing system.

In order to install the Rogue Wave® JViews Eclipse plug-ins, you need to install from the local site as shown below.

For Eclipse 3.7 or newer:

Launch your Eclipse installation.
Go to Help/Software Updates and select the Available Software tab.
Add a new local site: Click Add Site, then Local and specify the directory <installdir>/jviews-framework89/tools/ilog.views.eclipse.update.site
Select the features you want to install, and press the Install button.

Providing access to class loaders

Many services in JViews need to look up a resource. Since the classical way to provide access to resources is a class loader, JViews uses class loaders for this purpose. But in Eclipse/RCP applications, each plug-in corresponds to a class loader, and the JViews class loader sees only its own resources, not the application resources. To fix this problem, you can register plug-in class loaders with JViews through the IlvClassLoaderUtil.registerClassLoader function. Each resource lookup then considers the registered class loaders and, if the plug-ins are configured accordingly, also considers the dependencies of the registered class loaders.

The code for doing this is usually located in a plug-in activator class. For example:

public class MyPluginActivator extends AbstractUIPlugin 
{
    /**
     * This method is called upon plugin activation
     */
    public void start(BundleContext context) throws Exception {
      super.start(context);
      IlvClassLoaderUtil.registerClassLoader(getClass().getClassLoader());
    }

    /**
     * This method is called when the plugin is stopped
     */
    public void stop(BundleContext context) throws Exception {
      super.stop(context);
      IlvClassLoaderUtil.unregisterClassLoader(getClass().getClassLoader());
    }

  }

The overriding of stop() is necessary so that, when the plug-in gets unloaded, JViews gets notified about the plug-in that is going to stop and can drop references to its resources or instances of its classes. The activator plug-in is usually also the place where IlvProductUtil.registerApplication is called.

The bridge between AWT/Swing and SWT

The bridge between the AWT/Swing windowing system and the SWT windowing system consists of an IlvSwingControl class that encapsulates a Swing JComponent in an SWT widget. This class allows you to use IlpNetwork, IlpEquipment, IlpTree, and IlpTable objects in an SWT window, together with other SWT or JFace controls.

The following code shows how to create a bridge object:

Composite parent = ...;
IlpNetwork network = new IlpNetwork();
ControlSWTnetwork = new IlvSwingControl(parent, SWT.NONE, network);

At the JViews Framework level, the bridge between the AWT/Swing windowing system and the SWT windowing system consists of an IlvSwingControl class that encapsulates a Swing JComponent in an SWT widget. This class allows you to use IlvManager or IlvJManagerViewPanel objects in an SWT window, together with other SWT or JFace controls.

The following code shows how to create a bridge object at the JViews Framework level:

Composite parent = ...;
IlvManagerView mgrView = ...;
IlvJManagerViewPanel jmgrView = new IlvJManagerViewPanel(mgrView);
ControlSWTview = new IlvSwingControl(parent, SWT.NONE, jmgrView);

Using IlvSwingControl instead of the native SWT_AWT class has the following benefits:

Simplicity: it is easier to use, since you do not have to worry about the details of the Component hierarchy (see http://java.sun.com/javase/6/docs/api/java/awt/Component.html).
Portability: IlvSwingControl also works on platforms that do not have SWT_AWT, like X11/Motif® and MacOS® X 10.4.
Less flickering: on Linux®/Gtk, flickering is reduced.
Pop-up menus: pop-up menus can be positioned on each Component inside the AWT component hierarchy. For details of components, see http://java.sun.com/javase/6/docs/api/java/awt/Component.html.
Better size management: the size management between SWT and AWT (LayoutManager) is integrated.
Focus: it provides a workaround for a focus problem on Microsoft® Windows® platforms.

Note

The IlvSwingControl bridge is not supported on all platforms. It is only supported on Windows, UNIX® with X11 (Linux, Solaris™, AIX®, HP-UX®), and MacOS X 10.4 or later.

The IlvSwingControl bridge does not support arbitrary JComponents. Essentially, components that provide text editing are not supported. See IlvSwingControl for a precise description of the limitations.

Threading modes

You can handle the SWT-Swing user interface events in one or two threads.

Note

Single-thread mode is incompatible with AWT/Swing Dialogs. If you use single-thread mode, you cannot use AWT Dialogs , Swing JDialogs , or modal JInternalFrames in your application. There are also some other limitations. See the class IlvEventThreadUtil for a precise description of the limitations.

Two-thread mode

The SWT events are handled in the SWT event thread and AWT/Swing events are handled in the AWT/Swing event thread. This is the default mode.

You can switch between the two threads by using the SWT method Display.asyncExec() and the AWT method EventQueue.invokeLater() .

If your application uses this mode, you must be careful to:
- Make API calls on SWT widgets only in the SWT event thread. Otherwise, you will get SWTExceptions of type ERROR_THREAD_INVALID_ACCESS .
- Make API calls on JComponents, which include IlpNetwork, IlpEquipment, IlpTree, and IlpTable, only in the AWT/Swing event thread. Otherwise, you risk deadlocks.
  
  At the JViews Framework level, make API calls on JComponents, which include IlvManager and IlvJManagerViewPanel, only in the AWT/Swing event thread. Otherwise, you risk deadlocks.
Single-thread mode

In single-thread mode, SWT and AWT/Swing events are handled in the same thread.

Single-thread mode reduces the risk of producing deadlocks.

Enable this mode by calling setAWTThreadRedirect or enableAWTThreadRedirect early during initialization.

The following example shows how to enable single-thread mode:
```
// Switch single-event-thread mode during a static initialization.
      static {
          IlvEventThreadUtil.enableAWTThreadRedirect();
      }
```
If you are using JComponents other than IlpNetwork, IlpEquipment, IlpTree, and IlpTable in your application, your JComponents must use the method IlvSwingUtil.isDispatchThread() rather than EventQueue.isDispatchThread() or SwingUtilities.isEventDispatchThread().

For example:
```
   // Switch single-event-thread mode during a static initialization.
      static {
          IlvEventThreadUtil.enableAWTThreadRedirect();
      }
```
Note

This mode is incompatible with AWT/Swing Dialogs. If you use single-thread mode, you cannot use AWT Dialogs , Swing JDialogs , or modal JInternalFrames in your application. There are also some other limitations. See the class IlvEventThreadUtil for a precise description of the limitations.
At the JViews Framework level, if you are using JComponents other than IlvManager and IlvJManagerViewPanel in your application, your JComponents must use the method isDispatchThread rather than EventQueue.isDispatchThread() (see http://java.sun.com/javase/6/docs/api/java/awt/EventQueue.html#isDispatchThread()) or SwingUtilities.isEventDispatchThread() (see http://java.sun.com/javase/6/docs/api/javax/swing/SwingUtilities.html#isEventDispatchThread().)