001 /*
002 * Copyright 2000-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 javax.print.attribute;
027
028 import java.io.Serializable;
029
030 /**
031 * Class AttributeSetUtilities provides static methods for manipulating
032 * AttributeSets.
033 * <ul>
034 * <li>Methods for creating unmodifiable and synchronized views of attribute
035 * sets.
036 * <li>operations useful for building
037 * implementations of interface {@link AttributeSet AttributeSet}
038 * </ul>
039 * <P>
040 * An <B>unmodifiable view</B> <I>U</I> of an AttributeSet <I>S</I> provides a
041 * client with "read-only" access to <I>S</I>. Query operations on <I>U</I>
042 * "read through" to <I>S</I>; thus, changes in <I>S</I> are reflected in
043 * <I>U</I>. However, any attempt to modify <I>U</I>,
044 * results in an UnmodifiableSetException.
045 * The unmodifiable view object <I>U</I> will be serializable if the
046 * attribute set object <I>S</I> is serializable.
047 * <P>
048 * A <B>synchronized view</B> <I>V</I> of an attribute set <I>S</I> provides a
049 * client with synchronized (multiple thread safe) access to <I>S</I>. Each
050 * operation of <I>V</I> is synchronized using <I>V</I> itself as the lock
051 * object and then merely invokes the corresponding operation of <I>S</I>. In
052 * order to guarantee mutually exclusive access, it is critical that all
053 * access to <I>S</I> is accomplished through <I>V</I>. The synchronized view
054 * object <I>V</I> will be serializable if the attribute set object <I>S</I>
055 * is serializable.
056 * <P>
057 * As mentioned in the package description of javax.print, a null reference
058 * parameter to methods is
059 * incorrect unless explicitly documented on the method as having a meaningful
060 * interpretation. Usage to the contrary is incorrect coding and may result in
061 * a run time exception either immediately
062 * or at some later time. IllegalArgumentException and NullPointerException
063 * are examples of typical and acceptable run time exceptions for such cases.
064 *
065 * @author Alan Kaminsky
066 */
067 public final class AttributeSetUtilities {
068
069 /* Suppress default constructor, ensuring non-instantiability.
070 */
071 private AttributeSetUtilities() {
072 }
073
074 /**
075 * @serial include
076 */
077 private static class UnmodifiableAttributeSet implements
078 AttributeSet, Serializable {
079
080 private AttributeSet attrset;
081
082 /* Unmodifiable view of the underlying attribute set.
083 */
084 public UnmodifiableAttributeSet(AttributeSet attributeSet) {
085
086 attrset = attributeSet;
087 }
088
089 public Attribute get(Class<?> key) {
090 return attrset.get(key);
091 }
092
093 public boolean add(Attribute attribute) {
094 throw new UnmodifiableSetException();
095 }
096
097 public synchronized boolean remove(Class<?> category) {
098 throw new UnmodifiableSetException();
099 }
100
101 public boolean remove(Attribute attribute) {
102 throw new UnmodifiableSetException();
103 }
104
105 public boolean containsKey(Class<?> category) {
106 return attrset.containsKey(category);
107 }
108
109 public boolean containsValue(Attribute attribute) {
110 return attrset.containsValue(attribute);
111 }
112
113 public boolean addAll(AttributeSet attributes) {
114 throw new UnmodifiableSetException();
115 }
116
117 public int size() {
118 return attrset.size();
119 }
120
121 public Attribute[] toArray() {
122 return attrset.toArray();
123 }
124
125 public void clear() {
126 throw new UnmodifiableSetException();
127 }
128
129 public boolean isEmpty() {
130 return attrset.isEmpty();
131 }
132
133 public boolean equals(Object o) {
134 return attrset.equals(o);
135 }
136
137 public int hashCode() {
138 return attrset.hashCode();
139 }
140
141 }
142
143 /**
144 * @serial include
145 */
146 private static class UnmodifiableDocAttributeSet extends
147 UnmodifiableAttributeSet implements DocAttributeSet,
148 Serializable {
149
150 public UnmodifiableDocAttributeSet(DocAttributeSet attributeSet) {
151
152 super (attributeSet);
153 }
154 }
155
156 /**
157 * @serial include
158 */
159 private static class UnmodifiablePrintRequestAttributeSet extends
160 UnmodifiableAttributeSet implements
161 PrintRequestAttributeSet, Serializable {
162 public UnmodifiablePrintRequestAttributeSet(
163 PrintRequestAttributeSet attributeSet) {
164
165 super (attributeSet);
166 }
167 }
168
169 /**
170 * @serial include
171 */
172 private static class UnmodifiablePrintJobAttributeSet extends
173 UnmodifiableAttributeSet implements PrintJobAttributeSet,
174 Serializable {
175 public UnmodifiablePrintJobAttributeSet(
176 PrintJobAttributeSet attributeSet) {
177
178 super (attributeSet);
179 }
180 }
181
182 /**
183 * @serial include
184 */
185 private static class UnmodifiablePrintServiceAttributeSet extends
186 UnmodifiableAttributeSet implements
187 PrintServiceAttributeSet, Serializable {
188 public UnmodifiablePrintServiceAttributeSet(
189 PrintServiceAttributeSet attributeSet) {
190
191 super (attributeSet);
192 }
193 }
194
195 /**
196 * Creates an unmodifiable view of the given attribute set.
197 *
198 * @param attributeSet Underlying attribute set.
199 *
200 * @return Unmodifiable view of <CODE>attributeSet</CODE>.
201 *
202 * @exception NullPointerException
203 * Thrown if <CODE>attributeSet</CODE> is null. Null is never a
204 */
205 public static AttributeSet unmodifiableView(
206 AttributeSet attributeSet) {
207 if (attributeSet == null) {
208 throw new NullPointerException();
209 }
210
211 return new UnmodifiableAttributeSet(attributeSet);
212 }
213
214 /**
215 * Creates an unmodifiable view of the given doc attribute set.
216 *
217 * @param attributeSet Underlying doc attribute set.
218 *
219 * @return Unmodifiable view of <CODE>attributeSet</CODE>.
220 *
221 * @exception NullPointerException
222 * Thrown if <CODE>attributeSet</CODE> is null.
223 */
224 public static DocAttributeSet unmodifiableView(
225 DocAttributeSet attributeSet) {
226 if (attributeSet == null) {
227 throw new NullPointerException();
228 }
229 return new UnmodifiableDocAttributeSet(attributeSet);
230 }
231
232 /**
233 * Creates an unmodifiable view of the given print request attribute set.
234 *
235 * @param attributeSet Underlying print request attribute set.
236 *
237 * @return Unmodifiable view of <CODE>attributeSet</CODE>.
238 *
239 * @exception NullPointerException
240 * Thrown if <CODE>attributeSet</CODE> is null.
241 */
242 public static PrintRequestAttributeSet unmodifiableView(
243 PrintRequestAttributeSet attributeSet) {
244 if (attributeSet == null) {
245 throw new NullPointerException();
246 }
247 return new UnmodifiablePrintRequestAttributeSet(attributeSet);
248 }
249
250 /**
251 * Creates an unmodifiable view of the given print job attribute set.
252 *
253 * @param attributeSet Underlying print job attribute set.
254 *
255 * @return Unmodifiable view of <CODE>attributeSet</CODE>.
256 *
257 * @exception NullPointerException
258 * Thrown if <CODE>attributeSet</CODE> is null.
259 */
260 public static PrintJobAttributeSet unmodifiableView(
261 PrintJobAttributeSet attributeSet) {
262 if (attributeSet == null) {
263 throw new NullPointerException();
264 }
265 return new UnmodifiablePrintJobAttributeSet(attributeSet);
266 }
267
268 /**
269 * Creates an unmodifiable view of the given print service attribute set.
270 *
271 * @param attributeSet Underlying print service attribute set.
272 *
273 * @return Unmodifiable view of <CODE>attributeSet</CODE>.
274 *
275 * @exception NullPointerException
276 * Thrown if <CODE>attributeSet</CODE> is null.
277 */
278 public static PrintServiceAttributeSet unmodifiableView(
279 PrintServiceAttributeSet attributeSet) {
280 if (attributeSet == null) {
281 throw new NullPointerException();
282 }
283 return new UnmodifiablePrintServiceAttributeSet(attributeSet);
284 }
285
286 /**
287 * @serial include
288 */
289 private static class SynchronizedAttributeSet implements
290 AttributeSet, Serializable {
291
292 private AttributeSet attrset;
293
294 public SynchronizedAttributeSet(AttributeSet attributeSet) {
295 attrset = attributeSet;
296 }
297
298 public synchronized Attribute get(Class<?> category) {
299 return attrset.get(category);
300 }
301
302 public synchronized boolean add(Attribute attribute) {
303 return attrset.add(attribute);
304 }
305
306 public synchronized boolean remove(Class<?> category) {
307 return attrset.remove(category);
308 }
309
310 public synchronized boolean remove(Attribute attribute) {
311 return attrset.remove(attribute);
312 }
313
314 public synchronized boolean containsKey(Class<?> category) {
315 return attrset.containsKey(category);
316 }
317
318 public synchronized boolean containsValue(Attribute attribute) {
319 return attrset.containsValue(attribute);
320 }
321
322 public synchronized boolean addAll(AttributeSet attributes) {
323 return attrset.addAll(attributes);
324 }
325
326 public synchronized int size() {
327 return attrset.size();
328 }
329
330 public synchronized Attribute[] toArray() {
331 return attrset.toArray();
332 }
333
334 public synchronized void clear() {
335 attrset.clear();
336 }
337
338 public synchronized boolean isEmpty() {
339 return attrset.isEmpty();
340 }
341
342 public synchronized boolean equals(Object o) {
343 return attrset.equals(o);
344 }
345
346 public synchronized int hashCode() {
347 return attrset.hashCode();
348 }
349 }
350
351 /**
352 * @serial include
353 */
354 private static class SynchronizedDocAttributeSet extends
355 SynchronizedAttributeSet implements DocAttributeSet,
356 Serializable {
357
358 public SynchronizedDocAttributeSet(DocAttributeSet attributeSet) {
359 super (attributeSet);
360 }
361 }
362
363 /**
364 * @serial include
365 */
366 private static class SynchronizedPrintRequestAttributeSet extends
367 SynchronizedAttributeSet implements
368 PrintRequestAttributeSet, Serializable {
369
370 public SynchronizedPrintRequestAttributeSet(
371 PrintRequestAttributeSet attributeSet) {
372 super (attributeSet);
373 }
374 }
375
376 /**
377 * @serial include
378 */
379 private static class SynchronizedPrintJobAttributeSet extends
380 SynchronizedAttributeSet implements PrintJobAttributeSet,
381 Serializable {
382
383 public SynchronizedPrintJobAttributeSet(
384 PrintJobAttributeSet attributeSet) {
385 super (attributeSet);
386 }
387 }
388
389 /**
390 * @serial include
391 */
392 private static class SynchronizedPrintServiceAttributeSet extends
393 SynchronizedAttributeSet implements
394 PrintServiceAttributeSet, Serializable {
395 public SynchronizedPrintServiceAttributeSet(
396 PrintServiceAttributeSet attributeSet) {
397 super (attributeSet);
398 }
399 }
400
401 /**
402 * Creates a synchronized view of the given attribute set.
403 *
404 * @param attributeSet Underlying attribute set.
405 *
406 * @return Synchronized view of <CODE>attributeSet</CODE>.
407 *
408 * @exception NullPointerException
409 * Thrown if <CODE>attributeSet</CODE> is null.
410 */
411 public static AttributeSet synchronizedView(
412 AttributeSet attributeSet) {
413 if (attributeSet == null) {
414 throw new NullPointerException();
415 }
416 return new SynchronizedAttributeSet(attributeSet);
417 }
418
419 /**
420 * Creates a synchronized view of the given doc attribute set.
421 *
422 * @param attributeSet Underlying doc attribute set.
423 *
424 * @return Synchronized view of <CODE>attributeSet</CODE>.
425 *
426 * @exception NullPointerException
427 * Thrown if <CODE>attributeSet</CODE> is null.
428 */
429 public static DocAttributeSet synchronizedView(
430 DocAttributeSet attributeSet) {
431 if (attributeSet == null) {
432 throw new NullPointerException();
433 }
434 return new SynchronizedDocAttributeSet(attributeSet);
435 }
436
437 /**
438 * Creates a synchronized view of the given print request attribute set.
439 *
440 * @param attributeSet Underlying print request attribute set.
441 *
442 * @return Synchronized view of <CODE>attributeSet</CODE>.
443 *
444 * @exception NullPointerException
445 * Thrown if <CODE>attributeSet</CODE> is null.
446 */
447 public static PrintRequestAttributeSet synchronizedView(
448 PrintRequestAttributeSet attributeSet) {
449 if (attributeSet == null) {
450 throw new NullPointerException();
451 }
452 return new SynchronizedPrintRequestAttributeSet(attributeSet);
453 }
454
455 /**
456 * Creates a synchronized view of the given print job attribute set.
457 *
458 * @param attributeSet Underlying print job attribute set.
459 *
460 * @return Synchronized view of <CODE>attributeSet</CODE>.
461 *
462 * @exception NullPointerException
463 * Thrown if <CODE>attributeSet</CODE> is null.
464 */
465 public static PrintJobAttributeSet synchronizedView(
466 PrintJobAttributeSet attributeSet) {
467 if (attributeSet == null) {
468 throw new NullPointerException();
469 }
470 return new SynchronizedPrintJobAttributeSet(attributeSet);
471 }
472
473 /**
474 * Creates a synchronized view of the given print service attribute set.
475 *
476 * @param attributeSet Underlying print service attribute set.
477 *
478 * @return Synchronized view of <CODE>attributeSet</CODE>.
479 */
480 public static PrintServiceAttributeSet synchronizedView(
481 PrintServiceAttributeSet attributeSet) {
482 if (attributeSet == null) {
483 throw new NullPointerException();
484 }
485 return new SynchronizedPrintServiceAttributeSet(attributeSet);
486 }
487
488 /**
489 * Verify that the given object is a {@link java.lang.Class Class} that
490 * implements the given interface, which is assumed to be interface {@link
491 * Attribute Attribute} or a subinterface thereof.
492 *
493 * @param object Object to test.
494 * @param interfaceName Interface the object must implement.
495 *
496 * @return If <CODE>object</CODE> is a {@link java.lang.Class Class}
497 * that implements <CODE>interfaceName</CODE>,
498 * <CODE>object</CODE> is returned downcast to type {@link
499 * java.lang.Class Class}; otherwise an exception is thrown.
500 *
501 * @exception NullPointerException
502 * (unchecked exception) Thrown if <CODE>object</CODE> is null.
503 * @exception ClassCastException
504 * (unchecked exception) Thrown if <CODE>object</CODE> is not a
505 * {@link java.lang.Class Class} that implements
506 * <CODE>interfaceName</CODE>.
507 */
508 public static Class<?> verifyAttributeCategory(Object object,
509 Class<?> interfaceName) {
510
511 Class result = (Class) object;
512 if (interfaceName.isAssignableFrom(result)) {
513 return result;
514 } else {
515 throw new ClassCastException();
516 }
517 }
518
519 /**
520 * Verify that the given object is an instance of the given interface, which
521 * is assumed to be interface {@link Attribute Attribute} or a subinterface
522 * thereof.
523 *
524 * @param object Object to test.
525 * @param interfaceName Interface of which the object must be an instance.
526 *
527 * @return If <CODE>object</CODE> is an instance of
528 * <CODE>interfaceName</CODE>, <CODE>object</CODE> is returned
529 * downcast to type {@link Attribute Attribute}; otherwise an
530 * exception is thrown.
531 *
532 * @exception NullPointerException
533 * (unchecked exception) Thrown if <CODE>object</CODE> is null.
534 * @exception ClassCastException
535 * (unchecked exception) Thrown if <CODE>object</CODE> is not an
536 * instance of <CODE>interfaceName</CODE>.
537 */
538 public static Attribute verifyAttributeValue(Object object,
539 Class<?> interfaceName) {
540
541 if (object == null) {
542 throw new NullPointerException();
543 } else if (interfaceName.isInstance(object)) {
544 return (Attribute) object;
545 } else {
546 throw new ClassCastException();
547 }
548 }
549
550 /**
551 * Verify that the given attribute category object is equal to the
552 * category of the given attribute value object. If so, this method
553 * returns doing nothing. If not, this method throws an exception.
554 *
555 * @param category Attribute category to test.
556 * @param attribute Attribute value to test.
557 *
558 * @exception NullPointerException
559 * (unchecked exception) Thrown if the <CODE>category</CODE> is
560 * null or if the <CODE>attribute</CODE> is null.
561 * @exception IllegalArgumentException
562 * (unchecked exception) Thrown if the <CODE>category</CODE> is not
563 * equal to the category of the <CODE>attribute</CODE>.
564 */
565 public static void verifyCategoryForValue(Class<?> category,
566 Attribute attribute) {
567
568 if (!category.equals(attribute.getCategory())) {
569 throw new IllegalArgumentException();
570 }
571 }
572 }
|