Class AbstractMediaHandler

  extended by
All Implemented Interfaces:
Direct Known Subclasses:
BaseImageMediaHandler, BasicIconBasedMediaHandler

public abstract class AbstractMediaHandler
extends java.lang.Object
implements MediaHandler

Base class for MediaHandler implementations.

This class is a good starting point for MediaHandler implementations to extend. It provides many useful methods common to most implementations.

The handleMetadata(MediaRequest, Resource, MediaItem) method makes use of SmetaMediaMetadata to extract metadata from media resources, so is able to handle any file type supported by the application's configuration of sMeta.

The configurable properties of this class are:

The DomainObjectFactory to use for creating new domain objects.
An instance of the MediaBiz to use.
An instance of the UserBiz for getting user locale information from.
The file extension to use for the media files processed by this MediaHandler. In many cases there is a one-to-one mapping of MediaHandler instances to file types they support, and thus will only need to return a single file extension at all times. This property can be configured with this file extension.
A MIME type to associate with this handler. Similarly to how the preferredFileExtension is configurable in this class, this MIME type property allows implementations to return a single MIME type for every file handled by each instance of this class.
An optional Map of JavaBean properties to apply to each SmetaMediaMetadata instance created in the getMediaMetadataInstance(MediaRequest, Resource, MediaItem) method. A Spring BeanWrapper is used on the newly created objects, so this provides a way to initialize properties on those objects after they are created.
A Set of MediaSize instances which should not have a watermark applied, if a user has a watermark configured. This defaults to all thumbnail sizes.

$Revision: 176 $ $Date: 2008-12-28 14:33:18 +1300 (Sun, 28 Dec 2008) $

Field Summary
protected  org.apache.log4j.Logger log
          A class Logger.
static java.lang.String METADATA_PARAMETER_KEY
          An MediaRequest parameter key for a cached MediaMetadata object.
Constructor Summary
AbstractMediaHandler(java.lang.String mime)
          Construct with MIME type.
Method Summary
protected  void applyEffects(MediaItem item, MediaRequest request, MediaResponse response)
          Apply the effects for a request.
protected  java.util.List<Metadata> createMetadataList(java.util.Map<java.lang.String,java.lang.String> map)
          Create a new List of Metadata instances from a Map.
protected  void defaultHandleRequestOriginal(MediaItem item, itemResource, MediaResponse response)
          Handle the original media data, without altering.
 DomainObjectFactory getDomainObjectFactory()
 MediaEffect getEffect(java.lang.String key, java.util.Map<java.lang.String,?> effectParameters)
          Get a MediaEffect instance for a specific key.
 java.lang.String getFileExtension(MediaItem item, MediaRequest request)
          Get the file extension.
 MediaBiz getMediaBiz()
protected  MediaMetadata getMediaMetadataInstance(MediaRequest request, mediaResource, MediaItem item)
          Get a MediaMetadata instance for the given resource.
 java.lang.String getMime()
 java.util.Set<MediaSize> getNoWatermarkSizes()
 java.lang.String getPreferredFileExtension()
protected  java.util.List<MediaEffect> getRequestEffects(MediaItem item, MediaRequest request)
          Get a list of effects to apply to a request.
 java.util.Map<java.lang.String,java.lang.Object> getSmetaPropertyMap()
 UserBiz getUserBiz()
protected  MediaMetadata handleMetadata(MediaRequest request, mediaResource, MediaItem item)
          Extract metadata from a resource and replace item metadata with all extracted data.
protected  boolean needToAlter(MediaItem item, MediaRequest request)
          Test if the current request needs to alter the original media item in some way or not.
protected  boolean needToRotate(MediaItem item, MediaRequest request)
          Check if rotation needs to be performed for a given media item.
 void setDomainObjectFactory(DomainObjectFactory domainObjectFactory)
 void setMediaBiz(MediaBiz mediaBiz)
 void setMime(java.lang.String mime)
 void setNoWatermarkSizes(java.util.Set<MediaSize> noWatermarkSizes)
 void setPreferredFileExtension(java.lang.String preferredFileExtension)
 void setSmetaPropertyMap(java.util.Map<java.lang.String,java.lang.Object> smetaPropertyMap)
 void setUserBiz(UserBiz userBiz)
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface magoffin.matt.ma2.MediaHandler
createNewMediaItem, handleMediaRequest

