Package org.eclipse.jface.resource

## Class ResourceManager

- java.lang.Object
- - org.eclipse.jface.resource.ResourceManager

Direct Known Subclasses:
  `DeviceResourceManager`, `LazyResourceManager`, `LocalResourceManager`

    public abstract class ResourceManager
    extends Object

This class manages SWT resources. It manages reference-counted instances of resources such as Fonts, Images, and Colors, and allows them to be accessed using descriptors. Everything allocated through the registry should also be disposed through the registry. Since the resources are shared and reference counted, they should never be disposed directly.

ResourceManager handles correct allocation and disposal of resources. It differs from the various JFace *Registry classes, which also map symbolic IDs onto resources. In general, you should use a *Registry class to map IDs onto descriptors, and use a ResourceManager to convert the descriptors into real Images/Fonts/etc.

Since:
  3.1

### Constructor Summary

Constructors
`ResourceManager()`

### Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
`void` `cancelDisposeExec​(Runnable r)` Cancels a runnable that was previously scheduled with `disposeExec`.
`abstract Object` `create​(DeviceResourceDescriptor descriptor)` Returns the resource described by the given descriptor.
`Color` `createColor​(ColorDescriptor descriptor)` Allocates a color, given a color descriptor.
`Color` `createColor​(RGB descriptor)` Allocates a color, given its RGB value.
`Font` `createFont​(FontDescriptor descriptor)` Returns the Font described by the given FontDescriptor.
`Image` `createImage​(ImageDescriptor descriptor)` Creates an image, given an image descriptor.
`Image` `createImageWithDefault​(ImageDescriptor descriptor)` Creates an image, given an image descriptor.
`abstract void` `destroy​(DeviceResourceDescriptor descriptor)` Deallocates a resource previously allocated by `create(DeviceResourceDescriptor)`.
`void` `destroyColor​(ColorDescriptor descriptor)` Undoes everything that was done by a call to `createColor(ColorDescriptor)`.
`void` `destroyColor​(RGB descriptor)` Undoes everything that was done by a call to `createColor(RGB)`.
`void` `destroyFont​(FontDescriptor descriptor)` Undoes everything that was done by a previous call to `createFont(FontDescriptor)`.
`void` `destroyImage​(ImageDescriptor descriptor)` Undoes everything that was done by `createImage(ImageDescriptor)`.
`void` `dispose()` Disposes any remaining resources allocated by this manager.
`void` `disposeExec​(Runnable r)` Causes the `run()` method of the runnable to be invoked just before the receiver is disposed.
`abstract Object` `find​(DeviceResourceDescriptor descriptor)` Returns a previously allocated resource associated with the given descriptor, or null if none exists yet.
`Object` `get​(DeviceResourceDescriptor descriptor)` Returns a previously-allocated resource or allocates a new one if none exists yet.
`protected abstract Image` `getDefaultImage()` Returns the default image that will be returned in the event that the intended image is missing.
`abstract Device` `getDevice()` Returns the Device for which this ResourceManager will create resources

### Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

### Constructor Detail

#### ResourceManager

    public ResourceManager()

### Method Detail

#### getDevice

    public abstract Device getDevice()

Returns the Device for which this ResourceManager will create resources

Returns:
  the Device associated with this ResourceManager
Since:
  3.1

#### create

    public abstract Object create​(DeviceResourceDescriptor descriptor)

Returns the resource described by the given descriptor. If the resource already exists, the reference count is incremented and the exiting resource is returned. Otherwise, a new resource is allocated. Every call to this method should have a corresponding call to `destroy(DeviceResourceDescriptor)`.

If the resource is intended to live for entire lifetime of the resource manager, a subsequent call to `destroy(DeviceResourceDescriptor)` may be omitted and the resource will be cleaned up when the resource manager is disposed. This pattern is useful for short-lived `LocalResourceManager`s, but should never be used with the global resource manager since doing so effectively leaks the resource.

The resources returned from this method are reference counted and may be shared internally with other resource managers. They should never be disposed outside of the ResourceManager framework, or it will cause exceptions in other code that shares them. For example, never call `Resource.dispose()` on anything returned from this method.

Callers may safely downcast the result to the resource type associated with the descriptor. For example, when given an ImageDescriptor, the return value of this method will always be an Image.

Parameters:
  `descriptor` - descriptor for the resource to allocate
Returns:
  the newly allocated resource (not null)
Throws:
  `DeviceResourceException` - if unable to allocate the resource
Since:
  3.1

#### destroy

    public abstract void destroy​(DeviceResourceDescriptor descriptor)

Deallocates a resource previously allocated by `create(DeviceResourceDescriptor)`. Descriptors are compared by equality, not identity. If the same resource was created multiple times, this may decrement a reference count rather than disposing the actual resource.

Parameters:
  `descriptor` - identifier for the resource
Since:
  3.1

#### get

    public final Object get​(DeviceResourceDescriptor descriptor)

Returns a previously-allocated resource or allocates a new one if none exists yet. The resource will remain allocated for at least the lifetime of this resource manager. If necessary, the resource will be deallocated automatically when the resource manager is disposed.

The resources returned from this method are reference counted and may be shared internally with other resource managers. They should never be disposed outside of the ResourceManager framework, or it will cause exceptions in other code that shares them. For example, never call `Resource.dispose()` on anything returned from this method.

