6.2 Disposing Resources

Chapter 6 Programmer's Guide
	6.2 Disposing Resources

6.2.1 Disposing SWT-Resources

In SWT operation system resources needed for widgets, images, graphics, fonts etc. are created in the respective constructors. The resources are not freed automatically. The programmer has to call the method dispose() to free them. SWT has two rules how to manage the resources. This article describes SWT resource handling: http://www.eclipse.org/articles/swt-design-2/swt-design-2.html

If you created it, you dispose it.
Disposing the parent disposes the children.

XMA adds one rule

If it is created by the XMA-Runtime, it its disposed by the XMA-Runtime.

All widgets declared in the guidesigner, including their images and colors are created by the runtime and disposed by the runtime. The SWT objects are created by the code generated from the guidesigner and disposed there, too. You only dispose SWT objects if you called their constructor yourself.

There exist methods in the component to help you to manage some SWT resources (images, colors and fonts). See Managed SWT Resources(Managed SWT Resources).

6.2.2 Disposing Components

XMA Components behave similar. When they are created, they register themselves to the session. This enables the runtime to automatically create and synchronize them on the server side in remote procedure calls. When they are no longer needed, the programmer has to dispose them, so the runtime can remove the server side component too.

The rules stated above apply to XMA Components too.

Components Created by You

If you create the component by calling getComponent(name) or getComponentExtern(uri) on the session, you also have to dispose it by calling ComponentClient.dispose() on it.

    component.dispose();

For modal components you can call it right after invoking it and reading its output properties.

For Non modal components you have to determine when the component is no longer needed. If you called it as a non modal dialog, you best register a ComponentListener and dispose the component in the componentClosed() event.

   component.addEventListener(this);
        ...
    void componentClosed(EventObject event) {
        ((IComponent)event.getSource()).dispose();
    }

If you dynamically embedded the component into a page, you best dispose it when you later remove it from the page. When the component of the parent page is disposed the currently embedded component is disposed, too.

Components Created by the Runtime

If you call a modal component by calling launchRelative() or launchExtern(), the component is created and disposed by the runtime. There is no need for you to dispose it.

If you call a component over a Task(Task) using callBlocking() or callNonBlocking(), the component is created and disposed by the runtime.

If you statically embedded a component into a page by defining this embedding in the guidesigner, the runtime creates and disposes the embedded component. The embedded component is disposed, when the component of the parent page is disposed.

If you dynamically replace a statically embedded component, you have to dispose the replaced component. The runtime will dispose the component which is embedded at the time of disposal of the component of the parent page.

6.2.3 Pages

When pages are created, they register themselves to their component. This enables the runtime to automatically create and synchronize them on the server side in remote procedure calls. Pages are disposed automatically, when their component is disposed.

When a dialog is opened, the SWT-Widgets of the dialog page and all its embedded subpages are created. When the dialog is closed, the SWT-Widgets of the dialog page and all its embedded subpages are disposed. If you open the same instance of the dialog page again, the widget are created anew.

If your component creates very much pages, you can save memory on the server by manually freeing their models when you no longer need them. You can free a page by calling its method removeModel().

    page.removeModel();

This removes all Widget Models from the page and all its embedded subpages and de-registers the page and all its embedded subpages from the component. When the next remote procedure call occurs, these pages and widget models are removed on the server automatically.

If you reopens a page where you removed the models, the widget models are created anew and the page is registered at the component again. This causes it to be recreated on the server side, too.