Field Detail


public static final java.lang.String METADATA_PARAMETER_KEY
An MediaRequest parameter key for a cached MediaMetadata object.

See Also:
Constant Field Values


protected final org.apache.log4j.Logger log
A class Logger.

Constructor Detail


public AbstractMediaHandler(java.lang.String mime)
Construct with MIME type.

mime - the MIME type
Method Detail


protected java.util.List<Metadata> createMetadataList(java.util.Map<java.lang.String,java.lang.String> map)
Create a new List of Metadata instances from a Map.

This will return a list of newly-constructed Metadata objects, using the keys of the map to call Metadata.setKey(String) and the corresponding map values to call Metadata.setValue(String). This can be useful for converting metadata properties returned by sMeta into Metadata objects for persisting on a MediaItem (i.e. by adding the list to MediaItem.getMetadata().

map - the map of properties to turn into Metadata
the list of newly created Metadata objects


protected MediaMetadata handleMetadata(MediaRequest request,
                                       MediaItem item)
Extract metadata from a resource and replace item metadata with all extracted data.

This method provides a simple way to populate the Metadata list of a newly created MediaItem. It will generate the list of Metadata and then add all of them into the List returned by MediaItem.getMetadata().

This method first calls getMediaMetadataInstance(MediaRequest, Resource, MediaItem) to create a new instance of MediaMetadata and then calls MediaMetadata.setMediaResource(Resource).

If MediaMetadata.getCreationDate() returns a non-null value then a new Calendar instance will be created from it and used to set the creationDate property of the MediaItem.

If the MediaMetadata is an instance of EmbeddedImageMetadata then EmbeddedImageMetadata.getEmbeddedImage() will be called, and the width/height of the returned image will be used to set the width/height properties of the MediaItem provided.

request - the reqeust (may be null)
mediaResource - the media resource to extract the metadata from
item - the item to replace the extracted metadata in
the resulting metadata instance


protected MediaMetadata getMediaMetadataInstance(MediaRequest request,
                                                 MediaItem item)
Get a MediaMetadata instance for the given resource.

This implementation returns a new SmetaMediaMetadata instance. Extending classes may want to change this behavior or set properties onto the returned instance.

If the getSmetaPropertyMap() is configured, then the created instance will have all the properties defined in that Map set onto it before being returned. This allows the instance to be easily configured. The properties are set via a Spring BeanWrapper so should follow those naming conventions.

If the request parameter is not null then the SmetaMediaMetadata instance will also be placed into the parameter Map of the MediaRequest, using the key METADATA_PARAMETER_KEY.

request - the reqeust (may be null)
mediaResource - the resource
item - the item
a new MediaMetadata instance


public java.lang.String getFileExtension(MediaItem item,
                                         MediaRequest request)
Get the file extension.

This method simply returns getPreferredFileExtension(). Extending class may override this for request-specific handling.

Specified by:
getFileExtension in interface MediaHandler
item - the media item to process
request - the request
a file extension, without the period


public MediaEffect getEffect(java.lang.String key,
                             java.util.Map<java.lang.String,?> effectParameters)
Description copied from interface: MediaHandler
Get a MediaEffect instance for a specific key.

Implementaions must define the keys they support, and define the parameters that go with it.

Specified by:
getEffect in interface MediaHandler
key - the key of the desired effect
effectParameters - a Map of parameters (optional)
a MediaEffect instance


protected java.util.List<MediaEffect> getRequestEffects(MediaItem item,
                                                        MediaRequest request)
Get a list of effects to apply to a request.

This method provides a way to create a list of standard effects useful for every request:

  1. Resizing: scaling to the size requested by MediaRequest.getSize(). If the requested width/height are not the same as those returned by MediaItem.getWidth() and MediaItem.getHeight() then this method will call MediaHandler.getEffect(String, Map) using the key MediaEffect.KEY_SCALE.
  2. Rotation: if the MediaRequest.getParameters() contains the key MediaEffect.MEDIA_REQUEST_PARAM_ROTATE_DEGREES, then this method will call MediaHandler.getEffect(String, Map) using the key MediaEffect.KEY_ROTATE.

Extending classes that wish to support additional effects can override this method, adding any additional effects to the returned list as desired.

item - the item the effects are to be applied to
request - the current request
list of effects (or empty list of no effects appropriate for this request)


protected void applyEffects(MediaItem item,
                            MediaRequest request,
                            MediaResponse response)
Apply the effects for a request.

This method provides a default way to apply effects to a media request.

This method will call getRequestEffects(MediaItem, MediaRequest) and the call MediaEffect.apply(MediaItem, MediaRequest, MediaResponse) for each effect returned. Note the MediaHandler implementation must have set up any required parameters needed by the effects prior to calling this method.

item - the item to apply the effects to
request - the current request
response - the current response


protected boolean needToAlter(MediaItem item,
                              MediaRequest request)
Test if the current request needs to alter the original media item in some way or not.

This method provides a way test if there are any alterations needed to satifsy the request, including:

  1. Resize (scale): if the request is for a size different from the MediaItem.getWidth() or MediaItem.getHeight().
  2. Recompress: if the request is not for MediaQuality.HIGHEST.
  3. Effects: if MediaRequest.getEffects() has at least one effect in it.
  4. Rotate: if needToRotate(MediaItem, MediaRequest) returns true.

If any of these are found to be true then this method will also return true.

item - the item being tested
request - the current request


protected boolean needToRotate(MediaItem item,
                               MediaRequest request)
Check if rotation needs to be performed for a given media item.

This method will return true if any of the following are found to be true:

  1. The MediaRequest.getParameters() Map contains a key MediaEffect.MEDIA_REQUEST_PARAM_ROTATE_DEGREES.
  2. The MediaRequest.getEffects() contains an effect where MediaEffect.getKey() ends with MediaEffect.KEY_ROTATE.

item - the item
request - the request


protected void defaultHandleRequestOriginal(MediaItem item,
                                            MediaResponse response)
Handle the original media data, without altering.

This method will call MediaResponse.setMimeType(String) with the value of getMime(). Then it will call MediaResponse.setMediaLength(long) with the value returned by the itemResource's File File.length(). It will also call MediaResponse.setModifiedDate(long) with the value returned by File.lastModified().

Finally, it will copy the file to the MediaResponse.getOutputStream().

item - the item to handle
itemResource - the item's Resource
response - the response


public DomainObjectFactory getDomainObjectFactory()
Returns the domainObjectFactory.


public void setDomainObjectFactory(DomainObjectFactory domainObjectFactory)
domainObjectFactory - The domainObjectFactory to set.


public MediaBiz getMediaBiz()
Returns the mediaBiz.


public void setMediaBiz(MediaBiz mediaBiz)
mediaBiz - The mediaBiz to set.


public java.lang.String getPreferredFileExtension()
Returns the preferredFileExtension.


public void setPreferredFileExtension(java.lang.String preferredFileExtension)
preferredFileExtension - The preferredFileExtension to set.


public java.lang.String getMime()
the mime


public void setMime(java.lang.String mime)
mime - the mime to set


public java.util.Map<java.lang.String,java.lang.Object> getSmetaPropertyMap()
the smetaPropertyMap


public void setSmetaPropertyMap(java.util.Map<java.lang.String,java.lang.Object> smetaPropertyMap)
smetaPropertyMap - the smetaPropertyMap to set


public UserBiz getUserBiz()
the userBiz


public void setUserBiz(UserBiz userBiz)
userBiz - the userBiz to set


public java.util.Set<MediaSize> getNoWatermarkSizes()
the noWatermarkSizes


public void setNoWatermarkSizes(java.util.Set<MediaSize> noWatermarkSizes)
noWatermarkSizes - the noWatermarkSizes to set