Callers may safely downcast the result to the resource type associated with the descriptor. For example, when given an ImageDescriptor, the return value of this method may be downcast to Image.

This method should only be used for resources that should remain allocated for the lifetime of the resource manager. To allocate shorter-lived resources, manage them with `create`, and `destroy` rather than this method.

This method should never be called on the global resource manager, since all resources will remain allocated for the lifetime of the app and will be effectively leaked.

Parameters:
  `descriptor` - identifier for the requested resource
Returns:
  the requested resource. Never null.
Throws:
  `DeviceResourceException` - if the resource does not exist yet and cannot be created for any reason.
Since:
  3.3

#### createImage

    public final Image createImage​(ImageDescriptor descriptor)

Creates an image, given an image descriptor. Images allocated in this manner must be disposed by `destroyImage(ImageDescriptor)`, and never by calling `Resource.dispose()`.

If the image is intended to remain allocated for the lifetime of the ResourceManager, the call to destroyImage may be omitted and the image will be cleaned up automatically when the ResourceManager is disposed. This should only be done with short-lived ResourceManagers, as doing so with the global manager effectively leaks the resource.

Parameters:
  `descriptor` - descriptor for the image to create
Returns:
  the Image described by this descriptor (possibly shared by other equivalent ImageDescriptors)
Throws:
  `DeviceResourceException` - if unable to allocate the Image
Since:
  3.1

#### createImageWithDefault

    public final Image createImageWithDefault​(ImageDescriptor descriptor)

Creates an image, given an image descriptor. Images allocated in this manner must be disposed by `destroyImage(ImageDescriptor)`, and never by calling `Resource.dispose()`.

Parameters:
  `descriptor` - descriptor for the image to create
Returns:
  the Image described by this descriptor (possibly shared by other equivalent ImageDescriptors)
Since:
  3.1

#### getDefaultImage

    protected abstract Image getDefaultImage()

Returns the default image that will be returned in the event that the intended image is missing.

Returns:
  a default image that will be returned in the event that the intended image is missing.
Since:
  3.1

#### destroyImage

    public final void destroyImage​(ImageDescriptor descriptor)

Undoes everything that was done by `createImage(ImageDescriptor)`.

Parameters:
  `descriptor` - identifier for the image to dispose
Since:
  3.1

#### createColor

    public final Color createColor​(ColorDescriptor descriptor)

Allocates a color, given a color descriptor. Any color allocated in this manner must be disposed by calling `destroyColor(ColorDescriptor)`, or by an eventual call to `dispose()`. `Color.dispose()` must never been called directly on the returned color.

Parameters:
  `descriptor` - descriptor for the color to create
Returns:
  the Color described by the given ColorDescriptor (not null)
Throws:
  `DeviceResourceException` - if unable to create the color
Since:
  3.1

#### createColor

    public final Color createColor​(RGB descriptor)

Allocates a color, given its RGB value. Any color allocated in this manner must be disposed by calling `destroyColor(RGB)`, or by an eventual call to `dispose()`. `Color.dispose()` must never been called directly on the returned color.

Parameters:
  `descriptor` - descriptor for the color to create
Returns:
  the Color described by the given ColorDescriptor (not null)
Throws:
  `DeviceResourceException` - if unable to create the color
Since:
  3.1

#### destroyColor

    public final void destroyColor​(RGB descriptor)

Undoes everything that was done by a call to `createColor(RGB)`.

Parameters:
  `descriptor` - RGB value of the color to dispose
Since:
  3.1

#### destroyColor

    public final void destroyColor​(ColorDescriptor descriptor)

Undoes everything that was done by a call to `createColor(ColorDescriptor)`.

Parameters:
  `descriptor` - identifier for the color to dispose
Since:
  3.1

#### createFont

    public final Font createFont​(FontDescriptor descriptor)

Returns the Font described by the given FontDescriptor. Any Font allocated in this manner must be deallocated by calling disposeFont(...), or by an eventual call to `dispose()`. The method `Resource.dispose()` must never be called directly on the returned font.

Parameters:
  `descriptor` - description of the font to create
Returns:
  the Font described by the given descriptor
Throws:
  `DeviceResourceException` - if unable to create the font
Since:
  3.1

#### destroyFont

    public final void destroyFont​(FontDescriptor descriptor)

Undoes everything that was done by a previous call to `createFont(FontDescriptor)`.

Parameters:
  `descriptor` - description of the font to destroy
Since:
  3.1

#### dispose

    public void dispose()

Disposes any remaining resources allocated by this manager.

#### find

    public abstract Object find​(DeviceResourceDescriptor descriptor)

Returns a previously allocated resource associated with the given descriptor, or null if none exists yet.

Parameters:
  `descriptor` - descriptor to find
Returns:
  a previously allocated resource for the given descriptor or null if none.
Since:
  3.1

#### disposeExec

    public void disposeExec​(Runnable r)

Causes the `run()` method of the runnable to be invoked just before the receiver is disposed. The runnable can be subsequently canceled by a call to `cancelDisposeExec`.

Parameters:
  `r` - runnable to execute.

#### cancelDisposeExec

    public void cancelDisposeExec​(Runnable r)

Cancels a runnable that was previously scheduled with `disposeExec`. Has no effect if the given runnable was not previously registered with disposeExec.

Parameters:
  `r` - runnable to cancel