Commits

P_W999 committed 7c6b748

- update javadoc for external classses

Comments (0)

Files changed (7)

src/be/pw/jexif/JExifInfo.java

 import be.pw.jexif.enums.tag.Tag;
 import be.pw.jexif.exception.ExifError;
 import be.pw.jexif.exception.JExifException;
+import be.pw.jexif.internal.util.TagUtil;
 
 import com.google.common.annotations.Beta;
 
     }
 
     /**
-     * Immediately writes a value to a tag.
+     * Writes a single value to an Exif tag. <br />
+     * Be aware that not all tags are writable. The following methods should all return false if you can safely write something to an Exif tag.
+     * <ul>
+     * 	<li>{@link Tag#isAvoided()}</li>
+     *  <li>{@link Tag#isProtectedField()}</li>
+     *  <li>{@link Tag#isUnsafe()}</li>
+     * </ul>
      *
      * @param tag   the tag to write to.
      * @param value the value to write.
     }
     
     /**
-     * 
+     * Writes GPS info.
      * @param GPSLatitude gps latitude
      * @param GPSLatitudeRef N or S (Northern or Southern hemisphere)
      * @param GPSLongitude gps longitude
     } 
     
     /**
-     * Reads out all the tag values in human read-able format, limited to only the tags known to J-ExifTool. 
+     * Reads out all the tag values in human read-able format, limited to only the tags known to J-ExifTool.<br />
+     * The set of known tags can be extended by using {@link TagUtil#register(Class)}.
      * 
      * @return a map with all the tag values.
      * @throws JExifException in case something goes wrong internally.
     }
     
     /**
-     * Reads out all the tag values in exact format, limited to only the tags known to J-ExifTool. 
+     * Reads out all the tag values in exact format, limited to only the tags known to J-ExifTool. <br />
+     * The set of known tags can be extended by using {@link TagUtil#register(Class)}.
      * 
      * @return a map with all the tag values.
      * @throws JExifException in case something goes wrong internally.

src/be/pw/jexif/JExifTool.java

 import com.google.common.eventbus.EventBus;
 
 /**
- * JExifTool is the main class to use. <br />
- * This class is responsible for starting and stopping ExifTool.
- *
+ * The JExifTool class acts as the bridge between ExifTool and your java code.<br /> 
+ * 
+ * This class is responsible for starting and stopping the ExifTool process. <br />
+ * <br />
+ * In order to use J-ExifTool you must download ExifTool from <a href="http://www.sno.phy.queensu.ca/~phil/exiftool/">http://www.sno.phy.queensu.ca/~phil/exiftool/</a> <br />
+ * The System Property {@link ExecutionConstant#EXIFTOOLPATH} should point to the executable.<br />
+ * <br />
+ * If you want to read or write Exif tags, you first need to make an instance of this class and the use the {@link #getInfo(File)) method to create a {@link JExifInfo} object.
+ * <br />
+ * <b>JExifTool is not thread-safe</b>
+ * 
  * @author phillip
  */
 @Beta
      *
      * @see be.pw.jexif.internal.constants.ExecutionConstant#EXIFTOOLDEADLOCK
      */
-    private final int deadLock = Integer.getInteger(ExecutionConstant.EXIFTOOLDEADLOCK, 2000);
+    private final int deadLock = Integer.getInteger(ExecutionConstant.EXIFTOOLDEADLOCK, 4000);
     /**
      * This will hold a reference to the ExifTool.exe process.
      */
 
     /**
      * Default constructor. <br />
-     * This automatically starts the ExifTool process.
+     * This automatically starts the ExifTool process and registers the standard Tag-set that comes with this library.
      */
     @Beta
     public JExifTool() {
     }
 
     /**
-     * Creates a new instance of a JExifInfo object.
+     * Creates a new instance of a JExifInfo object. This object can be used to read and write Exif tags to the specified file.
      *
      * @param file the image file from which tags shall be read from or written to.
      * @return a JExifInfo object.
-     * @throws IOException if the file does not exist of if it's folder
+     * @throws IOException if the file does not exist or if it's folder
      */
     @Beta
     public JExifInfo getInfo(final File file) throws IOException {
     }
 
     /**
-     * Starts the ExifTool process and several subthreads to handle the streams.<br />
+     * Starts the ExifTool process and several sub-threads to handle the in- and output streams.<br />
      * This method is automatically called when a new instance of JExifTool is created.
      */
     private synchronized void start() {
     }
 
     /**
-     * Stops the ExifTool-thread.
+     * Stops the ExifTool-thread. You <b>ALWAYS</b> have to call this method when you don't need J-ExifTool anymore, otherwise the ExifTool process will continue running in the background.
      *
      * @throws JExifException if it failed to stop (there is a Thread.sleep which may throw an InterruptedException).
      */

