Class ResourceManager
- Direct Known Subclasses:
DeviceResourceManager
,LazyResourceManager
,LocalResourceManager
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
-
Method Summary
Modifier and TypeMethodDescriptionvoid
Cancels a runnable that was previously scheduled withdisposeExec(Runnable)
.abstract <R> R
create
(DeviceResourceDescriptor<R> descriptor) Returns the resource described by the given descriptor.final Color
createColor
(ColorDescriptor descriptor) Deprecated.final Color
createColor
(RGB descriptor) Allocates a color, given its RGB value.final Font
createFont
(FontDescriptor descriptor) Deprecated.usecreate(DeviceResourceDescriptor)
insteadfinal Image
createImage
(ImageDescriptor descriptor) Deprecated.usecreate(DeviceResourceDescriptor)
insteadfinal Image
createImageWithDefault
(ImageDescriptor descriptor) Creates an image, given an image descriptor.abstract <R> void
destroy
(DeviceResourceDescriptor<R> descriptor) Deallocates a resource previously allocated bycreate(DeviceResourceDescriptor)
.final void
destroyColor
(ColorDescriptor descriptor) Deprecated.usedestroy(DeviceResourceDescriptor)
insteadfinal void
destroyColor
(RGB descriptor) Undoes everything that was done by a call tocreateColor(RGB)
.final void
destroyFont
(FontDescriptor descriptor) Deprecated.usedestroy(DeviceResourceDescriptor)
insteadfinal void
destroyImage
(ImageDescriptor descriptor) Deprecated.usedestroy(DeviceResourceDescriptor)
insteadvoid
dispose()
Disposes any remaining resources allocated by this manager.void
Causes therun()
method of the runnable to be invoked just before the receiver is disposed.abstract <R> R
find
(DeviceResourceDescriptor<R> descriptor) Returns a previously allocated resource associated with the given descriptor, or null if none exists yet.final <R> R
get
(DeviceResourceDescriptor<R> descriptor) Returns a previously-allocated resource or allocates a new one if none exists yet.protected abstract Image
Returns the default image that will be returned in the event that the intended image is missing.abstract Device
Returns the Device for which this ResourceManager will create resources
-
Constructor Details
-
ResourceManager
public ResourceManager()
-
-
Method Details
-
getDevice
Returns the Device for which this ResourceManager will create resources- Returns:
- the Device associated with this ResourceManager
- Since:
- 3.1
-
create
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 todestroy(DeviceResourceDescriptor)
.If the resource is intended to live for entire lifetime of this resource-manager, a subsequent call to
destroy(DeviceResourceDescriptor)
may be omitted and the resource will be cleaned up when this resource-manager is disposed. This pattern is useful for short-livedLocalResourceManager
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.- 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
Deallocates a resource previously allocated bycreate(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
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 this 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.This method should only be used for resources that should remain allocated for the lifetime of this resource-manager. To allocate shorter-lived resources, manage them with
create
, anddestroy
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
Deprecated.usecreate(DeviceResourceDescriptor)
insteadCreates an image, given an image descriptor. Images allocated in this manner must be disposed by
destroyImage(ImageDescriptor)
, and never by callingResource.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
Creates an image, given an image descriptor. Images allocated in this manner must be disposed bydestroyImage(ImageDescriptor)
, and never by callingResource.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
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
Deprecated.usedestroy(DeviceResourceDescriptor)
insteadUndoes everything that was done bycreateImage(ImageDescriptor)
.- Parameters:
descriptor
- identifier for the image to dispose- Since:
- 3.1
-
createColor
Deprecated.usecreate(DeviceResourceDescriptor)
insteadAllocates a color, given a color descriptor. Any color allocated in this manner must be disposed by callingdestroyColor(ColorDescriptor)
, or by an eventual call todispose()
.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
Allocates a color, given its RGB value. Any color allocated in this manner must be disposed by callingdestroyColor(RGB)
, or by an eventual call todispose()
.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
Undoes everything that was done by a call tocreateColor(RGB)
.- Parameters:
descriptor
- RGB value of the color to dispose- Since:
- 3.1
-
destroyColor
Deprecated.usedestroy(DeviceResourceDescriptor)
insteadUndoes everything that was done by a call tocreateColor(ColorDescriptor)
.- Parameters:
descriptor
- identifier for the color to dispose- Since:
- 3.1
-
createFont
Deprecated.usecreate(DeviceResourceDescriptor)
insteadReturns the Font described by the given FontDescriptor. Any Font allocated in this manner must be deallocated by calling disposeFont(...), or by an eventual call todispose()
. The methodResource.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
Deprecated.usedestroy(DeviceResourceDescriptor)
insteadUndoes everything that was done by a previous call tocreateFont(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
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
Causes therun()
method of the runnable to be invoked just before the receiver is disposed. The runnable can be subsequently canceled by a call tocancelDisposeExec(Runnable)
.- Parameters:
r
- runnable to execute.
-
cancelDisposeExec
Cancels a runnable that was previously scheduled withdisposeExec(Runnable)
. Has no effect if the given runnable was not previously registered with disposeExec.- Parameters:
r
- runnable to cancel
-
create(DeviceResourceDescriptor)
instead