001 /*
002 * Copyright 1998-2004 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025
026 package java.awt.image.renderable;
027
028 import java.awt.image.RenderedImage;
029 import java.io.Serializable;
030 import java.util.Vector;
031
032 /**
033 * A <code>ParameterBlock</code> encapsulates all the information about sources and
034 * parameters (Objects) required by a RenderableImageOp, or other
035 * classes that process images.
036 *
037 * <p> Although it is possible to place arbitrary objects in the
038 * source Vector, users of this class may impose semantic constraints
039 * such as requiring all sources to be RenderedImages or
040 * RenderableImage. <code>ParameterBlock</code> itself is merely a container and
041 * performs no checking on source or parameter types.
042 *
043 * <p> All parameters in a <code>ParameterBlock</code> are objects; convenience
044 * add and set methods are available that take arguments of base type and
045 * construct the appropriate subclass of Number (such as
046 * Integer or Float). Corresponding get methods perform a
047 * downward cast and have return values of base type; an exception
048 * will be thrown if the stored values do not have the correct type.
049 * There is no way to distinguish between the results of
050 * "short s; add(s)" and "add(new Short(s))".
051 *
052 * <p> Note that the get and set methods operate on references.
053 * Therefore, one must be careful not to share references between
054 * <code>ParameterBlock</code>s when this is inappropriate. For example, to create
055 * a new <code>ParameterBlock</code> that is equal to an old one except for an
056 * added source, one might be tempted to write:
057 *
058 * <pre>
059 * ParameterBlock addSource(ParameterBlock pb, RenderableImage im) {
060 * ParameterBlock pb1 = new ParameterBlock(pb.getSources());
061 * pb1.addSource(im);
062 * return pb1;
063 * }
064 * </pre>
065 *
066 * <p> This code will have the side effect of altering the original
067 * <code>ParameterBlock</code>, since the getSources operation returned a reference
068 * to its source Vector. Both pb and pb1 share their source Vector,
069 * and a change in either is visible to both.
070 *
071 * <p> A correct way to write the addSource function is to clone
072 * the source Vector:
073 *
074 * <pre>
075 * ParameterBlock addSource (ParameterBlock pb, RenderableImage im) {
076 * ParameterBlock pb1 = new ParameterBlock(pb.getSources().clone());
077 * pb1.addSource(im);
078 * return pb1;
079 * }
080 * </pre>
081 *
082 * <p> The clone method of <code>ParameterBlock</code> has been defined to
083 * perform a clone of both the source and parameter Vectors for
084 * this reason. A standard, shallow clone is available as
085 * shallowClone.
086 *
087 * <p> The addSource, setSource, add, and set methods are
088 * defined to return 'this' after adding their argument. This allows
089 * use of syntax like:
090 *
091 * <pre>
092 * ParameterBlock pb = new ParameterBlock();
093 * op = new RenderableImageOp("operation", pb.add(arg1).add(arg2));
094 * </pre>
095 * */
096 public class ParameterBlock implements Cloneable, Serializable {
097 /** A Vector of sources, stored as arbitrary Objects. */
098 protected Vector<Object> sources = new Vector<Object>();
099
100 /** A Vector of non-source parameters, stored as arbitrary Objects. */
101 protected Vector<Object> parameters = new Vector<Object>();
102
103 /** A dummy constructor. */
104 public ParameterBlock() {
105 }
106
107 /**
108 * Constructs a <code>ParameterBlock</code> with a given Vector
109 * of sources.
110 * @param sources a <code>Vector</code> of source images
111 */
112 public ParameterBlock(Vector<Object> sources) {
113 setSources(sources);
114 }
115
116 /**
117 * Constructs a <code>ParameterBlock</code> with a given Vector of sources and
118 * Vector of parameters.
119 * @param sources a <code>Vector</code> of source images
120 * @param parameters a <code>Vector</code> of parameters to be used in the
121 * rendering operation
122 */
123 public ParameterBlock(Vector<Object> sources,
124 Vector<Object> parameters) {
125 setSources(sources);
126 setParameters(parameters);
127 }
128
129 /**
130 * Creates a shallow copy of a <code>ParameterBlock</code>. The source and
131 * parameter Vectors are copied by reference -- additions or
132 * changes will be visible to both versions.
133 *
134 * @return an Object clone of the <code>ParameterBlock</code>.
135 */
136 public Object shallowClone() {
137 try {
138 return super .clone();
139 } catch (Exception e) {
140 // We can't be here since we implement Cloneable.
141 return null;
142 }
143 }
144
145 /**
146 * Creates a copy of a <code>ParameterBlock</code>. The source and parameter
147 * Vectors are cloned, but the actual sources and parameters are
148 * copied by reference. This allows modifications to the order
149 * and number of sources and parameters in the clone to be invisible
150 * to the original <code>ParameterBlock</code>. Changes to the shared sources or
151 * parameters themselves will still be visible.
152 *
153 * @return an Object clone of the <code>ParameterBlock</code>.
154 */
155 public Object clone() {
156 ParameterBlock theClone;
157
158 try {
159 theClone = (ParameterBlock) super .clone();
160 } catch (Exception e) {
161 // We can't be here since we implement Cloneable.
162 return null;
163 }
164
165 if (sources != null) {
166 theClone.setSources((Vector) sources.clone());
167 }
168 if (parameters != null) {
169 theClone.setParameters((Vector) parameters.clone());
170 }
171 return (Object) theClone;
172 }
173
174 /**
175 * Adds an image to end of the list of sources. The image is
176 * stored as an object in order to allow new node types in the
177 * future.
178 *
179 * @param source an image object to be stored in the source list.
180 * @return a new <code>ParameterBlock</code> containing the specified
181 * <code>source</code>.
182 */
183 public ParameterBlock addSource(Object source) {
184 sources.addElement(source);
185 return this ;
186 }
187
188 /**
189 * Returns a source as a general Object. The caller must cast it into
190 * an appropriate type.
191 *
192 * @param index the index of the source to be returned.
193 * @return an <code>Object</code> that represents the source located
194 * at the specified index in the <code>sources</code>
195 * <code>Vector</code>.
196 * @see #setSource(Object, int)
197 */
198 public Object getSource(int index) {
199 return sources.elementAt(index);
200 }
201
202 /**
203 * Replaces an entry in the list of source with a new source.
204 * If the index lies beyond the current source list,
205 * the list is extended with nulls as needed.
206 * @param source the specified source image
207 * @param index the index into the <code>sources</code>
208 * <code>Vector</code> at which to
209 * insert the specified <code>source</code>
210 * @return a new <code>ParameterBlock</code> that contains the
211 * specified <code>source</code> at the specified
212 * <code>index</code>.
213 * @see #getSource(int)
214 */
215 public ParameterBlock setSource(Object source, int index) {
216 int oldSize = sources.size();
217 int newSize = index + 1;
218 if (oldSize < newSize) {
219 sources.setSize(newSize);
220 }
221 sources.setElementAt(source, index);
222 return this ;
223 }
224
225 /**
226 * Returns a source as a <code>RenderedImage</code>. This method is
227 * a convenience method.
228 * An exception will be thrown if the source is not a RenderedImage.
229 *
230 * @param index the index of the source to be returned
231 * @return a <code>RenderedImage</code> that represents the source
232 * image that is at the specified index in the
233 * <code>sources</code> <code>Vector</code>.
234 */
235 public RenderedImage getRenderedSource(int index) {
236 return (RenderedImage) sources.elementAt(index);
237 }
238
239 /**
240 * Returns a source as a RenderableImage. This method is a
241 * convenience method.
242 * An exception will be thrown if the sources is not a RenderableImage.
243 *
244 * @param index the index of the source to be returned
245 * @return a <code>RenderableImage</code> that represents the source
246 * image that is at the specified index in the
247 * <code>sources</code> <code>Vector</code>.
248 */
249 public RenderableImage getRenderableSource(int index) {
250 return (RenderableImage) sources.elementAt(index);
251 }
252
253 /**
254 * Returns the number of source images.
255 * @return the number of source images in the <code>sources</code>
256 * <code>Vector</code>.
257 */
258 public int getNumSources() {
259 return sources.size();
260 }
261
262 /**
263 * Returns the entire Vector of sources.
264 * @return the <code>sources</code> <code>Vector</code>.
265 * @see #setSources(Vector)
266 */
267 public Vector<Object> getSources() {
268 return sources;
269 }
270
271 /**
272 * Sets the entire Vector of sources to a given Vector.
273 * @param sources the <code>Vector</code> of source images
274 * @see #getSources
275 */
276 public void setSources(Vector<Object> sources) {
277 this .sources = sources;
278 }
279
280 /** Clears the list of source images. */
281 public void removeSources() {
282 sources = new Vector();
283 }
284
285 /**
286 * Returns the number of parameters (not including source images).
287 * @return the number of parameters in the <code>parameters</code>
288 * <code>Vector</code>.
289 */
290 public int getNumParameters() {
291 return parameters.size();
292 }
293
294 /**
295 * Returns the entire Vector of parameters.
296 * @return the <code>parameters</code> <code>Vector</code>.
297 * @see #setParameters(Vector)
298 */
299 public Vector<Object> getParameters() {
300 return parameters;
301 }
302
303 /**
304 * Sets the entire Vector of parameters to a given Vector.
305 * @param parameters the specified <code>Vector</code> of
306 * parameters
307 * @see #getParameters
308 */
309 public void setParameters(Vector<Object> parameters) {
310 this .parameters = parameters;
311 }
312
313 /** Clears the list of parameters. */
314 public void removeParameters() {
315 parameters = new Vector();
316 }
317
318 /**
319 * Adds an object to the list of parameters.
320 * @param obj the <code>Object</code> to add to the
321 * <code>parameters</code> <code>Vector</code>
322 * @return a new <code>ParameterBlock</code> containing
323 * the specified parameter.
324 */
325 public ParameterBlock add(Object obj) {
326 parameters.addElement(obj);
327 return this ;
328 }
329
330 /**
331 * Adds a Byte to the list of parameters.
332 * @param b the byte to add to the
333 * <code>parameters</code> <code>Vector</code>
334 * @return a new <code>ParameterBlock</code> containing
335 * the specified parameter.
336 */
337 public ParameterBlock add(byte b) {
338 return add(new Byte(b));
339 }
340
341 /**
342 * Adds a Character to the list of parameters.
343 * @param c the char to add to the
344 * <code>parameters</code> <code>Vector</code>
345 * @return a new <code>ParameterBlock</code> containing
346 * the specified parameter.
347 */
348 public ParameterBlock add(char c) {
349 return add(new Character(c));
350 }
351
352 /**
353 * Adds a Short to the list of parameters.
354 * @param s the short to add to the
355 * <code>parameters</code> <code>Vector</code>
356 * @return a new <code>ParameterBlock</code> containing
357 * the specified parameter.
358 */
359 public ParameterBlock add(short s) {
360 return add(new Short(s));
361 }
362
363 /**
364 * Adds a Integer to the list of parameters.
365 * @param i the int to add to the
366 * <code>parameters</code> <code>Vector</code>
367 * @return a new <code>ParameterBlock</code> containing
368 * the specified parameter.
369 */
370 public ParameterBlock add(int i) {
371 return add(new Integer(i));
372 }
373
374 /**
375 * Adds a Long to the list of parameters.
376 * @param l the long to add to the
377 * <code>parameters</code> <code>Vector</code>
378 * @return a new <code>ParameterBlock</code> containing
379 * the specified parameter.
380 */
381 public ParameterBlock add(long l) {
382 return add(new Long(l));
383 }
384
385 /**
386 * Adds a Float to the list of parameters.
387 * @param f the float to add to the
388 * <code>parameters</code> <code>Vector</code>
389 * @return a new <code>ParameterBlock</code> containing
390 * the specified parameter.
391 */
392 public ParameterBlock add(float f) {
393 return add(new Float(f));
394 }
395
396 /**
397 * Adds a Double to the list of parameters.
398 * @param d the double to add to the
399 * <code>parameters</code> <code>Vector</code>
400 * @return a new <code>ParameterBlock</code> containing
401 * the specified parameter.
402 */
403 public ParameterBlock add(double d) {
404 return add(new Double(d));
405 }
406
407 /**
408 * Replaces an Object in the list of parameters.
409 * If the index lies beyond the current source list,
410 * the list is extended with nulls as needed.
411 * @param obj the parameter that replaces the
412 * parameter at the specified index in the
413 * <code>parameters</code> <code>Vector</code>
414 * @param index the index of the parameter to be
415 * replaced with the specified parameter
416 * @return a new <code>ParameterBlock</code> containing
417 * the specified parameter.
418 */
419 public ParameterBlock set(Object obj, int index) {
420 int oldSize = parameters.size();
421 int newSize = index + 1;
422 if (oldSize < newSize) {
423 parameters.setSize(newSize);
424 }
425 parameters.setElementAt(obj, index);
426 return this ;
427 }
428
429 /**
430 * Replaces an Object in the list of parameters with a Byte.
431 * If the index lies beyond the current source list,
432 * the list is extended with nulls as needed.
433 * @param b the parameter that replaces the
434 * parameter at the specified index in the
435 * <code>parameters</code> <code>Vector</code>
436 * @param index the index of the parameter to be
437 * replaced with the specified parameter
438 * @return a new <code>ParameterBlock</code> containing
439 * the specified parameter.
440 */
441 public ParameterBlock set(byte b, int index) {
442 return set(new Byte(b), index);
443 }
444
445 /**
446 * Replaces an Object in the list of parameters with a Character.
447 * If the index lies beyond the current source list,
448 * the list is extended with nulls as needed.
449 * @param c the parameter that replaces the
450 * parameter at the specified index in the
451 * <code>parameters</code> <code>Vector</code>
452 * @param index the index of the parameter to be
453 * replaced with the specified parameter
454 * @return a new <code>ParameterBlock</code> containing
455 * the specified parameter.
456 */
457 public ParameterBlock set(char c, int index) {
458 return set(new Character(c), index);
459 }
460
461 /**
462 * Replaces an Object in the list of parameters with a Short.
463 * If the index lies beyond the current source list,
464 * the list is extended with nulls as needed.
465 * @param s the parameter that replaces the
466 * parameter at the specified index in the
467 * <code>parameters</code> <code>Vector</code>
468 * @param index the index of the parameter to be
469 * replaced with the specified parameter
470 * @return a new <code>ParameterBlock</code> containing
471 * the specified parameter.
472 */
473 public ParameterBlock set(short s, int index) {
474 return set(new Short(s), index);
475 }
476
477 /**
478 * Replaces an Object in the list of parameters with an Integer.
479 * If the index lies beyond the current source list,
480 * the list is extended with nulls as needed.
481 * @param i the parameter that replaces the
482 * parameter at the specified index in the
483 * <code>parameters</code> <code>Vector</code>
484 * @param index the index of the parameter to be
485 * replaced with the specified parameter
486 * @return a new <code>ParameterBlock</code> containing
487 * the specified parameter.
488 */
489 public ParameterBlock set(int i, int index) {
490 return set(new Integer(i), index);
491 }
492
493 /**
494 * Replaces an Object in the list of parameters with a Long.
495 * If the index lies beyond the current source list,
496 * the list is extended with nulls as needed.
497 * @param l the parameter that replaces the
498 * parameter at the specified index in the
499 * <code>parameters</code> <code>Vector</code>
500 * @param index the index of the parameter to be
501 * replaced with the specified parameter
502 * @return a new <code>ParameterBlock</code> containing
503 * the specified parameter.
504 */
505 public ParameterBlock set(long l, int index) {
506 return set(new Long(l), index);
507 }
508
509 /**
510 * Replaces an Object in the list of parameters with a Float.
511 * If the index lies beyond the current source list,
512 * the list is extended with nulls as needed.
513 * @param f the parameter that replaces the
514 * parameter at the specified index in the
515 * <code>parameters</code> <code>Vector</code>
516 * @param index the index of the parameter to be
517 * replaced with the specified parameter
518 * @return a new <code>ParameterBlock</code> containing
519 * the specified parameter.
520 */
521 public ParameterBlock set(float f, int index) {
522 return set(new Float(f), index);
523 }
524
525 /**
526 * Replaces an Object in the list of parameters with a Double.
527 * If the index lies beyond the current source list,
528 * the list is extended with nulls as needed.
529 * @param d the parameter that replaces the
530 * parameter at the specified index in the
531 * <code>parameters</code> <code>Vector</code>
532 * @param index the index of the parameter to be
533 * replaced with the specified parameter
534 * @return a new <code>ParameterBlock</code> containing
535 * the specified parameter.
536 */
537 public ParameterBlock set(double d, int index) {
538 return set(new Double(d), index);
539 }
540
541 /**
542 * Gets a parameter as an object.
543 * @param index the index of the parameter to get
544 * @return an <code>Object</code> representing the
545 * the parameter at the specified index
546 * into the <code>parameters</code>
547 * <code>Vector</code>.
548 */
549 public Object getObjectParameter(int index) {
550 return parameters.elementAt(index);
551 }
552
553 /**
554 * A convenience method to return a parameter as a byte. An
555 * exception is thrown if the parameter is
556 * <code>null</code> or not a <code>Byte</code>.
557 *
558 * @param index the index of the parameter to be returned.
559 * @return the parameter at the specified index
560 * as a <code>byte</code> value.
561 * @throws ClassCastException if the parameter at the
562 * specified index is not a <code>Byte</code>
563 * @throws NullPointerException if the parameter at the specified
564 * index is <code>null</code>
565 * @throws ArrayIndexOutOfBoundsException if <code>index</code>
566 * is negative or not less than the current size of this
567 * <code>ParameterBlock</code> object
568 */
569 public byte getByteParameter(int index) {
570 return ((Byte) parameters.elementAt(index)).byteValue();
571 }
572
573 /**
574 * A convenience method to return a parameter as a char. An
575 * exception is thrown if the parameter is
576 * <code>null</code> or not a <code>Character</code>.
577 *
578 * @param index the index of the parameter to be returned.
579 * @return the parameter at the specified index
580 * as a <code>char</code> value.
581 * @throws ClassCastException if the parameter at the
582 * specified index is not a <code>Character</code>
583 * @throws NullPointerException if the parameter at the specified
584 * index is <code>null</code>
585 * @throws ArrayIndexOutOfBoundsException if <code>index</code>
586 * is negative or not less than the current size of this
587 * <code>ParameterBlock</code> object
588 */
589 public char getCharParameter(int index) {
590 return ((Character) parameters.elementAt(index)).charValue();
591 }
592
593 /**
594 * A convenience method to return a parameter as a short. An
595 * exception is thrown if the parameter is
596 * <code>null</code> or not a <code>Short</code>.
597 *
598 * @param index the index of the parameter to be returned.
599 * @return the parameter at the specified index
600 * as a <code>short</code> value.
601 * @throws ClassCastException if the parameter at the
602 * specified index is not a <code>Short</code>
603 * @throws NullPointerException if the parameter at the specified
604 * index is <code>null</code>
605 * @throws ArrayIndexOutOfBoundsException if <code>index</code>
606 * is negative or not less than the current size of this
607 * <code>ParameterBlock</code> object
608 */
609 public short getShortParameter(int index) {
610 return ((Short) parameters.elementAt(index)).shortValue();
611 }
612
613 /**
614 * A convenience method to return a parameter as an int. An
615 * exception is thrown if the parameter is
616 * <code>null</code> or not an <code>Integer</code>.
617 *
618 * @param index the index of the parameter to be returned.
619 * @return the parameter at the specified index
620 * as a <code>int</code> value.
621 * @throws ClassCastException if the parameter at the
622 * specified index is not a <code>Integer</code>
623 * @throws NullPointerException if the parameter at the specified
624 * index is <code>null</code>
625 * @throws ArrayIndexOutOfBoundsException if <code>index</code>
626 * is negative or not less than the current size of this
627 * <code>ParameterBlock</code> object
628 */
629 public int getIntParameter(int index) {
630 return ((Integer) parameters.elementAt(index)).intValue();
631 }
632
633 /**
634 * A convenience method to return a parameter as a long. An
635 * exception is thrown if the parameter is
636 * <code>null</code> or not a <code>Long</code>.
637 *
638 * @param index the index of the parameter to be returned.
639 * @return the parameter at the specified index
640 * as a <code>long</code> value.
641 * @throws ClassCastException if the parameter at the
642 * specified index is not a <code>Long</code>
643 * @throws NullPointerException if the parameter at the specified
644 * index is <code>null</code>
645 * @throws ArrayIndexOutOfBoundsException if <code>index</code>
646 * is negative or not less than the current size of this
647 * <code>ParameterBlock</code> object
648 */
649 public long getLongParameter(int index) {
650 return ((Long) parameters.elementAt(index)).longValue();
651 }
652
653 /**
654 * A convenience method to return a parameter as a float. An
655 * exception is thrown if the parameter is
656 * <code>null</code> or not a <code>Float</code>.
657 *
658 * @param index the index of the parameter to be returned.
659 * @return the parameter at the specified index
660 * as a <code>float</code> value.
661 * @throws ClassCastException if the parameter at the
662 * specified index is not a <code>Float</code>
663 * @throws NullPointerException if the parameter at the specified
664 * index is <code>null</code>
665 * @throws ArrayIndexOutOfBoundsException if <code>index</code>
666 * is negative or not less than the current size of this
667 * <code>ParameterBlock</code> object
668 */
669 public float getFloatParameter(int index) {
670 return ((Float) parameters.elementAt(index)).floatValue();
671 }
672
673 /**
674 * A convenience method to return a parameter as a double. An
675 * exception is thrown if the parameter is
676 * <code>null</code> or not a <code>Double</code>.
677 *
678 * @param index the index of the parameter to be returned.
679 * @return the parameter at the specified index
680 * as a <code>double</code> value.
681 * @throws ClassCastException if the parameter at the
682 * specified index is not a <code>Double</code>
683 * @throws NullPointerException if the parameter at the specified
684 * index is <code>null</code>
685 * @throws ArrayIndexOutOfBoundsException if <code>index</code>
686 * is negative or not less than the current size of this
687 * <code>ParameterBlock</code> object
688 */
689 public double getDoubleParameter(int index) {
690 return ((Double) parameters.elementAt(index)).doubleValue();
691 }
692
693 /**
694 * Returns an array of Class objects describing the types
695 * of the parameters.
696 * @return an array of <code>Class</code> objects.
697 */
698 public Class[] getParamClasses() {
699 int numParams = getNumParameters();
700 Class[] classes = new Class[numParams];
701 int i;
702
703 for (i = 0; i < numParams; i++) {
704 Object obj = getObjectParameter(i);
705 if (obj instanceof Byte) {
706 classes[i] = byte.class;
707 } else if (obj instanceof Character) {
708 classes[i] = char.class;
709 } else if (obj instanceof Short) {
710 classes[i] = short.class;
711 } else if (obj instanceof Integer) {
712 classes[i] = int.class;
713 } else if (obj instanceof Long) {
714 classes[i] = long.class;
715 } else if (obj instanceof Float) {
716 classes[i] = float.class;
717 } else if (obj instanceof Double) {
718 classes[i] = double.class;
719 } else {
720 classes[i] = obj.getClass();
721 }
722 }
723
724 return classes;
725 }
726 }
|