1. /*
  2. * @(#)ParameterBlock.java 1.12 03/01/23
  3. *
  4. * Copyright 2003 Sun Microsystems, Inc. All rights reserved.
  5. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  6. */
  7. package java.awt.image.renderable;
  8. import java.awt.image.RenderedImage;
  9. import java.io.Serializable;
  10. import java.util.Vector;
  11. /**
  12. * A <code>ParameterBlock</code> encapsulates all the information about sources and
  13. * parameters (Objects) required by a RenderableImageOp, or other
  14. * classes that process images.
  15. *
  16. * <p> Although it is possible to place arbitrary objects in the
  17. * source Vector, users of this class may impose semantic constraints
  18. * such as requiring all sources to be RenderedImages or
  19. * RenderableImage. <code>ParameterBlock</code> itself is merely a container and
  20. * performs no checking on source or parameter types.
  21. *
  22. * <p> All parameters in a <code>ParameterBlock</code> are objects; convenience
  23. * add and set methods are available that take arguments of base type and
  24. * construct the appropriate subclass of Number (such as
  25. * Integer or Float). Corresponding get methods perform a
  26. * downward cast and have return values of base type; an exception
  27. * will be thrown if the stored values do not have the correct type.
  28. * There is no way to distinguish between the results of
  29. * "short s; add(s)" and "add(new Short(s))".
  30. *
  31. * <p> Note that the get and set methods operate on references.
  32. * Therefore, one must be careful not to share references between
  33. * <code>ParameterBlock</code>s when this is inappropriate. For example, to create
  34. * a new <code>ParameterBlock</code> that is equal to an old one except for an
  35. * added source, one might be tempted to write:
  36. *
  37. * <pre>
  38. * ParameterBlock addSource(ParameterBlock pb, RenderableImage im) {
  39. * ParameterBlock pb1 = new ParameterBlock(pb.getSources());
  40. * pb1.addSource(im);
  41. * return pb1;
  42. * }
  43. * </pre>
  44. *
  45. * <p> This code will have the side effect of altering the original
  46. * <code>ParameterBlock</code>, since the getSources operation returned a reference
  47. * to its source Vector. Both pb and pb1 share their source Vector,
  48. * and a change in either is visible to both.
  49. *
  50. * <p> A correct way to write the addSource function is to clone
  51. * the source Vector:
  52. *
  53. * <pre>
  54. * ParameterBlock addSource (ParameterBlock pb, RenderableImage im) {
  55. * ParameterBlock pb1 = new ParameterBlock(pb.getSources().clone());
  56. * pb1.addSource(im);
  57. * return pb1;
  58. * }
  59. * </pre>
  60. *
  61. * <p> The clone method of <code>ParameterBlock</code> has been defined to
  62. * perform a clone of both the source and parameter Vectors for
  63. * this reason. A standard, shallow clone is available as
  64. * shallowClone.
  65. *
  66. * <p> The addSource, setSource, add, and set methods are
  67. * defined to return 'this' after adding their argument. This allows
  68. * use of syntax like:
  69. *
  70. * <pre>
  71. * ParameterBlock pb = new ParameterBlock();
  72. * op = new RenderableImageOp("operation", pb.add(arg1).add(arg2));
  73. * </pre>
  74. * */
  75. public class ParameterBlock implements Cloneable, Serializable {
  76. /** A Vector of sources, stored as arbitrary Objects. */
  77. protected Vector sources = new Vector();
  78. /** A Vector of non-source parameters, stored as arbitrary Objects. */
  79. protected Vector parameters = new Vector();
  80. /** A dummy constructor. */
  81. public ParameterBlock() {}
  82. /**
  83. * Constructs a <code>ParameterBlock</code> with a given Vector
  84. * of sources.
  85. * @param sources a <code>Vector</code> of source images
  86. */
  87. public ParameterBlock(Vector sources) {
  88. setSources(sources);
  89. }
  90. /**
  91. * Constructs a <code>ParameterBlock</code> with a given Vector of sources and
  92. * Vector of parameters.
  93. * @param sources a <code>Vector</code> of source images
  94. * @param parameters a <code>Vector</code> of parameters to be used in the
  95. * rendering operation
  96. */
  97. public ParameterBlock(Vector sources, Vector parameters) {
  98. setSources(sources);
  99. setParameters(parameters);
  100. }
  101. /**
  102. * Creates a shallow copy of a <code>ParameterBlock</code>. The source and
  103. * parameter Vectors are copied by reference -- additions or
  104. * changes will be visible to both versions.
  105. *
  106. * @return an Object clone of the <code>ParameterBlock</code>.
  107. */
  108. public Object shallowClone() {
  109. try {
  110. return super.clone();
  111. } catch (Exception e) {
  112. // We can't be here since we implement Cloneable.
  113. return null;
  114. }
  115. }
  116. /**
  117. * Creates a copy of a <code>ParameterBlock</code>. The source and parameter
  118. * Vectors are cloned, but the actual sources and parameters are
  119. * copied by reference. This allows modifications to the order
  120. * and number of sources and parameters in the clone to be invisible
  121. * to the original <code>ParameterBlock</code>. Changes to the shared sources or
  122. * parameters themselves will still be visible.
  123. *
  124. * @return an Object clone of the <code>ParameterBlock</code>.
  125. */
  126. public Object clone() {
  127. ParameterBlock theClone;
  128. try {
  129. theClone = (ParameterBlock) super.clone();
  130. } catch (Exception e) {
  131. // We can't be here since we implement Cloneable.
  132. return null;
  133. }
  134. if (sources != null) {
  135. theClone.setSources((Vector)sources.clone());
  136. }
  137. if (parameters != null) {
  138. theClone.setParameters((Vector)parameters.clone());
  139. }
  140. return (Object) theClone;
  141. }
  142. /**
  143. * Adds an image to end of the list of sources. The image is
  144. * stored as an object in order to allow new node types in the
  145. * future.
  146. *
  147. * @param source an image object to be stored in the source list.
  148. * @return a new <code>ParameterBlock</code> containing the specified
  149. * <code>source</code>.
  150. */
  151. public ParameterBlock addSource(Object source) {
  152. sources.addElement(source);
  153. return this;
  154. }
  155. /**
  156. * Returns a source as a general Object. The caller must cast it into
  157. * an appropriate type.
  158. *
  159. * @param index the index of the source to be returned.
  160. * @return an <code>Object</code> that represents the source located
  161. * at the specified index in the <code>sources</code>
  162. * <code>Vector</code>.
  163. * @see #setSource(Object, int)
  164. */
  165. public Object getSource(int index) {
  166. return sources.elementAt(index);
  167. }
  168. /**
  169. * Replaces an entry in the list of source with a new source.
  170. * If the index lies beyond the current source list,
  171. * the list is extended with nulls as needed.
  172. * @param source the specified source image
  173. * @param index the index into the <code>sources</code>
  174. * <code>Vector</code> at which to
  175. * insert the specified <code>source</code>
  176. * @return a new <code>ParameterBlock</code> that contains the
  177. * specified <code>source</code> at the specified
  178. * <code>index</code>.
  179. * @see #getSource(int)
  180. */
  181. public ParameterBlock setSource(Object source, int index) {
  182. int oldSize = sources.size();
  183. int newSize = index + 1;
  184. if (oldSize < newSize) {
  185. sources.setSize(newSize);
  186. }
  187. sources.setElementAt(source, index);
  188. return this;
  189. }
  190. /**
  191. * Returns a source as a <code>RenderedImage</code>. This method is
  192. * a convenience method.
  193. * An exception will be thrown if the source is not a RenderedImage.
  194. *
  195. * @param index the index of the source to be returned
  196. * @return a <code>RenderedImage</code> that represents the source
  197. * image that is at the specified index in the
  198. * <code>sources</code> <code>Vector</code>.
  199. */
  200. public RenderedImage getRenderedSource(int index) {
  201. return (RenderedImage) sources.elementAt(index);
  202. }
  203. /**
  204. * Returns a source as a RenderableImage. This method is a
  205. * convenience method.
  206. * An exception will be thrown if the sources is not a RenderableImage.
  207. *
  208. * @param index the index of the source to be returned
  209. * @return a <code>RenderableImage</code> that represents the source
  210. * image that is at the specified index in the
  211. * <code>sources</code> <code>Vector</code>.
  212. */
  213. public RenderableImage getRenderableSource(int index) {
  214. return (RenderableImage) sources.elementAt(index);
  215. }
  216. /**
  217. * Returns the number of source images.
  218. * @return the number of source images in the <code>sources</code>
  219. * <code>Vector</code>.
  220. */
  221. public int getNumSources() {
  222. return sources.size();
  223. }
  224. /**
  225. * Returns the entire Vector of sources.
  226. * @return the <code>sources</code> <code>Vector</code>.
  227. * @see #setSources(Vector)
  228. */
  229. public Vector getSources() {
  230. return sources;
  231. }
  232. /**
  233. * Sets the entire Vector of sources to a given Vector.
  234. * @param sources the <code>Vector</code> of source images
  235. * @see #getSources
  236. */
  237. public void setSources(Vector sources) {
  238. this.sources = sources;
  239. }
  240. /** Clears the list of source images. */
  241. public void removeSources() {
  242. sources = new Vector();
  243. }
  244. /**
  245. * Returns the number of parameters (not including source images).
  246. * @return the number of parameters in the <code>parameters</code>
  247. * <code>Vector</code>.
  248. */
  249. public int getNumParameters() {
  250. return parameters.size();
  251. }
  252. /**
  253. * Returns the entire Vector of parameters.
  254. * @return the <code>parameters</code> <code>Vector</code>.
  255. * @see #setParameters(Vector)
  256. */
  257. public Vector getParameters() {
  258. return parameters;
  259. }
  260. /**
  261. * Sets the entire Vector of parameters to a given Vector.
  262. * @param parameters the specified <code>Vector</code> of
  263. * parameters
  264. * @see #getParameters
  265. */
  266. public void setParameters(Vector parameters) {
  267. this.parameters = parameters;
  268. }
  269. /** Clears the list of parameters. */
  270. public void removeParameters() {
  271. parameters = new Vector();
  272. }
  273. /**
  274. * Adds an object to the list of parameters.
  275. * @param obj the <code>Object</code> to add to the
  276. * <code>parameters</code> <code>Vector</code>
  277. * @return a new <code>ParameterBlock</code> containing
  278. * the specified parameter.
  279. */
  280. public ParameterBlock add(Object obj) {
  281. parameters.addElement(obj);
  282. return this;
  283. }
  284. /**
  285. * Adds a Byte to the list of parameters.
  286. * @param b the byte to add to the
  287. * <code>parameters</code> <code>Vector</code>
  288. * @return a new <code>ParameterBlock</code> containing
  289. * the specified parameter.
  290. */
  291. public ParameterBlock add(byte b) {
  292. return add(new Byte(b));
  293. }
  294. /**
  295. * Adds a Character to the list of parameters.
  296. * @param c the char to add to the
  297. * <code>parameters</code> <code>Vector</code>
  298. * @return a new <code>ParameterBlock</code> containing
  299. * the specified parameter.
  300. */
  301. public ParameterBlock add(char c) {
  302. return add(new Character(c));
  303. }
  304. /**
  305. * Adds a Short to the list of parameters.
  306. * @param s the short to add to the
  307. * <code>parameters</code> <code>Vector</code>
  308. * @return a new <code>ParameterBlock</code> containing
  309. * the specified parameter.
  310. */
  311. public ParameterBlock add(short s) {
  312. return add(new Short(s));
  313. }
  314. /**
  315. * Adds a Integer to the list of parameters.
  316. * @param i the int to add to the
  317. * <code>parameters</code> <code>Vector</code>
  318. * @return a new <code>ParameterBlock</code> containing
  319. * the specified parameter.
  320. */
  321. public ParameterBlock add(int i) {
  322. return add(new Integer(i));
  323. }
  324. /**
  325. * Adds a Long to the list of parameters.
  326. * @param l the long to add to the
  327. * <code>parameters</code> <code>Vector</code>
  328. * @return a new <code>ParameterBlock</code> containing
  329. * the specified parameter.
  330. */
  331. public ParameterBlock add(long l) {
  332. return add(new Long(l));
  333. }
  334. /**
  335. * Adds a Float to the list of parameters.
  336. * @param f the float to add to the
  337. * <code>parameters</code> <code>Vector</code>
  338. * @return a new <code>ParameterBlock</code> containing
  339. * the specified parameter.
  340. */
  341. public ParameterBlock add(float f) {
  342. return add(new Float(f));
  343. }
  344. /**
  345. * Adds a Double to the list of parameters.
  346. * @param d the double to add to the
  347. * <code>parameters</code> <code>Vector</code>
  348. * @return a new <code>ParameterBlock</code> containing
  349. * the specified parameter.
  350. */
  351. public ParameterBlock add(double d) {
  352. return add(new Double(d));
  353. }
  354. /**
  355. * Replaces an Object in the list of parameters.
  356. * If the index lies beyond the current source list,
  357. * the list is extended with nulls as needed.
  358. * @param obj the parameter that replaces the
  359. * parameter at the specified index in the
  360. * <code>parameters</code> <code>Vector</code>
  361. * @param index the index of the parameter to be
  362. * replaced with the specified parameter
  363. * @return a new <code>ParameterBlock</code> containing
  364. * the specified parameter.
  365. */
  366. public ParameterBlock set(Object obj, int index) {
  367. int oldSize = parameters.size();
  368. int newSize = index + 1;
  369. if (oldSize < newSize) {
  370. parameters.setSize(newSize);
  371. }
  372. parameters.setElementAt(obj, index);
  373. return this;
  374. }
  375. /**
  376. * Replaces an Object in the list of parameters with a Byte.
  377. * If the index lies beyond the current source list,
  378. * the list is extended with nulls as needed.
  379. * @param b the parameter that replaces the
  380. * parameter at the specified index in the
  381. * <code>parameters</code> <code>Vector</code>
  382. * @param index the index of the parameter to be
  383. * replaced with the specified parameter
  384. * @return a new <code>ParameterBlock</code> containing
  385. * the specified parameter.
  386. */
  387. public ParameterBlock set(byte b, int index) {
  388. return set(new Byte(b), index);
  389. }
  390. /**
  391. * Replaces an Object in the list of parameters with a Character.
  392. * If the index lies beyond the current source list,
  393. * the list is extended with nulls as needed.
  394. * @param c the parameter that replaces the
  395. * parameter at the specified index in the
  396. * <code>parameters</code> <code>Vector</code>
  397. * @param index the index of the parameter to be
  398. * replaced with the specified parameter
  399. * @return a new <code>ParameterBlock</code> containing
  400. * the specified parameter.
  401. */
  402. public ParameterBlock set(char c, int index) {
  403. return set(new Character(c), index);
  404. }
  405. /**
  406. * Replaces an Object in the list of parameters with a Short.
  407. * If the index lies beyond the current source list,
  408. * the list is extended with nulls as needed.
  409. * @param s the parameter that replaces the
  410. * parameter at the specified index in the
  411. * <code>parameters</code> <code>Vector</code>
  412. * @param index the index of the parameter to be
  413. * replaced with the specified parameter
  414. * @return a new <code>ParameterBlock</code> containing
  415. * the specified parameter.
  416. */
  417. public ParameterBlock set(short s, int index) {
  418. return set(new Short(s), index);
  419. }
  420. /**
  421. * Replaces an Object in the list of parameters with an Integer.
  422. * If the index lies beyond the current source list,
  423. * the list is extended with nulls as needed.
  424. * @param i the parameter that replaces the
  425. * parameter at the specified index in the
  426. * <code>parameters</code> <code>Vector</code>
  427. * @param index the index of the parameter to be
  428. * replaced with the specified parameter
  429. * @return a new <code>ParameterBlock</code> containing
  430. * the specified parameter.
  431. */
  432. public ParameterBlock set(int i, int index) {
  433. return set(new Integer(i), index);
  434. }
  435. /**
  436. * Replaces an Object in the list of parameters with a Long.
  437. * If the index lies beyond the current source list,
  438. * the list is extended with nulls as needed.
  439. * @param l the parameter that replaces the
  440. * parameter at the specified index in the
  441. * <code>parameters</code> <code>Vector</code>
  442. * @param index the index of the parameter to be
  443. * replaced with the specified parameter
  444. * @return a new <code>ParameterBlock</code> containing
  445. * the specified parameter.
  446. */
  447. public ParameterBlock set(long l, int index) {
  448. return set(new Long(l), index);
  449. }
  450. /**
  451. * Replaces an Object in the list of parameters with a Float.
  452. * If the index lies beyond the current source list,
  453. * the list is extended with nulls as needed.
  454. * @param f the parameter that replaces the
  455. * parameter at the specified index in the
  456. * <code>parameters</code> <code>Vector</code>
  457. * @param index the index of the parameter to be
  458. * replaced with the specified parameter
  459. * @return a new <code>ParameterBlock</code> containing
  460. * the specified parameter.
  461. */
  462. public ParameterBlock set(float f, int index) {
  463. return set(new Float(f), index);
  464. }
  465. /**
  466. * Replaces an Object in the list of parameters with a Double.
  467. * If the index lies beyond the current source list,
  468. * the list is extended with nulls as needed.
  469. * @param d the parameter that replaces the
  470. * parameter at the specified index in the
  471. * <code>parameters</code> <code>Vector</code>
  472. * @param index the index of the parameter to be
  473. * replaced with the specified parameter
  474. * @return a new <code>ParameterBlock</code> containing
  475. * the specified parameter.
  476. */
  477. public ParameterBlock set(double d, int index) {
  478. return set(new Double(d), index);
  479. }
  480. /**
  481. * Gets a parameter as an object.
  482. * @param index the index of the parameter to get
  483. * @return an <code>Object</code> representing the
  484. * the parameter at the specified index
  485. * into the <code>parameters</code>
  486. * <code>Vector</code>.
  487. */
  488. public Object getObjectParameter(int index) {
  489. return parameters.elementAt(index);
  490. }
  491. /**
  492. * A convenience method to return a parameter as a byte. An
  493. * exception is thrown if the parameter is
  494. * <code>null</code> or not a <code>Byte</code>.
  495. *
  496. * @param index the index of the parameter to be returned.
  497. * @return the parameter at the specified index
  498. * as a <code>byte</code> value.
  499. * @throws ClassCastException if the parameter at the
  500. * specified index is not a <code>Byte</code>
  501. * @throws NullPointerException if the parameter at the specified
  502. * index is <code>null</code>
  503. * @throws ArrayIndexOutOfBoundsException if <code>index</code>
  504. * is negative or not less than the current size of this
  505. * <code>ParameterBlock</code> object
  506. */
  507. public byte getByteParameter(int index) {
  508. return ((Byte)parameters.elementAt(index)).byteValue();
  509. }
  510. /**
  511. * A convenience method to return a parameter as a char. An
  512. * exception is thrown if the parameter is
  513. * <code>null</code> or not a <code>Character</code>.
  514. *
  515. * @param index the index of the parameter to be returned.
  516. * @return the parameter at the specified index
  517. * as a <code>char</code> value.
  518. * @throws ClassCastException if the parameter at the
  519. * specified index is not a <code>Character</code>
  520. * @throws NullPointerException if the parameter at the specified
  521. * index is <code>null</code>
  522. * @throws ArrayIndexOutOfBoundsException if <code>index</code>
  523. * is negative or not less than the current size of this
  524. * <code>ParameterBlock</code> object
  525. */
  526. public char getCharParameter(int index) {
  527. return ((Character)parameters.elementAt(index)).charValue();
  528. }
  529. /**
  530. * A convenience method to return a parameter as a short. An
  531. * exception is thrown if the parameter is
  532. * <code>null</code> or not a <code>Short</code>.
  533. *
  534. * @param index the index of the parameter to be returned.
  535. * @return the parameter at the specified index
  536. * as a <code>short</code> value.
  537. * @throws ClassCastException if the parameter at the
  538. * specified index is not a <code>Short</code>
  539. * @throws NullPointerException if the parameter at the specified
  540. * index is <code>null</code>
  541. * @throws ArrayIndexOutOfBoundsException if <code>index</code>
  542. * is negative or not less than the current size of this
  543. * <code>ParameterBlock</code> object
  544. */
  545. public short getShortParameter(int index) {
  546. return ((Short)parameters.elementAt(index)).shortValue();
  547. }
  548. /**
  549. * A convenience method to return a parameter as an int. An
  550. * exception is thrown if the parameter is
  551. * <code>null</code> or not an <code>Integer</code>.
  552. *
  553. * @param index the index of the parameter to be returned.
  554. * @return the parameter at the specified index
  555. * as a <code>int</code> value.
  556. * @throws ClassCastException if the parameter at the
  557. * specified index is not a <code>Integer</code>
  558. * @throws NullPointerException if the parameter at the specified
  559. * index is <code>null</code>
  560. * @throws ArrayIndexOutOfBoundsException if <code>index</code>
  561. * is negative or not less than the current size of this
  562. * <code>ParameterBlock</code> object
  563. */
  564. public int getIntParameter(int index) {
  565. return ((Integer)parameters.elementAt(index)).intValue();
  566. }
  567. /**
  568. * A convenience method to return a parameter as a long. An
  569. * exception is thrown if the parameter is
  570. * <code>null</code> or not a <code>Long</code>.
  571. *
  572. * @param index the index of the parameter to be returned.
  573. * @return the parameter at the specified index
  574. * as a <code>long</code> value.
  575. * @throws ClassCastException if the parameter at the
  576. * specified index is not a <code>Long</code>
  577. * @throws NullPointerException if the parameter at the specified
  578. * index is <code>null</code>
  579. * @throws ArrayIndexOutOfBoundsException if <code>index</code>
  580. * is negative or not less than the current size of this
  581. * <code>ParameterBlock</code> object
  582. */
  583. public long getLongParameter(int index) {
  584. return ((Long)parameters.elementAt(index)).longValue();
  585. }
  586. /**
  587. * A convenience method to return a parameter as a float. An
  588. * exception is thrown if the parameter is
  589. * <code>null</code> or not a <code>Float</code>.
  590. *
  591. * @param index the index of the parameter to be returned.
  592. * @return the parameter at the specified index
  593. * as a <code>float</code> value.
  594. * @throws ClassCastException if the parameter at the
  595. * specified index is not a <code>Float</code>
  596. * @throws NullPointerException if the parameter at the specified
  597. * index is <code>null</code>
  598. * @throws ArrayIndexOutOfBoundsException if <code>index</code>
  599. * is negative or not less than the current size of this
  600. * <code>ParameterBlock</code> object
  601. */
  602. public float getFloatParameter(int index) {
  603. return ((Float)parameters.elementAt(index)).floatValue();
  604. }
  605. /**
  606. * A convenience method to return a parameter as a double. An
  607. * exception is thrown if the parameter is
  608. * <code>null</code> or not a <code>Double</code>.
  609. *
  610. * @param index the index of the parameter to be returned.
  611. * @return the parameter at the specified index
  612. * as a <code>double</code> value.
  613. * @throws ClassCastException if the parameter at the
  614. * specified index is not a <code>Double</code>
  615. * @throws NullPointerException if the parameter at the specified
  616. * index is <code>null</code>
  617. * @throws ArrayIndexOutOfBoundsException if <code>index</code>
  618. * is negative or not less than the current size of this
  619. * <code>ParameterBlock</code> object
  620. */
  621. public double getDoubleParameter(int index) {
  622. return ((Double)parameters.elementAt(index)).doubleValue();
  623. }
  624. /**
  625. * Returns an array of Class objects describing the types
  626. * of the parameters.
  627. * @return an array of <code>Class</code> objects.
  628. */
  629. public Class [] getParamClasses() {
  630. int numParams = getNumParameters();
  631. Class [] classes = new Class[numParams];
  632. int i;
  633. for (i = 0; i < numParams; i++) {
  634. Object obj = getObjectParameter(i);
  635. if (obj instanceof Byte) {
  636. classes[i] = byte.class;
  637. } else if (obj instanceof Character) {
  638. classes[i] = char.class;
  639. } else if (obj instanceof Short) {
  640. classes[i] = short.class;
  641. } else if (obj instanceof Integer) {
  642. classes[i] = int.class;
  643. } else if (obj instanceof Long) {
  644. classes[i] = long.class;
  645. } else if (obj instanceof Float) {
  646. classes[i] = float.class;
  647. } else if (obj instanceof Double) {
  648. classes[i] = double.class;
  649. } else {
  650. classes[i] = obj.getClass();
  651. }
  652. }
  653. return classes;
  654. }
  655. }