| /* |
| * Copyright (c) 2005, 2016, 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. |
| * |
| * <p> 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 |
| * {@code TIFFTagSet}s 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<Integer,String> valueNames = null; |
| |
| /** |
| * Constructs a {@code 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 {@code TIFFTagSet}. |
| * |
| * <p> 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.</p> |
| * |
| * <p> 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.</p> |
| * |
| * @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 {@code TIFFTag} with a given name, tag number and |
| * {@code 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 {@code TIFFTagSet} will |
| * represent the set of {@code TIFFTag}s which appear in the IFD |
| * pointed to. A {@code TIFFTag} represents an IFD pointer if and |
| * only if {@code tagSet} is non-{@code null} or the data |
| * type {@code TIFF_IFD_POINTER} is legal. |
| * |
| * @param name the name of the tag. |
| * @param number the number used to represent the tag. |
| * @param tagSet the {@code 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 {@code 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 {@code 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 {@code datatype} is |
| * less than {@code MIN_DATATYPE} or greater than |
| * {@code 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 {@code String}. |
| */ |
| public String getName() { |
| return name; |
| } |
| |
| /** |
| * Returns the integer used to represent the tag. |
| * |
| * @return the tag number, as an {@code 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: |
| * |
| * <pre> |
| * (1 << TIFFTag.TIFF_SHORT) | (1 << TIFFTag.TIFF_LONG) |
| * </pre> |
| * |
| * @return an {@code 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 {@code 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 {@code BitsPerSample} field is {@code SamplesPerPixel}, |
| * or it may be variable as in the case of most {@code US-ASCII} |
| * fields. |
| * |
| * @return the value count of this tag. |
| */ |
| public int getCount() { |
| return count; |
| } |
| |
| /** |
| * Returns {@code 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 |
| * {@code TIFF_BYTE}, {@code TIFF_SHORT}, etc. |
| * |
| * @return a {@code boolean} indicating whether the given |
| * data type may be used with this tag. |
| * |
| * @throws IllegalArgumentException if {@code datatype} is |
| * less than {@code MIN_DATATYPE} or greater than |
| * {@code 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 {@code TIFFTagSet} of which this tag is a part. |
| * |
| * @return the containing {@code TIFFTagSet}. |
| */ |
| public TIFFTagSet getTagSet() { |
| return tagSet; |
| } |
| |
| /** |
| * Returns {@code true} if this tag is used to point to an IFD |
| * structure containing additional tags. A {@code TIFFTag} represents |
| * an IFD pointer if and only if its {@code TIFFTagSet} is |
| * non-{@code null} or the data type {@code TIFF_IFD_POINTER} is |
| * legal. This condition will be satisfied if and only if either |
| * {@code getTagSet() != null} or |
| * {@code isDataTypeOK(TIFF_IFD_POINTER) == true}. |
| * |
| * <p>Many TIFF extensions use the IFD mechanism in order to limit the |
| * number of new tags that may appear in the root IFD.</p> |
| * |
| * @return {@code true} if this tag points to an IFD. |
| */ |
| public boolean isIFDPointer() { |
| return tagSet != null || isDataTypeOK(TIFF_IFD_POINTER); |
| } |
| |
| /** |
| * Returns {@code 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 {@code 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<Integer,String>(); |
| } |
| valueNames.put(Integer.valueOf(value), name); |
| } |
| |
| /** |
| * Returns the mnemonic name associated with a particular value |
| * that this tag's data may take on, or {@code 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 |
| * {@code 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<Integer> values = valueNames.keySet(); |
| Iterator<Integer> iter = values.iterator(); |
| intValues = new int[values.size()]; |
| int i = 0; |
| while (iter.hasNext()) { |
| intValues[i++] = iter.next(); |
| } |
| } |
| return intValues; |
| } |
| } |
