Changeset 6127 in josm for trunk/src/com/drew/imaging

Timestamp:

2013-08-09T18:05:11+02:00 (12 years ago)

Author:

bastiK

Message:

applied #8895 - Upgrade metadata-extractor to v. 2.6.4 (patch by ebourg)

Location:

trunk/src/com/drew/imaging

Files:

• ImageProcessingException.java (added)
• PhotographicConversions.java (modified) (5 diffs)
• jpeg/JpegMetadataReader.java (modified) (3 diffs)
• jpeg/JpegProcessingException.java (modified) (1 diff)
• jpeg/JpegSegmentData.java (modified) (3 diffs)
• jpeg/JpegSegmentReader.java (modified) (13 diffs)

trunk/src/com/drew/imaging/PhotographicConversions.java

@@ -1 +1 @@
 /*
- * This is public domain software - that is, you can do whatever you want
- * with it, and include it software that is licensed under the GNU or the
- * BSD license, or whatever other licence you choose, including proprietary
- * closed source licenses.  I do ask that you leave this header in tact.
+ * Copyright 2002-2012 Drew Noakes
  *
- * If you make modifications to this code that you think would benefit the
- * wider community, please send me a copy and I'll post it on my site.
+ *    Licensed under the Apache License, Version 2.0 (the "License");
+ *    you may not use this file except in compliance with the License.
+ *    You may obtain a copy of the License at
  *
- * If you make use of this code, I'd appreciate hearing about it.
- *   drew@drewnoakes.com
- * Latest version of this software kept at
- *   http://drewnoakes.com/
+ *        http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *    Unless required by applicable law or agreed to in writing, software
+ *    distributed under the License is distributed on an "AS IS" BASIS,
+ *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *    See the License for the specific language governing permissions and
+ *    limitations under the License.
+ *
+ * More information about this project is available at:
+ *
+ *    http://drewnoakes.com/code/exif/
+ *    http://code.google.com/p/metadata-extractor/
  */
 package com.drew.imaging;
@@ -17 +23 @@
 /**
  * Contains helper methods that perform photographic conversions.
+ *
+ * @author Drew Noakes http://drewnoakes.com
  */