src/be/pw/jexif/enums/DataType.java

 package be.pw.jexif.enums;
 
 /**
- * Since tags can be either signed or unsigned, we need to find a way to make a difference between eg int32u and int32s.
+ * Defines the data-type a tag value.<br />
+ * Supported types are:
+ * <ul>
+ * <li>Short signed</li>
+ * <li>Short unsigned</li>
+ * <li>Integer signed</li>
+ * <li>Integer unsigned</li>
+ * <li>Long signed</li>
+ * <li>Long unsigned</li>
+ * <li>Double signed</li>
+ * <li>Double unsigned (unsupported by Java)</li>
+ * <li>String</li>
+ * <li>Float</li>
+ * <li>Undefined for any other case</li>
+ * </ul>
+ * 
  * @author phillip
  */
 public enum DataType {

src/be/pw/jexif/enums/tag/ExifGPS.java

 import be.pw.jexif.enums.DataType;
 
 /**
+ * Implementation of the GPS group: <a href="http://www.sno.phy.queensu.ca/~phil/exiftool/TagNames/GPS.html">http://www.sno.phy.queensu.ca/~phil/exiftool/TagNames/GPS.html</a>
+ * 
  * @author phillip
  */
 public enum ExifGPS implements Tag {
 		this.type = type;
 	}
 
-	/*
-	 * (non-Javadoc)
-	 * @see be.pw.jexif.enums.tag.Tag#isAvoided()
+	/**
+	 * {@inheritDoc}
 	 */
 	@Override
 	public final boolean isAvoided() {
 		return avoided;
 	}
 
-	/*
-	 * (non-Javadoc)
-	 * @see be.pw.jexif.enums.tag.Tag#isUnsafe()
+	/**
+	 * {@inheritDoc}
 	 */
 	@Override
 	public final boolean isUnsafe() {
 		return unsafe;
 	}
 
-	/*
-	 * (non-Javadoc)
-	 * @see be.pw.jexif.enums.tag.Tag#isProtectedField()
+	/**
+	 * {@inheritDoc}
 	 */
 	@Override
 	public final boolean isProtectedField() {
 		return protectedField;
 	}
 
-	/*
-	 * (non-Javadoc)
-	 * @see be.pw.jexif.enums.tag.Tag#getName()
+	/**
+	 * {@inheritDoc}
 	 */
 	@Override
 	public final String getName() {
 		return name;
 	}
 
-	/*
-	 * (non-Javadoc)
-	 * @see be.pw.jexif.enums.tag.Tag#getType()
+	/**
+	 * {@inheritDoc}
 	 */
 	@Override
 	public final DataType getType() {

src/be/pw/jexif/enums/tag/ExifIFD.java

 import be.pw.jexif.enums.DataType;
 
 /**
- * Implementation of the ExifIFD group.
+ * Implementation of the ExifIFD group: <a href="http://www.sno.phy.queensu.ca/~phil/exiftool/TagNames/EXIF.html">http://www.sno.phy.queensu.ca/~phil/exiftool/TagNames/EXIF.html</a>
+ * 
+ * @author phillip
  */
 public enum ExifIFD implements Tag {
 
         this.type = type;
     }
 
-    /*
-      * (non-Javadoc)
-      * @see be.pw.jexif.enums.tag.Tag#isAvoided()
-      */
-    @Override
-    public final boolean isAvoided() {
-        return avoided;
-    }
+    /**
+	 * {@inheritDoc}
+	 */
+	@Override
+	public final boolean isAvoided() {
+		return avoided;
+	}
 
-    /*
-      * (non-Javadoc)
-      * @see be.pw.jexif.enums.tag.Tag#isUnsafe()
-      */
-    @Override
-    public final boolean isUnsafe() {
-        return unsafe;
-    }
+	/**
+	 * {@inheritDoc}
+	 */
+	@Override
+	public final boolean isUnsafe() {
+		return unsafe;
+	}
 
-    /*
-      * (non-Javadoc)
-      * @see be.pw.jexif.enums.tag.Tag#isProtectedField()
-      */
-    @Override
-    public final boolean isProtectedField() {
-        return protectedField;
-    }
+	/**
+	 * {@inheritDoc}
+	 */
+	@Override
+	public final boolean isProtectedField() {
+		return protectedField;
+	}
 
-    /*
-      * (non-Javadoc)
-      * @see be.pw.jexif.enums.tag.Tag#getName()
-      */
-    @Override
-    public final String getName() {
-        return name;
-    }
+	/**
+	 * {@inheritDoc}
+	 */
+	@Override
+	public final String getName() {
+		return name;
+	}
 
-    /*
-      * (non-Javadoc)
-      * @see be.pw.jexif.enums.tag.Tag#getType()
-      */
-    @Override
-    public final DataType getType() {
-        return type;
-    }
+	/**
+	 * {@inheritDoc}
+	 */
+	@Override
+	public final DataType getType() {
+		return type;
+	}
 
 }

src/be/pw/jexif/enums/tag/IFD0.java

 import static be.pw.jexif.enums.DataType.RAT64U;
 import static be.pw.jexif.enums.DataType.STRING;
 import static be.pw.jexif.enums.DataType.UNDEF;
-
-import java.util.HashMap;
-import java.util.Map;
-
 import be.pw.jexif.enums.DataType;
 
 /**
- * Implementation of the IFD0 tag group.
+ * Implementation of the IFD0 group: <a href="http://www.sno.phy.queensu.ca/~phil/exiftool/TagNames/EXIF.html">http://www.sno.phy.queensu.ca/~phil/exiftool/TagNames/EXIF.html</a>
+ * 
+ * @author phillip
  */
 public enum IFD0 implements Tag {
 
     private final boolean protectedField;
     private final String name;
     private final DataType type;
-    private static final Map<String, IFD0> TAG_LOOKUP_MAP;
 
     /**
      * @param avoided        indicate that the tag is avoided
     }
 
     /**
-     * Initializer used to init the <code>static final</code> tag/name lookup map used by all instances of this class.
-     */
-    static {
-        IFD0[] values = IFD0.values();
-        TAG_LOOKUP_MAP = new HashMap<>(values.length * 3);
-
-        for (IFD0 tag : values) {
-            TAG_LOOKUP_MAP.put(tag.name, tag);
-        }
-    }
+	 * {@inheritDoc}
+	 */
+	@Override
+	public final boolean isAvoided() {
+		return avoided;
+	}
 
-    /*
-      * (non-Javadoc)
-      * @see be.pw.jexif.enums.tag.Tag#isAvoided()
-      */
-    @Override
-    public final boolean isAvoided() {
-        return avoided;
-    }
-
-    /*
-      * (non-Javadoc)
-      * @see be.pw.jexif.enums.tag.Tag#isUnsafe()
-      */
-    @Override
-    public final boolean isUnsafe() {
-        return unsafe;
-    }
+	/**
+	 * {@inheritDoc}
+	 */
+	@Override
+	public final boolean isUnsafe() {
+		return unsafe;
+	}
 
-    /*
-      * (non-Javadoc)
-      * @see be.pw.jexif.enums.tag.Tag#isProtectedField()
-      */
-    @Override
-    public final boolean isProtectedField() {
-        return protectedField;
-    }
+	/**
+	 * {@inheritDoc}
+	 */
+	@Override
+	public final boolean isProtectedField() {
+		return protectedField;
+	}
 
-    /*
-      * (non-Javadoc)
-      * @see be.pw.jexif.enums.tag.Tag#getName()
-      */
-    @Override
-    public final String getName() {
-        return name;
-    }
+	/**
+	 * {@inheritDoc}
+	 */
+	@Override
+	public final String getName() {
+		return name;
+	}
 
-    /*
-      * (non-Javadoc)
-      * @see be.pw.jexif.enums.tag.Tag#getType()
-      */
-    @Override
-    public final DataType getType() {
-        return type;
-    }
+	/**
+	 * {@inheritDoc}
+	 */
+	@Override
+	public final DataType getType() {
+		return type;
+	}
 
 }

src/be/pw/jexif/enums/tag/Tag.java

 import be.pw.jexif.enums.DataType;
 
 /**
- * This is the definition of an exif tag.
- * Implementations of this interface is based on the info found on the website of ExifTool.
- * {@link http://www.sno.phy.queensu.ca/~phil/exiftool/TagNames/index.html}
+ * This is the definition of an Exif tag. For each group of tags, an enumeration which implements this interface should be created.<br />
+ * Implementations of this interface are based on the info found on the website of ExifTool: <a href="http://www.sno.phy.queensu.ca/~phil/exiftool/TagNames/index.html">http://www.sno.phy.queensu.ca/~phil/exiftool/TagNames/index.html</a>
  */
 public interface Tag {