1 /*
2 * Copyright (c) 2005, 2015, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25 package javax.imageio.plugins.tiff;
26
27 import java.util.ArrayList;
28 import java.util.Arrays;
29 import java.util.Iterator;
30 import java.util.List;
31 import java.util.Map;
32 import java.util.TreeMap;
33 import javax.imageio.metadata.IIOInvalidTreeException;
34 import javax.imageio.metadata.IIOMetadata;
35 import javax.imageio.metadata.IIOMetadataFormatImpl;
36 import com.sun.imageio.plugins.tiff.TIFFIFD;
37 import com.sun.imageio.plugins.tiff.TIFFImageMetadata;
38
39 /**
40 * A convenience class for simplifying interaction with TIFF native
41 * image metadata. A TIFF image metadata tree represents an Image File
42 * Directory (IFD) from a TIFF 6.0 stream. An IFD consists of a number of
43 * IFD Entries each of which associates an identifying tag number with
44 * a compatible value. A <code>TIFFDirectory</code> instance corresponds
45 * to an IFD and contains a set of {@link TIFFField}s each of which
46 * corresponds to an IFD Entry in the IFD.
47 *
48 * <p>When reading, a <code>TIFFDirectory</code> may be created by passing
49 * the value returned by {@link javax.imageio.ImageReader#getImageMetadata
50 * ImageReader.getImageMetadata()} to {@link #createFromMetadata
51 * createFromMetadata()}. The {@link TIFFField}s in the directory may then
52 * be obtained using the accessor methods provided in this class.</p>
53 *
54 * <p>When writing, an {@link IIOMetadata} object for use by one of the
55 * <code>write()</code> methods of {@link javax.imageio.ImageWriter} may be
56 * created from a <code>TIFFDirectory</code> by {@link #getAsMetadata()}.
57 * The <code>TIFFDirectory</code> itself may be created by construction or
58 * from the <code>IIOMetadata</code> object returned by
59 * {@link javax.imageio.ImageWriter#getDefaultImageMetadata
60 * ImageWriter.getDefaultImageMetadata()}. The <code>TIFFField</code>s in the
61 * directory may be set using the mutator methods provided in this class.</p>
62 *
63 * <p>A <code>TIFFDirectory</code> is aware of the tag numbers in the
64 * group of {@link TIFFTagSet}s associated with it. When
65 * a <code>TIFFDirectory</code> is created from a native image metadata
66 * object, these tag sets are derived from the <tt>tagSets</tt> attribute
67 * of the <tt>TIFFIFD</tt> node.</p>
68 *
69 * <p>A <code>TIFFDirectory</code> might also have a parent {@link TIFFTag}.
70 * This will occur if the directory represents an IFD other than the root
71 * IFD of the image. The parent tag is the tag of the IFD Entry which is a
72 * pointer to the IFD represented by this <code>TIFFDirectory</code>. The
73 * {@link TIFFTag#isIFDPointer} method of this parent <code>TIFFTag</code>
74 * must return <code>true</code>. When a <code>TIFFDirectory</code> is
75 * created from a native image metadata object, the parent tag set is set
76 * from the <tt>parentTagName</tt> attribute of the corresponding
77 * <tt>TIFFIFD</tt> node. Note that a <code>TIFFDirectory</code> instance
78 * which has a non-<code>null</code> parent tag will be contained in the
79 * data field of a <code>TIFFField</code> instance which has a tag field
80 * equal to the contained directory's parent tag.</p>
81 *
82 * <p>As an example consider an Exif image. The <code>TIFFDirectory</code>
83 * instance corresponding to the Exif IFD in the Exif stream would have parent
84 * tag {@link ExifParentTIFFTagSet#TAG_EXIF_IFD_POINTER TAG_EXIF_IFD_POINTER}
85 * and would include {@link ExifTIFFTagSet} in its group of known tag sets.
86 * The <code>TIFFDirectory</code> corresponding to this Exif IFD will be
87 * contained in the data field of a <code>TIFFField</code> which will in turn
88 * be contained in the <code>TIFFDirectory</code> corresponding to the primary
89 * IFD of the Exif image which will itself have a <code>null</code>-valued
90 * parent tag.</p>
91 *
92 * <p><b>Note that this implementation is not synchronized. </b>If multiple
93 * threads use a <code>TIFFDirectory</code> instance concurrently, and at
94 * least one of the threads modifies the directory, for example, by adding
95 * or removing <code>TIFFField</code>s or <code>TIFFTagSet</code>s, it
96 * <i>must</i> be synchronized externally.</p>
97 *
98 * @since 9
99 * @see IIOMetadata
100 * @see TIFFField
101 * @see TIFFTag
102 * @see TIFFTagSet
103 */
104 public class TIFFDirectory implements Cloneable {
105
106 /** The largest low-valued tag number in the TIFF 6.0 specification. */
107 private static final int MAX_LOW_FIELD_TAG_NUM =
108 BaselineTIFFTagSet.TAG_REFERENCE_BLACK_WHITE;
109
110 /** The <code>TIFFTagSets</code> associated with this directory. */
111 private List<TIFFTagSet> tagSets;
112
113 /** The parent <code>TIFFTag</code> of this directory. */
114 private TIFFTag parentTag;
115
116 /**
117 * The fields in this directory which have a low tag number. These are
118 * managed as an array for efficiency as they are the most common fields.
119 */
120 private TIFFField[] lowFields = new TIFFField[MAX_LOW_FIELD_TAG_NUM + 1];
121
122 /** The number of low tag numbered fields in the directory. */
123 private int numLowFields = 0;
124
125 /**
126 * A mapping of <code>Integer</code> tag numbers to <code>TIFFField</code>s
127 * for fields which are not low tag numbered.
128 */
129 private Map<Integer,TIFFField> highFields = new TreeMap<Integer,TIFFField>();
130
131 /**
132 * Creates a <code>TIFFDirectory</code> instance from the contents of
133 * an image metadata object. The supplied object must support an image
134 * metadata format supported by the TIFF {@link javax.imageio.ImageWriter}
135 * plug-in. This will usually be either the TIFF native image metadata
136 * format <tt>javax_imageio_tiff_image_1.0</tt> or the Java
137 * Image I/O standard metadata format <tt>javax_imageio_1.0</tt>.
138 *
139 * @param tiffImageMetadata A metadata object which supports a compatible
140 * image metadata format.
141 *
142 * @return A <code>TIFFDirectory</code> populated from the contents of
143 * the supplied metadata object.
144 *
145 * @throws NullPointerException if <code>tiffImageMetadata</code>
146 * is <code>null</code>.
147 * @throws IllegalArgumentException if <code>tiffImageMetadata</code>
148 * does not support a compatible image metadata format.
149 * @throws IIOInvalidTreeException if the supplied metadata object
150 * cannot be parsed.
151 */
152 public static TIFFDirectory
153 createFromMetadata(IIOMetadata tiffImageMetadata)
154 throws IIOInvalidTreeException {
155
156 if(tiffImageMetadata == null) {
157 throw new NullPointerException("tiffImageMetadata == null");
158 }
159
160 TIFFImageMetadata tim;
161 if(tiffImageMetadata instanceof TIFFImageMetadata) {
162 tim = (TIFFImageMetadata)tiffImageMetadata;
163 } else {
164 // Create a native metadata object.
165 ArrayList<TIFFTagSet> l = new ArrayList<TIFFTagSet>(1);
166 l.add(BaselineTIFFTagSet.getInstance());
167 tim = new TIFFImageMetadata(l);
168
169 // Determine the format name to use.
170 String formatName = null;
171 if(TIFFImageMetadata.NATIVE_METADATA_FORMAT_NAME.equals
172 (tiffImageMetadata.getNativeMetadataFormatName())) {
173 formatName = TIFFImageMetadata.NATIVE_METADATA_FORMAT_NAME;
174 } else {
175 String[] extraNames =
176 tiffImageMetadata.getExtraMetadataFormatNames();
177 if(extraNames != null) {
178 for(int i = 0; i < extraNames.length; i++) {
179 if(TIFFImageMetadata.NATIVE_METADATA_FORMAT_NAME.equals
180 (extraNames[i])) {
181 formatName = extraNames[i];
182 break;
183 }
184 }
185 }
186
187 if(formatName == null) {
188 if(tiffImageMetadata.isStandardMetadataFormatSupported()) {
189 formatName =
190 IIOMetadataFormatImpl.standardMetadataFormatName;
191 } else {
192 throw new IllegalArgumentException
193 ("Parameter does not support required metadata format!");
194 }
195 }
196 }
197
198 // Set the native metadata object from the tree.
199 tim.setFromTree(formatName,
200 tiffImageMetadata.getAsTree(formatName));
201 }
202
203 return tim.getRootIFD();
204 }
205
206 /**
207 * Converts a <code>TIFFDirectory</code> to a <code>TIFFIFD</code>.
208 */
209 private static TIFFIFD getDirectoryAsIFD(TIFFDirectory dir) {
210 if(dir instanceof TIFFIFD) {
211 return (TIFFIFD)dir;
212 }
213
214 TIFFIFD ifd = new TIFFIFD(Arrays.asList(dir.getTagSets()),
215 dir.getParentTag());
216 TIFFField[] fields = dir.getTIFFFields();
217 int numFields = fields.length;
218 for(int i = 0; i < numFields; i++) {
219 TIFFField f = fields[i];
220 TIFFTag tag = f.getTag();
221 if(tag.isIFDPointer()) {
222 TIFFDirectory subIFD =
223 getDirectoryAsIFD((TIFFDirectory)f.getData());
224 f = new TIFFField(tag, f.getType(), (long)f.getCount(), subIFD);
225 }
226 ifd.addTIFFField(f);
227 }
228
229 return ifd;
230 }
231
232 /**
233 * Constructs a <code>TIFFDirectory</code> which is aware of a given
234 * group of {@link TIFFTagSet}s. An optional parent {@link TIFFTag}
235 * may also be specified.
236 *
237 * @param tagSets The <code>TIFFTagSets</code> associated with this
238 * directory.
239 * @param parentTag The parent <code>TIFFTag</code> of this directory;
240 * may be <code>null</code>.
241 * @throws NullPointerException if <code>tagSets</code> is
242 * <code>null</code>.
243 */
244 public TIFFDirectory(TIFFTagSet[] tagSets, TIFFTag parentTag) {
245 if(tagSets == null) {
246 throw new NullPointerException("tagSets == null!");
247 }
248 this.tagSets = new ArrayList<TIFFTagSet>(tagSets.length);
249 int numTagSets = tagSets.length;
250 for(int i = 0; i < numTagSets; i++) {
251 this.tagSets.add(tagSets[i]);
252 }
253 this.parentTag = parentTag;
254 }
255
256 /**
257 * Returns the {@link TIFFTagSet}s of which this directory is aware.
258 *
259 * @return The <code>TIFFTagSet</code>s associated with this
260 * <code>TIFFDirectory</code>.
261 */
262 public TIFFTagSet[] getTagSets() {
263 return tagSets.toArray(new TIFFTagSet[tagSets.size()]);
264 }
265
266 /**
267 * Adds an element to the group of {@link TIFFTagSet}s of which this
268 * directory is aware.
269 *
270 * @param tagSet The <code>TIFFTagSet</code> to add.
271 * @throws NullPointerException if <code>tagSet</code> is
272 * <code>null</code>.
273 */
274 public void addTagSet(TIFFTagSet tagSet) {
275 if(tagSet == null) {
276 throw new NullPointerException("tagSet == null");
277 }
278
279 if(!tagSets.contains(tagSet)) {
280 tagSets.add(tagSet);
281 }
282 }
283
284 /**
285 * Removes an element from the group of {@link TIFFTagSet}s of which this
286 * directory is aware.
287 *
288 * @param tagSet The <code>TIFFTagSet</code> to remove.
289 * @throws NullPointerException if <code>tagSet</code> is
290 * <code>null</code>.
291 */
292 public void removeTagSet(TIFFTagSet tagSet) {
293 if(tagSet == null) {
294 throw new NullPointerException("tagSet == null");
295 }
296
297 if(tagSets.contains(tagSet)) {
298 tagSets.remove(tagSet);
299 }
300 }
301
302 /**
303 * Returns the parent {@link TIFFTag} of this directory if one
304 * has been defined or <code>null</code> otherwise.
305 *
306 * @return The parent <code>TIFFTag</code> of this
307 * <code>TIFFDiectory</code> or <code>null</code>.
308 */
309 public TIFFTag getParentTag() {
310 return parentTag;
311 }
312
313 /**
314 * Returns the {@link TIFFTag} which has tag number equal to
315 * <code>tagNumber</code> or <code>null</code> if no such tag
316 * exists in the {@link TIFFTagSet}s associated with this
317 * directory.
318 *
319 * @param tagNumber The tag number of interest.
320 * @return The corresponding <code>TIFFTag</code> or <code>null</code>.
321 */
322 public TIFFTag getTag(int tagNumber) {
323 return TIFFIFD.getTag(tagNumber, tagSets);
324 }
325
326 /**
327 * Returns the number of {@link TIFFField}s in this directory.
328 *
329 * @return The number of <code>TIFFField</code>s in this
330 * <code>TIFFDirectory</code>.
331 */
332 public int getNumTIFFFields() {
333 return numLowFields + highFields.size();
334 }
335
336 /**
337 * Determines whether a TIFF field with the given tag number is
338 * contained in this directory.
339 *
340 * @param tagNumber The tag number.
341 * @return Whether a {@link TIFFTag} with tag number equal to
342 * <code>tagNumber</code> is present in this <code>TIFFDirectory</code>.
343 */
344 public boolean containsTIFFField(int tagNumber) {
345 return (tagNumber >= 0 && tagNumber <= MAX_LOW_FIELD_TAG_NUM &&
346 lowFields[tagNumber] != null) ||
347 highFields.containsKey(Integer.valueOf(tagNumber));
348 }
349
350 /**
351 * Adds a TIFF field to the directory.
352 *
353 * @param f The field to add.
354 * @throws NullPointerException if <code>f</code> is <code>null</code>.
355 */
356 public void addTIFFField(TIFFField f) {
357 if(f == null) {
358 throw new NullPointerException("f == null");
359 }
360 int tagNumber = f.getTagNumber();
361 if(tagNumber >= 0 && tagNumber <= MAX_LOW_FIELD_TAG_NUM) {
362 if(lowFields[tagNumber] == null) {
363 numLowFields++;
364 }
365 lowFields[tagNumber] = f;
366 } else {
367 highFields.put(Integer.valueOf(tagNumber), f);
368 }
369 }
370
371 /**
372 * Retrieves a TIFF field from the directory.
373 *
374 * @param tagNumber The tag number of the tag associated with the field.
375 * @return A <code>TIFFField</code> with the requested tag number of
376 * <code>null</code> if no such field is present.
377 */
378 public TIFFField getTIFFField(int tagNumber) {
379 TIFFField f;
380 if(tagNumber >= 0 && tagNumber <= MAX_LOW_FIELD_TAG_NUM) {
381 f = lowFields[tagNumber];
382 } else {
383 f = highFields.get(Integer.valueOf(tagNumber));
384 }
385 return f;
386 }
387
388 /**
389 * Removes a TIFF field from the directory.
390 *
391 * @param tagNumber The tag number of the tag associated with the field.
392 */
393 public void removeTIFFField(int tagNumber) {
394 if(tagNumber >= 0 && tagNumber <= MAX_LOW_FIELD_TAG_NUM) {
395 if(lowFields[tagNumber] != null) {
396 numLowFields--;
397 lowFields[tagNumber] = null;
398 }
399 } else {
400 highFields.remove(Integer.valueOf(tagNumber));
401 }
402 }
403
404 /**
405 * Retrieves all TIFF fields from the directory.
406 *
407 * @return An array of all TIFF fields in order of numerically increasing
408 * tag number.
409 */
410 public TIFFField[] getTIFFFields() {
411 // Allocate return value.
412 TIFFField[] fields = new TIFFField[numLowFields + highFields.size()];
413
414 // Copy any low-index fields.
415 int nextIndex = 0;
416 for(int i = 0; i <= MAX_LOW_FIELD_TAG_NUM; i++) {
417 if(lowFields[i] != null) {
418 fields[nextIndex++] = lowFields[i];
419 if(nextIndex == numLowFields) break;
420 }
421 }
422
423 // Copy any high-index fields.
424 if(!highFields.isEmpty()) {
425 Iterator<Integer> keys = highFields.keySet().iterator();
426 while(keys.hasNext()) {
427 fields[nextIndex++] = highFields.get(keys.next());
428 }
429 }
430
431 return fields;
432 }
433
434 /**
435 * Removes all TIFF fields from the directory.
436 */
437 public void removeTIFFFields() {
438 Arrays.fill(lowFields, (Object)null);
439 numLowFields = 0;
440 highFields.clear();
441 }
442
443 /**
444 * Converts the directory to a metadata object.
445 *
446 * @return A metadata instance initialized from the contents of this
447 * <code>TIFFDirectory</code>.
448 */
449 public IIOMetadata getAsMetadata() {
450 return new TIFFImageMetadata(getDirectoryAsIFD(this));
451 }
452
453 /**
454 * Clones the directory and all the fields contained therein.
455 *
456 * @return A clone of this <code>TIFFDirectory</code>.
457 * @throws CloneNotSupportedException if the instance cannot be cloned.
458 */
459 @Override
460 public TIFFDirectory clone() throws CloneNotSupportedException {
461 TIFFDirectory dir = (TIFFDirectory) super.clone();
462 dir.tagSets = new ArrayList<TIFFTagSet>(tagSets);
463 dir.parentTag = getParentTag();
464 TIFFField[] fields = getTIFFFields();
465 for(TIFFField field : fields) {
466 dir.addTIFFField(field.clone());
467 }
468
469 return dir;
470 }
471 }