This is an automated email from the ASF dual-hosted git repository. ggregory pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/commons-imaging.git
commit 88ae2f8de1d58c0659b6ee2b467e17cd74c3f502 Author: Gary Gregory <[email protected]> AuthorDate: Mon Jan 5 14:10:29 2026 -0500 Javadoc --- .../formats/tiff/write/AbstractTiffOutputItem.java | 30 ++ .../tiff/write/TiffImageWriterLossless.java | 11 + .../formats/tiff/write/TiffImageWriterLossy.java | 11 + .../formats/tiff/write/TiffOutputDirectory.java | 324 +++++++++++++++++++++ .../formats/tiff/write/TiffOutputField.java | 77 +++++ .../imaging/formats/tiff/write/TiffOutputSet.java | 138 +++++++++ 6 files changed, 591 insertions(+) diff --git a/src/main/java/org/apache/commons/imaging/formats/tiff/write/AbstractTiffOutputItem.java b/src/main/java/org/apache/commons/imaging/formats/tiff/write/AbstractTiffOutputItem.java index 8362c005..764c8228 100644 --- a/src/main/java/org/apache/commons/imaging/formats/tiff/write/AbstractTiffOutputItem.java +++ b/src/main/java/org/apache/commons/imaging/formats/tiff/write/AbstractTiffOutputItem.java @@ -57,21 +57,51 @@ abstract class AbstractTiffOutputItem { } } + /** + * Undefined offset value constant. + */ public static final long UNDEFINED_VALUE = -1; private long offset = UNDEFINED_VALUE; + /** + * Gets a description of this item. + * + * @return the item description. + */ public abstract String getItemDescription(); + /** + * Gets the length of this item in bytes. + * + * @return the item length. + */ public abstract int getItemLength(); + /** + * Gets the offset of this item. + * + * @return the offset. + */ protected long getOffset() { return offset; } + /** + * Sets the offset of this item. + * + * @param offset the offset. + */ protected void setOffset(final long offset) { this.offset = offset; } + /** + * Writes this item to the output stream. + * + * @param bos the output stream. + * @throws IOException if an I/O error occurs. + * @throws ImagingException if an imaging error occurs. + */ public abstract void writeItem(AbstractBinaryOutputStream bos) throws IOException, ImagingException; } diff --git a/src/main/java/org/apache/commons/imaging/formats/tiff/write/TiffImageWriterLossless.java b/src/main/java/org/apache/commons/imaging/formats/tiff/write/TiffImageWriterLossless.java index 7d349052..cc5faa51 100644 --- a/src/main/java/org/apache/commons/imaging/formats/tiff/write/TiffImageWriterLossless.java +++ b/src/main/java/org/apache/commons/imaging/formats/tiff/write/TiffImageWriterLossless.java @@ -82,10 +82,21 @@ public class TiffImageWriterLossless extends AbstractTiffImageWriter { private final byte[] exifBytes; + /** + * Constructs a new instance. + * + * @param exifBytes the EXIF bytes. + */ public TiffImageWriterLossless(final byte[] exifBytes) { this.exifBytes = exifBytes; } + /** + * Constructs a new instance. + * + * @param byteOrder the byte order. + * @param exifBytes the EXIF bytes. + */ public TiffImageWriterLossless(final ByteOrder byteOrder, final byte[] exifBytes) { super(byteOrder); this.exifBytes = exifBytes; diff --git a/src/main/java/org/apache/commons/imaging/formats/tiff/write/TiffImageWriterLossy.java b/src/main/java/org/apache/commons/imaging/formats/tiff/write/TiffImageWriterLossy.java index 7f10592d..01d07340 100644 --- a/src/main/java/org/apache/commons/imaging/formats/tiff/write/TiffImageWriterLossy.java +++ b/src/main/java/org/apache/commons/imaging/formats/tiff/write/TiffImageWriterLossy.java @@ -26,12 +26,23 @@ import java.util.List; import org.apache.commons.imaging.ImagingException; import org.apache.commons.imaging.common.AbstractBinaryOutputStream; +/** + * TIFF lossy image writer. + */ public class TiffImageWriterLossy extends AbstractTiffImageWriter { + /** + * Constructs a new instance with default byte order. + */ public TiffImageWriterLossy() { // with default byte order } + /** + * Constructs a new instance with the specified byte order. + * + * @param byteOrder the byte order. + */ public TiffImageWriterLossy(final ByteOrder byteOrder) { super(byteOrder); } diff --git a/src/main/java/org/apache/commons/imaging/formats/tiff/write/TiffOutputDirectory.java b/src/main/java/org/apache/commons/imaging/formats/tiff/write/TiffOutputDirectory.java index 59e9419f..67ebf716 100644 --- a/src/main/java/org/apache/commons/imaging/formats/tiff/write/TiffOutputDirectory.java +++ b/src/main/java/org/apache/commons/imaging/formats/tiff/write/TiffOutputDirectory.java @@ -72,8 +72,16 @@ import org.apache.commons.imaging.formats.tiff.taginfos.TagInfoShortOrRational; import org.apache.commons.imaging.formats.tiff.taginfos.TagInfoShorts; import org.apache.commons.imaging.formats.tiff.taginfos.TagInfoXpString; +/** + * Represents a TIFF output directory containing fields and image data. + */ public final class TiffOutputDirectory extends AbstractTiffOutputItem implements Iterable<TiffOutputField> { + + /** + * Comparator for sorting directories by type. + */ public static final Comparator<TiffOutputDirectory> COMPARATOR = Comparator.comparingInt(TiffOutputDirectory::getType); + private final int type; private final List<TiffOutputField> fields = new ArrayList<>(); private final ByteOrder byteOrder; @@ -81,11 +89,24 @@ public final class TiffOutputDirectory extends AbstractTiffOutputItem implements private JpegImageData jpegImageData; private AbstractTiffImageData abstractTiffImageData; + /** + * Constructs a new instance. + * + * @param type the directory type. + * @param byteOrder the byte order. + */ public TiffOutputDirectory(final int type, final ByteOrder byteOrder) { this.type = type; this.byteOrder = byteOrder; } + /** + * Adds an ASCII field. + * + * @param tagInfo the tag info. + * @param values the string values. + * @throws ImagingException if the values are invalid. + */ public void add(final TagInfoAscii tagInfo, final String... values) throws ImagingException { final byte[] bytes = tagInfo.encodeValue(byteOrder, values); if (tagInfo.length > 0 && tagInfo.length != bytes.length) { @@ -95,6 +116,13 @@ public final class TiffOutputDirectory extends AbstractTiffOutputItem implements add(tiffOutputField); } + /** + * Adds an ASCII or byte field with string values. + * + * @param tagInfo the tag info. + * @param values the string values. + * @throws ImagingException if the values are invalid. + */ public void add(final TagInfoAsciiOrByte tagInfo, final String... values) throws ImagingException { final byte[] bytes = tagInfo.encodeValue(AbstractFieldType.ASCII, values, byteOrder); if (tagInfo.length > 0 && tagInfo.length != bytes.length) { @@ -104,6 +132,13 @@ public final class TiffOutputDirectory extends AbstractTiffOutputItem implements add(tiffOutputField); } + /** + * Adds an ASCII or rational field with rational values. + * + * @param tagInfo the tag info. + * @param values the rational values. + * @throws ImagingException if the values are invalid. + */ public void add(final TagInfoAsciiOrRational tagInfo, final RationalNumber... values) throws ImagingException { if (tagInfo.length > 0 && tagInfo.length != values.length) { throw new ImagingException("Tag expects " + tagInfo.length + " value(s), not " + values.length); @@ -113,6 +148,13 @@ public final class TiffOutputDirectory extends AbstractTiffOutputItem implements add(tiffOutputField); } + /** + * Adds an ASCII or rational field with string values. + * + * @param tagInfo the tag info. + * @param values the string values. + * @throws ImagingException if the values are invalid. + */ public void add(final TagInfoAsciiOrRational tagInfo, final String... values) throws ImagingException { final byte[] bytes = tagInfo.encodeValue(AbstractFieldType.ASCII, values, byteOrder); if (tagInfo.length > 0 && tagInfo.length != bytes.length) { @@ -122,6 +164,13 @@ public final class TiffOutputDirectory extends AbstractTiffOutputItem implements add(tiffOutputField); } + /** + * Adds a byte field. + * + * @param tagInfo the tag info. + * @param value the byte value. + * @throws ImagingException if the value is invalid. + */ public void add(final TagInfoByte tagInfo, final byte value) throws ImagingException { if (tagInfo.length != 1) { throw new ImagingException("Tag expects " + tagInfo.length + " value(s), not 1"); @@ -131,6 +180,13 @@ public final class TiffOutputDirectory extends AbstractTiffOutputItem implements add(tiffOutputField); } + /** + * Adds a byte or short field with byte values. + * + * @param tagInfo the tag info. + * @param values the byte values. + * @throws ImagingException if the values are invalid. + */ public void add(final TagInfoByteOrShort tagInfo, final byte... values) throws ImagingException { if (tagInfo.length > 0 && tagInfo.length != values.length) { throw new ImagingException("Tag expects " + tagInfo.length + " value(s), not " + values.length); @@ -140,6 +196,13 @@ public final class TiffOutputDirectory extends AbstractTiffOutputItem implements add(tiffOutputField); } + /** + * Adds a byte or short field with short values. + * + * @param tagInfo the tag info. + * @param values the short values. + * @throws ImagingException if the values are invalid. + */ public void add(final TagInfoByteOrShort tagInfo, final short... values) throws ImagingException { if (tagInfo.length > 0 && tagInfo.length != values.length) { throw new ImagingException("Tag expects " + tagInfo.length + " value(s), not " + values.length); @@ -149,6 +212,13 @@ public final class TiffOutputDirectory extends AbstractTiffOutputItem implements add(tiffOutputField); } + /** + * Adds a bytes field. + * + * @param tagInfo the tag info. + * @param values the byte values. + * @throws ImagingException if the values are invalid. + */ public void add(final TagInfoBytes tagInfo, final byte... values) throws ImagingException { if (tagInfo.length > 0 && tagInfo.length != values.length) { throw new ImagingException("Tag expects " + tagInfo.length + " value(s), not " + values.length); @@ -158,6 +228,13 @@ public final class TiffOutputDirectory extends AbstractTiffOutputItem implements add(tiffOutputField); } + /** + * Adds a double field. + * + * @param tagInfo the tag info. + * @param value the double value. + * @throws ImagingException if the value is invalid. + */ public void add(final TagInfoDouble tagInfo, final double value) throws ImagingException { if (tagInfo.length != 1) { throw new ImagingException("Tag expects " + tagInfo.length + " value(s), not 1"); @@ -167,6 +244,13 @@ public final class TiffOutputDirectory extends AbstractTiffOutputItem implements add(tiffOutputField); } + /** + * Adds a doubles field. + * + * @param tagInfo the tag info. + * @param values the double values. + * @throws ImagingException if the values are invalid. + */ public void add(final TagInfoDoubles tagInfo, final double... values) throws ImagingException { if (tagInfo.length > 0 && tagInfo.length != values.length) { throw new ImagingException("Tag expects " + tagInfo.length + " value(s), not " + values.length); @@ -176,6 +260,13 @@ public final class TiffOutputDirectory extends AbstractTiffOutputItem implements add(tiffOutputField); } + /** + * Adds a float field. + * + * @param tagInfo the tag info. + * @param value the float value. + * @throws ImagingException if the value is invalid. + */ public void add(final TagInfoFloat tagInfo, final float value) throws ImagingException { if (tagInfo.length != 1) { throw new ImagingException("Tag expects " + tagInfo.length + " value(s), not 1"); @@ -185,6 +276,13 @@ public final class TiffOutputDirectory extends AbstractTiffOutputItem implements add(tiffOutputField); } + /** + * Adds a floats field. + * + * @param tagInfo the tag info. + * @param values the float values. + * @throws ImagingException if the values are invalid. + */ public void add(final TagInfoFloats tagInfo, final float... values) throws ImagingException { if (tagInfo.length > 0 && tagInfo.length != values.length) { throw new ImagingException("Tag expects " + tagInfo.length + " value(s), not " + values.length); @@ -194,12 +292,26 @@ public final class TiffOutputDirectory extends AbstractTiffOutputItem implements add(tiffOutputField); } + /** + * Adds a GPS text field. + * + * @param tagInfo the tag info. + * @param value the string value. + * @throws ImagingException if the value is invalid. + */ public void add(final TagInfoGpsText tagInfo, final String value) throws ImagingException { final byte[] bytes = tagInfo.encodeValue(AbstractFieldType.UNDEFINED, value, byteOrder); final TiffOutputField tiffOutputField = new TiffOutputField(tagInfo.tag, tagInfo, tagInfo.dataTypes.get(0), bytes.length, bytes); add(tiffOutputField); } + /** + * Adds a long field. + * + * @param tagInfo the tag info. + * @param value the int value. + * @throws ImagingException if the value is invalid. + */ public void add(final TagInfoLong tagInfo, final int value) throws ImagingException { if (tagInfo.length != 1) { throw new ImagingException("Tag expects " + tagInfo.length + " value(s), not 1"); @@ -209,6 +321,13 @@ public final class TiffOutputDirectory extends AbstractTiffOutputItem implements add(tiffOutputField); } + /** + * Adds a longs field. + * + * @param tagInfo the tag info. + * @param values the int values. + * @throws ImagingException if the values are invalid. + */ public void add(final TagInfoLongs tagInfo, final int... values) throws ImagingException { if (tagInfo.length > 0 && tagInfo.length != values.length) { throw new ImagingException("Tag expects " + tagInfo.length + " value(s), not " + values.length); @@ -218,6 +337,13 @@ public final class TiffOutputDirectory extends AbstractTiffOutputItem implements add(tiffOutputField); } + /** + * Adds a rational field. + * + * @param tagInfo the tag info. + * @param value the rational value. + * @throws ImagingException if the value is invalid. + */ public void add(final TagInfoRational tagInfo, final RationalNumber value) throws ImagingException { if (tagInfo.length != 1) { throw new ImagingException("Tag expects " + tagInfo.length + " value(s), not 1"); @@ -227,6 +353,13 @@ public final class TiffOutputDirectory extends AbstractTiffOutputItem implements add(tiffOutputField); } + /** + * Adds a rationals field. + * + * @param tagInfo the tag info. + * @param values the rational values. + * @throws ImagingException if the values are invalid. + */ public void add(final TagInfoRationals tagInfo, final RationalNumber... values) throws ImagingException { if (tagInfo.length > 0 && tagInfo.length != values.length) { throw new ImagingException("Tag expects " + tagInfo.length + " value(s), not " + values.length); @@ -236,6 +369,13 @@ public final class TiffOutputDirectory extends AbstractTiffOutputItem implements add(tiffOutputField); } + /** + * Adds a signed byte field. + * + * @param tagInfo the tag info. + * @param value the byte value. + * @throws ImagingException if the value is invalid. + */ public void add(final TagInfoSByte tagInfo, final byte value) throws ImagingException { if (tagInfo.length != 1) { throw new ImagingException("Tag expects " + tagInfo.length + " value(s), not 1"); @@ -245,6 +385,13 @@ public final class TiffOutputDirectory extends AbstractTiffOutputItem implements add(tiffOutputField); } + /** + * Adds a signed bytes field. + * + * @param tagInfo the tag info. + * @param values the byte values. + * @throws ImagingException if the values are invalid. + */ public void add(final TagInfoSBytes tagInfo, final byte... values) throws ImagingException { if (tagInfo.length > 0 && tagInfo.length != values.length) { throw new ImagingException("Tag expects " + tagInfo.length + " value(s), not " + values.length); @@ -254,6 +401,13 @@ public final class TiffOutputDirectory extends AbstractTiffOutputItem implements add(tiffOutputField); } + /** + * Adds a short field. + * + * @param tagInfo the tag info. + * @param value the short value. + * @throws ImagingException if the value is invalid. + */ public void add(final TagInfoShort tagInfo, final short value) throws ImagingException { if (tagInfo.length != 1) { throw new ImagingException("Tag expects " + tagInfo.length + " value(s), not 1"); @@ -263,6 +417,13 @@ public final class TiffOutputDirectory extends AbstractTiffOutputItem implements add(tiffOutputField); } + /** + * Adds a short or long field with int values. + * + * @param tagInfo the tag info. + * @param values the int values. + * @throws ImagingException if the values are invalid. + */ public void add(final TagInfoShortOrLong tagInfo, final int... values) throws ImagingException { if (tagInfo.length > 0 && tagInfo.length != values.length) { throw new ImagingException("Tag expects " + tagInfo.length + " value(s), not " + values.length); @@ -272,6 +433,13 @@ public final class TiffOutputDirectory extends AbstractTiffOutputItem implements add(tiffOutputField); } + /** + * Adds a short or long field with short values. + * + * @param tagInfo the tag info. + * @param values the short values. + * @throws ImagingException if the values are invalid. + */ public void add(final TagInfoShortOrLong tagInfo, final short... values) throws ImagingException { if (tagInfo.length > 0 && tagInfo.length != values.length) { throw new ImagingException("Tag expects " + tagInfo.length + " value(s), not " + values.length); @@ -281,6 +449,13 @@ public final class TiffOutputDirectory extends AbstractTiffOutputItem implements add(tiffOutputField); } + /** + * Adds a short or long or rational field with int values. + * + * @param tagInfo the tag info. + * @param values the int values. + * @throws ImagingException if the values are invalid. + */ public void add(final TagInfoShortOrLongOrRational tagInfo, final int... values) throws ImagingException { if (tagInfo.length > 0 && tagInfo.length != values.length) { throw new ImagingException("Tag expects " + tagInfo.length + " value(s), not " + values.length); @@ -290,6 +465,13 @@ public final class TiffOutputDirectory extends AbstractTiffOutputItem implements add(tiffOutputField); } + /** + * Adds a short or long or rational field with rational values. + * + * @param tagInfo the tag info. + * @param values the rational values. + * @throws ImagingException if the values are invalid. + */ public void add(final TagInfoShortOrLongOrRational tagInfo, final RationalNumber... values) throws ImagingException { if (tagInfo.length > 0 && tagInfo.length != values.length) { throw new ImagingException("Tag expects " + tagInfo.length + " value(s), not " + values.length); @@ -299,6 +481,13 @@ public final class TiffOutputDirectory extends AbstractTiffOutputItem implements add(tiffOutputField); } + /** + * Adds a short or long or rational field with short values. + * + * @param tagInfo the tag info. + * @param values the short values. + * @throws ImagingException if the values are invalid. + */ public void add(final TagInfoShortOrLongOrRational tagInfo, final short... values) throws ImagingException { if (tagInfo.length > 0 && tagInfo.length != values.length) { throw new ImagingException("Tag expects " + tagInfo.length + " value(s), not " + values.length); @@ -308,6 +497,13 @@ public final class TiffOutputDirectory extends AbstractTiffOutputItem implements add(tiffOutputField); } + /** + * Adds a short or rational field with rational values. + * + * @param tagInfo the tag info. + * @param values the rational values. + * @throws ImagingException if the values are invalid. + */ public void add(final TagInfoShortOrRational tagInfo, final RationalNumber... values) throws ImagingException { if (tagInfo.length > 0 && tagInfo.length != values.length) { throw new ImagingException("Tag expects " + tagInfo.length + " value(s), not " + values.length); @@ -317,6 +513,13 @@ public final class TiffOutputDirectory extends AbstractTiffOutputItem implements add(tiffOutputField); } + /** + * Adds a short or rational field with short values. + * + * @param tagInfo the tag info. + * @param values the short values. + * @throws ImagingException if the values are invalid. + */ public void add(final TagInfoShortOrRational tagInfo, final short... values) throws ImagingException { if (tagInfo.length > 0 && tagInfo.length != values.length) { throw new ImagingException("Tag expects " + tagInfo.length + " value(s), not " + values.length); @@ -326,6 +529,13 @@ public final class TiffOutputDirectory extends AbstractTiffOutputItem implements add(tiffOutputField); } + /** + * Adds a shorts field. + * + * @param tagInfo the tag info. + * @param values the short values. + * @throws ImagingException if the values are invalid. + */ public void add(final TagInfoShorts tagInfo, final short... values) throws ImagingException { if (tagInfo.length > 0 && tagInfo.length != values.length) { throw new ImagingException("Tag expects " + tagInfo.length + " value(s), not " + values.length); @@ -335,6 +545,13 @@ public final class TiffOutputDirectory extends AbstractTiffOutputItem implements add(tiffOutputField); } + /** + * Adds a signed long field. + * + * @param tagInfo the tag info. + * @param value the int value. + * @throws ImagingException if the value is invalid. + */ public void add(final TagInfoSLong tagInfo, final int value) throws ImagingException { if (tagInfo.length != 1) { throw new ImagingException("Tag expects " + tagInfo.length + " value(s), not 1"); @@ -344,6 +561,13 @@ public final class TiffOutputDirectory extends AbstractTiffOutputItem implements add(tiffOutputField); } + /** + * Adds a signed longs field. + * + * @param tagInfo the tag info. + * @param values the int values. + * @throws ImagingException if the values are invalid. + */ public void add(final TagInfoSLongs tagInfo, final int... values) throws ImagingException { if (tagInfo.length > 0 && tagInfo.length != values.length) { throw new ImagingException("Tag expects " + tagInfo.length + " value(s), not " + values.length); @@ -353,6 +577,13 @@ public final class TiffOutputDirectory extends AbstractTiffOutputItem implements add(tiffOutputField); } + /** + * Adds a signed rational field. + * + * @param tagInfo the tag info. + * @param value the rational value. + * @throws ImagingException if the value is invalid. + */ public void add(final TagInfoSRational tagInfo, final RationalNumber value) throws ImagingException { if (tagInfo.length != 1) { throw new ImagingException("Tag expects " + tagInfo.length + " value(s), not 1"); @@ -362,6 +593,13 @@ public final class TiffOutputDirectory extends AbstractTiffOutputItem implements add(tiffOutputField); } + /** + * Adds a signed rationals field. + * + * @param tagInfo the tag info. + * @param values the rational values. + * @throws ImagingException if the values are invalid. + */ public void add(final TagInfoSRationals tagInfo, final RationalNumber... values) throws ImagingException { if (tagInfo.length > 0 && tagInfo.length != values.length) { throw new ImagingException("Tag expects " + tagInfo.length + " value(s), not " + values.length); @@ -371,6 +609,13 @@ public final class TiffOutputDirectory extends AbstractTiffOutputItem implements add(tiffOutputField); } + /** + * Adds a signed short field. + * + * @param tagInfo the tag info. + * @param value the short value. + * @throws ImagingException if the value is invalid. + */ public void add(final TagInfoSShort tagInfo, final short value) throws ImagingException { if (tagInfo.length != 1) { throw new ImagingException("Tag expects " + tagInfo.length + " value(s), not 1"); @@ -380,6 +625,13 @@ public final class TiffOutputDirectory extends AbstractTiffOutputItem implements add(tiffOutputField); } + /** + * Adds a signed shorts field. + * + * @param tagInfo the tag info. + * @param values the short values. + * @throws ImagingException if the values are invalid. + */ public void add(final TagInfoSShorts tagInfo, final short... values) throws ImagingException { if (tagInfo.length > 0 && tagInfo.length != values.length) { throw new ImagingException("Tag expects " + tagInfo.length + " value(s), not " + values.length); @@ -389,16 +641,33 @@ public final class TiffOutputDirectory extends AbstractTiffOutputItem implements add(tiffOutputField); } + /** + * Adds an XP string field. + * + * @param tagInfo the tag info. + * @param value the string value. + * @throws ImagingException if the value is invalid. + */ public void add(final TagInfoXpString tagInfo, final String value) throws ImagingException { final byte[] bytes = tagInfo.encodeValue(AbstractFieldType.BYTE, value, byteOrder); final TiffOutputField tiffOutputField = new TiffOutputField(tagInfo.tag, tagInfo, AbstractFieldType.BYTE, bytes.length, bytes); add(tiffOutputField); } + /** + * Adds a field to this directory. + * + * @param field the field to add. + */ public void add(final TiffOutputField field) { fields.add(field); } + /** + * Gets a description of this directory. + * + * @return the description. + */ public String description() { return TiffDirectory.description(getType()); } @@ -438,6 +707,11 @@ public final class TiffOutputDirectory extends AbstractTiffOutputItem implements return findField(tagInfo.tag); } + /** + * Gets all fields in this directory. + * + * @return a list of all fields. + */ public List<TiffOutputField> getFields() { return new ArrayList<>(fields); } @@ -453,6 +727,13 @@ public final class TiffOutputDirectory extends AbstractTiffOutputItem implements return ENTRY_LENGTH * fields.size() + DIRECTORY_HEADER_LENGTH + DIRECTORY_FOOTER_LENGTH; } + /** + * Gets all output items from this directory including fields and image data. + * + * @param outputSummary the output summary. + * @return the list of output items. + * @throws ImagingException if an error occurs. + */ protected List<AbstractTiffOutputItem> getOutputItems(final TiffOutputSummary outputSummary) throws ImagingException { // first validate directory fields. @@ -542,14 +823,29 @@ public final class TiffOutputDirectory extends AbstractTiffOutputItem implements return result; } + /** + * Gets the raw JPEG image data. + * + * @return the JPEG image data, or null if not present. + */ public JpegImageData getRawJpegImageData() { return jpegImageData; } + /** + * Gets the raw TIFF image data. + * + * @return the TIFF image data, or null if not present. + */ public AbstractTiffImageData getRawTiffImageData() { return abstractTiffImageData; } + /** + * Gets the directory type. + * + * @return the directory type. + */ public int getType() { return type; } @@ -559,6 +855,11 @@ public final class TiffOutputDirectory extends AbstractTiffOutputItem implements return fields.iterator(); } + /** + * Removes a field from this directory. + * + * @param tag the tag of the field to remove. + */ public void removeField(final int tag) { final List<TiffOutputField> matches = new ArrayList<>(); for (final TiffOutputField field : fields) { @@ -569,6 +870,11 @@ public final class TiffOutputDirectory extends AbstractTiffOutputItem implements fields.removeAll(matches); } + /** + * Removes a field from this directory. + * + * @param tagInfo the tag info of the field to remove. + */ public void removeField(final TagInfo tagInfo) { removeField(tagInfo.tag); } @@ -580,18 +886,36 @@ public final class TiffOutputDirectory extends AbstractTiffOutputItem implements } } + /** + * Sets the JPEG image data. + * + * @param rawJpegImageData the JPEG image data. + */ public void setJpegImageData(final JpegImageData rawJpegImageData) { this.jpegImageData = rawJpegImageData; } + /** + * Sets the next directory. + * + * @param nextDirectory the next directory. + */ public void setNextDirectory(final TiffOutputDirectory nextDirectory) { this.nextDirectory = nextDirectory; } + /** + * Sets the TIFF image data. + * + * @param rawTiffImageData the TIFF image data. + */ public void setTiffImageData(final AbstractTiffImageData rawTiffImageData) { this.abstractTiffImageData = rawTiffImageData; } + /** + * Sorts fields by tag number and sort hint. + */ public void sortFields() { final Comparator<TiffOutputField> comparator = (e1, e2) -> { if (e1.tag != e2.tag) { diff --git a/src/main/java/org/apache/commons/imaging/formats/tiff/write/TiffOutputField.java b/src/main/java/org/apache/commons/imaging/formats/tiff/write/TiffOutputField.java index 4a8ff4cd..72662a9e 100644 --- a/src/main/java/org/apache/commons/imaging/formats/tiff/write/TiffOutputField.java +++ b/src/main/java/org/apache/commons/imaging/formats/tiff/write/TiffOutputField.java @@ -27,22 +27,58 @@ import org.apache.commons.imaging.common.AbstractBinaryOutputStream; import org.apache.commons.imaging.formats.tiff.fieldtypes.AbstractFieldType; import org.apache.commons.imaging.formats.tiff.taginfos.TagInfo; +/** + * Represents a TIFF output field. + */ public class TiffOutputField { private static final String NEWLINE = System.lineSeparator(); + /** + * Creates an offset field. + * + * @param tagInfo the tag info. + * @param byteOrder the byte order. + * @return the offset field. + * @throws ImagingException if an error occurs. + */ protected static TiffOutputField createOffsetField(final TagInfo tagInfo, final ByteOrder byteOrder) throws ImagingException { return new TiffOutputField(tagInfo, AbstractFieldType.LONG, 1, AbstractFieldType.LONG.writeData(0, byteOrder)); } + /** + * The tag number. + */ public final int tag; + + /** + * The tag info. + */ public final TagInfo tagInfo; + + /** + * The field type. + */ public final AbstractFieldType abstractFieldType; + + /** + * The value count. + */ public final int count; + private byte[] bytes; private final AbstractTiffOutputItem.Value separateValueItem; private int sortHint = -1; + /** + * Constructs a new instance. + * + * @param tag the tag number. + * @param tagInfo the tag info. + * @param abstractFieldType the field type. + * @param count the value count. + * @param bytes the field data. + */ public TiffOutputField(final int tag, final TagInfo tagInfo, final AbstractFieldType abstractFieldType, final int count, final byte[] bytes) { this.tag = tag; this.tagInfo = tagInfo; @@ -58,6 +94,14 @@ public class TiffOutputField { } } + /** + * Constructs a new instance. + * + * @param tagInfo the tag info. + * @param abstractFieldType the field type. + * @param count the value count. + * @param bytes the field data. + */ public TiffOutputField(final TagInfo tagInfo, final AbstractFieldType abstractFieldType, final int count, final byte[] bytes) { this(tagInfo.tag, tagInfo, abstractFieldType, count, bytes); } @@ -71,14 +115,29 @@ public class TiffOutputField { return Arrays.copyOf(this.bytes, this.bytes.length); } + /** + * Gets the separate value item if this field is not a local value. + * + * @return the separate value item, or null. + */ protected AbstractTiffOutputItem getSeperateValue() { return separateValueItem; } + /** + * Gets the sort hint. + * + * @return the sort hint. + */ public int getSortHint() { return sortHint; } + /** + * Checks if this field's value fits in the tag entry. + * + * @return true if the value is local. + */ protected final boolean isLocalValue() { return bytes.length <= ENTRY_MAX_VALUE_LENGTH; } @@ -108,6 +167,11 @@ public class TiffOutputField { // + tagInfo.getDescription()); } + /** + * Sets the sort hint for this field. + * + * @param sortHint the sort hint. + */ public void setSortHint(final int sortHint) { this.sortHint = sortHint; } @@ -117,6 +181,12 @@ public class TiffOutputField { return toString(null); } + /** + * Gets a string representation with optional prefix. + * + * @param prefix the prefix, or null. + * @return the string representation. + */ public String toString(String prefix) { if (prefix == null) { prefix = ""; @@ -139,6 +209,13 @@ public class TiffOutputField { return result.toString(); } + /** + * Writes this field to the output stream. + * + * @param bos the output stream. + * @throws IOException if an I/O error occurs. + * @throws ImagingException if an imaging error occurs. + */ protected void writeField(final AbstractBinaryOutputStream bos) throws IOException, ImagingException { bos.write2Bytes(tag); bos.write2Bytes(abstractFieldType.getType()); diff --git a/src/main/java/org/apache/commons/imaging/formats/tiff/write/TiffOutputSet.java b/src/main/java/org/apache/commons/imaging/formats/tiff/write/TiffOutputSet.java index 0d30cf82..8eaf101d 100644 --- a/src/main/java/org/apache/commons/imaging/formats/tiff/write/TiffOutputSet.java +++ b/src/main/java/org/apache/commons/imaging/formats/tiff/write/TiffOutputSet.java @@ -30,20 +30,42 @@ import org.apache.commons.imaging.formats.tiff.constants.TiffDirectoryConstants; import org.apache.commons.imaging.formats.tiff.taginfos.TagInfo; import org.apache.commons.imaging.internal.Debug; +/** + * Represents a complete TIFF output set containing multiple directories. + */ public final class TiffOutputSet implements Iterable<TiffOutputDirectory> { private static final String NEWLINE = System.lineSeparator(); + + /** + * The byte order for this output set. + */ public final ByteOrder byteOrder; + private final List<TiffOutputDirectory> directories = new ArrayList<>(); + /** + * Constructs a new instance with default byte order. + */ public TiffOutputSet() { this(DEFAULT_TIFF_BYTE_ORDER); } + /** + * Constructs a new instance with the specified byte order. + * + * @param byteOrder the byte order. + */ public TiffOutputSet(final ByteOrder byteOrder) { this.byteOrder = byteOrder; } + /** + * Adds a directory to this output set. + * + * @param directory the directory to add. + * @throws ImagingException if a directory of that type already exists. + */ public void addDirectory(final TiffOutputDirectory directory) throws ImagingException { if (null != findDirectory(directory.getType())) { throw new ImagingException("Output set already contains a directory of that type."); @@ -51,18 +73,36 @@ public final class TiffOutputSet implements Iterable<TiffOutputDirectory> { directories.add(directory); } + /** + * Adds an EXIF directory to this output set. + * + * @return the new EXIF directory. + * @throws ImagingException if an EXIF directory already exists. + */ public TiffOutputDirectory addExifDirectory() throws ImagingException { final TiffOutputDirectory result = new TiffOutputDirectory(TiffDirectoryConstants.DIRECTORY_TYPE_EXIF, byteOrder); addDirectory(result); return result; } + /** + * Adds a GPS directory to this output set. + * + * @return the new GPS directory. + * @throws ImagingException if a GPS directory already exists. + */ public TiffOutputDirectory addGpsDirectory() throws ImagingException { final TiffOutputDirectory result = new TiffOutputDirectory(TiffDirectoryConstants.DIRECTORY_TYPE_GPS, byteOrder); addDirectory(result); return result; } + /** + * Adds an Interoperability directory to this output set. + * + * @return the new Interoperability directory. + * @throws ImagingException if an Interoperability directory already exists. + */ public TiffOutputDirectory addInteroperabilityDirectory() throws ImagingException { getOrCreateExifDirectory(); @@ -71,16 +111,31 @@ public final class TiffOutputSet implements Iterable<TiffOutputDirectory> { return result; } + /** + * Adds a Root directory to this output set. + * + * @return the new Root directory. + * @throws ImagingException if a Root directory already exists. + */ public TiffOutputDirectory addRootDirectory() throws ImagingException { final TiffOutputDirectory result = new TiffOutputDirectory(TiffDirectoryConstants.DIRECTORY_TYPE_ROOT, byteOrder); addDirectory(result); return result; } + /** + * Dumps the content of this TIFF output set to the debug output. + */ public void dump() { Debug.debug(this.toString()); } + /** + * Finds a directory of the specified type in this output set. + * + * @param directoryType the type of the directory to find. + * @return the found directory, or null if no such directory exists. + */ public TiffOutputDirectory findDirectory(final int directoryType) { for (final TiffOutputDirectory directory : directories) { if (directory.getType() == directoryType) { @@ -90,6 +145,12 @@ public final class TiffOutputSet implements Iterable<TiffOutputDirectory> { return null; } + /** + * Finds a field with the specified tag in this output set. + * + * @param tag the tag of the field to find. + * @return the found field, or null if no such field exists. + */ public TiffOutputField findField(final int tag) { for (final TiffOutputDirectory directory : directories) { final TiffOutputField field = directory.findField(tag); @@ -100,26 +161,58 @@ public final class TiffOutputSet implements Iterable<TiffOutputDirectory> { return null; } + /** + * Finds a field with the specified tag info in this output set. + * + * @param tagInfo the tag info of the field to find. + * @return the found field, or null if no such field exists. + */ public TiffOutputField findField(final TagInfo tagInfo) { return findField(tagInfo.tag); } + /** + * Gets a list of all directories in this output set. + * + * @return a list of all directories. + */ public List<TiffOutputDirectory> getDirectories() { return new ArrayList<>(directories); } + /** + * Gets the EXIF directory in this output set. + * + * @return the EXIF directory, or null if no EXIF directory exists. + */ public TiffOutputDirectory getExifDirectory() { return findDirectory(TiffDirectoryConstants.DIRECTORY_TYPE_EXIF); } + /** + * Gets the GPS directory in this output set. + * + * @return the GPS directory, or null if no GPS directory exists. + */ public TiffOutputDirectory getGpsDirectory() { return findDirectory(TiffDirectoryConstants.DIRECTORY_TYPE_GPS); } + /** + * Gets the Interoperability directory in this output set. + * + * @return the Interoperability directory, or null if no Interoperability directory exists. + */ public TiffOutputDirectory getInteroperabilityDirectory() { return findDirectory(TiffDirectoryConstants.DIRECTORY_TYPE_INTEROPERABILITY); } + /** + * Gets the EXIF directory in this output set, creating it if it doesn't exist. + * + * @return the EXIF directory. + * @throws ImagingException if it fails to create the directory. + */ public TiffOutputDirectory getOrCreateExifDirectory() throws ImagingException { // EXIF directory requires root directory. getOrCreateRootDirectory(); @@ -131,6 +224,12 @@ public final class TiffOutputSet implements Iterable<TiffOutputDirectory> { return addExifDirectory(); } + /** + * Gets the GPS directory in this output set, creating it if it doesn't exist. + * + * @return the GPS directory. + * @throws ImagingException if it fails to create the directory. + */ public TiffOutputDirectory getOrCreateGpsDirectory() throws ImagingException { // GPS directory requires EXIF directory getOrCreateExifDirectory(); @@ -142,6 +241,12 @@ public final class TiffOutputSet implements Iterable<TiffOutputDirectory> { return addGpsDirectory(); } + /** + * Gets the Root directory in this output set, creating it if it doesn't exist. + * + * @return the Root directory. + * @throws ImagingException if it fails to create the directory. + */ public TiffOutputDirectory getOrCreateRootDirectory() throws ImagingException { final TiffOutputDirectory result = findDirectory(TiffDirectoryConstants.DIRECTORY_TYPE_ROOT); if (null != result) { @@ -150,6 +255,13 @@ public final class TiffOutputSet implements Iterable<TiffOutputDirectory> { return addRootDirectory(); } + /** + * Gets all output items from all directories in this output set. + * + * @param outputSummary the output summary. + * @return the list of all output items. + * @throws ImagingException if an error occurs. + */ protected List<AbstractTiffOutputItem> getOutputItems(final TiffOutputSummary outputSummary) throws ImagingException { final List<AbstractTiffOutputItem> result = new ArrayList<>(); @@ -160,10 +272,20 @@ public final class TiffOutputSet implements Iterable<TiffOutputDirectory> { return result; } + /** + * Gets the Root directory in this output set. + * + * @return the Root directory. + */ public TiffOutputDirectory getRootDirectory() { return findDirectory(TiffDirectoryConstants.DIRECTORY_TYPE_ROOT); } + /** + * Checks if this output set is empty (i.e., contains no directories). + * + * @return true if this output set is empty, false otherwise. + */ public boolean isEmpty() { return directories.isEmpty(); } @@ -173,12 +295,22 @@ public final class TiffOutputSet implements Iterable<TiffOutputDirectory> { return directories.iterator(); } + /** + * Removes a field with the specified tag from all directories in this output set. + * + * @param tag the tag of the field to remove. + */ public void removeField(final int tag) { for (final TiffOutputDirectory directory : directories) { directory.removeField(tag); } } + /** + * Removes a field with the specified tag info from all directories in this output set. + * + * @param tagInfo the tag info of the field to remove. + */ public void removeField(final TagInfo tagInfo) { removeField(tagInfo.tag); } @@ -244,6 +376,12 @@ public final class TiffOutputSet implements Iterable<TiffOutputDirectory> { return toString(null); } + /** + * Gets a string representation with optional prefix. + * + * @param prefix the prefix, or null. + * @return the string representation. + */ public String toString(String prefix) { if (prefix == null) { prefix = "";
