001: /*
002: * $RCSfile: OperationNode.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:13 $
010: * $State: Exp $
011: */
012: package javax.media.jai;
013:
014: import java.awt.RenderingHints;
015: import java.awt.image.renderable.ParameterBlock;
016:
017: /**
018: * A class which is a node in a chain of operations. This interface
019: * aggregates the minimal set of methods which would be expected to be
020: * implemented by such a class.
021: *
022: * <p> Accessors and mutators of the critical attributes of the node
023: * are provided:
024: *
025: * <ul>
026: * <li> The name of the operation as a <code>String</code>;
027: * <li> The <code>OperationRegistry</code> to be used to resolve the
028: * operation name into an image factory which renders the node;
029: * <li> The lists of sources and parameters of the node as a
030: * <code>ParameterBlock</code>; and
031: * <li> The mapping of hints to be used when rendering the node.
032: * </ul>
033: *
034: * Whether an implementing class maintains these critical attributes by
035: * reference or by copying or cloning is left to the discretion of the
036: * implementation.
037: *
038: * <p> <code>OperationNode</code>s should fire a
039: * <code>PropertyChangeEventJAI</code> when any of the critical attributes of
040: * the node is modified. These events should be named "OperationName",
041: * "OperationRegistry", "ParameterBlock", and "RenderingHints" corresponding
042: * to the respective critical attributes. Events named "Sources" and
043: * "Parameters" may instead be fired if it can be determined that a
044: * <code>ParameterBlock</code> modification has affected only the sources
045: * or parameters of the node, respectively. Nodes which implement convenience
046: * methods to edit individual node sources, parameters, or hints should
047: * still fire an event for the attribute as a whole. Note that this might
048: * require cloning the respective object. <code>OperationNode</code>s are
049: * also required to fire <code>PropertySourceChangeEvent</code>s by virtue
050: * of their being a <code>PropertySource</code> as well as a
051: * <code>PropertyChangeEmitter</code>.
052: *
053: * <p> Methods are also provided to modify the local property environment
054: * of the node. The global property environment is maintained by the
055: * associated <code>OperationRegistry</code> and used to initialize the
056: * local property environment. Methods are provided to:
057: *
058: * <ul>
059: * <li> Add a <code>PropertyGenerator</code>;
060: * <li> Direct that a given property be copied from a certain source; and
061: * <li> Suppress the emission of a certain property.
062: * </ul>
063: *
064: * Invocation of these methods would not affect the global property
065: * environment of the operation as maintained by the
066: * <code>OperationRegistry</code>.
067: *
068: * @since JAI 1.1
069: */
070: public interface OperationNode extends PropertySource,
071: PropertyChangeEmitter {
072:
073: /**
074: * Returns the name of the <code>RegistryMode</code> corresponding to
075: * this <code>OperationNode</code>. This value should be immutable
076: * for a given node.
077: */
078: String getRegistryModeName();
079:
080: /**
081: * Returns the name of the operation this node represents as
082: * a <code>String</code>.
083: */
084: String getOperationName();
085:
086: /**
087: * Sets the name of the operation this node represents.
088: *
089: * <p> If the operation name changes according to a case-insensitive
090: * comparison by <code>equals()</code> of the old and new names,
091: * a <code>PropertyChangeEventJAI</code> named "OperationName"
092: * should be fired with
093: * source equal to this node and old and new values set to the old
094: * and new values of the operation name, respectively.
095: *
096: * @param opName The new operation name to be set.
097: *
098: * @throws IllegalArgumentException if <code>opName</code> is
099: * <code>null</code>.
100: */
101: void setOperationName(String opName);
102:
103: /**
104: * Returns the <code>OperationRegistry</code> that is used
105: * by this node. If the registry is not set, the default
106: * registry is returned.
107: */
108: OperationRegistry getRegistry();
109:
110: /**
111: * Sets the <code>OperationRegistry</code> that is used by
112: * this node. If the specified registry is <code>null</code>, the
113: * default registry is used.
114: *
115: * <p> If the registry changes according to a direct comparison
116: * of the old and new registry references,
117: * a <code>PropertyChangeEventJAI</code> named "OperationRegistry"
118: * should be fired with
119: * source equal to this node and old and new values set to the old
120: * and new values of the registry, respectively.
121: *
122: * @param registry The new <code>OperationRegistry</code> to be set;
123: * it may be <code>null</code>.
124: */
125: void setRegistry(OperationRegistry registry);
126:
127: /**
128: * Returns the <code>ParameterBlock</code> of this node.
129: */
130: ParameterBlock getParameterBlock();
131:
132: /**
133: * Sets the <code>ParameterBlock</code> of this node. If the specified
134: * new <code>ParameterBlock</code> is <code>null</code>, it is assumed
135: * that this node has no input sources and parameters.
136: *
137: * <p> This method does not validate the content of the supplied
138: * <code>ParameterBlock</code>. The caller should ensure that
139: * the sources and parameters in the <code>ParameterBlock</code>
140: * are suitable for the operation this node represents; otherwise
141: * some form of error or exception may occur at the time of rendering.
142: *
143: * <p> If the <code>ParameterBlock</code> changes according to a
144: * comparison of the sources and parameters <code>Vector</code>s of the
145: * old and new <code>ParameterBlock</code>s using <code>equals()</code>,
146: * a <code>PropertyChangeEventJAI</code> named "ParameterBlock"
147: * should be fired with
148: * source equal to this node and old and new values set to the old
149: * and new values of the <code>ParameterBlock</code>, respectively.
150: * A <code>PropertyChangeEventJAI</code> named "Sources" or
151: * "Parameters" may instead be fired if it can be determined that the
152: * <code>ParameterBlock</code> modification has affected only the sources
153: * or parameters of the node, respectively.
154: *
155: * <p> The <code>ParameterBlock</code> may include
156: * <code>DeferredData</code> parameters. These will not be evaluated
157: * until their values are actually required, i.e., when the node is
158: * rendered. Any <code>Observable</code> events generated by such
159: * <code>DeferredData</code> parameters will be trapped by the node
160: * and acted upon.
161: *
162: * @param pb The new <code>ParameterBlock</code> to be set;
163: * it may be <code>null</code>.
164: */
165: void setParameterBlock(ParameterBlock pb);
166:
167: /**
168: * Returns the <code>RenderingHints</code> of this node.
169: * It may be <code>null</code>.
170: */
171: RenderingHints getRenderingHints();
172:
173: /**
174: * Sets the <code>RenderingHints</code> of this node. It is legal
175: * for nodes to ignore <code>RenderingHints</code> set on them by
176: * this mechanism.
177: *
178: * <p> If the <code>RenderingHints</code> changes according to a
179: * comparison by <code>equals()</code> of the old and new hints,
180: * a <code>PropertyChangeEventJAI</code> named "RenderingHints"
181: * should be fired with
182: * source equal to this node and old and new values set to the old
183: * and new values of the hints, respectively.
184: *
185: * @param hints The new <code>RenderingHints</code> to be set;
186: * it may be <code>null</code>.
187: */
188: void setRenderingHints(RenderingHints hints);
189:
190: /**
191: * Returns the property associated with the specified property name,
192: * or <code>java.awt.Image.UndefinedProperty</code> if the specified
193: * property is not set on the image. This method is dynamic in the
194: * sense that subsequent invocations of this method on the same object
195: * may return different values as a function of changes in the property
196: * environment of the node, e.g., a change in which
197: * <code>PropertyGenerator</code>s are registered or in the values
198: * associated with properties of node sources. The case of the property
199: * name passed to this method is ignored.
200: *
201: * @param name A <code>String</code> naming the property.
202: *
203: * @throws IllegalArgumentException if
204: * <code>name</code> is <code>null</code>.
205: */
206: Object getDynamicProperty(String name);
207:
208: /**
209: * Adds a <code>PropertyGenerator</code> to the node. The property values
210: * emitted by this property generator override any previous
211: * definitions.
212: *
213: * @param pg A <code>PropertyGenerator</code> to be added to this node's
214: * property environment.
215: *
216: * @throws IllegalArgumentException if
217: * <code>pg</code> is <code>null</code>.
218: */
219: void addPropertyGenerator(PropertyGenerator pg);
220:
221: /**
222: * Forces a property to be copied from the specified source node.
223: * By default, a property is copied from the first source node
224: * that emits it. The result of specifying an invalid source is
225: * undefined.
226: *
227: * @param propertyName the name of the property to be copied.
228: * @param sourceIndex the index of the from which to copy the property.
229: * @throws IllegalArgumentException if <code>propertyName</code> is
230: * <code>null</code>.
231: */
232: void copyPropertyFromSource(String propertyName, int sourceIndex);
233:
234: /**
235: * Removes a named property from the property environment of this
236: * node. Unless the property is stored locally either due
237: * to having been set explicitly or to having been cached for property
238: * synchronization purposes, subsequent calls to
239: * <code>getProperty(name)</code> will return
240: * <code>java.awt.Image.UndefinedProperty</code>, and <code>name</code>
241: * will not appear on the list of properties emitted by
242: * <code>getPropertyNames()</code>.
243: *
244: * @param name A <code>String</code> naming the property to be suppressed.
245: *
246: * @throws IllegalArgumentException if
247: * <code>name</code> is <code>null</code>.
248: */
249: void suppressProperty(String name);
250: }
|