/* * Copyright (c) 2005, 2015, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package javax.imageio.plugins.tiff; import java.util.Iterator; import java.util.Set; import java.util.SortedMap; import java.util.TreeMap; /** * A class defining the notion of a TIFF tag. A TIFF tag is a key * that may appear in an Image File Directory (IFD). In the IFD * each tag has some data associated with it, which may consist of zero * or more values of a given data type. The combination of a tag and a * value is known as an IFD Entry or TIFF Field. * *

The actual tag values used in the root IFD of a standard ("baseline") * tiff stream are defined in the {@link BaselineTIFFTagSet * BaselineTIFFTagSet} class. * * @since 9 * @see BaselineTIFFTagSet * @see TIFFField * @see TIFFTagSet */ public class TIFFTag { // TIFF 6.0 + Adobe PageMaker(R) 6.0 TIFF Technical Notes 1 IFD data type /** Flag for 8 bit unsigned integers. */ public static final int TIFF_BYTE = 1; /** Flag for null-terminated ASCII strings. */ public static final int TIFF_ASCII = 2; /** Flag for 16 bit unsigned integers. */ public static final int TIFF_SHORT = 3; /** Flag for 32 bit unsigned integers. */ public static final int TIFF_LONG = 4; /** Flag for pairs of 32 bit unsigned integers. */ public static final int TIFF_RATIONAL = 5; /** Flag for 8 bit signed integers. */ public static final int TIFF_SBYTE = 6; /** Flag for 8 bit uninterpreted bytes. */ public static final int TIFF_UNDEFINED = 7; /** Flag for 16 bit signed integers. */ public static final int TIFF_SSHORT = 8; /** Flag for 32 bit signed integers. */ public static final int TIFF_SLONG = 9; /** Flag for pairs of 32 bit signed integers. */ public static final int TIFF_SRATIONAL = 10; /** Flag for 32 bit IEEE floats. */ public static final int TIFF_FLOAT = 11; /** Flag for 64 bit IEEE doubles. */ public static final int TIFF_DOUBLE = 12; /** * Flag for IFD pointer defined in TIFF Tech Note 1 in * TIFF Specification Supplement 1. */ public static final int TIFF_IFD_POINTER = 13; /** * The numerically smallest constant representing a TIFF data type. */ public static final int MIN_DATATYPE = TIFF_BYTE; /** * The numerically largest constant representing a TIFF data type. */ public static final int MAX_DATATYPE = TIFF_IFD_POINTER; /** * The name assigned to a tag with an unknown tag number. Such * a tag may be created for example when reading an IFD and a * tag number is encountered which is not in any of the * TIFFTagSets known to the reader. */ public static final String UNKNOWN_TAG_NAME = "UnknownTag"; /** * Disallowed data type mask. */ private static final int DISALLOWED_DATATYPES_MASK = ~0x3fff; private static final int[] SIZE_OF_TYPE = { 0, // 0 = n/a 1, // 1 = byte 1, // 2 = ascii 2, // 3 = short 4, // 4 = long 8, // 5 = rational 1, // 6 = sbyte 1, // 7 = undefined 2, // 8 = sshort 4, // 9 = slong 8, // 10 = srational 4, // 11 = float 8, // 12 = double 4, // 13 = IFD_POINTER }; private int number; private String name; private int dataTypes; private int count; private TIFFTagSet tagSet = null; // Mnemonic names for integral enumerated constants private SortedMap valueNames = null; /** * Constructs a TIFFTag with a given name, tag number, set * of legal data types, and value count. A negative value count signifies * that either an arbitrary number of values is legal or the required count * is determined by the values of other fields in the IFD. A non-negative * count specifies the number of values which an associated field must * contain. The tag will have no associated TIFFTagSet. * *

If there are mnemonic names to be associated with the legal * data values for the tag, {@link #addValueName(int, String) * addValueName()} should be called on the new instance for each name. * Mnemonic names apply only to tags which have integral data type.

* *

See the documentation for {@link #getDataTypes() * getDataTypes()} for an explanation of how the set * of data types is to be converted into a bit mask.

* * @param name the name of the tag. * @param number the number used to represent the tag. * @param dataTypes a bit mask indicating the set of legal data * types for this tag. * @param count the value count for this tag. * @throws NullPointerException if name is null. * @throws IllegalArgumentException if number is negative or dataTypes * is negative or specifies an out of range type. */ public TIFFTag(String name, int number, int dataTypes, int count) { if (name == null) { throw new NullPointerException("name == null"); } else if (number < 0) { throw new IllegalArgumentException("number (" + number + ") < 0"); } else if (dataTypes < 0 || (dataTypes & DISALLOWED_DATATYPES_MASK) != 0) { throw new IllegalArgumentException("dataTypes out of range"); } this.name = name; this.number = number; this.dataTypes = dataTypes; this.count = count; } /** * Constructs a TIFFTag with a given name, tag number and * TIFFTagSet to which it refers. The legal data types are * set to include {@link #TIFF_LONG} and {@link #TIFF_IFD_POINTER} and the * value count is unity. The TIFFTagSet will * represent the set of TIFFTags which appear in the IFD * pointed to. A TIFFTag represents an IFD pointer if and * only if tagSet is non-null or the data * type TIFF_IFD_POINTER is legal. * * @param name the name of the tag. * @param number the number used to represent the tag. * @param tagSet the TIFFTagSet to which this tag belongs. * @throws NullPointerException if name or tagSet is null. * @throws IllegalArgumentException if number is negative. * * @see #TIFFTag(String, int, int, int) */ public TIFFTag(String name, int number, TIFFTagSet tagSet) { this(name, number, 1 << TIFFTag.TIFF_LONG | 1 << TIFFTag.TIFF_IFD_POINTER, 1); if (tagSet == null) { throw new NullPointerException("tagSet == null"); } this.tagSet = tagSet; } /** * Constructs a TIFFTag with a given name, tag number, * and set of legal data types. The value count of the tag will be * undefined and it will have no associated TIFFTagSet. * * @param name the name of the tag. * @param number the number used to represent the tag. * @param dataTypes a bit mask indicating the set of legal data * types for this tag. * @throws NullPointerException if name is null. * @throws IllegalArgumentException if number is negative or dataTypes * is negative or specifies an out of range type. * * @see #TIFFTag(String, int, int, int) */ public TIFFTag(String name, int number, int dataTypes) { this(name, number, dataTypes, -1); } /** * Returns the number of bytes used to store a value of the given * data type. * * @param dataType the data type to be queried. * * @return the number of bytes used to store the given data type. * * @throws IllegalArgumentException if datatype is * less than MIN_DATATYPE or greater than * MAX_DATATYPE. */ public static int getSizeOfType(int dataType) { if (dataType < MIN_DATATYPE ||dataType > MAX_DATATYPE) { throw new IllegalArgumentException("dataType out of range!"); } return SIZE_OF_TYPE[dataType]; } /** * Returns the name of the tag, as it will appear in image metadata. * * @return the tag name, as a String. */ public String getName() { return name; } /** * Returns the integer used to represent the tag. * * @return the tag number, as an int. */ public int getNumber() { return number; } /** * Returns a bit mask indicating the set of data types that may * be used to store the data associated with the tag. * For example, a tag that can store both SHORT and LONG values * would return a value of: * * 
     * (1 << TIFFTag.TIFF_SHORT) | (1 << TIFFTag.TIFF_LONG)
     *
* * @return an int containing a bitmask encoding the * set of valid data types. */ public int getDataTypes() { return dataTypes; } /** * Returns the value count of this tag. If this value is positive, it * represents the required number of values for a TIFFField * which has this tag. If the value is negative, the count is undefined. * In the latter case the count may be derived, e.g., the number of values * of the BitsPerSample field is SamplesPerPixel, * or it may be variable as in the case of most US-ASCII * fields. * * @return the value count of this tag. */ public int getCount() { return count; } /** * Returns true if the given data type * may be used for the data associated with this tag. * * @param dataType the data type to be queried, one of * TIFF_BYTE, TIFF_SHORT, etc. * * @return a boolean indicating whether the given * data type may be used with this tag. * * @throws IllegalArgumentException if datatype is * less than MIN_DATATYPE or greater than * MAX_DATATYPE. */ public boolean isDataTypeOK(int dataType) { if (dataType < MIN_DATATYPE || dataType > MAX_DATATYPE) { throw new IllegalArgumentException("datatype not in range!"); } return (dataTypes & (1 << dataType)) != 0; } /** * Returns the TIFFTagSet of which this tag is a part. * * @return the containing TIFFTagSet. */ public TIFFTagSet getTagSet() { return tagSet; } /** * Returns true if this tag is used to point to an IFD * structure containing additional tags. A TIFFTag represents * an IFD pointer if and only if its TIFFTagSet is * non-null or the data type TIFF_IFD_POINTER is * legal. This condition will be satisfied if and only if either * getTagSet() != null or * isDataTypeOK(TIFF_IFD_POINTER) == true. * *

Many TIFF extensions use the IFD mechanism in order to limit the * number of new tags that may appear in the root IFD.

* * @return true if this tag points to an IFD. */ public boolean isIFDPointer() { return tagSet != null || isDataTypeOK(TIFF_IFD_POINTER); } /** * Returns true if there are mnemonic names associated with * the set of legal values for the data associated with this tag. Mnemonic * names apply only to tags which have integral data type. * * @return true if mnemonic value names are available. */ public boolean hasValueNames() { return valueNames != null; } /** * Adds a mnemonic name for a particular value that this tag's data may take * on. Mnemonic names apply only to tags which have integral data type. * * @param value the data value. * @param name the name to associate with the value. */ protected void addValueName(int value, String name) { if (valueNames == null) { valueNames = new TreeMap(); } valueNames.put(Integer.valueOf(value), name); } /** * Returns the mnemonic name associated with a particular value * that this tag's data may take on, or null if * no name is present. Mnemonic names apply only to tags which have * integral data type. * * @param value the data value. * * @return the mnemonic name associated with the value, as a * String. */ public String getValueName(int value) { if (valueNames == null) { return null; } return valueNames.get(Integer.valueOf(value)); } /** * Returns an array of values for which mnemonic names are defined. The * method {@link #getValueName(int) getValueName()} will return * non-{@code null} only for values contained in the returned array. * Mnemonic names apply only to tags which have integral data type. * * @return the values for which there is a mnemonic name. */ public int[] getNamedValues() { int[] intValues = null; if (valueNames != null) { Set values = valueNames.keySet(); Iterator iter = values.iterator(); intValues = new int[values.size()]; int i = 0; while (iter.hasNext()) { intValues[i++] = iter.next(); } } return intValues; } }