001: /*
002: * $RCSfile: PropertySource.java,v $
003: *
004: * Copyright (c) 2005 Sun Microsystems, Inc. All rights reserved.
005: *
006: * Use is subject to license terms.
007: *
008: * $Revision: 1.1 $
009: * $Date: 2005/02/11 04:57:17 $
010: * $State: Exp $
011: */
012: package javax.media.jai;
013:
014: /**
015: * An interface encapsulating the set of operations involved in
016: * identifying and reading properties.
017: *
018: * <p> The interface includes the <code>getProperty()</code> and
019: * <code>getPropertyNames()</code> methods familiar from the
020: * <code>RenderedImage</code> and <code>RenderableImage</code> interfaces.
021: * Classes which implement this interface should do so in a manner which
022: * treats the property names as case-retentive. That is to say that as
023: * concerns operations effected using the property name as a key, the
024: * operation should ignore the case of the property name while on the
025: * other hand the property name retrieval methods should return the names
026: * with their case preserved.
027: *
028: * <p> <code>PropertySource</code> is implemented by the <code>ImageJAI</code>
029: * interface and, among other classes, by <code>PlanarImage</code>,
030: * <code>RenderableOp</code> and <code>CollectionImage</code>.
031: * Since all <code>RenderedImage</code>s used with JAI are "wrapped"
032: * by a <code>RenderedImageAdapter</code>, all JAI <code>RenderedImage</code>s
033: * may be assumed to implement <code>PropertySource</code>.
034: *
035: * <p> If a <code>PropertySource</code> is also a
036: * <code>PropertyChangeEmitter</code>
037: * then it should fire <code>PropertySourceChangeEvent</code>s to all
038: * registered listeners whenever this is reasonable to do so in the context
039: * of the <code>PropertySource</code> in question.
040: *
041: * <p> Property name space collisions may be prevented by adhering to
042: * an hierarchical naming convention. This could for example be based
043: * on the name of the package in question, e.g.,
044: * <i>com.sun.media.jai.MyProperty</i>.
045: * The names of properties generated by JAI itself will not adhere to the
046: * aforementioned naming convention, but this should not pose a problem if
047: * users adopt this convention for their own property names.
048:
049: * <p> Another approach to handling multiple property name spaces would
050: * be to define a separate PropertySource for each name space of properties.
051: * These PropertySources could themselves be attached to images as properties.
052: * Inheritance of these properties would occur by the default mechanism.
053: * Modification of these properties within an operation chain could be
054: * managed by PropertyGenerators which are capable of recognizing these
055: * properties. Note that a potential problem with this approach exists
056: * when a <code>PropertySourceChangeEvent</code> is fired: it might be
057: * necessary to clone the entire tree of properties in order to obtain
058: * the old value of event object.
059: *
060: * @see ImageJAI
061: * @see PlanarImage
062: * @see PropertyChangeEmitter
063: * @see WritablePropertySource
064: * @see java.awt.image.RenderedImage
065: * @see java.awt.image.renderable.RenderableImage
066: */
067: public interface PropertySource {
068:
069: /**
070: * Returns an array of <code>String</code>s recognized as names by
071: * this property source. If no properties are available,
072: * <code>null</code> will be returned.
073: *
074: * @return an array of <code>String</code>s giving the valid
075: * property names or <code>null</code>.
076: */
077: String[] getPropertyNames();
078:
079: /**
080: * Returns an array of <code>String</code>s recognized as names by
081: * this property source that begin with the supplied prefix. If
082: * no property names match, <code>null</code> will be returned.
083: * The comparison is done in a case-independent manner.
084: *
085: * @return an array of <code>String</code>s giving the valid
086: * property names.
087: *
088: * @exception IllegalArgumentException if <code>prefix</code>
089: * is <code>null</code>.
090: */
091: String[] getPropertyNames(String prefix);
092:
093: /**
094: * Returns the class expected to be returned by a request for
095: * the property with the specified name. If this information
096: * is unavailable, <code>null</code> will be returned indicating
097: * that <code>getProperty(propertyName).getClass()</code> should
098: * be executed instead. A <code>null</code> value might
099: * be returned for example to prevent generating the value of
100: * a deferred property solely to obtain its class. <code>null</code>
101: * will also be returned if the requested property is not emitted
102: * by this property source.
103: *
104: * @param propertyName the name of the property, as a <code>String</code>.
105: *
106: * @return The <code>Class</code> expected to be return by a
107: * request for the value of this property or <code>null</code>.
108: *
109: * @exception IllegalArgumentException if <code>propertyName</code>
110: * is <code>null</code>.
111: *
112: * @since JAI 1.1
113: */
114: Class getPropertyClass(String propertyName);
115:
116: /**
117: * Returns the value of a property. If the property name is not
118: * recognized, <code>java.awt.Image.UndefinedProperty</code> will
119: * be returned.
120: *
121: * @param propertyName the name of the property, as a <code>String</code>.
122: *
123: * @return the value of the property, as an
124: * <code>Object</code>, or the value
125: * <code>java.awt.Image.UndefinedProperty</code>.
126: *
127: * @exception IllegalArgumentException if <code>propertyName</code>
128: * is <code>null</code>.
129: */
130: Object getProperty(String propertyName);
131: }
|