IndirectObjects


1   /*
2     Copyright � 2006 Stefano Chizzolini. http://clown.stefanochizzolini.it
3   
4     Contributors:
5       * Stefano Chizzolini (original code developer, info@stefanochizzolini.it):
6         contributed code is Copyright � 2006 by Stefano Chizzolini.
7   
8     This file should be part of the source code distribution of "PDF Clown library"
9     (the Program): see the accompanying README files for more info.
10  
11    This Program is free software; you can redistribute it and/or modify it under
12    the terms of the GNU General Public License as published by the Free Software
13    Foundation; either version 2 of the License, or (at your option) any later version.
14  
15    This Program is distributed in the hope that it will be useful, but WITHOUT ANY
16    WARRANTY, either expressed or implied; without even the implied warranty of
17    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the License for more details.
18  
19    You should have received a copy of the GNU General Public License along with this
20    Program (see README files); if not, go to the GNU website (http://www.gnu.org/).
21  
22    Redistribution and use, with or without modification, are permitted provided that such
23    redistributions retain the above copyright notice, license and disclaimer, along with
24    this list of conditions.
25  */
26  
27  package it.stefanochizzolini.clown.files;
28  
29  import it.stefanochizzolini.clown.objects.PdfDataObject;
30  import it.stefanochizzolini.clown.objects.PdfIndirectObject;
31  import it.stefanochizzolini.clown.tokens.XRefEntry;
32  import it.stefanochizzolini.clown.tokens.XRefEntryUsageEnum;
33  import it.stefanochizzolini.clown.util.NotImplementedException;
34  
35  import java.util.ArrayList  ;
36  import java.util.Collection  ;
37  import java.util.Hashtable  ;
38  import java.util.Iterator  ;
39  import java.util.List  ;
40  import java.util.ListIterator  ;
41  import java.util.NoSuchElementException  ;
42  import java.util.TreeMap  ;
43  
44  /**
45    Collection of the <b>alive indirect objects</b> available inside the file.
46    <h3>Remarks</h3>
47    <p>According to the PDF spec, <i>indirect object entries may be free
48    (no data object associated) or in-use (data object associated)</i>.</p>
49    <p>We can effectively subdivide indirect objects in two possibly-overriding
50    collections: the <b>original indirect objects</b> (coming from the associated
51    preexisting file) and the <b>newly-registered indirect objects</b> (coming
52    from new data objects or original indirect objects manipulated during the
53    current session).</p>
54    <p><i>To ensure that the modifications applied to an original indirect object
55    are committed to being persistent</i> is critical that the modified original
56    indirect object is newly-registered (practically overriding the original
57    indirect object).</p>
58    <p><b>Alive indirect objects</b> encompass all the newly-registered ones plus
59    not-overridden original ones.</p>
60  */
61  public class IndirectObjects
62    implements List  <PdfIndirectObject>
63  {
64    // <class>
65    // <dynamic>
66    // <fields>
67    /**
68      Associated file.
69    */
70    private File file;
71  
72    /**
73      Map of matching references of imported indirect objects.
74      <h3>Remarks</h3>
75      <p>This collection is used to prevent duplications among imported indirect
76      objects.</p>
77      <p><code>Key</code> is the external indirect object hashcode, <code>Value</code> is the
78      matching internal indirect object.</p>
79    */
80    private Hashtable  <Integer  ,PdfIndirectObject> importedObjects = new Hashtable  <Integer  ,PdfIndirectObject>();
81    /**
82      Collection of newly-registered indirect objects.
83    */
84    private TreeMap  <Integer  ,PdfIndirectObject> modifiedObjects = new TreeMap  <Integer  ,PdfIndirectObject>();
85    /**
86      Collection of instantiated original indirect objects.
87      <h3>Remarks</h3>
88      <p>This collection is useful as a cache to avoid unconsistent parsing duplications.</p>
89    */
90    private TreeMap  <Integer  ,PdfIndirectObject> wokenObjects = new TreeMap  <Integer  ,PdfIndirectObject>();
91  
92    /**
93      Object counter.
94    */
95    private int lastObjectNumber = -1; // Empty.
96    /**
97      Offsets of the original indirect objects inside the associated file (to say:
98      implicit collection of the original indirect objects).
99      <h3>Remarks
100     <p>This information is vital to randomly retrieve the indirect-object persistent
101     representation inside the associated file.</p>
102   */
103   private XRefEntry[] xrefEntries;
104 
105   private UpdateModeEnum updateMode = UpdateModeEnum.Manual;
106   // </fields>
107 
108   // <constructors>
109   IndirectObjects(
110     File file,
111     XRefEntry[] xrefEntries
112     )
113   {
114     this.file = file;
115     this.xrefEntries = xrefEntries;
116     // Are there original indirect objects?
117     if(this.xrefEntries == null)
118     {
119       /*
120       [PDF:1.6:3.4.3] Mandatory head of the linked list of free objects
121       at object number 0.
122       */
123       // Register the leading free-object!
124       lastObjectNumber++;
125       modifiedObjects.put(
126         lastObjectNumber,
127         new PdfIndirectObject(
128           this.file,
129           null,
130           new XRefEntry(
131             lastObjectNumber,
132             65535,
133             0,
134             XRefEntryUsageEnum.Free
135             )
136           )
137         );
138     }
139     else
140     {
141       // Adjust the object counter!
142       lastObjectNumber = xrefEntries.length - 1;
143     }
144   }
145   // </constructors>
146 
147   // <interface>
148   // <public>
149   public File getFile(
150     )
151   {return file;}
152 
153   /**
154     Register an <b>internal data object</b>.
155     <h3>Remarks</h3>
156     <p>Alternatives:<ul>
157     <li>To register a modified internal indirect object, use
158     {@link #set(int,PdfIndirectObject) set(int,PdfIndirectObject)}.</li>
159     <li>To register an external indirect object, use
160     {@link #addExternal(PdfIndirectObject) addExternal(PdfIndirectObject)}.</li>
161     </ul></p>
162   */
163   public PdfIndirectObject add(
164     PdfDataObject object
165     )
166   {
167     // Wrap the data object inside a new indirect object!
168     lastObjectNumber++;
169     PdfIndirectObject indirectObject = new PdfIndirectObject(
170       file,
171       object,
172       new XRefEntry(
173         lastObjectNumber,
174         0,
175         0,
176         XRefEntryUsageEnum.InUse
177         )
178       );
179     // Register the object!
180     modifiedObjects.put(lastObjectNumber,indirectObject);
181 
182     return indirectObject;
183   }
184 
185   /**
186     Registers and gets an <b>external indirect object</b>.
187     <h3>Remarks</h3>
188     <p>External indirect objects come from alien PDF files. <i>This is a powerful
189     way to import the content of one file into another</i>.</p>
190     <p>Alternatives:<ul>
191     <li>To register a modified internal indirect object, use
192     {@link #set(int,PdfIndirectObject) set(int,PdfIndirectObject)}.</li>
193     <li>To register an internal data object, use
194     {@link #add(PdfDataObject) add(PdfDataObject)}.</li></ul></p>
195   */
196   public PdfIndirectObject addExternal(
197     PdfIndirectObject object
198     )
199   {
200     PdfIndirectObject indirectObject = importedObjects.get(object.hashCode());
201     // Hasn't the external indirect object been imported yet?
202     if(indirectObject == null)
203     {
204       // Register the clone of the data object corresponding to the external indirect object!
205       indirectObject = add((PdfDataObject)object.getDataObject().clone(file));
206       // Keep track of the imported indirect object!
207       importedObjects.put(object.hashCode(),indirectObject);
208     }
209 
210     return indirectObject;
211   }
212 
213   public Collection  <? extends PdfIndirectObject> addAllExternal(
214     Collection  <? extends PdfIndirectObject> objects
215     )
216   {
217     ArrayList  <PdfIndirectObject> addedObjects = new ArrayList  <PdfIndirectObject>(objects.size());
218     for(PdfIndirectObject object : objects)
219     {addedObjects.add((PdfIndirectObject)addExternal(object));}
220 
221     return addedObjects;
222   }
223 
224   // <List>
225   public void add(
226     int index,
227     PdfIndirectObject object
228     )
229   {throw new UnsupportedOperationException  ();}
230 
231   public boolean addAll(
232     int index,
233     Collection  <? extends PdfIndirectObject> objects
234     )
235   {throw new UnsupportedOperationException  ();}
236 
237   /**
238     Gets an indirect object with the specified object number.
239     @param index Object number of the indirect object to get.
240     @return Indirect object corresponding to the specified object number.
241   */
242   public PdfIndirectObject get(
243     int index
244     )
245   {
246     // Try among the new objects!
247     PdfIndirectObject object = modifiedObjects.get(index);
248     // Is it among the original objects?
249     if(object == null)
250     {
251       // Try among the woken original objects!
252       object = wokenObjects.get(index);
253       // Is it among the sleeping original objects?
254       if(object == null)
255       {
256         try
257         {
258           object = new PdfIndirectObject(
259             file,
260             null,
261             xrefEntries[index]
262             );
263         }
264         catch(Exception   e)
265         {throw new RuntimeException  (e);}
266 
267         // Now it's awake!
268         /*
269         NOTE: This operation allows to keep a consistant state across the whole session,
270         avoiding multiple incoherent instantiations of the same original indirect object.
271         */
272         wokenObjects.put(index,object);
273 
274         // Early registration?
275         if(updateMode == UpdateModeEnum.Automatic)
276         {update(object); /* Force early registration. */}
277       }
278     }
279 
280     return object;
281   }
282 
283   public int indexOf(
284     Object   object
285     )
286   {
287     // Is this indirect object associated to this file?
288     if(((PdfIndirectObject)object).getFile() != file)
289       return -1;
290 
291     return ((PdfIndirectObject)object).getReference().getObjectNumber();
292   }
293 
294   public int lastIndexOf(
295     Object   object
296     )
297   {
298     /*
299       NOTE: By definition, there's a bijective relation between indirect objects
300       and their indices.
301     */
302     return indexOf(object);
303   }
304 
305   public ListIterator  <PdfIndirectObject> listIterator(
306     )
307   {throw new NotImplementedException();}
308 
309   public ListIterator  <PdfIndirectObject> listIterator(
310     int index
311     )
312   {throw new NotImplementedException();}
313 
314   public PdfIndirectObject remove(
315     int index
316     )
317   {
318     /*
319       NOTE: Acrobat 6.0 and later (PDF 1.5+) DO NOT use the free list to recycle object numbers;
320       new objects are assigned new numbers [PDF:1.6:H.3:16].
321       According to such an implementation note, we simply mark the removed object as 'not-reusable'
322       newly-freed entry (generation 65535), neglecting both to add it to the linked list of free
323       entries and to increment by 1 its generation number.
324     */
325     return update(
326       new PdfIndirectObject(
327         file,
328         null,
329         new XRefEntry(
330           index,
331           65535, // Not reusable.
332           0,
333           XRefEntryUsageEnum.Free
334           )
335         )
336       );
337   }
338 
339   /**
340     Sets an indirect object with the specified object number.
341     <h3>Contract</h3>
342     <ul>
343       <li>Preconditions:
344         <ol>
345           <li><code>index</code> value MUST be between 1 and (size() - 1); index 0
346           is reserved to the mandatory head of the linked list of free objects [PDF:1.6:3.4.3].</li>
347         </ol>
348       </li>
349       <li>Postconditions:<ol><li>(none).</li></ol></li>
350       <li>Invariants:<ol><li>(none).</li></ol></li>
351       <li>Side-effects:<ol><li>(none).</li></ol></li>
352     </ul>
353     <h3>Remarks</h3>
354     <p>This method is currently limited to <b>internal indirect
355     objects</b>: <i>use it to register modified internal indirect objects only</i>.
356     If you need to register alternative-type objects, consider the following
357     methods:</p>
358     <ul>
359       <li>to register an <b>external indirect object</b>, use
360       {@link #addExternal(PdfIndirectObject) addExternal(PdfIndirectObject)}.</li>
361       <li>to register an <b>internal data object</b>, use
362       {@link #add(PdfDataObject) add(PdfDataObject)}.</li>
363     </ul>
364     @param index Object number of the indirect object to set.
365     @param object Indirect object to set.
366     @return Replaced indirect object.
367   */
368   public PdfIndirectObject set(
369     int index,
370     PdfIndirectObject object
371     )
372   {throw new UnsupportedOperationException  ();}
373 
374   public List  <PdfIndirectObject> subList(
375     int fromIndex,
376     int toIndex
377     )
378   {throw new NotImplementedException();}
379 
380   // <Collection>
381   /**
382     Registers an <b>external indirect object</b>.
383     <h3>Remarks</h3>
384     <p>External indirect objects come from alien PDF files. <i>This is a powerful
385     way to import the content of one file into another</i>.</p>
386     <p>Alternatives:<ul>
387     <li>To register and get an external indirect object, use
388     {@link #addExternal(PdfIndirectObject) addExternal(PdfIndirectObject)}.</li>
389     </ul></p>
390   */
391   public boolean add(
392     PdfIndirectObject object
393     )
394   {
395     boolean changed = (addExternal(object) != null);
396 
397     return changed;
398   }
399 
400   /**
401     Registers <b>external indirect objects</b>.
402     <h3>Remarks</h3>
403     <p>External indirect objects come from alien PDF files. <i>This is a powerful
404     way to import the content of one file into another</i>.</p>
405     <p>Alternatives:<ul>
406     <li>To register and get external indirect object, use
407     {@link #addAllExternal(PdfIndirectObject) addAllExternal(Collection<? extends PdfIndirectObject>)}.</li>
408     </ul></p>
409   */
410   public boolean addAll(
411     Collection  <? extends PdfIndirectObject> objects
412     )
413   {
414     boolean changed = false;
415     for(PdfIndirectObject object : objects)
416     {
417       changed |= (addExternal(object) != null);
418     }
419 
420     return changed;
421   }
422 
423   public void clear(
424     )
425   {throw new UnsupportedOperationException  ();}
426 
427   public boolean contains(
428     Object   object
429     )
430   {throw new NotImplementedException();}
431 
432   public boolean containsAll(
433     Collection  <?> objects
434     )
435   {throw new NotImplementedException();}
436 
437   public boolean equals(
438     Object   object
439     )
440   {throw new NotImplementedException();}
441 
442   public int hashCode(
443     )
444   {throw new NotImplementedException();}
445 
446   public boolean isEmpty(
447     )
448   {
449     /*
450     NOTE: Semantics of the indirect objects collection imply that the collection is considered
451     empty in any case no in-use object is available.
452     */
453     for(PdfIndirectObject object : this)
454     {
455       if(object.isInUse())
456         return false;
457     }
458 
459     return true;
460   }
461 
462   public boolean remove(
463     Object   object
464     )
465   {throw new NotImplementedException();}
466 
467   public boolean removeAll(
468     Collection  <?> objects
469     )
470   {throw new NotImplementedException();}
471 
472   public boolean retainAll(
473     Collection  <?> objects
474     )
475   {throw new UnsupportedOperationException  ();}
476 
477   /**
478     Gets the number of entries available (both in-use and free) in the
479     collection.
480     @return The number of entries available in the collection.
481   */
482   public int size(
483     )
484   {return (lastObjectNumber + 1);}
485 
486   public PdfIndirectObject[] toArray(
487     )
488   {throw new NotImplementedException();}
489 
490   public <PdfIndirectObject> PdfIndirectObject[] toArray(
491     PdfIndirectObject[] objects
492     )
493   {throw new NotImplementedException();}
494 
495   // <Iterable>
496   public Iterator  <PdfIndirectObject> iterator(
497     )
498   {
499     return new Iterator  <PdfIndirectObject>()
500     {
501       // <class>
502       // <dynamic>
503       // <fields>
504       /** Index of the next item. */
505       private int index = 0;
506       // </fields>
507 
508       // <interface>
509       // <public>
510       // <Iterator>
511       public boolean hasNext(
512         )
513       {return (index < size());}
514 
515       public PdfIndirectObject next(
516         )
517       {
518         if(!hasNext())
519           throw new NoSuchElementException  ();
520 
521         return get(index++);
522       }
523 
524       public void remove(
525         )
526       {throw new UnsupportedOperationException  ();}
527       // </Iterator>
528       // </public>
529       // </interface>
530       // </dynamic>
531       // </class>
532     };
533   }
534   // </Iterable>
535   // </Collection>
536   // </List>
537   // </public>
538 
539   // <internal>
540   /**
541     <h3>Remarks</h3>
542     <p>For internal use only.</p>
543   */
544   public TreeMap  <Integer  ,PdfIndirectObject> getModifiedObjects(
545     )
546   {return modifiedObjects;}
547 
548   /**
549     <h3>Remarks</h3>
550     <p>For internal use only.</p>
551   */
552   public PdfIndirectObject update(
553     PdfIndirectObject object
554     )
555   {
556     int index = object.getReference().getObjectNumber();
557 
558     // Get the old indirect object to be replaced!
559     PdfIndirectObject old = get(index);
560     if(old != object)
561     {old.dropFile(); /* Disconnect the old indirect object. */}
562 
563     // Insert the new indirect object into the modified objects collection!
564     modifiedObjects.put(index,object);
565     // Remove old indirect object from cache!
566     wokenObjects.remove(index);
567     // Mark the new indirect object as modified!
568     object.dropOriginal();
569 
570     return old;
571   }
572   // </internal>
573   // </interface>
574   // </dynamic>
575   // </class>
576 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags