org.hd.d.pg2k.svrCore.MIME
Class AbstractHandler

java.lang.Object
  org.hd.d.pg2k.svrCore.MIME.AbstractHandler

All Implemented Interfaces:

Handler

Direct Known Subclasses:

AbstractImageHandler, AbstractSampledSoundHandler, mid, mp3, swf

public abstract class AbstractHandler
extends java.lang.Object
implements Handler

Base class implementing Handler with nearly all methods returning default values. This makes implementation of a new concrete handler as easy as possible.

The concrete implementation must provide getExhibitType().

AbstractHandler

public AbstractHandler()

get2DImageDimensions

public java.awt.Dimension get2DImageDimensions(java.io.InputStream is)
                                        throws java.io.IOException

Efficiently get X,Y pixel dimensions of an image exhibit, else null if dimensions cannot be computed. This will always return null for items which do not have a fixed X,Y size in pixels such as for AU sound files for example.

For something like a movie in a fixed frame this may be able to return its dimensions, eg to embed in a page.

This does not close its input stream when done.

This should work efficiently, by directly reading (opening) bytes of the exhibit passed as an input stream.

This will only work correctly if the exhibit is of the correct type, eg its magic number must already have been tested.

Specified by:

get2DImageDimensions in interface Handler

Parameters:

is - the exhibit as a binary data stream

Throws:

java.io.IOException - in case of problems with corrupt data (or a broken exhibit)

canMakeThumbnails

public boolean canMakeThumbnails()

Returns true if handler can make thumbnails for this type. makeThumbnails() has to be able to succeed for some real exhibits of this type, producing thumbnails/samples of the same MIME type (though possibly at much-reduced fidelity), but makeThumbnails() need not succeed for all exhibits of this type.

By default, returns false, ie thumbnails cannot be made.

Specified by:

canMakeThumbnails in interface Handler

getThumbnailParams

public Handler.ThumbnailParams getThumbnailParams()

Get ThumbnailParameters for a particular handler. A handler that does not build thumbnails (ie canMakeThumbnails() returns false) may return null for this, which is the default, but otherwise this should return non-null.

This is assumed to be fast, ie to return a fixed static instance for each handler.

This is protected, since only the support routines in this base class need access this data.

Specified by:

getThumbnailParams in interface Handler

makeSizeConstrainedEncodedImage

public byte[] makeSizeConstrainedEncodedImage(int lowerQualityBound,
                                              int initialQualityHint,
                                              int upperQualityBound,
                                              java.awt.image.BufferedImage scaledImage,
                                              int targetMin,
                                              int targetMax,
                                              int absMinSize,
                                              int absMaxSize,
                                              int targetBytes)
                                       throws java.io.IOException,
                                              java.lang.IllegalArgumentException

Make a byte[]-encoded image of this type constained above and below by size; null if not possible. This uses a binary-chop algorithm to attempt to quickly find the optimal "quality" to make the image at, lower quality values asking the encoder to discard more information, eg by doing colour reduction or other quantisation.

This is not possible for all exhibit types.

Specified by:

makeSizeConstrainedEncodedImage in interface Handler

Parameters:

upperQualityBound - maximum value of quality to use; non-negative

lowerQualityBound - minimum value of quality to use; non-negative and no greater than upperQualityBound

initialQualityHint - initial suggested quality hint; non-negative, no greater than upperQualityBound, no less than lowerQualityBound

scaledImage - the input image to encode

targetMin - target lower bound, should be higher than absMinSize

targetMax - target upper bound, should be lower than absMaxSize

absMinSize - absolute minimum number of bytes

absMaxSize - absolute maximum number of bytes

targetBytes - target number of bytes

Returns:

encoded image, or null if the image cannot be generated with given constraints

Throws:

java.io.IOException - in case of difficulty generating the image

java.lang.IllegalArgumentException - if the arguments are invalid

makeThumbnails

public ExhibitThumbnails makeThumbnails(java.io.InputStream is,
                                        long originalLength)
                                 throws java.io.IOException

Make thumbnails/samples for the specified exhibit; null if not possible. This may fail with an IOException or return null to indicate that it is currently unable to create thumbnails/samples (though this condition may be temporary).

If this wishes to indicate that it cannot ever make one or more thumbnails/samples for a given exhibit then this should return a ExhibitThumbnails object with one or both thumbnails set to null.

(If canMakeThumbnails() returns false, this should return null.)

This does not close its input stream when done.

