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