Home » pdfbox-1.1.0-src » org.apache.pdfbox.cos » [javadoc | source]

    1   /*
    2    * Licensed to the Apache Software Foundation (ASF) under one or more
    3    * contributor license agreements.  See the NOTICE file distributed with
    4    * this work for additional information regarding copyright ownership.
    5    * The ASF licenses this file to You under the Apache License, Version 2.0
    6    * (the "License"); you may not use this file except in compliance with
    7    * the License.  You may obtain a copy of the License at
    8    *
    9    *      http://www.apache.org/licenses/LICENSE-2.0
   10    *
   11    * Unless required by applicable law or agreed to in writing, software
   12    * distributed under the License is distributed on an "AS IS" BASIS,
   13    * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   14    * See the License for the specific language governing permissions and
   15    * limitations under the License.
   16    */
   17   package org.apache.pdfbox.cos;
   18   
   19   import java.io.IOException;
   20   import java.util.ArrayList;
   21   import java.util.Calendar;
   22   import java.util.Collection;
   23   import java.util.LinkedHashMap;
   24   import java.util.List;
   25   import java.util.Map;
   26   import java.util.Set;
   27   
   28   import org.apache.pdfbox.exceptions.COSVisitorException;
   29   
   30   import org.apache.pdfbox.pdmodel.common.COSObjectable;
   31   import org.apache.pdfbox.util.DateConverter;
   32   
   33   /**
   34    * This class represents a dictionary where name/value pairs reside.
   35    *
   36    * @author <a href="ben@benlitchfield.com">Ben Litchfield</a>
   37    * @version $Revision: 1.32 $
   38    */
   39   public class COSDictionary extends COSBase
   40   {
   41       private static final String PATH_SEPARATOR = "/";
   42   
   43       /**
   44        * The name-value pairs of this dictionary. The pairs are kept in the
   45        * order they were added to the dictionary.
   46        */
   47       private final Map<COSName, COSBase> items =
   48           new LinkedHashMap<COSName, COSBase>();
   49   
   50       /**
   51        * Constructor.
   52        */
   53       public COSDictionary()
   54       {
   55           //default constructor
   56       }
   57   
   58       /**
   59        * Copy Constructor.  This will make a shallow copy of this dictionary.
   60        *
   61        * @param dict The dictionary to copy.
   62        */
   63       public COSDictionary( COSDictionary dict )
   64       {
   65           items.putAll( dict.items );
   66       }
   67   
   68       /**
   69        * @see java.util.Map#containsValue(java.lang.Object)
   70        *
   71        * @param value The value to find in the map.
   72        *
   73        * @return true if the map contains this value.
   74        */
   75       public boolean containsValue( Object value )
   76       {
   77           boolean contains = items.containsValue( value );
   78           if( !contains && value instanceof COSObject )
   79           {
   80               contains = items.containsValue( ((COSObject)value).getObject());
   81           }
   82           return contains;
   83       }
   84   
   85       /**
   86        * Search in the map for the value that matches the parameter
   87        * and return the first key that maps to that value.
   88        *
   89        * @param value The value to search for in the map.
   90        * @return The key for the value in the map or null if it does not exist.
   91        */
   92       public COSName getKeyForValue( Object value )
   93       {
   94           for( Map.Entry<COSName, COSBase> entry : items.entrySet() )
   95           {
   96               Object nextValue = entry.getValue();
   97               if( nextValue.equals( value ) ||
   98                   (nextValue instanceof COSObject &&
   99                    ((COSObject)nextValue).getObject().equals( value))
  100                   )
  101               {
  102                   return entry.getKey();
  103               }
  104           }
  105   
  106           return null;
  107       }
  108   
  109       /**
  110        * This will return the number of elements in this dictionary.
  111        *
  112        * @return The number of elements in the dictionary.
  113        */
  114       public int size()
  115       {
  116           return items.size();
  117       }
  118   
  119       /**
  120        * This will clear all items in the map.
  121        */
  122       public void clear()
  123       {
  124           items.clear();
  125       }
  126   
  127       /**
  128        * This will get an object from this dictionary.  If the object is a reference then it will
  129        * dereference it and get it from the document.  If the object is COSNull then
  130        * null will be returned.
  131        *
  132        * @param key The key to the object that we are getting.
  133        *
  134        * @return The object that matches the key.
  135        */
  136       public COSBase getDictionaryObject( String key )
  137       {
  138           return getDictionaryObject( COSName.getPDFName( key ) );
  139       }
  140   
  141       /**
  142        * This is a special case of getDictionaryObject that takes multiple keys, it will handle
  143        * the situation where multiple keys could get the same value, ie if either CS or ColorSpace
  144        * is used to get the colorspace.
  145        * This will get an object from this dictionary.  If the object is a reference then it will
  146        * dereference it and get it from the document.  If the object is COSNull then
  147        * null will be returned.
  148        *
  149        * @param firstKey The first key to try.
  150        * @param secondKey The second key to try.
  151        *
  152        * @return The object that matches the key.
  153        */
  154       public COSBase getDictionaryObject( String firstKey, String secondKey )
  155       {
  156           COSBase retval = getDictionaryObject( COSName.getPDFName( firstKey ) );
  157           if( retval == null )
  158           {
  159               retval = getDictionaryObject( COSName.getPDFName( secondKey ) );
  160           }
  161           return retval;
  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 keyList The list of keys to find a value.
  173        *
  174        * @return The object that matches the key.
  175        */
  176       public COSBase getDictionaryObject( String[] keyList )
  177       {
  178           COSBase retval = null;
  179           for( int i=0; i<keyList.length && retval == null; i++ )
  180           {
  181               retval = getDictionaryObject( COSName.getPDFName( keyList[i] ) );
  182           }
  183           return retval;
  184       }
  185   
  186       /**
  187        * This will get an object from this dictionary.  If the object is a reference then it will
  188        * dereference it and get it from the document.  If the object is COSNull then
  189        * null will be returned.
  190        *
  191        * @param key The key to the object that we are getting.
  192        *
  193        * @return The object that matches the key.
  194        */
  195       public COSBase getDictionaryObject( COSName key )
  196       {
  197           COSBase retval = items.get( key );
  198           if( retval instanceof COSObject )
  199           {
  200               retval = ((COSObject)retval).getObject();
  201           }
  202           if( retval instanceof COSNull )
  203           {
  204               retval = null;
  205           }
  206           return retval;
  207       }
  208   
  209       /**
  210        * This will set an item in the dictionary.  If value is null then the result
  211        * will be the same as removeItem( key ).
  212        *
  213        * @param key The key to the dictionary object.
  214        * @param value The value to the dictionary object.
  215        */
  216       public void setItem( COSName key, COSBase value )
  217       {
  218           if( value == null )
  219           {
  220               removeItem( key );
  221           }
  222           else
  223           {
  224               items.put( key, value );
  225           }
  226       }
  227   
  228       /**
  229        * This will set an item in the dictionary.  If value is null then the result
  230        * will be the same as removeItem( key ).
  231        *
  232        * @param key The key to the dictionary object.
  233        * @param value The value to the dictionary object.
  234        */
  235       public void setItem( COSName key, COSObjectable value )
  236       {
  237           COSBase base = null;
  238           if( value != null )
  239           {
  240               base = value.getCOSObject();
  241           }
  242           setItem( key, base );
  243       }
  244   
  245       /**
  246        * This will set an item in the dictionary.  If value is null then the result
  247        * will be the same as removeItem( key ).
  248        *
  249        * @param key The key to the dictionary object.
  250        * @param value The value to the dictionary object.
  251        */
  252       public void setItem( String key, COSObjectable value )
  253       {
  254           setItem( COSName.getPDFName( key ), value );
  255       }
  256   
  257       /**
  258        * This will set an item in the dictionary.
  259        *
  260        * @param key The key to the dictionary object.
  261        * @param value The value to the dictionary object.
  262        */
  263       public void setBoolean( String key, boolean value )
  264       {
  265           setItem( COSName.getPDFName( key ), COSBoolean.getBoolean( value ) );
  266       }
  267   
  268       /**
  269        * This will set an item in the dictionary.
  270        *
  271        * @param key The key to the dictionary object.
  272        * @param value The value to the dictionary object.
  273        */
  274       public void setBoolean( COSName key, boolean value )
  275       {
  276           setItem( key , COSBoolean.getBoolean( value ) );
  277       }
  278   
  279       /**
  280        * This will set an item in the dictionary.  If value is null then the result
  281        * will be the same as removeItem( key ).
  282        *
  283        * @param key The key to the dictionary object.
  284        * @param value The value to the dictionary object.
  285        */
  286       public void setItem( String key, COSBase value )
  287       {
  288           setItem( COSName.getPDFName( key ), value );
  289       }
  290   
  291       /**
  292        * This is a convenience method that will convert the value to a COSName
  293        * object.  If it is null then the object will be removed.
  294        *
  295        * @param key The key to the object,
  296        * @param value The string value for the name.
  297        */
  298       public void setName( String key, String value )
  299       {
  300           setName( COSName.getPDFName( key ), value );
  301       }
  302   
  303       /**
  304        * This is a convenience method that will convert the value to a COSName
  305        * object.  If it is null then the object will be removed.
  306        *
  307        * @param key The key to the object,
  308        * @param value The string value for the name.
  309        */
  310       public void setName( COSName key, String value )
  311       {
  312           COSName name = null;
  313           if( value != null )
  314           {
  315               name = COSName.getPDFName( value );
  316           }
  317           setItem( key, name );
  318       }
  319   
  320       /**
  321        * Set the value of a date entry in the dictionary.
  322        *
  323        * @param key The key to the date value.
  324        * @param date The date value.
  325        */
  326       public void setDate( String key, Calendar date )
  327       {
  328           setDate( COSName.getPDFName( key ), date );
  329       }
  330   
  331       /**
  332        * Set the date object.
  333        *
  334        * @param key The key to the date.
  335        * @param date The date to set.
  336        */
  337       public void setDate( COSName key, Calendar date )
  338       {
  339           setString( key, DateConverter.toString( date ) );
  340       }
  341   
  342       /**
  343        * Set the value of a date entry in the dictionary.
  344        *
  345        * @param embedded The embedded dictionary.
  346        * @param key The key to the date value.
  347        * @param date The date value.
  348        */
  349       public void setEmbeddedDate( String embedded, String key, Calendar date )
  350       {
  351           setEmbeddedDate( embedded, COSName.getPDFName( key ), date );
  352       }
  353   
  354       /**
  355        * Set the date object.
  356        *
  357        * @param embedded The embedded dictionary.
  358        * @param key The key to the date.
  359        * @param date The date to set.
  360        */
  361       public void setEmbeddedDate( String embedded, COSName key, Calendar date )
  362       {
  363           COSDictionary dic = (COSDictionary)getDictionaryObject( embedded );
  364           if( dic == null && date != null )
  365           {
  366               dic = new COSDictionary();
  367               setItem( embedded, dic );
  368           }
  369           if( dic != null )
  370           {
  371               dic.setDate( key, date );
  372           }
  373       }
  374   
  375       /**
  376        * This is a convenience method that will convert the value to a COSString
  377        * object.  If it is null then the object will be removed.
  378        *
  379        * @param key The key to the object,
  380        * @param value The string value for the name.
  381        */
  382       public void setString( String key, String value )
  383       {
  384           setString( COSName.getPDFName( key ), value );
  385       }
  386   
  387       /**
  388        * This is a convenience method that will convert the value to a COSString
  389        * object.  If it is null then the object will be removed.
  390        *
  391        * @param key The key to the object,
  392        * @param value The string value for the name.
  393        */
  394       public void setString( COSName key, String value )
  395       {
  396           COSString name = null;
  397           if( value != null )
  398           {
  399               name = new COSString( value );
  400           }
  401           setItem( key, name );
  402       }
  403   
  404       /**
  405        * This is a convenience method that will convert the value to a COSString
  406        * object.  If it is null then the object will be removed.
  407        *
  408        * @param embedded The embedded dictionary to set the item in.
  409        * @param key The key to the object,
  410        * @param value The string value for the name.
  411        */
  412       public void setEmbeddedString( String embedded, String key, String value )
  413       {
  414           setEmbeddedString( embedded, COSName.getPDFName( key ), value );
  415       }
  416   
  417       /**
  418        * This is a convenience method that will convert the value to a COSString
  419        * object.  If it is null then the object will be removed.
  420        *
  421        * @param embedded The embedded dictionary to set the item in.
  422        * @param key The key to the object,
  423        * @param value The string value for the name.
  424        */
  425       public void setEmbeddedString( String embedded, COSName key, String value )
  426       {
  427           COSDictionary dic = (COSDictionary)getDictionaryObject( embedded );
  428           if( dic == null && value != null )
  429           {
  430               dic = new COSDictionary();
  431               setItem( embedded, dic );
  432           }
  433           if( dic != null )
  434           {
  435               dic.setString( key, value );
  436           }
  437       }
  438   
  439       /**
  440        * This is a convenience method that will convert the value to a COSInteger
  441        * object.
  442        *
  443        * @param key The key to the object,
  444        * @param value The int value for the name.
  445        */
  446       public void setInt( String key, int value )
  447       {
  448           setInt( COSName.getPDFName( key ), value );
  449       }
  450   
  451       /**
  452        * This is a convenience method that will convert the value to a COSInteger
  453        * object.
  454        *
  455        * @param key The key to the object,
  456        * @param value The int value for the name.
  457        */
  458       public void setInt( COSName key, int value )
  459       {
  460           setItem( key, COSInteger.get(value) );
  461       }
  462   
  463       /**
  464        * This is a convenience method that will convert the value to a COSInteger
  465        * object.
  466        *
  467        * @param key The key to the object,
  468        * @param value The int value for the name.
  469        */
  470       public void setLong( String key, long value )
  471       {
  472           setLong( COSName.getPDFName( key ), value );
  473       }
  474   
  475       /**
  476        * This is a convenience method that will convert the value to a COSInteger
  477        * object.
  478        *
  479        * @param key The key to the object,
  480        * @param value The int value for the name.
  481        */
  482       public void setLong( COSName key, long value )
  483       {
  484           COSInteger intVal = null;
  485           intVal = COSInteger.get(value);
  486           setItem( key, intVal );
  487       }
  488   
  489       /**
  490        * This is a convenience method that will convert the value to a COSInteger
  491        * object.
  492        *
  493        * @param embeddedDictionary The embedded dictionary.
  494        * @param key The key to the object,
  495        * @param value The int value for the name.
  496        */
  497       public void setEmbeddedInt( String embeddedDictionary, String key, int value )
  498       {
  499           setEmbeddedInt( embeddedDictionary, COSName.getPDFName( key ), value );
  500       }
  501   
  502       /**
  503        * This is a convenience method that will convert the value to a COSInteger
  504        * object.
  505        *
  506        * @param embeddedDictionary The embedded dictionary.
  507        * @param key The key to the object,
  508        * @param value The int value for the name.
  509        */
  510       public void setEmbeddedInt( String embeddedDictionary, COSName key, int value )
  511       {
  512           COSDictionary embedded = (COSDictionary)getDictionaryObject( embeddedDictionary );
  513           if( embedded == null )
  514           {
  515               embedded = new COSDictionary();
  516               setItem( embeddedDictionary, embedded );
  517           }
  518           embedded.setInt( key, value );
  519       }
  520   
  521       /**
  522        * This is a convenience method that will convert the value to a COSFloat
  523        * object.
  524        *
  525        * @param key The key to the object,
  526        * @param value The int value for the name.
  527        */
  528       public void setFloat( String key, float value )
  529       {
  530           setFloat( COSName.getPDFName( key ), value );
  531       }
  532   
  533       /**
  534        * This is a convenience method that will convert the value to a COSFloat
  535        * object.
  536        *
  537        * @param key The key to the object,
  538        * @param value The int value for the name.
  539        */
  540       public void setFloat( COSName key, float value )
  541       {
  542           COSFloat fltVal = new COSFloat( value );
  543           setItem( key, fltVal );
  544       }
  545   
  546       /**
  547        * This is a convenience method that will get the dictionary object that
  548        * is expected to be a name and convert it to a string.  Null is returned
  549        * if the entry does not exist in the dictionary.
  550        *
  551        * @param key The key to the item in the dictionary.
  552        * @return The name converted to a string.
  553        */
  554       public String getNameAsString( String key )
  555       {
  556           return getNameAsString( COSName.getPDFName( key ) );
  557       }
  558   
  559       /**
  560        * This is a convenience method that will get the dictionary object that
  561        * is expected to be a name and convert it to a string.  Null is returned
  562        * if the entry does not exist in the dictionary.
  563        *
  564        * @param key The key to the item in the dictionary.
  565        * @return The name converted to a string.
  566        */
  567       public String getNameAsString( COSName key )
  568       {
  569           String retval = null;
  570           COSBase name = getDictionaryObject( key );
  571           if( name != null )
  572           {
  573               if ( name instanceof COSName) 
  574               {
  575                   retval = ((COSName)name).getName();
  576               }
  577               else if ( name instanceof COSString) 
  578               {
  579                   retval = ((COSString)name).getString();
  580               }
  581           }
  582           return retval;
  583       }
  584   
  585       /**
  586        * This is a convenience method that will get the dictionary object that
  587        * is expected to be a name and convert it to a string.  Null is returned
  588        * if the entry does not exist in the dictionary.
  589        *
  590        * @param key The key to the item in the dictionary.
  591        * @param defaultValue The value to return if the dictionary item is null.
  592        * @return The name converted to a string.
  593        */
  594       public String getNameAsString( String key, String defaultValue )
  595       {
  596           return getNameAsString( COSName.getPDFName( key ), defaultValue );
  597       }
  598   
  599       /**
  600        * This is a convenience method that will get the dictionary object that
  601        * is expected to be a name and convert it to a string.  Null is returned
  602        * if the entry does not exist in the dictionary.
  603        *
  604        * @param key The key to the item in the dictionary.
  605        * @param defaultValue The value to return if the dictionary item is null.
  606        * @return The name converted to a string.
  607        */
  608       public String getNameAsString( COSName key, String defaultValue )
  609       {
  610           String retval = getNameAsString( key );
  611           if( retval == null )
  612           {
  613               retval = defaultValue;
  614           }
  615           return retval;
  616       }
  617   
  618       /**
  619        * This is a convenience method that will get the dictionary object that
  620        * is expected to be a name and convert it to a string.  Null is returned
  621        * if the entry does not exist in the dictionary.
  622        *
  623        * @param key The key to the item in the dictionary.
  624        * @return The name converted to a string.
  625        */
  626       public String getString( String key )
  627       {
  628           return getString( COSName.getPDFName( key ) );
  629       }
  630   
  631       /**
  632        * This is a convenience method that will get the dictionary object that
  633        * is expected to be a name and convert it to a string.  Null is returned
  634        * if the entry does not exist in the dictionary.
  635        *
  636        * @param key The key to the item in the dictionary.
  637        * @return The name converted to a string.
  638        */
  639       public String getString( COSName key )
  640       {
  641           String retval = null;
  642           COSBase value = getDictionaryObject( key );
  643           if( value != null && value instanceof COSString)
  644           {
  645               retval = ((COSString)value).getString();
  646           }
  647           return retval;
  648       }
  649   
  650       /**
  651        * This is a convenience method that will get the dictionary object that
  652        * is expected to be a name and convert it to a string.  Null is returned
  653        * if the entry does not exist in the dictionary.
  654        *
  655        * @param key The key to the item in the dictionary.
  656        * @param defaultValue The default value to return.
  657        * @return The name converted to a string.
  658        */
  659       public String getString( String key, String defaultValue )
  660       {
  661           return getString( COSName.getPDFName( key ), defaultValue );
  662       }
  663   
  664       /**
  665        * This is a convenience method that will get the dictionary object that
  666        * is expected to be a name and convert it to a string.  Null is returned
  667        * if the entry does not exist in the dictionary.
  668        *
  669        * @param key The key to the item in the dictionary.
  670        * @param defaultValue The default value to return.
  671        * @return The name converted to a string.
  672        */
  673       public String getString( COSName key, String defaultValue )
  674       {
  675           String retval = getString( key );
  676           if( retval == null )
  677           {
  678               retval = defaultValue;
  679           }
  680           return retval;
  681       }
  682   
  683       /**
  684        * This is a convenience method that will get the dictionary object that
  685        * is expected to be a name and convert it to a string.  Null is returned
  686        * if the entry does not exist in the dictionary.
  687        *
  688        * @param embedded The embedded dictionary.
  689        * @param key The key to the item in the dictionary.
  690        * @return The name converted to a string.
  691        */
  692       public String getEmbeddedString( String embedded, String key )
  693       {
  694           return getEmbeddedString( embedded, COSName.getPDFName( key ), null );
  695       }
  696   
  697       /**
  698        * This is a convenience method that will get the dictionary object that
  699        * is expected to be a name and convert it to a string.  Null is returned
  700        * if the entry does not exist in the dictionary.
  701        *
  702        * @param embedded The embedded dictionary.
  703        * @param key The key to the item in the dictionary.
  704        * @return The name converted to a string.
  705        */
  706       public String getEmbeddedString( String embedded, COSName key )
  707       {
  708           return getEmbeddedString( embedded, key, null );
  709       }
  710   
  711       /**
  712        * This is a convenience method that will get the dictionary object that
  713        * is expected to be a name and convert it to a string.  Null is returned
  714        * if the entry does not exist in the dictionary.
  715        *
  716        * @param embedded The embedded dictionary.
  717        * @param key The key to the item in the dictionary.
  718        * @param defaultValue The default value to return.
  719        * @return The name converted to a string.
  720        */
  721       public String getEmbeddedString( String embedded, String key, String defaultValue )
  722       {
  723           return getEmbeddedString( embedded, COSName.getPDFName( key ), defaultValue );
  724       }
  725   
  726       /**
  727        * This is a convenience method that will get the dictionary object that
  728        * is expected to be a name and convert it to a string.  Null is returned
  729        * if the entry does not exist in the dictionary.
  730        *
  731        * @param embedded The embedded dictionary.
  732        * @param key The key to the item in the dictionary.
  733        * @param defaultValue The default value to return.
  734        * @return The name converted to a string.
  735        */
  736       public String getEmbeddedString( String embedded, COSName key, String defaultValue )
  737       {
  738           String retval = defaultValue;
  739           COSDictionary dic = (COSDictionary)getDictionaryObject( embedded );
  740           if( dic != null )
  741           {
  742               retval = dic.getString( key, defaultValue );
  743           }
  744           return retval;
  745       }
  746   
  747       /**
  748        * This is a convenience method that will get the dictionary object that
  749        * is expected to be a name and convert it to a string.  Null is returned
  750        * if the entry does not exist in the dictionary.
  751        *
  752        * @param key The key to the item in the dictionary.
  753        * @return The name converted to a string.
  754        * @throws IOException If there is an error converting to a date.
  755        */
  756       public Calendar getDate( String key ) throws IOException
  757       {
  758           return getDate( COSName.getPDFName( key ) );
  759       }
  760   
  761       /**
  762        * This is a convenience method that will get the dictionary object that
  763        * is expected to be a name and convert it to a string.  Null is returned
  764        * if the entry does not exist in the dictionary.
  765        *
  766        * @param key The key to the item in the dictionary.
  767        * @return The name converted to a string.
  768        *
  769        * @throws IOException If there is an error converting to a date.
  770        */
  771       public Calendar getDate( COSName key ) throws IOException
  772       {
  773           COSString date = (COSString)getDictionaryObject( key );
  774           return DateConverter.toCalendar( date );
  775       }
  776   
  777       /**
  778        * This is a convenience method that will get the dictionary object that
  779        * is expected to be a date.  Null is returned
  780        * if the entry does not exist in the dictionary.
  781        *
  782        * @param key The key to the item in the dictionary.
  783        * @param defaultValue The default value to return.
  784        * @return The name converted to a string.
  785        * @throws IOException If there is an error converting to a date.
  786        */
  787       public Calendar getDate( String key, Calendar defaultValue ) throws IOException
  788       {
  789           return getDate( COSName.getPDFName( key ), defaultValue );
  790       }
  791   
  792       /**
  793        * This is a convenience method that will get the dictionary object that
  794        * is expected to be a date.  Null is returned
  795        * if the entry does not exist in the dictionary.
  796        *
  797        * @param key The key to the item in the dictionary.
  798        * @param defaultValue The default value to return.
  799        * @return The name converted to a string.
  800        * @throws IOException If there is an error converting to a date.
  801        */
  802       public Calendar getDate( COSName key, Calendar defaultValue ) throws IOException
  803       {
  804           Calendar retval = getDate( key );
  805           if( retval == null )
  806           {
  807               retval = defaultValue;
  808           }
  809           return retval;
  810       }
  811   
  812       /**
  813        * This is a convenience method that will get the dictionary object that
  814        * is expected to be a name and convert it to a string.  Null is returned
  815        * if the entry does not exist in the dictionary.
  816        *
  817        * @param embedded The embedded dictionary to get.
  818        * @param key The key to the item in the dictionary.
  819        * @return The name converted to a string.
  820        * @throws IOException If there is an error converting to a date.
  821        */
  822       public Calendar getEmbeddedDate( String embedded, String key ) throws IOException
  823       {
  824           return getEmbeddedDate( embedded, COSName.getPDFName( key ), null );
  825       }
  826   
  827       /**
  828        * This is a convenience method that will get the dictionary object that
  829        * is expected to be a name and convert it to a string.  Null is returned
  830        * if the entry does not exist in the dictionary.
  831        *
  832        * @param embedded The embedded dictionary to get.
  833        * @param key The key to the item in the dictionary.
  834        * @return The name converted to a string.
  835        *
  836        * @throws IOException If there is an error converting to a date.
  837        */
  838       public Calendar getEmbeddedDate( String embedded, COSName key ) throws IOException
  839       {
  840           return getEmbeddedDate( embedded, key, null );
  841       }
  842   
  843       /**
  844        * This is a convenience method that will get the dictionary object that
  845        * is expected to be a date.  Null is returned
  846        * if the entry does not exist in the dictionary.
  847        *
  848        * @param embedded The embedded dictionary to get.
  849        * @param key The key to the item in the dictionary.
  850        * @param defaultValue The default value to return.
  851        * @return The name converted to a string.
  852        * @throws IOException If there is an error converting to a date.
  853        */
  854       public Calendar getEmbeddedDate( String embedded, String key, Calendar defaultValue ) throws IOException
  855       {
  856           return getEmbeddedDate( embedded, COSName.getPDFName( key ), defaultValue );
  857       }
  858   
  859       /**
  860        * This is a convenience method that will get the dictionary object that
  861        * is expected to be a date.  Null is returned
  862        * if the entry does not exist in the dictionary.
  863        *
  864        * @param embedded The embedded dictionary to get.
  865        * @param key The key to the item in the dictionary.
  866        * @param defaultValue The default value to return.
  867        * @return The name converted to a string.
  868        * @throws IOException If there is an error converting to a date.
  869        */
  870       public Calendar getEmbeddedDate( String embedded, COSName key, Calendar defaultValue ) throws IOException
  871       {
  872           Calendar retval = defaultValue;
  873           COSDictionary eDic = (COSDictionary)getDictionaryObject( embedded );
  874           if( eDic != null )
  875           {
  876               retval = eDic.getDate( key, defaultValue );
  877           }
  878           return retval;
  879       }
  880   
  881       /**
  882        * This is a convenience method that will get the dictionary object that
  883        * is expected to be a cos boolean and convert it to a primitive boolean.
  884        *
  885        * @param key The key to the item in the dictionary.
  886        * @param defaultValue The value returned if the entry is null.
  887        *
  888        * @return The value converted to a boolean.
  889        */
  890       public boolean getBoolean( String key, boolean defaultValue )
  891       {
  892           return getBoolean( COSName.getPDFName( key ), defaultValue );
  893       }
  894   
  895       /**
  896        * This is a convenience method that will get the dictionary object that
  897        * is expected to be a COSBoolean and convert it to a primitive boolean.
  898        *
  899        * @param key The key to the item in the dictionary.
  900        * @param defaultValue The value returned if the entry is null.
  901        *
  902        * @return The entry converted to a boolean.
  903        */
  904       public boolean getBoolean( COSName key, boolean defaultValue )
  905       {
  906           boolean retval = defaultValue;
  907           COSBase bool = getDictionaryObject( key );
  908           if( bool != null && bool instanceof COSBoolean)
  909           {
  910               retval = ((COSBoolean)bool).getValue();
  911           }
  912           return retval;
  913       }
  914   
  915       /**
  916        * Get an integer from an embedded dictionary.  Useful for 1-1 mappings.  default:-1
  917        *
  918        * @param embeddedDictionary The name of the embedded dictionary.
  919        * @param key The key in the embedded dictionary.
  920        *
  921        * @return The value of the embedded integer.
  922        */
  923       public int getEmbeddedInt( String embeddedDictionary, String key )
  924       {
  925           return getEmbeddedInt( embeddedDictionary, COSName.getPDFName( key ) );
  926       }
  927   
  928       /**
  929        * Get an integer from an embedded dictionary.  Useful for 1-1 mappings.  default:-1
  930        *
  931        * @param embeddedDictionary The name of the embedded dictionary.
  932        * @param key The key in the embedded dictionary.
  933        *
  934        * @return The value of the embedded integer.
  935        */
  936       public int getEmbeddedInt( String embeddedDictionary, COSName key )
  937       {
  938           return getEmbeddedInt( embeddedDictionary, key, -1 );
  939       }
  940   
  941       /**
  942        * Get an integer from an embedded dictionary.  Useful for 1-1 mappings.
  943        *
  944        * @param embeddedDictionary The name of the embedded dictionary.
  945        * @param key The key in the embedded dictionary.
  946        * @param defaultValue The value if there is no embedded dictionary or it does not contain the key.
  947        *
  948        * @return The value of the embedded integer.
  949        */
  950       public int getEmbeddedInt( String embeddedDictionary, String key, int defaultValue )
  951       {
  952           return getEmbeddedInt( embeddedDictionary, COSName.getPDFName( key ), defaultValue );
  953       }
  954   
  955   
  956       /**
  957        * Get an integer from an embedded dictionary.  Useful for 1-1 mappings.
  958        *
  959        * @param embeddedDictionary The name of the embedded dictionary.
  960        * @param key The key in the embedded dictionary.
  961        * @param defaultValue The value if there is no embedded dictionary or it does not contain the key.
  962        *
  963        * @return The value of the embedded integer.
  964        */
  965       public int getEmbeddedInt( String embeddedDictionary, COSName key, int defaultValue )
  966       {
  967           int retval = defaultValue;
  968           COSDictionary embedded = (COSDictionary)getDictionaryObject( embeddedDictionary );
  969           if( embedded != null )
  970           {
  971               retval = embedded.getInt( key, defaultValue );
  972           }
  973           return retval;
  974       }
  975   
  976       /**
  977        * This is a convenience method that will get the dictionary object that
  978        * is expected to be an int.  -1 is returned if there is no value.
  979        *
  980        * @param key The key to the item in the dictionary.
  981        * @return The integer value.
  982        */
  983       public int getInt( String key )
  984       {
  985           return getInt( COSName.getPDFName( key ), -1 );
  986       }
  987   
  988       /**
  989        * This is a convenience method that will get the dictionary object that
  990        * is expected to be an int.  -1 is returned if there is no value.
  991        *
  992        * @param key The key to the item in the dictionary.
  993        * @return The integer value..
  994        */
  995       public int getInt( COSName key )
  996       {
  997           return getInt( key, -1 );
  998       }
  999   
 1000       /**
 1001        * This is a convenience method that will get the dictionary object that
 1002        * is expected to be an integer.  If the dictionary value is null then the
 1003        * default Value will be returned.
 1004        *
 1005        * @param keyList The key to the item in the dictionary.
 1006        * @param defaultValue The value to return if the dictionary item is null.
 1007        * @return The integer value.
 1008        */
 1009       public int getInt( String[] keyList, int defaultValue )
 1010       {
 1011           int retval = defaultValue;
 1012           COSBase obj = getDictionaryObject( keyList );
 1013           if( obj != null && obj instanceof COSNumber)
 1014           {
 1015               retval = ((COSNumber)obj).intValue();
 1016           }
 1017           return retval;
 1018       }
 1019   
 1020       /**
 1021        * This is a convenience method that will get the dictionary object that
 1022        * is expected to be an integer.  If the dictionary value is null then the
 1023        * default Value will be returned.
 1024        *
 1025        * @param key The key to the item in the dictionary.
 1026        * @param defaultValue The value to return if the dictionary item is null.
 1027        * @return The integer value.
 1028        */
 1029       public int getInt( String key, int defaultValue )
 1030       {
 1031           return getInt( COSName.getPDFName( key ), defaultValue );
 1032       }
 1033   
 1034       /**
 1035        * This is a convenience method that will get the dictionary object that
 1036        * is expected to be an integer.  If the dictionary value is null then the
 1037        * default Value will be returned.
 1038        *
 1039        * @param key The key to the item in the dictionary.
 1040        * @param defaultValue The value to return if the dictionary item is null.
 1041        * @return The integer value.
 1042        */
 1043       public int getInt( COSName key, int defaultValue )
 1044       {
 1045           int retval = defaultValue;
 1046           COSBase obj = getDictionaryObject( key );
 1047           if( obj != null && obj instanceof COSNumber)
 1048           {
 1049               retval = ((COSNumber)obj).intValue();
 1050           }
 1051           return retval;
 1052       }
 1053   
 1054       /**
 1055        * This is a convenience method that will get the dictionary object that
 1056        * is expected to be an long.  -1 is returned if there is no value.
 1057        *
 1058        * @param key The key to the item in the dictionary.
 1059        *
 1060        * @return The long value.
 1061        */
 1062       public long getLong( String key )
 1063       {
 1064           return getLong( COSName.getPDFName( key ), -1L );
 1065       }
 1066   
 1067       /**
 1068        * This is a convenience method that will get the dictionary object that
 1069        * is expected to be an long.  -1 is returned if there is no value.
 1070        *
 1071        * @param key The key to the item in the dictionary.
 1072        * @return The long value.
 1073        */
 1074       public long getLong( COSName key )
 1075       {
 1076           return getLong( key, -1L );
 1077       }
 1078   
 1079       /**
 1080        * This is a convenience method that will get the dictionary object that
 1081        * is expected to be an long.  If the dictionary value is null then the
 1082        * default Value will be returned.
 1083        *
 1084        * @param keyList The key to the item in the dictionary.
 1085        * @param defaultValue The value to return if the dictionary item is null.
 1086        * @return The long value.
 1087        */
 1088       public long getLong( String[] keyList, long defaultValue )
 1089       {
 1090           long retval = defaultValue;
 1091           COSBase obj = getDictionaryObject( keyList );
 1092           if( obj != null && obj instanceof COSNumber)
 1093           {
 1094               retval = ((COSNumber)obj).longValue();
 1095           }
 1096           return retval;
 1097       }
 1098   
 1099       /**
 1100        * This is a convenience method that will get the dictionary object that
 1101        * is expected to be an integer.  If the dictionary value is null then the
 1102        * default Value will be returned.
 1103        *
 1104        * @param key The key to the item in the dictionary.
 1105        * @param defaultValue The value to return if the dictionary item is null.
 1106        * @return The integer value.
 1107        */
 1108       public long getLong( String key, long defaultValue )
 1109       {
 1110           return getLong( COSName.getPDFName( key ), defaultValue );
 1111       }
 1112   
 1113       /**
 1114        * This is a convenience method that will get the dictionary object that
 1115        * is expected to be an integer.  If the dictionary value is null then the
 1116        * default Value will be returned.
 1117        *
 1118        * @param key The key to the item in the dictionary.
 1119        * @param defaultValue The value to return if the dictionary item is null.
 1120        * @return The integer value.
 1121        */
 1122       public long getLong( COSName key, long defaultValue )
 1123       {
 1124           long retval = defaultValue;
 1125           COSBase obj = getDictionaryObject( key );
 1126           if( obj != null && obj instanceof COSNumber)
 1127           {
 1128               retval = ((COSNumber)obj).longValue();
 1129           }
 1130           return retval;
 1131       }
 1132   
 1133       /**
 1134        * This is a convenience method that will get the dictionary object that
 1135        * is expected to be an float.  -1 is returned if there is no value.
 1136        *
 1137        * @param key The key to the item in the dictionary.
 1138        * @return The float value.
 1139        */
 1140       public float getFloat( String key )
 1141       {
 1142           return getFloat( COSName.getPDFName( key ), -1 );
 1143       }
 1144   
 1145       /**
 1146        * This is a convenience method that will get the dictionary object that
 1147        * is expected to be an float.  -1 is returned if there is no value.
 1148        *
 1149        * @param key The key to the item in the dictionary.
 1150        * @return The float value.
 1151        */
 1152       public float getFloat( COSName key )
 1153       {
 1154           return getFloat( key, -1 );
 1155       }
 1156   
 1157       /**
 1158        * This is a convenience method that will get the dictionary object that
 1159        * is expected to be a float.  If the dictionary value is null then the
 1160        * default Value will be returned.
 1161        *
 1162        * @param key The key to the item in the dictionary.
 1163        * @param defaultValue The value to return if the dictionary item is null.
 1164        * @return The float value.
 1165        */
 1166       public float getFloat( String key, float defaultValue )
 1167       {
 1168           return getFloat( COSName.getPDFName( key ), defaultValue );
 1169       }
 1170   
 1171       /**
 1172        * This is a convenience method that will get the dictionary object that
 1173        * is expected to be an float.  If the dictionary value is null then the
 1174        * default Value will be returned.
 1175        *
 1176        * @param key The key to the item in the dictionary.
 1177        * @param defaultValue The value to return if the dictionary item is null.
 1178        * @return The float value.
 1179        */
 1180       public float getFloat( COSName key, float defaultValue )
 1181       {
 1182           float retval = defaultValue;
 1183           COSBase obj = getDictionaryObject( key );
 1184           if( obj != null && obj instanceof COSNumber)
 1185           {
 1186               retval = ((COSNumber)obj).floatValue();
 1187           }
 1188           return retval;
 1189       }
 1190   
 1191       /**
 1192        * This will remove an item for the dictionary.  This
 1193        * will do nothing of the object does not exist.
 1194        *
 1195        * @param key The key to the item to remove from the dictionary.
 1196        */
 1197       public void removeItem( COSName key )
 1198       {
 1199           items.remove( key );
 1200       }
 1201   
 1202       /**
 1203        * This will do a lookup into the dictionary.
 1204        *
 1205        * @param key The key to the object.
 1206        *
 1207        * @return The item that matches the key.
 1208        */
 1209       public COSBase getItem( COSName key )
 1210       {
 1211           return items.get( key );
 1212       }
 1213   
 1214       /**
 1215        * This will get the keys for all objects in the dictionary in the sequence that
 1216        * they were added.
 1217        *
 1218        * @deprecated Use the {@link #entrySet()} method instead.
 1219        * @return a list of the keys in the sequence of insertion
 1220        */
 1221       public List<COSName> keyList()
 1222       {
 1223           return new ArrayList<COSName>(items.keySet());
 1224       }
 1225   
 1226       /**
 1227        * Returns the names of the entries in this dictionary. The returned
 1228        * set is in the order the entries were added to the dictionary.
 1229        *
 1230        * @since Apache PDFBox 1.1.0
 1231        * @return names of the entries in this dictionary
 1232        */
 1233       public Set<COSName> keySet()
 1234       {
 1235           return items.keySet();
 1236       }
 1237   
 1238       /**
 1239        * Returns the name-value entries in this dictionary. The returned
 1240        * set is in the order the entries were added to the dictionary.
 1241        *
 1242        * @since Apache PDFBox 1.1.0
 1243        * @return name-value entries in this dictionary
 1244        */
 1245       public Set<Map.Entry<COSName, COSBase>> entrySet() {
 1246           return items.entrySet();
 1247       }
 1248   
 1249       /**
 1250        * This will get all of the values for the dictionary.
 1251        *
 1252        * @return All the values for the dictionary.
 1253        */
 1254       public Collection<COSBase> getValues()
 1255       {
 1256           return items.values();
 1257       }
 1258   
 1259       /**
 1260        * visitor pattern double dispatch method.
 1261        *
 1262        * @param visitor The object to notify when visiting this object.
 1263        * @return The object that the visitor returns.
 1264        *
 1265        * @throws COSVisitorException If there is an error visiting this object.
 1266        */
 1267       public Object accept(ICOSVisitor  visitor) throws COSVisitorException
 1268       {
 1269           return visitor.visitFromDictionary(this);
 1270       }
 1271   
 1272       /**
 1273        * This will add all of the dictionarys keys/values to this dictionary.
 1274        * Only called when adding keys to a trailer that already exists. 
 1275        *
 1276        * @param dic The dic to get the keys from.
 1277        */
 1278       public void addAll( COSDictionary dic )
 1279       {
 1280           for( Map.Entry<COSName, COSBase> entry : dic.entrySet() )
 1281           {
 1282               /*
 1283                * If we're at a second trailer, we have a linearized 
 1284                * pdf file, meaning that the first Size entry represents
 1285                * all of the objects so we don't need to grab the second. 
 1286                */
 1287               if(!entry.getKey().getName().equals("Size")
 1288                       || !items.containsKey(COSName.getPDFName("Size")))
 1289               {
 1290                   setItem( entry.getKey(), entry.getValue() );
 1291               }
 1292           }
 1293       }
 1294   
 1295       /**
 1296        * This will add all of the dictionarys keys/values to this dictionary, but only
 1297        * if they don't already exist.  If a key already exists in this dictionary then
 1298        * nothing is changed.
 1299        *
 1300        * @param dic The dic to get the keys from.
 1301        */
 1302       public void mergeInto( COSDictionary dic )
 1303       {
 1304           for( Map.Entry<COSName, COSBase> entry : dic.entrySet() )
 1305           {
 1306               if( getItem( entry.getKey() ) == null )
 1307               {
 1308                   setItem( entry.getKey(), entry.getValue() );
 1309               }
 1310           }
 1311       }
 1312   
 1313       /**
 1314        * Nice method, gives you every object you want
 1315        * Arrays works properly too. Try "P/Annots/[k]/Rect"
 1316        * where k means the index of the Annotsarray.
 1317        *
 1318        * @param objPath the relative path to the object.
 1319        * @return the object
 1320        */
 1321       public COSBase getObjectFromPath(String objPath)
 1322       {
 1323           COSBase retval = null;
 1324           String[] path = objPath.split(PATH_SEPARATOR);
 1325           retval = this;
 1326   
 1327           for (int i = 0; i < path.length; i++)
 1328           {
 1329               if(retval instanceof COSArray)
 1330               {
 1331                   int idx = new Integer(path[i].replaceAll("\\[","").replaceAll("\\]","")).intValue();
 1332                   retval = ((COSArray)retval).getObject(idx);
 1333               }
 1334               else if (retval instanceof COSDictionary)
 1335               {
 1336                   retval = ((COSDictionary)retval).getDictionaryObject( path[i] );
 1337               }
 1338           }
 1339           return retval;
 1340       }
 1341       
 1342       /**
 1343        * {@inheritDoc}
 1344        */
 1345       public String toString()
 1346       {
 1347           StringBuilder retVal = new StringBuilder("COSDictionary{");
 1348           for( COSName key : items.keySet() )
 1349           {
 1350               retVal.append("(" + key + ":" + getDictionaryObject(key).toString() + ") ");
 1351           }
 1352           retVal.append("}");
 1353           return retVal.toString();
 1354       }
 1355   
 1356   
 1357   }

Home » pdfbox-1.1.0-src » org.apache.pdfbox.cos » [javadoc | source]