com.communote.server.api.core.image

Interface ImageManager

All Known Implementing Classes:

FileSystemCachingImageManager

public interface ImageManager

Service for accessing different kinds of images in different sizes (width-height dimension). To support a certain image type like a user profile picture, an ImageTypeDescriptor can be registered along with an ImageProvider which is responsible for retrieving the full-size (= unscaled) image.

On startup a set of built-in image types and providers are added automatically.

Author:

Communote GmbH - http://www.communote.com/

Method Summary

Modifier and Type	Method and Description
void	defaultImageChanged(String typeName, String providerIdentifier) Inform the image manager that the default image of the given provider changed.
Image	getImage(String typeName, ImageDescriptor descriptor) Get an image
Image	getImage(String typeName, Map<String,? extends Object> parameters, ImageSizeType size) Get an image
Image	getImage(String typeName, String imageIdentifier, ImageSizeType size) Get an image
ImageSize	getImageSize(String typeName, ImageSizeType sizeType) Map the size type constant to the actual size.
String	getImageVersionString(String typeName, String imageIdentifier) Return a string which represents the version of the image.
void	imageChanged(String typeName, String providerIdentifier, String imageIdentifier) Inform the image manager that an image was changed.
void	registerImageProvider(String imageTypeName, ImageProvider provider) Register an image provider which can load images for the given image type.
void	registerImageType(ImageTypeDescriptor imageType) Register an image type.
void	unregisterImageProvider(String imageTypeName, ImageProvider provider) Remove an image provider which was added for a given image type.
void	unregisterImageType(ImageTypeDescriptor imageType) Remove a previously registered image type.

Method Detail

defaultImageChanged

void defaultImageChanged(String typeName,
                         String providerIdentifier)

Inform the image manager that the default image of the given provider changed. The image manager will clear caches and notify the provider about the change. To avoid unnecessary cache invalidations the caller should provide as much details as possible.

Parameters:

typeName - the type of the image that changed. If there is no provider for the image type, this call has no effect.

providerIdentifier - the ID of the ImageProvider that loaded the changed image. If null, all providers that are registered for that type are considered.

getImage

Image getImage(String typeName,
               ImageDescriptor descriptor)
        throws AuthorizationException,
               IOException,
               ImageNotFoundException

Get an image

Parameters:

typeName - Name of the image type

descriptor - the descriptor with image ID and details about scaling

Returns:

The image or the default image, if there is one.

Throws:

AuthorizationException - in case the current user has no access to the image

IOException - in case retrieving or scaling the image failed

ImageNotFoundException - in case the image type is not known or there is no provider for the image type or the provider has no image for the descriptor and a default image doesn't exist neither

getImage

Image getImage(String typeName,
               Map<String,? extends Object> parameters,
               ImageSizeType size)
        throws AuthorizationException,
               IOException,
               ImageNotFoundException

Get an image

Parameters:

typeName - the name of the type of the image

parameters - the parameters as a key to value mapping which can contain the image identifier. The ImageTypeDescriptor identified by the typeName will be used to extract the identifier.

size - the size type constant which will be mapped to the actual size

Returns:

the image

Throws:

AuthorizationException - in case the current user has no access to the image

IOException - in case retrieving or scaling the image failed

ImageNotFoundException - in case the image type is not known or there is no provider for the image type or the provider has no image for the extracted identifier and a default image doesn't exist neither

getImage

Image getImage(String typeName,
               String imageIdentifier,
               ImageSizeType size)
        throws AuthorizationException,
               IOException,
               ImageNotFoundException

Get an image

Parameters:

typeName - the name of the type of the image

imageIdentifier - the identifier of the image

size - the size type constant which will be mapped to the actual size

Returns:

the image

Throws:

AuthorizationException - in case the current user has no access to the image

IOException - in case retrieving or scaling the image failed

ImageNotFoundException - in case the image type is not known or there is no provider for the image type or the provider has no image for the identifier and a default image doesn't exist neither

getImageSize

ImageSize getImageSize(String typeName,
                       ImageSizeType sizeType)

Map the size type constant to the actual size.

Parameters:

typeName - the name of the image type

sizeType - the size type constant to map

Returns:

the image size or null if there if no image type descriptor for the type was registered

getImageVersionString

String getImageVersionString(String typeName,
                             String imageIdentifier)
                      throws ImageNotFoundException,
                             AuthorizationException

Return a string which represents the version of the image. Whenever an image is modified the version string will usually change. If the image does not exist but the provider has a default image, the version string of that image is returned
This result of this method can be used to create a unique URL to image to bypass caches of clients like browsers.

Parameters:

typeName - Name of the image type.

imageIdentifier - identifier of the image

Returns:

The version string

Throws:

ImageNotFoundException - in case there is no provider for that image type or the image with the identifier does not exist the provider has no default image

AuthorizationException - in case the current user is not allowed to access the image

imageChanged

void imageChanged(String typeName,
                  String providerIdentifier,
                  String imageIdentifier)

Inform the image manager that an image was changed. The image manager will clear caches and notify the provider about the change. To avoid unnecessary cache invalidations the caller should provide as much details as possible.

Parameters:

typeName - the type of the image that changed. If there is no provider for the image type, this call has no effect.

providerIdentifier - the ID of the ImageProvider that loaded the changed image. If null, all providers that are registered for that type are considered.

imageIdentifier - the ID of the image that changed. If null, all images of the provider are treated as having changed.

registerImageProvider

void registerImageProvider(String imageTypeName,
                           ImageProvider provider)
                    throws ImageProviderManagerException,
                           ImageTypeNotFoundException

Register an image provider which can load images for the given image type. There can be several providers for a type.

Parameters:

imageTypeName - the name of the type which must have been registered before

provider - the provider to add

Throws:

ImageProviderManagerException - in case there is already a provider with the same identifier

ImageTypeNotFoundException - in case the image type does not exist

registerImageType

void registerImageType(ImageTypeDescriptor imageType)

Register an image type. If there is already a type with the same name the new one will be an overlay for the existing, that is, it will become the active descriptor for that type. The existing descriptor will become the active one as soon as the overlay is unregistered. Such an overlay is for instance useful for changing the supported image sizes. After adding a type, providers for that type can be registered.

Parameters:

imageType - the descriptor of the type

Throws:

IllegalArgumentException - in case the type has no name

unregisterImageProvider

void unregisterImageProvider(String imageTypeName,
                             ImageProvider provider)
                      throws ImageProviderManagerException

Remove an image provider which was added for a given image type. If the type or the provider do not exist the call is ignored.

Parameters:

imageTypeName - the name of the type

provider - the provider to remove

Throws:

ImageProviderManagerException - in case the provider to remove is a built-in provider

unregisterImageType

void unregisterImageType(ImageTypeDescriptor imageType)

Remove a previously registered image type. If there are several types with the same name and the type to remove is the active one the next type which was registered before this type will become the active one.
Providers will not be removed by this method, even if there are no more types with the same name. However, accessing images of the type is not possible anymore.
If the type to remove does not exist the call is ignored.

Parameters:

imageType - the type to remove