javax.media.jai
Interface PropertySource

All Known Subinterfaces:

ImageJAI, OperationNode, WritablePropertySource

All Known Implementing Classes:

PropertySourceImpl

public interface PropertySource

An interface encapsulating the set of operations involved in identifying and reading properties.

The interface includes the getProperty() and getPropertyNames() methods familiar from the RenderedImage and RenderableImage interfaces. Classes which implement this interface should do so in a manner which treats the property names as case-retentive. That is to say that as concerns operations effected using the property name as a key, the operation should ignore the case of the property name while on the other hand the property name retrieval methods should return the names with their case preserved.

PropertySource is implemented by the ImageJAI interface and, among other classes, by PlanarImage, RenderableOp and CollectionImage. Since all RenderedImages used with JAI are "wrapped" by a RenderedImageAdapter, all JAI RenderedImages may be assumed to implement PropertySource.

If a PropertySource is also a PropertyChangeEmitter then it should fire PropertySourceChangeEvents to all registered listeners whenever this is reasonable to do so in the context of the PropertySource in question.

Property name space collisions may be prevented by adhering to an hierarchical naming convention. This could for example be based on the name of the package in question, e.g., com.sun.media.jai.MyProperty. The names of properties generated by JAI itself will not adhere to the aforementioned naming convention, but this should not pose a problem if users adopt this convention for their own property names.

Another approach to handling multiple property name spaces would be to define a separate PropertySource for each name space of properties. These PropertySources could themselves be attached to images as properties. Inheritance of these properties would occur by the default mechanism. Modification of these properties within an operation chain could be managed by PropertyGenerators which are capable of recognizing these properties. Note that a potential problem with this approach exists when a PropertySourceChangeEvent is fired: it might be necessary to clone the entire tree of properties in order to obtain the old value of event object.

See Also:

ImageJAI, PlanarImage, PropertyChangeEmitter, WritablePropertySource, RenderedImage, RenderableImage

Method Summary

Object	getProperty(String propertyName) Returns the value of a property.
Class	getPropertyClass(String propertyName) Returns the class expected to be returned by a request for the property with the specified name.
String[]	getPropertyNames() Returns an array of Strings recognized as names by this property source.
String[]	getPropertyNames(String prefix) Returns an array of Strings recognized as names by this property source that begin with the supplied prefix.

Method Detail

getPropertyNames

public String[] getPropertyNames()

Returns an array of Strings recognized as names by this property source. If no properties are available, null will be returned.

Returns:

an array of Strings giving the valid property names or null.

getPropertyNames

public String[] getPropertyNames(String prefix)

Returns an array of Strings recognized as names by this property source that begin with the supplied prefix. If no property names match, null will be returned. The comparison is done in a case-independent manner.

Returns:

an array of Strings giving the valid property names.

Throws:

IllegalArgumentException - if prefix is null.

getPropertyClass

public Class getPropertyClass(String propertyName)

Returns the class expected to be returned by a request for the property with the specified name. If this information is unavailable, null will be returned indicating that getProperty(propertyName).getClass() should be executed instead. A null value might be returned for example to prevent generating the value of a deferred property solely to obtain its class. null will also be returned if the requested property is not emitted by this property source.

Parameters:

propertyName - the name of the property, as a String.

Returns:

The Class expected to be return by a request for the value of this property or null.

Throws:

IllegalArgumentException - if propertyName is null.

Since:

JAI 1.1

getProperty

public Object getProperty(String propertyName)

Returns the value of a property. If the property name is not recognized, java.awt.Image.UndefinedProperty will be returned.

Parameters:

propertyName - the name of the property, as a String.

Returns:

the value of the property, as an Object, or the value java.awt.Image.UndefinedProperty.

Throws:

IllegalArgumentException - if propertyName is null.