org.hd.d.pg2k.svrCore.MIME
Interface Handler

All Known Implementing Classes:

AbstractHandler, AbstractImageHandler, AbstractSampledSoundHandler, au, bmp, gif, jp2, jpg, mid, mp3, png, swf, tif, wav

public interface Handler

Interface for exhibit media-handler classes. The media handlers do such things as make thumbnails/samples, and are loaded by name to allow for run-time configuration and presence/absence of such items as Sun's JPEG support.

Implementing classes must have an public non-args descriptor so that we can use Class.forName() to manufacture instances.

Implementing classes must be immutable and stateless and thread-safe, so that one instance can be shared between many threads.

Both CPU time and memory will be severe run-time constraints on implementing classes, and they must allow for concurrent operation with many other instances or internally reduce concurrency (eg with static locks).

This interface represents a ``fat'' API, ie implementing classes may not implement all of the API at run-time but return default/failure values instead.

TAG_NAME_METADATA_TOP

static final java.lang.String TAG_NAME_METADATA_TOP

Top-level node name for exhibit meta-data; never null or empty.

See Also:

Constant Field Values

getExhibitType

ExhibitMIME.ExhibitTypeParameters getExhibitType()

Get internal type of ExhibitMIME type; never null.

get2DImageDimensions

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

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 generally be efficient, by directly reading (opening) bytes of the exhibit passed as an input stream, if at all possible, but generic implementations may be very slow.

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

Parameters:

is - the exhibit as a binary data stream

Throws:

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

makeSizeConstrainedEncodedImage

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 constrained above and below by size. 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.

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

getThumbnailParams

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.

canMakeThumbnails

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.

makeThumbnails

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

Make thumbnails/samples for the specified 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 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.

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

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

Make thumbnails/samples for the specified exhibit. 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().

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

decodeImage

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

Decode image as BufferedImage, or null if not possible. The input stream must be non-null and of the correct exhibit type else behaviour is undefined.

This does not close its input stream when done.

Throws:

java.io.IOException

makeImageBinary

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

Return image as file-format byte array. This should only be used for making an image that is compatible 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 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.

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.

Parameters:

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

quality - desired encoding quality in range 0--100 inclusive, with 0 interpreted as "high compression is important," and 100 (or over) interpreted as "high image quality is important."; this parameter is ignored where it does not make sense for the format

Throws:

java.io.IOException

getMetadata

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.

Under extreme circumstances, eg with damaged exhibit files, this may throw Error or other RuntimeException values, though implementations should try to return null rather than do this if the error appears to be permanent.

Parameters:

is - input stream; never null

exhibitName - TODO

Returns:

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