This will only work correctly if the exhibit is of the correct type, eg its magic number must already have been tested.

This assumes enough memory and other resource is available.

Specified by:

makeThumbnails in interface Handler

Parameters:

is - the whole raw image positioned at its start

originalLength - is the length of the encoded original in bytes; always positive and must reflect the stream input and will be constrained to Integer.MAX_VALUE if larger

Returns:

thumbnails, else null if not possible now; ExhibitThumbnails.NO_THUMBNAILS may be returned if it looks like it never be possible/sensible to make thumbnails for this exhibit

Throws:

java.io.IOException

makeThumbnails

public ExhibitThumbnails makeThumbnails(ExhibitStaticAttr esa,
                                        AllExhibitProperties.ExhibitDataSource eds,
                                        AllExhibitProperties aep,
                                        boolean unlimitedResources)
                                 throws java.io.IOException

Make thumbnails/samples for the specified exhibit; null or ExhibitThumbnails.NO_THUMBNAILS if not possible. A data source for the exhibit must be supplied, along with all available properties of that exhibit.

This may fail with an IOException or return null to indicate that it is currently unable to create thumbnails/samples (though this condition may be temporary).

If this wishes to indicate that it cannot make one or more thumbnails/samples for a given exhibit then this should return a ExhibitThumbnails object with one or both thumbnails set to null.

(If canMakeThumbnails() returns false, this should return null.)

By default, returns null, ie thumbnails cannot be made.

This routine regulates memory use, rejecting the attempt to make the thumbnails if it cannot find/reserve sufficient memory using MemoryTools.runMemoryIntensiveOperation().

Calls the InputStream version of makeThumbnails().

Specified by:

makeThumbnails in interface Handler

Parameters:

unlimitedResources - if true, the generation routine is allowed to try to use unlimited resources (especially memory)

Returns:

thumbnails, else null if not possible now; ExhibitThumbnails.NO_THUMBNAILS may be returned if it looks like it never be possible/sensible to make thumbnails for this exhibit

Throws:

java.io.IOException

makeImageBinary

public byte[] makeImageBinary(java.awt.image.BufferedImage imageIn,
                              int quality)
                       throws java.io.IOException

Return image as file-format byte array; null if not possible. This should only be used for making an image that is compatable with the output format, eg trying to build a GIF from a true-colour image is unlikely to work.

This is used for still images and possible animations or movies where the bounding rectangle and the contained data is scaled to the given bounds.

The output image will, if possible, use the same colour scheme and other characteristics as the input, though some optional features that usually consume extra space, such as interlacing, may be disabled.

If no output can be generated then this returns null, which is the default behaviour.

This should adjust the image "quality" with the detail value (adjusted within the bounds supplied by the handler class) to try to tune the output size. For a lossy encoding format such as JPEG this may be the "quality" factor or compression. For a lossless format the may have to be the number of bits-per-pixel that a colour map is reduced to, for example. If at all possible, no value of the quality parameter should cause null to be returned if there is any value that can generate a valud image, and output size should not decrease at any point as the value of the quality parameter increases, else some routines such as thumbnail generation will not work well.

The quality parameter usage is format- and implementation- dependent, but 0 will generally be the lowest-quality rendering available and 100 will be the highest, with values in between monotonically increasing, though that does not mean that there will be any distinguishable different in the output with any pair of adjacent (or indeed any) quality values.

Specified by:

makeImageBinary in interface Handler

Parameters:

imageIn - source image; must not be null and must be suitable for the target format

quality - hint as to how good to make the target image in norminal range [0-100]; anything above 100 (eg Integer.MAX_VALUE) indicates maximum quality

Throws:

java.io.IOException

decodeImage

public java.awt.image.BufferedImage decodeImage(java.io.InputStream is)
                                         throws java.io.IOException

Decode image as BufferedImage, or null if not possible. This does not close its input stream when done.

By default, returns null.

Specified by:

decodeImage in interface Handler

Throws:

java.io.IOException

getMetadata

public org.w3c.dom.Node getMetadata(java.io.InputStream is,
                                    Name.ExhibitFull exhibitName)

Gets all available exhibit metadata as a single XML DOM tree; null if none. We do not (yet) have a schema for this and may never do so, since its structure and content will depend on various external sources and parts of (for example) the ImageIO and JAI subsystems.

Specified by:

getMetadata in interface Handler

Parameters:

is - input stream; never null

exhibitName - TODO

Returns:

top-level node "metadata" with captured metadata beneath, else null