Java > Open Source Codes > org > pdfbox > cos > COSDictionary


1 /**
2  * Copyright (c) 2003-2005, www.pdfbox.org
3  * All rights reserved.
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions are met:
7  *
8  * 1. Redistributions of source code must retain the above copyright notice,
9  * this list of conditions and the following disclaimer.
10  * 2. Redistributions in binary form must reproduce the above copyright notice,
11  * this list of conditions and the following disclaimer in the documentation
12  * and/or other materials provided with the distribution.
13  * 3. Neither the name of pdfbox; nor the names of its
14  * contributors may be used to endorse or promote products derived from this
15  * software without specific prior written permission.
16  *
17  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
18  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
20  * DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY
21  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
22  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
23  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
24  * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
26  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27  *
28  * http://www.pdfbox.org
29  *
30  */
31 package org.pdfbox.cos;
32
33 import java.io.IOException ;
34 import java.util.ArrayList ;
35 import java.util.Calendar ;
36 import java.util.Collection ;
37 import java.util.HashMap ;
38 import java.util.List ;
39 import java.util.Map ;
40
41 import java.util.Iterator ;
42
43 import org.pdfbox.exceptions.COSVisitorException;
44
45 import org.pdfbox.pdmodel.common.COSObjectable;
46 import org.pdfbox.util.DateConverter;
47
48 /**
49  * This class represents a dictionary where name/value pairs reside.
50  *
51  * @author <a HREF="ben@benlitchfield.com">Ben Litchfield</a>
52  * @version $Revision: 1.32 $
53  */
54 public class COSDictionary extends COSBase
55 {
56     private static final String PATH_SEPARATOR = "/";
57     
58     /**
59      * These are all of the items in the dictionary.
60      */
61     private Map items = new HashMap ();
62
63     /**
64      * Used to store original sequence of keys, for testing.
65      */
66     private List keys = new ArrayList ();
67
68     /**
69      * Constructor.
70      */
71     public COSDictionary()
72     {
73         //default constructor
74 }
75
76     /**
77      * Copy Constructor. This will make a shallow copy of this dictionary.
78      *
79      * @param dict The dictionary to copy.
80      */
81     public COSDictionary( COSDictionary dict )
82     {
83         items = new HashMap ( dict.items );
84         keys = new ArrayList ( dict.keys );
85     }
86     
87     /**
88      * @see java.util.Map#containsValue(java.lang.Object)
89      *
90      * @param value The value to find in the map.
91      *
92      * @return true if the map contains this value.
93      */
94     public boolean containsValue( Object value )
95     {
96         boolean contains = items.containsValue( value );
97         if( !contains && value instanceof COSObject )
98         {
99             contains = items.containsValue( ((COSObject)value).getObject());
100         }
101         return contains;
102     }
103     
104     /**
105      * Search in the map for the value that matches the parameter
106      * and return the first key that maps to that value.
107      *
108      * @param value The value to search for in the map.
109      * @return The key for the value in the map or null if it does not exist.
110      */
111     public COSName getKeyForValue( Object value )
112     {
113         COSName key = null;
114         Iterator iter = items.entrySet().iterator();
115         while( key == null && iter.hasNext() )
116         {
117             Map.Entry next = (Map.Entry )iter.next();
118             Object nextValue = next.getValue();
119             if( nextValue.equals( value ) ||
120                 (nextValue instanceof COSObject &&
121                  ((COSObject)nextValue).getObject().equals( value))
122                 )
123             {
124                 key = (COSName)next.getKey();
125             }
126         }
127         
128         return key;
129     }
130
131     /**
132      * This will return the number of elements in this dictionary.
133      *
134      * @return The number of elements in the dictionary.
135      */
136     public int size()
137     {
138         return keys.size();
139     }
140
141     /**
142      * This will clear all items in the map.
143      */
144     public void clear()
145     {
146         items.clear();
147         keys.clear();
148     }
149
150     /**
151      * This will get an object from this dictionary. If the object is a reference then it will
152      * dereference it and get it from the document. If the object is COSNull then
153      * null will be returned.
154      *
155      * @param key The key to the object that we are getting.
156      *
157      * @return The object that matches the key.
158      */
159     public COSBase getDictionaryObject( String key )
160     {
161         return getDictionaryObject( COSName.getPDFName( key ) );
162     }
163     
164     /**
165      * This is a special case of getDictionaryObject that takes multiple keys, it will handle
166      * the situation where multiple keys could get the same value, ie if either CS or ColorSpace
167      * is used to get the colorspace.
168      * This will get an object from this dictionary. If the object is a reference then it will
169      * dereference it and get it from the document. If the object is COSNull then
170      * null will be returned.
171      *
172      * @param firstKey The first key to try.
173      * @param secondKey The second key to try.
174      *
175      * @return The object that matches the key.
176      */
177     public COSBase getDictionaryObject( String firstKey, String secondKey )
178     {
179         COSBase retval = getDictionaryObject( COSName.getPDFName( firstKey ) );
180         if( retval == null )
181         {
182             retval = getDictionaryObject( COSName.getPDFName( secondKey ) );
183         }
184         return retval;
185     }
186     
187     /**
188      * This is a special case of getDictionaryObject that takes multiple keys, it will handle
189      * the situation where multiple keys could get the same value, ie if either CS or ColorSpace
190      * is used to get the colorspace.
191      * This will get an object from this dictionary. If the object is a reference then it will
192      * dereference it and get it from the document. If the object is COSNull then
193      * null will be returned.
194      *
195      * @param keyList The list of keys to find a value.
196      *
197      * @return The object that matches the key.
198      */
199     public COSBase getDictionaryObject( String [] keyList )
200     {
201         COSBase retval = null;
202         for( int i=0; i<keyList.length && retval == null; i++ )
203         {
204             retval = getDictionaryObject( COSName.getPDFName( keyList[i] ) );
205         }
206         return retval;
207     }
208
209     /**
210      * This will get an object from this dictionary. If the object is a reference then it will
211      * dereference it and get it from the document. If the object is COSNull then
212      * null will be returned.
213      *
214      * @param key The key to the object that we are getting.
215      *
216      * @return The object that matches the key.
217      */
218     public COSBase getDictionaryObject( COSName key )
219     {
220         COSBase retval = (COSBase)items.get( key );
221         if( retval instanceof COSObject )
222         {
223             retval = ((COSObject)retval).getObject();
224         }
225         if( retval instanceof COSNull )
226         {
227             retval = null;
228         }
229         return retval;
230     }
231
232     /**
233      * This will set an item in the dictionary. If value is null then the result
234      * will be the same as removeItem( key ).
235      *
236      * @param key The key to the dictionary object.
237      * @param value The value to the dictionary object.
238      */
239     public void setItem( COSName key, COSBase value )
240     {
241         if( value == null )
242         {
243             removeItem( key );
244         }
245         else
246         {
247             if (!items.containsKey(key))
248             {
249                 // insert only if not already there
250 keys.add(key);
251             }
252             items.put( key, value );
253         }
254     }
255
256     /**
257      * This will set an item in the dictionary. If value is null then the result
258      * will be the same as removeItem( key ).
259      *
260      * @param key The key to the dictionary object.
261      * @param value The value to the dictionary object.
262      */
263     public void setItem( COSName key, COSObjectable value )
264     {
265         COSBase base = null;
266         if( value != null )
267         {
268             base = value.getCOSObject();
269         }
270         setItem( key, base );
271     }
272
273     /**
274      * This will set an item in the dictionary. If value is null then the result
275      * will be the same as removeItem( key ).
276      *
277      * @param key The key to the dictionary object.
278      * @param value The value to the dictionary object.
279      */
280     public void setItem( String key, COSObjectable value )
281     {
282         setItem( COSName.getPDFName( key ), value );
283     }
284
285     /**
286      * This will set an item in the dictionary.
287      *
288      * @param key The key to the dictionary object.
289      * @param value The value to the dictionary object.
290      */
291     public void setBoolean( String key, boolean value )
292     {
293         setItem( COSName.getPDFName( key ), COSBoolean.getBoolean( value ) );
294     }
295
296     /**
297      * This will set an item in the dictionary.
298      *
299      * @param key The key to the dictionary object.
300      * @param value The value to the dictionary object.
301      */
302     public void setBoolean( COSName key, boolean value )
303     {
304         setItem( key , COSBoolean.getBoolean( value ) );
305     }
306
307     /**
308      * This will set an item in the dictionary. If value is null then the result
309      * will be the same as removeItem( key ).
310      *
311      * @param key The key to the dictionary object.
312      * @param value The value to the dictionary object.
313      */
314     public void setItem( String key, COSBase value )
315     {
316         setItem( COSName.getPDFName( key ), value );
317     }
318
319     /**
320      * This is a convenience method that will convert the value to a COSName
321      * object. If it is null then the object will be removed.
322      *
323      * @param key The key to the object,
324      * @param value The string value for the name.
325      */
326     public void setName( String key, String value )
327     {
328         setName( COSName.getPDFName( key ), value );
329     }
330
331     /**
332      * This is a convenience method that will convert the value to a COSName
333      * object. If it is null then the object will be removed.
334      *
335      * @param key The key to the object,
336      * @param value The string value for the name.
337      */
338     public void setName( COSName key, String value )
339     {
340         COSName name = null;
341         if( value != null )
342         {
343             name = COSName.getPDFName( value );
344         }
345         setItem( key, name );
346     }
347     
348     /**
349      * Set the value of a date entry in the dictionary.
350      *
351      * @param key The key to the date value.
352      * @param date The date value.
353      */
354     public void setDate( String key, Calendar date )
355     {
356         setDate( COSName.getPDFName( key ), date );
357     }
358     
359     /**
360      * Set the date object.
361      *
362      * @param key The key to the date.
363      * @param date The date to set.
364      */
365     public void setDate( COSName key, Calendar date )
366     {
367         setString( key, DateConverter.toString( date ) );
368     }
369     
370     /**
371      * Set the value of a date entry in the dictionary.
372      *
373      * @param embedded The embedded dictionary.
374      * @param key The key to the date value.
375      * @param date The date value.
376      */
377     public void setEmbeddedDate( String embedded, String key, Calendar date )
378     {
379         setEmbeddedDate( embedded, COSName.getPDFName( key ), date );
380     }
381     
382     /**
383      * Set the date object.
384      *
385      * @param embedded The embedded dictionary.
386      * @param key The key to the date.
387      * @param date The date to set.
388      */
389     public void setEmbeddedDate( String embedded, COSName key, Calendar date )
390     {
391         COSDictionary dic = (COSDictionary)getDictionaryObject( embedded );
392         if( dic == null && date != null )
393         {
394             dic = new COSDictionary();
395             setItem( embedded, dic );
396         }
397         if( dic != null )
398         {
399             dic.setDate( key, date );
400         }
401     }
402
403     /**
404      * This is a convenience method that will convert the value to a COSString
405      * object. If it is null then the object will be removed.
406      *
407      * @param key The key to the object,
408      * @param value The string value for the name.
409      */
410     public void setString( String key, String value )
411     {
412         setString( COSName.getPDFName( key ), value );
413     }
414
415     /**
416      * This is a convenience method that will convert the value to a COSString
417      * object. If it is null then the object will be removed.
418      *
419      * @param key The key to the object,
420      * @param value The string value for the name.
421      */
422     public void setString( COSName key, String value )
423     {
424         COSString name = null;
425         if( value != null )
426         {
427             name = new COSString( value );
428         }
429         setItem( key, name );
430     }
431     
432     /**
433      * This is a convenience method that will convert the value to a COSString
434      * object. If it is null then the object will be removed.
435      *
436      * @param embedded The embedded dictionary to set the item in.
437      * @param key The key to the object,
438      * @param value The string value for the name.
439      */
440     public void setEmbeddedString( String embedded, String key, String value )
441     {
442         setEmbeddedString( embedded, COSName.getPDFName( key ), value );
443     }
444
445     /**
446      * This is a convenience method that will convert the value to a COSString
447      * object. If it is null then the object will be removed.
448      *
449      * @param embedded The embedded dictionary to set the item in.
450      * @param key The key to the object,
451      * @param value The string value for the name.
452      */
453     public void setEmbeddedString( String embedded, COSName key, String value )
454     {
455         COSDictionary dic = (COSDictionary)getDictionaryObject( embedded );
456         if( dic == null && value != null )
457         {
458             dic = new COSDictionary();
459             setItem( embedded, dic );
460         }
461         if( dic != null )
462         {
463             dic.setString( key, value );
464         }
465     }
466     
467     /**
468      * This is a convenience method that will convert the value to a COSInteger
469      * object.
470      *
471      * @param key The key to the object,
472      * @param value The int value for the name.
473      */
474     public void setInt( String key, int value )
475     {
476         setInt( COSName.getPDFName( key ), value );
477     }
478
479     /**
480      * This is a convenience method that will convert the value to a COSInteger
481      * object.
482      *
483      * @param key The key to the object,
484      * @param value The int value for the name.
485      */
486     public void setInt( COSName key, int value )
487     {
488         COSInteger intVal = null;
489         intVal = new COSInteger(value);
490         setItem( key, intVal );
491     }
492     
493     /**
494      * This is a convenience method that will convert the value to a COSInteger
495      * object.
496      *
497      * @param key The key to the object,
498      * @param value The int value for the name.
499      */
500     public void setLong( String key, long value )
501     {
502         setLong( COSName.getPDFName( key ), value );
503     }
504
505     /**
506      * This is a convenience method that will convert the value to a COSInteger
507      * object.
508      *
509      * @param key The key to the object,
510      * @param value The int value for the name.
511      */
512     public void setLong( COSName key, long value )
513     {
514         COSInteger intVal = null;
515         intVal = new COSInteger(value);
516         setItem( key, intVal );
517     }
518     
519     /**
520      * This is a convenience method that will convert the value to a COSInteger
521      * object.
522      *
523      * @param embeddedDictionary The embedded dictionary.
524      * @param key The key to the object,
525      * @param value The int value for the name.
526      */
527     public void setEmbeddedInt( String embeddedDictionary, String key, int value )
528     {
529         setEmbeddedInt( embeddedDictionary, COSName.getPDFName( key ), value );
530     }
531
532     /**
533      * This is a convenience method that will convert the value to a COSInteger
534      * object.
535      *
536      * @param embeddedDictionary The embedded dictionary.
537      * @param key The key to the object,
538      * @param value The int value for the name.
539      */
540     public void setEmbeddedInt( String embeddedDictionary, COSName key, int value )
541     {
542         COSDictionary embedded = (COSDictionary)getDictionaryObject( embeddedDictionary );
543         if( embedded == null )
544         {
545             embedded = new COSDictionary();
546             setItem( embeddedDictionary, embedded );
547         }
548         embedded.setInt( key, value );
549     }
550     
551     /**
552      * This is a convenience method that will convert the value to a COSFloat
553      * object.
554      *
555      * @param key The key to the object,
556      * @param value The int value for the name.
557      */
558     public void setFloat( String key, float value )
559     {
560         setFloat( COSName.getPDFName( key ), value );
561     }
562
563     /**
564      * This is a convenience method that will convert the value to a COSFloat
565      * object.
566      *
567      * @param key The key to the object,
568      * @param value The int value for the name.
569      */
570     public void setFloat( COSName key, float value )
571     {
572         COSFloat fltVal = new COSFloat( value );
573         setItem( key, fltVal );
574     }
575
576     /**
577      * This is a convenience method that will get the dictionary object that
578      * is expected to be a name and convert it to a string. Null is returned
579      * if the entry does not exist in the dictionary.
580      *
581      * @param key The key to the item in the dictionary.
582      * @return The name converted to a string.
583      */
584     public String getNameAsString( String key )
585     {
586         return getNameAsString( COSName.getPDFName( key ) );
587     }
588
589     /**
590      * This is a convenience method that will get the dictionary object that
591      * is expected to be a name and convert it to a string. Null is returned
592      * if the entry does not exist in the dictionary.
593      *
594      * @param key The key to the item in the dictionary.
595      * @return The name converted to a string.
596      */
597     public String getNameAsString( COSName key )
598     {
599         String retval = null;
600         COSName name = (COSName)getDictionaryObject( key );
601         if( name != null )
602         {
603             retval = name.getName();
604         }
605         return retval;
606     }
607     
608     /**
609      * This is a convenience method that will get the dictionary object that
610      * is expected to be a name and convert it to a string. Null is returned
611      * if the entry does not exist in the dictionary.
612      *
613      * @param key The key to the item in the dictionary.
614      * @param defaultValue The value to return if the dictionary item is null.
615      * @return The name converted to a string.
616      */
617     public String getNameAsString( String key, String defaultValue )
618     {
619         return getNameAsString( COSName.getPDFName( key ), defaultValue );
620     }
621
622     /**
623      * This is a convenience method that will get the dictionary object that
624      * is expected to be a name and convert it to a string. Null is returned
625      * if the entry does not exist in the dictionary.
626      *
627      * @param key The key to the item in the dictionary.
628      * @param defaultValue The value to return if the dictionary item is null.
629      * @return The name converted to a string.
630      */
631     public String getNameAsString( COSName key, String defaultValue )
632     {
633         String retval = getNameAsString( key );
634         if( retval == null )
635         {
636             retval = defaultValue;
637         }
638         return retval;
639     }
640
641     /**
642      * This is a convenience method that will get the dictionary object that
643      * is expected to be a name and convert it to a string. Null is returned
644      * if the entry does not exist in the dictionary.
645      *
646      * @param key The key to the item in the dictionary.
647      * @return The name converted to a string.
648      */
649     public String getString( String key )
650     {
651         return getString( COSName.getPDFName( key ) );
652     }
653
654     /**
655      * This is a convenience method that will get the dictionary object that
656      * is expected to be a name and convert it to a string. Null is returned
657      * if the entry does not exist in the dictionary.
658      *
659      * @param key The key to the item in the dictionary.
660      * @return The name converted to a string.
661      */
662     public String getString( COSName key )
663     {
664         String retval = null;
665         COSString name = (COSString)getDictionaryObject( key );
666         if( name != null )
667         {
668             retval = name.getString();
669         }
670         return retval;
671     }
672     
673     /**
674      * This is a convenience method that will get the dictionary object that
675      * is expected to be a name and convert it to a string. Null is returned
676      * if the entry does not exist in the dictionary.
677      *
678      * @param key The key to the item in the dictionary.
679      * @param defaultValue The default value to return.
680      * @return The name converted to a string.
681      */
682     public String getString( String key, String defaultValue )
683     {
684         return getString( COSName.getPDFName( key ), defaultValue );
685     }
686
687     /**
688      * This is a convenience method that will get the dictionary object that
689      * is expected to be a name and convert it to a string. Null is returned
690      * if the entry does not exist in the dictionary.
691      *
692      * @param key The key to the item in the dictionary.
693      * @param defaultValue The default value to return.
694      * @return The name converted to a string.
695      */
696     public String getString( COSName key, String defaultValue )
697     {
698         String retval = getString( key );
699         if( retval == null )
700         {
701             retval = defaultValue;
702         }
703         return retval;
704     }
705     
706     /**
707      * This is a convenience method that will get the dictionary object that
708      * is expected to be a name and convert it to a string. Null is returned
709      * if the entry does not exist in the dictionary.
710      *
711      * @param embedded The embedded dictionary.
712      * @param key The key to the item in the dictionary.
713      * @return The name converted to a string.
714      */
715     public String getEmbeddedString( String embedded, String key )
716     {
717         return getEmbeddedString( embedded, COSName.getPDFName( key ), null );
718     }
719
720     /**
721      * This is a convenience method that will get the dictionary object that
722      * is expected to be a name and convert it to a string. Null is returned
723      * if the entry does not exist in the dictionary.
724      *
725      * @param embedded The embedded dictionary.
726      * @param key The key to the item in the dictionary.
727      * @return The name converted to a string.
728      */
729     public String getEmbeddedString( String embedded, COSName key )
730     {
731         return getEmbeddedString( embedded, key, null );
732     }
733     
734     /**
735      * This is a convenience method that will get the dictionary object that
736      * is expected to be a name and convert it to a string. Null is returned
737      * if the entry does not exist in the dictionary.
738      *
739      * @param embedded The embedded dictionary.
740      * @param key The key to the item in the dictionary.
741      * @param defaultValue The default value to return.
742      * @return The name converted to a string.
743      */
744     public String getEmbeddedString( String embedded, String key, String defaultValue )
745     {
746         return getEmbeddedString( embedded, COSName.getPDFName( key ), defaultValue );
747     }
748
749     /**
750      * This is a convenience method that will get the dictionary object that
751      * is expected to be a name and convert it to a string. Null is returned
752      * if the entry does not exist in the dictionary.
753      *
754      * @param embedded The embedded dictionary.
755      * @param key The key to the item in the dictionary.
756      * @param defaultValue The default value to return.
757      * @return The name converted to a string.
758      */
759     public String getEmbeddedString( String embedded, COSName key, String defaultValue )
760     {
761         String retval = defaultValue;
762         COSDictionary dic = (COSDictionary)getDictionaryObject( embedded );
763         if( dic != null )
764         {
765             retval = dic.getString( key, defaultValue );
766         }
767         return retval;
768     }
769     
770     /**
771      * This is a convenience method that will get the dictionary object that
772      * is expected to be a name and convert it to a string. Null is returned
773      * if the entry does not exist in the dictionary.
774      *
775      * @param key The key to the item in the dictionary.
776      * @return The name converted to a string.
777      * @throws IOException If there is an error converting to a date.
778      */
779     public Calendar getDate( String key ) throws IOException
780     {
781         return getDate( COSName.getPDFName( key ) );
782     }
783
784     /**
785      * This is a convenience method that will get the dictionary object that
786      * is expected to be a name and convert it to a string. Null is returned
787      * if the entry does not exist in the dictionary.
788      *
789      * @param key The key to the item in the dictionary.
790      * @return The name converted to a string.
791      *
792      * @throws IOException If there is an error converting to a date.
793      */
794     public Calendar getDate( COSName key ) throws IOException
795     {
796         COSString date = (COSString)getDictionaryObject( key );
797         return DateConverter.toCalendar( date );
798     }
799     
800     /**
801      * This is a convenience method that will get the dictionary object that
802      * is expected to be a date. Null is returned
803      * if the entry does not exist in the dictionary.
804      *
805      * @param key The key to the item in the dictionary.
806      * @param defaultValue The default value to return.
807      * @return The name converted to a string.
808      * @throws IOException If there is an error converting to a date.
809      */
810     public Calendar getDate( String key, Calendar defaultValue ) throws IOException
811     {
812         return getDate( COSName.getPDFName( key ), defaultValue );
813     }
814
815     /**
816      * This is a convenience method that will get the dictionary object that
817      * is expected to be a date. Null is returned
818      * if the entry does not exist in the dictionary.
819      *
820      * @param key The key to the item in the dictionary.
821      * @param defaultValue The default value to return.
822      * @return The name converted to a string.
823      * @throws IOException If there is an error converting to a date.
824      */
825     public Calendar getDate( COSName key, Calendar defaultValue ) throws IOException
826     {
827         Calendar retval = getDate( key );
828         if( retval == null )
829         {
830             retval = defaultValue;
831         }
832         return retval;
833     }
834     
835     /**
836      * This is a convenience method that will get the dictionary object that
837      * is expected to be a name and convert it to a string. Null is returned
838      * if the entry does not exist in the dictionary.
839      *
840      * @param embedded The embedded dictionary to get.
841      * @param key The key to the item in the dictionary.
842      * @return The name converted to a string.
843      * @throws IOException If there is an error converting to a date.
844      */
845     public Calendar getEmbeddedDate( String embedded, String key ) throws IOException
846     {
847         return getEmbeddedDate( embedded, COSName.getPDFName( key ), null );
848     }
849
850     /**
851      * This is a convenience method that will get the dictionary object that
852      * is expected to be a name and convert it to a string. Null is returned
853      * if the entry does not exist in the dictionary.
854      *
855      * @param embedded The embedded dictionary to get.
856      * @param key The key to the item in the dictionary.
857      * @return The name converted to a string.
858      *
859      * @throws IOException If there is an error converting to a date.
860      */
861     public Calendar getEmbeddedDate( String embedded, COSName key ) throws IOException
862     {
863         return getEmbeddedDate( embedded, key, null );
864     }
865     
866     /**
867      * This is a convenience method that will get the dictionary object that
868      * is expected to be a date. Null is returned
869      * if the entry does not exist in the dictionary.
870      *
871      * @param embedded The embedded dictionary to get.
872      * @param key The key to the item in the dictionary.
873      * @param defaultValue The default value to return.
874      * @return The name converted to a string.
875      * @throws IOException If there is an error converting to a date.
876      */
877     public Calendar getEmbeddedDate( String embedded, String key, Calendar defaultValue ) throws IOException
878     {
879         return getEmbeddedDate( embedded, COSName.getPDFName( key ), defaultValue );
880     }
881
882     /**
883      * This is a convenience method that will get the dictionary object that
884      * is expected to be a date. Null is returned
885      * if the entry does not exist in the dictionary.
886      *
887      * @param embedded The embedded dictionary to get.
888      * @param key The key to the item in the dictionary.
889      * @param defaultValue The default value to return.
890      * @return The name converted to a string.
891      * @throws IOException If there is an error converting to a date.
892      */
893     public Calendar getEmbeddedDate( String embedded, COSName key, Calendar defaultValue ) throws IOException
894     {
895         Calendar retval = defaultValue;
896         COSDictionary eDic = (COSDictionary)getDictionaryObject( embedded );
897         if( eDic != null )
898         {
899             retval = eDic.getDate( key, defaultValue );
900         }
901         return retval;
902     }
903
904     /**
905      * This is a convenience method that will get the dictionary object that
906      * is expected to be a cos boolean and convert it to a primitive boolean.
907      *
908      * @param key The key to the item in the dictionary.
909      * @param defaultValue The value returned if the entry is null.
910      *
911      * @return The value converted to a boolean.
912      */
913     public boolean getBoolean( String key, boolean defaultValue )
914     {
915         return getBoolean( COSName.getPDFName( key ), defaultValue );
916     }
917
918     /**
919      * This is a convenience method that will get the dictionary object that
920      * is expected to be a COSBoolean and convert it to a primitive boolean.
921      *
922      * @param key The key to the item in the dictionary.
923      * @param defaultValue The value returned if the entry is null.
924      *
925      * @return The entry converted to a boolean.
926      */
927     public boolean getBoolean( COSName key, boolean defaultValue )
928     {
929         boolean retval = defaultValue;
930         COSBoolean bool = (COSBoolean)getDictionaryObject( key );
931         if( bool != null )
932         {
933             retval = bool.getValue();
934         }
935