-public class PhotographicConversions
+public final class PhotographicConversions
 {
     public final static double ROOT_TWO = Math.sqrt(2);
 
-    private PhotographicConversions()
-    {}
+    private PhotographicConversions() throws Exception
+    {
+        throw new Exception("Not intended for instantiation.");
+    }
 
     /**
      * Converts an aperture value to its corresponding F-stop number.
+     *
      * @param aperture the aperture value to convert
      * @return the F-stop number of the specified aperture
@@ -32 +43 @@
     public static double apertureToFStop(double aperture)
     {
-        double fStop = Math.pow(ROOT_TWO, aperture);
-        return fStop;
+        return Math.pow(ROOT_TWO, aperture);
 
-        // Puzzle?!
-        // jhead uses a different calculation as far as i can tell...  this confuses me...
+        // NOTE jhead uses a different calculation as far as i can tell...  this confuses me...
         // fStop = (float)Math.exp(aperture * Math.log(2) * 0.5));
     }
@@ -42 +51 @@
     /**
      * Converts a shutter speed to an exposure time.
+     *
      * @param shutterSpeed the shutter speed to convert
      * @return the exposure time of the specified shutter speed
@@ -47 +57 @@
     public static double shutterSpeedToExposureTime(double shutterSpeed)
     {
-        return (float)(1 / Math.exp(shutterSpeed * Math.log(2)));
+        return (float) (1 / Math.exp(shutterSpeed * Math.log(2)));
     }
 }

trunk/src/com/drew/imaging/jpeg/JpegMetadataReader.java

@@ -1 +1 @@
 /*
- * This is public domain software - that is, you can do whatever you want
- * with it, and include it software that is licensed under the GNU or the
- * BSD license, or whatever other licence you choose, including proprietary
- * closed source licenses.  I do ask that you leave this header in tact.
+ * Copyright 2002-2012 Drew Noakes
  *
- * If you make modifications to this code that you think would benefit the
- * wider community, please send me a copy and I'll post it on my site.
+ *    Licensed under the Apache License, Version 2.0 (the "License");
+ *    you may not use this file except in compliance with the License.
+ *    You may obtain a copy of the License at
  *
- * If you make use of this code, I'd appreciate hearing about it.
- *   drew@drewnoakes.com
- * Latest version of this software kept at
- *   http://drewnoakes.com/
+ *        http://www.apache.org/licenses/LICENSE-2.0
  *
- * Created by dnoakes on 12-Nov-2002 18:51:36 using IntelliJ IDEA.
+ *    Unless required by applicable law or agreed to in writing, software
+ *    distributed under the License is distributed on an "AS IS" BASIS,
+ *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *    See the License for the specific language governing permissions and
+ *    limitations under the License.
+ *
+ * More information about this project is available at:
+ *
+ *    http://drewnoakes.com/code/exif/
+ *    http://code.google.com/p/metadata-extractor/
  */
 package com.drew.imaging.jpeg;
 
-import com.drew.metadata.Directory;
+import com.drew.lang.ByteArrayReader;
+import com.drew.lang.annotations.NotNull;
 import com.drew.metadata.Metadata;
-import com.drew.metadata.MetadataException;
-import com.drew.metadata.Tag;
-import com.drew.metadata.exif.ExifDirectory;
 import com.drew.metadata.exif.ExifReader;
 import com.drew.metadata.iptc.IptcReader;
 import com.drew.metadata.jpeg.JpegCommentReader;
+import com.drew.metadata.jpeg.JpegDirectory;
 import com.drew.metadata.jpeg.JpegReader;
 
@@ -30 +33 @@
 import java.io.IOException;
 import java.io.InputStream;
-import java.util.Iterator;
 
 /**
+ * Obtains all available metadata from Jpeg formatted files.
  *
+ * @author Drew Noakes http://drewnoakes.com
  */
 public class JpegMetadataReader
 {
+    // TODO investigate supporting javax.imageio
 //    public static Metadata readMetadata(IIOMetadata metadata) throws JpegProcessingException {}
 //    public static Metadata readMetadata(ImageInputStream in) throws JpegProcessingException{}
@@ -42 +47 @@
 //    public static Metadata readMetadata(ImageReader reader) throws JpegProcessingException{}
 
-    public static Metadata readMetadata(InputStream in) throws JpegProcessingException
+    @NotNull
+    public static Metadata readMetadata(@NotNull InputStream inputStream) throws JpegProcessingException
     {
-        JpegSegmentReader segmentReader = new JpegSegmentReader(in);
-        return extractMetadataFromJpegSegmentReader(segmentReader);
+        return readMetadata(inputStream, true);
     }
 
-    public static Metadata readMetadata(File file) throws JpegProcessingException
+    @NotNull
+    public static Metadata readMetadata(@NotNull InputStream inputStream, final boolean waitForBytes) throws JpegProcessingException
+    {
+        JpegSegmentReader segmentReader = new JpegSegmentReader(inputStream, waitForBytes);
+        return extractMetadataFromJpegSegmentReader(segmentReader.getSegmentData());
+    }
+
+    @NotNull
+    public static Metadata readMetadata(@NotNull File file) throws JpegProcessingException, IOException
     {
         JpegSegmentReader segmentReader = new JpegSegmentReader(file);
-        return extractMetadataFromJpegSegmentReader(segmentReader);
+        return extractMetadataFromJpegSegmentReader(segmentReader.getSegmentData());
     }
 
-    public static Metadata extractMetadataFromJpegSegmentReader(JpegSegmentReader segmentReader)
+    @NotNull
+    public static Metadata extractMetadataFromJpegSegmentReader(@NotNull JpegSegmentData segmentReader)
     {
         final Metadata metadata = new Metadata();
-        try {
-            byte[] exifSegment = segmentReader.readSegment(JpegSegmentReader.SEGMENT_APP1);
-            new ExifReader(exifSegment).extract(metadata);
-        } catch (JpegProcessingException e) {
-            // in the interests of catching as much data as possible, continue
-            // TODO lodge error message within exif directory?
+
+        // Loop through looking for all SOFn segments.  When we find one, we know what type of compression
+        // was used for the JPEG, and we can process the JPEG metadata in the segment too.
+        for (byte i = 0; i < 16; i++) {
+            // There are no SOF4 or SOF12 segments, so don't bother
+            if (i == 4 || i == 12)
+                continue;
+            // Should never have more than one SOFn for a given 'n'.
+            byte[] jpegSegment = segmentReader.getSegment((byte)(JpegSegmentReader.SEGMENT_SOF0 + i));
+            if (jpegSegment == null)
+                continue;
+            JpegDirectory directory = metadata.getOrCreateDirectory(JpegDirectory.class);
+            directory.setInt(JpegDirectory.TAG_JPEG_COMPRESSION_TYPE, i);
+            new JpegReader().extract(new ByteArrayReader(jpegSegment), metadata);
+            break;
         }
 
-        try {
-            byte[] iptcSegment = segmentReader.readSegment(JpegSegmentReader.SEGMENT_APPD);
-            new IptcReader(iptcSegment).extract(metadata);
-        } catch (JpegProcessingException e) {
-            // TODO lodge error message within iptc directory?
+        // There should never be more than one COM segment.
+        byte[] comSegment = segmentReader.getSegment(JpegSegmentReader.SEGMENT_COM);
+        if (comSegment != null)
+            new JpegCommentReader().extract(new ByteArrayReader(comSegment), metadata);
+
+        // Loop through all APP1 segments, checking the leading bytes to identify the format of each.
+        for (byte[] app1Segment : segmentReader.getSegments(JpegSegmentReader.SEGMENT_APP1)) {
+            if (app1Segment.length > 3 && "EXIF".equalsIgnoreCase(new String(app1Segment, 0, 4)))
+                new ExifReader().extract(new ByteArrayReader(app1Segment), metadata);
+
+            //if (app1Segment.length > 27 && "http://ns.adobe.com/xap/1.0/".equalsIgnoreCase(new String(app1Segment, 0, 28)))
+            //    new XmpReader().extract(new ByteArrayReader(app1Segment), metadata);
         }
 
-                try {
-                        byte[] jpegSegment = segmentReader.readSegment(JpegSegmentReader.SEGMENT_SOF0);
-                        new JpegReader(jpegSegment).extract(metadata);
-                } catch (JpegProcessingException e) {
-                        // TODO lodge error message within jpeg directory?
-                }
-
-                try {
-                        byte[] jpegCommentSegment = segmentReader.readSegment(JpegSegmentReader.SEGMENT_COM);
-                        new JpegCommentReader(jpegCommentSegment).extract(metadata);
-                } catch (JpegProcessingException e) {
-                        // TODO lodge error message within jpegcomment directory?
-                }
+        // Loop through all APPD segments, checking the leading bytes to identify the format of each.
+        for (byte[] appdSegment : segmentReader.getSegments(JpegSegmentReader.SEGMENT_APPD)) {
+            if (appdSegment.length > 12 && "Photoshop 3.0".compareTo(new String(appdSegment, 0, 13))==0) {
+                //new PhotoshopReader().extract(new ByteArrayReader(appdSegment), metadata);
+            } else {
+                // TODO might be able to check for a leading 0x1c02 for IPTC data...
+                new IptcReader().extract(new ByteArrayReader(appdSegment), metadata);
+            }
+        }
 
         return metadata;
     }
 
-    private JpegMetadataReader()
+    private JpegMetadataReader() throws Exception
     {
-    }
-
-    public static void main(String[] args) throws MetadataException, IOException
-    {
-        Metadata metadata = null;
-        try {
-            metadata = JpegMetadataReader.readMetadata(new File(args[0]));
-        } catch (Exception e) {
-            e.printStackTrace(System.err);
-            System.exit(1);
-        }
-
-        // iterate over the exif data and print to System.out
-        Iterator directories = metadata.getDirectoryIterator();
-        while (directories.hasNext()) {
-            Directory directory = (Directory)directories.next();
-            Iterator tags = directory.getTagIterator();
-            while (tags.hasNext()) {
-                Tag tag = (Tag)tags.next();
-                try {
-                    System.out.println("[" + directory.getName() + "] " + tag.getTagName() + " = " + tag.getDescription());
-                } catch (MetadataException e) {
-                    System.err.println(e.getMessage());
-                    System.err.println(tag.getDirectoryName() + " " + tag.getTagName() + " (error)");
-                }
-            }
-            if (directory.hasErrors()) {
-                Iterator errors = directory.getErrors();
-                while (errors.hasNext()) {
-                    System.out.println("ERROR: " + errors.next());
-                }
-            }
-        }
-
-        if (args.length>1 && args[1].trim().equals("/thumb"))
-        {
-            ExifDirectory directory = (ExifDirectory)metadata.getDirectory(ExifDirectory.class);
-            if (directory.containsThumbnail())
-            {
-                System.out.println("Writing thumbnail...");
-                directory.writeThumbnail(args[0].trim() + ".thumb.jpg");
-            }
-            else
-            {
-                System.out.println("No thumbnail data exists in this image");
-            }
-        }
+        throw new Exception("Not intended for instantiation");
     }
 }
+

trunk/src/com/drew/imaging/jpeg/JpegProcessingException.java

@@ -1 +1 @@
 /*
- * JpegProcessingException.java
+ * Copyright 2002-2012 Drew Noakes
  *
- * This class is public domain software - that is, you can do whatever you want
- * with it, and include it software that is licensed under the GNU or the
- * BSD license, or whatever other licence you choose, including proprietary
- * closed source licenses.  I do ask that you leave this header in tact.
+ *    Licensed under the Apache License, Version 2.0 (the "License");
+ *    you may not use this file except in compliance with the License.
+ *    You may obtain a copy of the License at
  *
- * If you make modifications to this code that you think would benefit the
- * wider community, please send me a copy and I'll post it on my site.
+ *        http://www.apache.org/licenses/LICENSE-2.0
  *
- * If you make use of this code, I'd appreciate hearing about it.
- *   drew@drewnoakes.com
- * Latest version of this software kept at
- *   http://drewnoakes.com/
+ *    Unless required by applicable law or agreed to in writing, software
+ *    distributed under the License is distributed on an "AS IS" BASIS,
+ *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *    See the License for the specific language governing permissions and
+ *    limitations under the License.
  *
- * Created by dnoakes on 04-Nov-2002 19:31:29 using IntelliJ IDEA.
+ * More information about this project is available at:
+ *
+ *    http://drewnoakes.com/code/exif/
+ *    http://code.google.com/p/metadata-extractor/
  */
 package com.drew.imaging.jpeg;
 
-import com.drew.lang.CompoundException;
+import com.drew.imaging.ImageProcessingException;
+import com.drew.lang.annotations.Nullable;
 
 /**
- * An exception class thrown upon unexpected and fatal conditions while processing
- * a Jpeg file.
- * @author  Drew Noakes http://drewnoakes.com
+ * An exception class thrown upon unexpected and fatal conditions while processing a Jpeg file.
+ *
+ * @author Drew Noakes http://drewnoakes.com
  */
-public class JpegProcessingException extends CompoundException
+public class JpegProcessingException extends ImageProcessingException
 {
-    public JpegProcessingException(String message)
+    private static final long serialVersionUID = -7870179776125450158L;
+
+    public JpegProcessingException(@Nullable String message)
     {
         super(message);
     }
 
-    public JpegProcessingException(String message, Throwable cause)
+    public JpegProcessingException(@Nullable String message, @Nullable Throwable cause)
     {
         super(message, cause);
     }
 
-    public JpegProcessingException(Throwable cause)
+    public JpegProcessingException(@Nullable Throwable cause)
     {
         super(cause);

trunk/src/com/drew/imaging/jpeg/JpegSegmentData.java

@@ -1 +1 @@
 /*
- * This is public domain software - that is, you can do whatever you want
- * with it, and include it software that is licensed under the GNU or the
- * BSD license, or whatever other licence you choose, including proprietary
- * closed source licenses.  I do ask that you leave this header in tact.
- *
- * If you make modifications to this code that you think would benefit the
- * wider community, please send me a copy and I'll post it on my site.
- *
- * If you make use of this code, I'd appreciate hearing about it.
- *   drew@drewnoakes.com
- * Latest version of this software kept at
- *   http://drewnoakes.com/
+ * Copyright 2002-2012 Drew Noakes
+ *
+ *    Licensed under the Apache License, Version 2.0 (the "License");
+ *    you may not use this file except in compliance with the License.
+ *    You may obtain a copy of the License at
+ *
+ *        http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *    Unless required by applicable law or agreed to in writing, software
+ *    distributed under the License is distributed on an "AS IS" BASIS,
+ *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *    See the License for the specific language governing permissions and
+ *    limitations under the License.
+ *
+ * More information about this project is available at:
+ *
+ *    http://drewnoakes.com/code/exif/
+ *    http://code.google.com/p/metadata-extractor/
  */
 package com.drew.imaging.jpeg;
+
+import com.drew.lang.annotations.NotNull;
+import com.drew.lang.annotations.Nullable;
 
 import java.io.*;
@@ -22 +31 @@
 /**
  * Holds a collection of Jpeg data segments.  This need not necessarily be all segments
- * within the Jpeg.  For example, it may be convenient to port about only the non-image
+ * within the Jpeg.  For example, it may be convenient to store only the non-image
  * segments when analysing (or serializing) metadata.
+ * <p/>
+ * Segments are keyed via their segment marker (a byte).  Where multiple segments use the
+ * same segment marker, they will all be stored and available.
+ *
+ * @author Drew Noakes http://drewnoakes.com
  */
 public class JpegSegmentData implements Serializable
 {
-    static final long serialVersionUID = 7110175216435025451L;
+    private static final long serialVersionUID = 7110175216435025451L;
     
     /** A map of byte[], keyed by the segment marker */
-    private final HashMap _segmentDataMap;
-
-    public JpegSegmentData()
-    {
-        _segmentDataMap = new HashMap(10);
-    }
-
-    public void addSegment(byte segmentMarker, byte[] segmentBytes)
-    {
-        List segmentList = getOrCreateSegmentList(segmentMarker);
+    @NotNull
+    private final HashMap<Byte, List<byte[]>> _segmentDataMap = new HashMap<Byte, List<byte[]>>(10);
+
+    /**
+     * Adds segment bytes to the collection.
+     * @param segmentMarker
+     * @param segmentBytes
+     */
+    @SuppressWarnings({ "MismatchedQueryAndUpdateOfCollection" })
+    public void addSegment(byte segmentMarker, @NotNull byte[] segmentBytes)
+    {
+        final List<byte[]> segmentList = getOrCreateSegmentList(segmentMarker);
         segmentList.add(segmentBytes);
     }
 
+    /**
+     * Gets the first Jpeg segment data for the specified marker.
+     * @param segmentMarker the byte identifier for the desired segment
+     * @return a byte[] containing segment data or null if no data exists for that segment
+     */
+    @Nullable
     public byte[] getSegment(byte segmentMarker)
     {
@@ -48 +70 @@
     }
 
+    /**
+     * Gets segment data for a specific occurrence and marker.  Use this method when more than one occurrence
+     * of segment data for a given marker exists.
+     * @param segmentMarker identifies the required segment
+     * @param occurrence the zero-based index of the occurrence
+     * @return the segment data as a byte[], or null if no segment exists for the marker & occurrence
+     */
+    @Nullable
     public byte[] getSegment(byte segmentMarker, int occurrence)
     {
-        final List segmentList = getSegmentList(segmentMarker);
+        final List<byte[]> segmentList = getSegmentList(segmentMarker);
 
         if (segmentList==null || segmentList.size()<=occurrence)
             return null;
         else
-            return (byte[]) segmentList.get(occurrence);
-    }
-
+            return segmentList.get(occurrence);
+    }
+
+    /**
+     * Returns all instances of a given Jpeg segment.  If no instances exist, an empty sequence is returned.
+     *
+     * @param segmentMarker a number which identifies the type of Jpeg segment being queried
+     * @return zero or more byte arrays, each holding the data of a Jpeg segment
+     */
+    @NotNull
+    public Iterable<byte[]> getSegments(byte segmentMarker)
+    {
+        final List<byte[]> segmentList = getSegmentList(segmentMarker);
+        return segmentList==null ? new ArrayList<byte[]>() : segmentList;
+    }
+
+    @Nullable
+    public List<byte[]> getSegmentList(byte segmentMarker)
+    {
+        return _segmentDataMap.get(Byte.valueOf(segmentMarker));
+    }
+
+    @NotNull
+    private List<byte[]> getOrCreateSegmentList(byte segmentMarker)
+    {
+        List<byte[]> segmentList;
+        if (_segmentDataMap.containsKey(segmentMarker)) {
+            segmentList = _segmentDataMap.get(segmentMarker);
+        } else {
+            segmentList = new ArrayList<byte[]>();
+            _segmentDataMap.put(segmentMarker, segmentList);
+        }
+        return segmentList;
+    }
+
+    /**
+     * Returns the count of segment data byte arrays stored for a given segment marker.
+     * @param segmentMarker identifies the required segment
+     * @return the segment count (zero if no segments exist).
+     */
     public int getSegmentCount(byte segmentMarker)
     {
-        final List segmentList = getSegmentList(segmentMarker);
-        if (segmentList==null)
-            return 0;
-        else
-            return segmentList.size();
-    }
-
+        final List<byte[]> segmentList = getSegmentList(segmentMarker);
+        return segmentList == null ? 0 : segmentList.size();
+    }
+
+    /**
+     * Removes a specified instance of a segment's data from the collection.  Use this method when more than one
+     * occurrence of segment data for a given marker exists.
+     * @param segmentMarker identifies the required segment
+     * @param occurrence the zero-based index of the segment occurrence to remove.
+     */
+    @SuppressWarnings({ "MismatchedQueryAndUpdateOfCollection" })
     public void removeSegmentOccurrence(byte segmentMarker, int occurrence)
     {
-        final List segmentList = (List)_segmentDataMap.get(new Byte(segmentMarker));
+        final List<byte[]> segmentList = _segmentDataMap.get(Byte.valueOf(segmentMarker));
         segmentList.remove(occurrence);
     }
 
+    /**
+     * Removes all segments from the collection having the specified marker.
+     * @param segmentMarker identifies the required segment
+     */
     public void removeSegment(byte segmentMarker)
     {
-        _segmentDataMap.remove(new Byte(segmentMarker));
-    }
-
-    private List getSegmentList(byte segmentMarker)
-    {
-        return (List)_segmentDataMap.get(new Byte(segmentMarker));
-    }
-
-    private List getOrCreateSegmentList(byte segmentMarker)
-    {
-        List segmentList;
-        Byte key = new Byte(segmentMarker);
-        if (_segmentDataMap.containsKey(key)) {
-            segmentList = (List)_segmentDataMap.get(key);
-        } else {
-            segmentList = new ArrayList();
-            _segmentDataMap.put(key, segmentList);
-        }
-        return segmentList;
-    }
-
+        _segmentDataMap.remove(Byte.valueOf(segmentMarker));
+    }
+
+    /**
+     * Determines whether data is present for a given segment marker.
+     * @param segmentMarker identifies the required segment
+     * @return true if data exists, otherwise false
+     */
     public boolean containsSegment(byte segmentMarker)
     {
-        return _segmentDataMap.containsKey(new Byte(segmentMarker));
-    }
-
-    public static void ToFile(File file, JpegSegmentData segmentData) throws IOException
-    {
-        ObjectOutputStream outputStream = null;
+        return _segmentDataMap.containsKey(Byte.valueOf(segmentMarker));
+    }
+
+    /**
+     * Serialises the contents of a JpegSegmentData to a file.
+     * @param file to file to write from
+     * @param segmentData the data to write
+     * @throws IOException if problems occur while writing
+     */
+    public static void toFile(@NotNull File file, @NotNull JpegSegmentData segmentData) throws IOException
+    {
+        FileOutputStream fileOutputStream = null;
         try
         {
-            outputStream = new ObjectOutputStream(new FileOutputStream(file));
-            outputStream.writeObject(segmentData);
+            fileOutputStream = new FileOutputStream(file);
+            new ObjectOutputStream(fileOutputStream).writeObject(segmentData);
         }
         finally
         {
-            if (outputStream!=null)
-                outputStream.close();
-        }
-    }
-
-    public static JpegSegmentData FromFile(File file) throws IOException, ClassNotFoundException
+            if (fileOutputStream!=null)
+                fileOutputStream.close();
+        }
+    }
+
+    /**
+     * Deserialises the contents of a JpegSegmentData from a file.
+     * @param file the file to read from
+     * @return the JpegSegmentData as read
+     * @throws IOException if problems occur while reading
+     * @throws ClassNotFoundException if problems occur while deserialising
+     */
+    @NotNull
+    public static JpegSegmentData fromFile(@NotNull File file) throws IOException, ClassNotFoundException
     {
         ObjectInputStream inputStream = null;

trunk/src/com/drew/imaging/jpeg/JpegSegmentReader.java

@@ -1 +1 @@
 /*
- * JpegSegmentReader.java
- *
- * This class written by Drew Noakes, in accordance with the Jpeg specification.
- *
- * This is public domain software - that is, you can do whatever you want
- * with it, and include it software that is licensed under the GNU or the
- * BSD license, or whatever other licence you choose, including proprietary
- * closed source licenses.  I do ask that you leave this header in tact.
- *
- * If you make modifications to this code that you think would benefit the
- * wider community, please send me a copy and I'll post it on my site.
- *
- * If you make use of this code, I'd appreciate hearing about it.
- *   drew@drewnoakes.com
- * Latest version of this software kept at
- *   http://drewnoakes.com/
- *
- * Created by dnoakes on 04-Nov-2002 00:54:00 using IntelliJ IDEA
+ * Copyright 2002-2012 Drew Noakes
+ *
+ *    Licensed under the Apache License, Version 2.0 (the "License");
+ *    you may not use this file except in compliance with the License.
+ *    You may obtain a copy of the License at
+ *
+ *        http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *    Unless required by applicable law or agreed to in writing, software
+ *    distributed under the License is distributed on an "AS IS" BASIS,
+ *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *    See the License for the specific language governing permissions and
+ *    limitations under the License.
+ *
+ * More information about this project is available at:
+ *
+ *    http://drewnoakes.com/code/exif/
+ *    http://code.google.com/p/metadata-extractor/
  */
 package com.drew.imaging.jpeg;
 
+import com.drew.lang.annotations.NotNull;
+import com.drew.lang.annotations.Nullable;
+
 import java.io.*;
 
 /**
  * Performs read functions of Jpeg files, returning specific file segments.
- * TODO add a findAvailableSegments() method
- * TODO add more segment identifiers
- * TODO add a getSegmentDescription() method, returning for example 'App1 application data segment, commonly containing Exif data'
  * @author  Drew Noakes http://drewnoakes.com
  */
 public class JpegSegmentReader
 {
-    // Jpeg data can be sourced from either a file, byte[] or InputStream
-
-    /** Jpeg file */
-    private final File _file;
-    /** Jpeg data as byte array */
-    private final byte[] _data;
-    /** Jpeg data as an InputStream */
-    private final InputStream _stream;
-
-    private JpegSegmentData _segmentData;
-
-    /**
-     * Private, because this segment crashes my algorithm, and searching for
-     * it doesn't work (yet).
+    // TODO add a findAvailableSegments() method
+    // TODO add more segment identifiers
+    // TODO add a getSegmentDescription() method, returning for example 'App1 application data segment, commonly containing Exif data'
+
+    @NotNull
+    private final JpegSegmentData _segmentData;
+
+    /**
+     * Private, because this segment crashes my algorithm, and searching for it doesn't work (yet).
      */
     private static final byte SEGMENT_SOS = (byte)0xDA;
@@ -54 +49 @@
     private static final byte MARKER_EOI = (byte)0xD9;
 
-    /** APP0 Jpeg segment identifier -- Jfif data. */
+    /** APP0 Jpeg segment identifier -- JFIF data (also JFXX apparently). */
     public static final byte SEGMENT_APP0 = (byte)0xE0;
-    /** APP1 Jpeg segment identifier -- where Exif data is kept. */
+    /** APP1 Jpeg segment identifier -- where Exif data is kept.  XMP data is also kept in here, though usually in a second instance. */
     public static final byte SEGMENT_APP1 = (byte)0xE1;
     /** APP2 Jpeg segment identifier. */
@@ -74 +69 @@
     /** APP9 Jpeg segment identifier. */
     public static final byte SEGMENT_APP9 = (byte)0xE9;
-    /** APPA Jpeg segment identifier -- can hold Unicode comments. */
+    /** APPA (App10) Jpeg segment identifier -- can hold Unicode comments. */
     public static final byte SEGMENT_APPA = (byte)0xEA;
-    /** APPB Jpeg segment identifier. */
+    /** APPB (App11) Jpeg segment identifier. */
     public static final byte SEGMENT_APPB = (byte)0xEB;
-    /** APPC Jpeg segment identifier. */
+    /** APPC (App12) Jpeg segment identifier. */
     public static final byte SEGMENT_APPC = (byte)0xEC;
-    /** APPD Jpeg segment identifier -- IPTC data in here. */
+    /** APPD (App13) Jpeg segment identifier -- IPTC data in here. */
     public static final byte SEGMENT_APPD = (byte)0xED;
-    /** APPE Jpeg segment identifier. */
+    /** APPE (App14) Jpeg segment identifier. */
     public static final byte SEGMENT_APPE = (byte)0xEE;
-    /** APPF Jpeg segment identifier. */
+    /** APPF (App15) Jpeg segment identifier. */
     public static final byte SEGMENT_APPF = (byte)0xEF;
     /** Start Of Image segment identifier. */
@@ -101 +96 @@
      * @param file the Jpeg file to read segments from
      */
-    public JpegSegmentReader(File file) throws JpegProcessingException
-    {
-        _file = file;
-        _data = null;
-        _stream = null;
-
-        readSegments();
+    @SuppressWarnings({ "ConstantConditions" })
+    public JpegSegmentReader(@NotNull File file) throws JpegProcessingException, IOException
+    {
+        if (file==null)
+            throw new NullPointerException();
+
+        InputStream inputStream = null;
+        try {
+            inputStream = new FileInputStream(file);
+            _segmentData = readSegments(new BufferedInputStream(inputStream), false);
+        } finally {
+            if (inputStream != null)
+                inputStream.close();
+        }
     }
 
@@ -114 +116 @@
      * @param fileContents the byte array containing Jpeg data
      */
-    public JpegSegmentReader(byte[] fileContents) throws JpegProcessingException
-    {
-        _file = null;
-        _data = fileContents;
-        _stream = null;
-
-        readSegments();
-    }
-
-    public JpegSegmentReader(InputStream in) throws JpegProcessingException
-    {
-        _stream = in;
-        _file = null;
-        _data = null;
-        
-        readSegments();
-    }
-
-    public JpegSegmentReader(JpegSegmentData segmentData)
-    {
-        _file = null;
-        _data = null;
-        _stream = null;
-
-        _segmentData = segmentData;
+    @SuppressWarnings({ "ConstantConditions" })
+    public JpegSegmentReader(@NotNull byte[] fileContents) throws JpegProcessingException
+    {
+        if (fileContents==null)
+            throw new NullPointerException();
+
+        BufferedInputStream stream = new BufferedInputStream(new ByteArrayInputStream(fileContents));
+        _segmentData = readSegments(stream, false);
+    }
+
+    /**
+     * Creates a JpegSegmentReader for an InputStream.
+     * @param inputStream the InputStream containing Jpeg data
+     */
+    @SuppressWarnings({ "ConstantConditions" })
+    public JpegSegmentReader(@NotNull InputStream inputStream, boolean waitForBytes) throws JpegProcessingException
+    {
+        if (inputStream==null)
+            throw new NullPointerException();
+
+        BufferedInputStream bufferedInputStream = inputStream instanceof BufferedInputStream
+                ? (BufferedInputStream)inputStream
+                : new BufferedInputStream(inputStream);
+
+        _segmentData = readSegments(bufferedInputStream, waitForBytes);
     }
 
@@ -146 +148 @@
      * @param segmentMarker the byte identifier for the desired segment
      * @return the byte array if found, else null
-     * @throws JpegProcessingException for any problems processing the Jpeg data,
-     *         including inner IOExceptions
-     */
-    public byte[] readSegment(byte segmentMarker) throws JpegProcessingException
+     */
+    @Nullable
+    public byte[] readSegment(byte segmentMarker)
     {
         return readSegment(segmentMarker, 0);
@@ -155 +156 @@
 
     /**
-     * Reads the first instance of a given Jpeg segment, returning the contents as
-     * a byte array.
+     * Reads the Nth instance of a given Jpeg segment, returning the contents as a byte array.
+     * 
      * @param segmentMarker the byte identifier for the desired segment
      * @param occurrence the occurrence of the specified segment within the jpeg file
      * @return the byte array if found, else null
      */
+    @Nullable
     public byte[] readSegment(byte segmentMarker, int occurrence)
     {
@@ -166 +168 @@
     }
 
+    /**
+     * Returns all instances of a given Jpeg segment.  If no instances exist, an empty sequence is returned.
+     *
+     * @param segmentMarker a number which identifies the type of Jpeg segment being queried
+     * @return zero or more byte arrays, each holding the data of a Jpeg segment
+     */
+    @NotNull
+    public Iterable<byte[]> readSegments(byte segmentMarker)
+    {
+        return _segmentData.getSegments(segmentMarker);
+    }
+
+    /**
+     * Returns the number of segments having the specified JPEG segment marker.
+     * @param segmentMarker the JPEG segment identifying marker.
+     * @return the count of matching segments.
+     */
     public final int getSegmentCount(byte segmentMarker)
     {
@@ -171 +190 @@
     }
 
+    /**
+     * Returns the JpegSegmentData object used by this reader.
+     * @return the JpegSegmentData object.
+     */
+    @NotNull
     public final JpegSegmentData getSegmentData()
     {
@@ -176 +200 @@
     }
 
-    private void readSegments() throws JpegProcessingException
-    {
-        _segmentData = new JpegSegmentData();
-
-        BufferedInputStream inStream = getJpegInputStream();
+    @NotNull
+    private JpegSegmentData readSegments(@NotNull final BufferedInputStream jpegInputStream, boolean waitForBytes) throws JpegProcessingException
+    {
+        JpegSegmentData segmentData = new JpegSegmentData();
+
         try {
             int offset = 0;
             // first two bytes should be jpeg magic number
-            if (!isValidJpegHeaderBytes(inStream)) {
+            byte[] headerBytes = new byte[2];
+            if (jpegInputStream.read(headerBytes, 0, 2)!=2)
                 throw new JpegProcessingException("not a jpeg file");
-            }
+            final boolean hasValidHeader = (headerBytes[0] & 0xFF) == 0xFF && (headerBytes[1] & 0xFF) == 0xD8;
+            if (!hasValidHeader)
+                throw new JpegProcessingException("not a jpeg file");
+
             offset += 2;
             do {
+                // need four bytes from stream for segment header before continuing
+                if (!checkForBytesOnStream(jpegInputStream, 4, waitForBytes))
+                    throw new JpegProcessingException("stream ended before segment header could be read");
+
                 // next byte is 0xFF
-                byte segmentIdentifier = (byte)(inStream.read() & 0xFF);
+                byte segmentIdentifier = (byte)(jpegInputStream.read() & 0xFF);
                 if ((segmentIdentifier & 0xFF) != 0xFF) {
                     throw new JpegProcessingException("expected jpeg segment start identifier 0xFF at offset " + offset + ", not 0x" + Integer.toHexString(segmentIdentifier & 0xFF));
@@ -196 +228 @@
                 offset++;
                 // next byte is <segment-marker>
-                byte thisSegmentMarker = (byte)(inStream.read() & 0xFF);
+                byte thisSegmentMarker = (byte)(jpegInputStream.read() & 0xFF);
                 offset++;
                 // next 2-bytes are <segment-size>: [high-byte] [low-byte]
                 byte[] segmentLengthBytes = new byte[2];
-                inStream.read(segmentLengthBytes, 0, 2);
+                if (jpegInputStream.read(segmentLengthBytes, 0, 2) != 2)
+                    throw new JpegProcessingException("Jpeg data ended unexpectedly.");
                 offset += 2;
                 int segmentLength = ((segmentLengthBytes[0] << 8) & 0xFF00) | (segmentLengthBytes[1] & 0xFF);
                 // segment length includes size bytes, so subtract two
                 segmentLength -= 2;
-                if (segmentLength > inStream.available())
+                if (!checkForBytesOnStream(jpegInputStream, segmentLength, waitForBytes))
                     throw new JpegProcessingException("segment size would extend beyond file stream length");
-                else if (segmentLength < 0)
+                if (segmentLength < 0)
                     throw new JpegProcessingException("segment size would be less than zero");
                 byte[] segmentBytes = new byte[segmentLength];
-                inStream.read(segmentBytes, 0, segmentLength);
+                if (jpegInputStream.read(segmentBytes, 0, segmentLength) != segmentLength)
+                    throw new JpegProcessingException("Jpeg data ended unexpectedly.");
                 offset += segmentLength;
                 if ((thisSegmentMarker & 0xFF) == (SEGMENT_SOS & 0xFF)) {
@@ -216 +250 @@
                     // have to search for the two bytes: 0xFF 0xD9 (EOI).
                     // It comes last so simply return at this point
-                    return;
+                    return segmentData;
                 } else if ((thisSegmentMarker & 0xFF) == (MARKER_EOI & 0xFF)) {
                     // the 'End-Of-Image' segment -- this should never be found in this fashion
-                    return;
+                    return segmentData;
                 } else {
-                    _segmentData.addSegment(thisSegmentMarker, segmentBytes);
+                    segmentData.addSegment(thisSegmentMarker, segmentBytes);
                 }
-                // didn't find the one we're looking for, loop through to the next segment
             } while (true);
         } catch (IOException ioe) {
-            //throw new JpegProcessingException("IOException processing Jpeg file", ioe);
             throw new JpegProcessingException("IOException processing Jpeg file: " + ioe.getMessage(), ioe);
         } finally {
             try {
-                if (inStream != null) {
-                    inStream.close();
+                if (jpegInputStream != null) {
+                    jpegInputStream.close();
                 }
             } catch (IOException ioe) {
-                //throw new JpegProcessingException("IOException processing Jpeg file", ioe);
                 throw new JpegProcessingException("IOException processing Jpeg file: " + ioe.getMessage(), ioe);
             }
@@ -240 +271 @@
     }
 
-    /**
-     * Private helper method to create a BufferedInputStream of Jpeg data from whichever
-     * data source was specified upon construction of this instance.
-     * @return a a BufferedInputStream of Jpeg data
-     * @throws JpegProcessingException for any problems obtaining the stream
-     */
-    private BufferedInputStream getJpegInputStream() throws JpegProcessingException
-    {
-        if (_stream!=null) {
-            if (_stream instanceof BufferedInputStream) {
-                return (BufferedInputStream) _stream;
-            } else {
-                return new BufferedInputStream(_stream);
+    private boolean checkForBytesOnStream(@NotNull BufferedInputStream stream, int bytesNeeded, boolean waitForBytes) throws IOException
+    {
+        // NOTE  waiting is essential for network streams where data can be delayed, but it is not necessary for byte[] or filesystems
+
+        if (!waitForBytes)
+            return bytesNeeded <= stream.available();
+
+        int count = 40; // * 100ms = approx 4 seconds
+        while (count > 0) {
+            if (bytesNeeded <= stream.available())
+               return true;
+            try {
+                Thread.sleep(100);
+            } catch (InterruptedException e) {
+                // continue
             }
+            count--;
         }
-        InputStream inputStream;
-        if (_data == null) {
-            try {
-                inputStream = new FileInputStream(_file);
-            } catch (FileNotFoundException e) {
-                throw new JpegProcessingException("Jpeg file does not exist", e);
-            }
-        } else {
-            inputStream = new ByteArrayInputStream(_data);
-        }
-        return new BufferedInputStream(inputStream);
-    }
-
-    /**
-     * Helper method that validates the Jpeg file's magic number.
-     * @param fileStream the InputStream to read bytes from, which must be positioned
-     *        at its start (i.e. no bytes read yet)
-     * @return true if the magic number is Jpeg (0xFFD8)
-     * @throws IOException for any problem in reading the file
-     */
-    private boolean isValidJpegHeaderBytes(InputStream fileStream) throws IOException
-    {
-        byte[] header = new byte[2];
-        fileStream.read(header, 0, 2);
-        return (header[0] & 0xFF) == 0xFF && (header[1] & 0xFF) == 0xD8;
+        return false;
     }
 }