001: /*
002: * $RCSfile: PropertyGenerator.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:16 $
010: * $State: Exp $
011: */
012: package javax.media.jai;
013:
014: import java.awt.image.renderable.ParameterBlock;
015: import java.io.Serializable;
016:
017: /**
018: * An interface through which properties may be computed dynamically
019: * with respect to an environment of pre-existing properties. In the
020: * interest of simplicity and consistency, a <code>PropertyGenerator</code>
021: * is required to be a pure function; that is, if called multiple times
022: * with the same environment it must produce identical results.
023: *
024: * <p> The <code>OperationRegistry</code> class allows
025: * <code>PropertyGenerator</code>s to be associated with a particular
026: * operation type, and will automatically insert them into imaging chains
027: * as needed.
028: *
029: * <p> Properties are treated in a case-insensitive manner.
030: *
031: * @see OperationRegistry
032: *
033: */
034: public interface PropertyGenerator extends Serializable {
035:
036: /**
037: * Returns an array of <code>String</code>s naming properties emitted
038: * by this property generator. The <code>String</code>s may contain
039: * characters of any case.
040: *
041: * @return an array of <code>String</code>s that may be passed as parameter
042: * names to the <code>getProperty()</code> method.
043: */
044: String[] getPropertyNames();
045:
046: /**
047: * Returns the class expected to be returned by a request for
048: * the property with the specified name. If this information
049: * is unavailable, <code>null</code> will be returned indicating
050: * that <code>getProperty(propertyName).getClass()</code> should
051: * be executed instead. A <code>null</code> value might
052: * be returned for example to prevent generating the value of
053: * a deferred property solely to obtain its class.
054: *
055: * @return The <code>Class</code> expected to be return by a
056: * request for the value of this property or <code>null</code>.
057: * @exception IllegalArgumentException if <code>propertyName</code>
058: * is <code>null</code>.
059: *
060: * @since JAI 1.1
061: */
062: Class getClass(String propertyName);
063:
064: /**
065: * Determines whether the specified <code>Object</code> will
066: * be recognized by <code>getProperty(String,Object)</code>.
067: *
068: * @exception IllegalArgumentException if <code>opNode</code>
069: * is <code>null</code>.
070: *
071: * @since JAI 1.1
072: */
073: boolean canGenerateProperties(Object opNode);
074:
075: /**
076: * Computes the value of a property relative to an environment
077: * of pre-existing properties. The case of the supplied
078: * <code>String</code> is ignored.
079: *
080: * <p> In the case of an <code>OperationNode</code> in a chain of
081: * operations these properties may be emitted by the sources of the
082: * node in a chain or the parameters of that operation. The information
083: * requisite to compute the requested property must be available via the
084: * supplied <code>OperationNode</code>. It is legal to call
085: * <code>getProperty()</code> on the operation's sources.
086: *
087: * @param name the name of the property, as a <code>String</code>.
088: * @param op the <code>Object</code> from which properties will
089: * be generated.
090: * @return the value of the property, as an <code>Object</code> or the
091: * value <code>java.awt.Image.UndefinedProperty</code>.
092: * @exception IllegalArgumentException if <code>name</code> or
093: * <code>opNode</code> is <code>null</code>.
094: * @exception IllegalArgumentException if <code>opNode</code> is
095: * not an instance of a supported class for this method, i.e.,
096: * <code>canGenerateProperties(opNode)</code> returns
097: * <code>false</code>.
098: *
099: * @since JAI 1.1
100: */
101: Object getProperty(String name, Object opNode);
102:
103: /**
104: * Computes the value of a property relative to an environment
105: * of pre-existing properties emitted by the sources of
106: * a <code>RenderedOp</code>, and the parameters of that operation.
107: *
108: * <p> The operation name, sources, and <code>ParameterBlock</code>
109: * of the <code>RenderedOp</code> being processed may be obtained by
110: * means of the <code>op.getOperationName</code>,
111: * <code>op.getSources()</code>, and <code>op.getParameterBlock()</code>
112: * methods. It is legal to call <code>getProperty()</code> on the
113: * operation's sources.
114: *
115: * @param name the name of the property, as a <code>String</code>.
116: * @param op the <code>RenderedOp</code> representing the operation.
117: * @return the value of the property, as an <code>Object</code> or the
118: * value <code>java.awt.Image.UndefinedProperty</code>.
119: * @exception IllegalArgumentException if <code>name</code> or
120: * <code>op</code> is <code>null</code>.
121: *
122: * @deprecated as of JAI 1.1. Use
123: * <code>getProperty(String,Object)</code> instead.
124: */
125: Object getProperty(String name, RenderedOp op);
126:
127: /**
128: * Computes the value of a property relative to an environment
129: * of pre-existing properties emitted by the sources of
130: * a <code>RenderableOp</code>, and the parameters of that operation.
131: *
132: * <p> The operation name, sources, and <code>ParameterBlock</code>
133: * of the <code>RenderableOp</code> being processed may be obtained by
134: * means of the <code>op.getOperationName</code>,
135: * <code>op.getSources()</code>, and <code>op.getParameterBlock()</code>
136: * methods. It is legal to call <code>getProperty()</code> on the
137: * operation's sources.
138: *
139: * @param name the name of the property, as a <code>String</code>.
140: * @param op the <code>RenderableOp</code> representing the operation.
141: * @return the value of the property, as an <code>Object</code> or the
142: * value <code>java.awt.Image.UndefinedProperty</code>.
143: * @exception IllegalArgumentException if <code>name</code> or
144: * <code>op</code> is <code>null</code>.
145: *
146: * @deprecated as of JAI 1.1. Use
147: * <code>getProperty(String,Object)</code> instead.
148: */
149: Object getProperty(String name, RenderableOp op);
150: }
|