public abstract class ResourceManager extends Object
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.
Constructor and Description |
---|
ResourceManager() |
Modifier and Type | Method and Description |
---|---|
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
|
public abstract Device getDevice()
public abstract Object create(DeviceResourceDescriptor descriptor)
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.
descriptor
- descriptor for the resource to allocateDeviceResourceException
- if unable to allocate the resourcepublic abstract void destroy(DeviceResourceDescriptor descriptor)
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.descriptor
- identifier for the resourcepublic 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.
descriptor
- identifier for the requested resourceDeviceResourceException
- if the resource does not exist yet and cannot
be created for any reason.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.
descriptor
- descriptor for the image to createDeviceResourceException
- if unable to allocate the Imagepublic final Image createImageWithDefault(ImageDescriptor descriptor)
destroyImage(ImageDescriptor)
, and never by calling
Resource.dispose()
.descriptor
- descriptor for the image to createprotected abstract Image getDefaultImage()
public final void destroyImage(ImageDescriptor descriptor)
createImage(ImageDescriptor)
.descriptor
- identifier for the image to disposepublic final Color createColor(ColorDescriptor descriptor)
destroyColor(ColorDescriptor)
,
or by an eventual call to dispose()
. Resource.dispose()
must
never been called directly on the returned color.descriptor
- descriptor for the color to createDeviceResourceException
- if unable to create the colorpublic final Color createColor(RGB descriptor)
destroyColor(RGB)
,
or by an eventual call to dispose()
. Resource.dispose()
must
never been called directly on the returned color.descriptor
- descriptor for the color to createDeviceResourceException
- if unable to create the colorpublic final void destroyColor(RGB descriptor)
createColor(RGB)
.descriptor
- RGB value of the color to disposepublic final void destroyColor(ColorDescriptor descriptor)
createColor(ColorDescriptor)
.descriptor
- identifier for the color to disposepublic final Font createFont(FontDescriptor descriptor)
dispose()
. The method Resource.dispose()
must never be called directly on the returned font.descriptor
- description of the font to createDeviceResourceException
- if unable to create the fontpublic final void destroyFont(FontDescriptor descriptor)
createFont(FontDescriptor)
.descriptor
- description of the font to destroypublic void dispose()
public abstract Object find(DeviceResourceDescriptor descriptor)
descriptor
- descriptor to findpublic void disposeExec(Runnable r)
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
.r
- runnable to execute.public void cancelDisposeExec(Runnable r)
disposeExec
.
Has no effect if the given runnable was not previously registered with
disposeExec.r
- runnable to cancel
Copyright (c) 2000, 2014 Eclipse Contributors and others. All rights reserved.Guidelines for using Eclipse APIs.