Commits

P_W999 committed 87ab6a8

- update internal javadoc

Comments (0)

Files changed (13)

src/be/pw/jexif/internal/action/IAction.java

 
 import be.pw.jexif.enums.tag.Tag;
 import be.pw.jexif.exception.JExifException;
+import be.pw.jexif.internal.action.impl.ActionFactory;
+import be.pw.jexif.internal.result.IResultParser;
+import be.pw.jexif.internal.result.ResultHandler;
 
 /**
- * IAction is the interface for any action that must be executed by ExifTool.
+ * An operation that should be executed by ExifTool is called an action. Eg: reading a tag in a human readable format is an action. Reading a tag in the exact format is another action.<br />
+ * A typical life-cycle of an action:
+ * <ol>
+ * <li>Create a new instance of the action</li>
+ * <li>Assign a unique id to the action</li>
+ * <li>Set parameters if required</li>
+ * <li>Create the arguments for ExifTool</li>
+ * <li>Wait for results to be returned by the {@link ResultHandler}
+ * </ol>
+ * 
+ * 
+ * The IAction interface describes such action.<br />
+ * An action may only be instantiated by the {@link ActionFactory} and for each action an {@link IResultParser} should be created.
+ * 
  * @author phillip
  */
 public interface IAction {
 
 	/**
 	 * Returns the result of the execution as a String.
+	 * 
 	 * @return the map with as key the Tag and as value the result of the execution
 	 */
 	Map<Tag, String> getResult();
 
 	/**
-	 * Sets the result of the executed action.
+	 * Adds the result for a Tag.
+	 * 
 	 * @param tag the tag for which the result is added
 	 * @param result the result of the action
 	 */
 	void addResult(Tag tag, String result);
 
+	/**
+	 * Returns the list of tags that were read but are not supported by J-ExifTool.
+	 * 
+	 * @return the list of unsupported tags.
+	 */
 	public abstract Map<String, String> getUnsupportedTags();
 
-	public abstract void addUnsupportedResult(final String tag, final String result);
+	/**
+	 * Adds the result for an unsupported tag.
+	 * 
+	 * @param tagName the name of the unsupported tag (as returned by ExifTool)
+	 * @param result the result
+	 */
+	public abstract void addUnsupportedResult(final String tagName, final String result);
 
 }

src/be/pw/jexif/internal/action/impl/TagWriteAction.java

 
 /**
  * Action to write an Exif-Tag
+ * @author phillip
  */
 public class TagWriteAction extends AbstractAction implements IAction {
 

src/be/pw/jexif/internal/constants/ExecutionConstant.java

      */
     public static final String MAC_CLA = "{0} " + STAY_OPEN + " true -@ \"{1}\"";
 
+    /**
+     * A list of ExifTool warnings that should be ignored by the result parser.
+     */
     public static final String[] WARNINGS_TO_IGNORE = {};
 
 }

src/be/pw/jexif/internal/result/IResultParser.java

 	 * Parses the result.
 	 * @param action the action where the results will be stored.
 	 * @param actionUID the UID of the action.
-	 * @param result the list with the output of ExifTool.
+	 * @param result the list with the output of ExifTool. Each line printed by ExifTool should represent a single String in the list.
 	 */
 	void parse(final IAction action, final String actionUID, final List<String> result) ;
 

src/be/pw/jexif/internal/result/ResultHandler.java

 import be.pw.jexif.internal.util.Cal10nUtil;
 
 /**
- * The ResultHandler will be used to run over the different results and actions in order to match the output with the input.
+ * The ResultHandler will be used to run over the different results (lines returned by ExifTool) in order to match the output with the input.
  * @author phillip
  */
 public class ResultHandler {

src/be/pw/jexif/internal/result/impl/TagReadAllParser.java

 
 import com.google.common.base.Preconditions;
 import com.google.common.base.Splitter;
-
+/**
+ * Parses the result for the {@link TagReadAllAction}
+ * @author phillip
+ *
+ */
 public class TagReadAllParser implements IResultParser {
-
+	/**
+	 * Logger for this class
+	 */
 	private static final Logger LOG = LoggerFactory.getLogger(TagReadAllParser.class);
 	
+	/**
+	 * {@inheritDoc}
+	 */
 	@Override
 	public void parse(IAction action, String actionUID, List<String> result) {
 		Preconditions.checkArgument(action.getClass().equals(validFor()), Cal10nUtil.get(Errors.PARSER_MISMATCH, getClass().getSimpleName(), action.getClass().getSimpleName()));
 		}
 	}
 
+	/**
+	 * {@inheritDoc}
+	 */
 	@Override
 	public Class<? extends IAction> validFor() {
 		return TagReadAllAction.class;

src/be/pw/jexif/internal/result/impl/TagReadExactAllParser.java

 import be.pw.jexif.internal.action.IAction;
 import be.pw.jexif.internal.action.impl.TagReadExactAllAction;
 import be.pw.jexif.internal.result.IResultParser;
-
+/**
+ * Parses the result for the {@link TagReadExactAllAction}
+ * @author phillip
+ *
+ */
 public class TagReadExactAllParser extends TagReadAllParser implements IResultParser {
 
-
+	/**
+	 * {@inheritDoc}
+	 */
 	@Override
 	public Class<? extends IAction> validFor() {
 		return TagReadExactAllAction.class;

src/be/pw/jexif/internal/result/impl/TagReadExactParser.java

 import be.pw.jexif.internal.action.impl.TagReadExactAction;
 
 /**
- * Class which can be used to parse the output of a {@link be.pw.jexif.internal.action.impl.TagReadExactAction}.
+ * Parses the result for the {@link TagReadExactAction}
  * @author phillip
+ *
  */
 public class TagReadExactParser extends TagReadParser {
 
 	TagReadExactParser() {
 	}
 
+	/**
+	 * {@inheritDoc}
+	 */
 	@Override
 	public Class<? extends IAction> validFor() {
 		return TagReadExactAction.class;

src/be/pw/jexif/internal/result/impl/TagReadParser.java

 import com.google.common.base.Splitter;
 
 /**
- * Class which can be used to parse the output of a {@link be.pw.jexif.internal.action.impl.TagReadAction}.
+ * Parses the result for the {@link TagReadAction}
  * @author phillip
+ *
  */
 public class TagReadParser implements IResultParser {
-
+	/**
+	 * Logger for this class
+	 */
 	private static final Logger LOG = LoggerFactory.getLogger(TagReadParser.class);
 
 	/**

src/be/pw/jexif/internal/result/impl/TagWriteParser.java

 import be.pw.jexif.internal.util.Cal10nUtil;
 
 import com.google.common.base.Preconditions;
-
+/**
+ * Parses the result for the {@link TagWriteAction}
+ * @author phillip
+ *
+ */
 public class TagWriteParser implements IResultParser {
-
+	/**
+	 * Logger for this class
+	 */
 	private static final Logger LOG = LoggerFactory.getLogger(TagWriteParser.class);
 
 	TagWriteParser() {
 	}
 
+	/**
+	 * {@inheritDoc}
+	 */
 	@Override
 	public void parse(final IAction action, final String actionUID, final List<String> result) {
 		Preconditions.checkArgument(action.getClass().equals(validFor()), Cal10nUtil.get(Errors.PARSER_MISMATCH, getClass().getSimpleName(), action.getClass().getSimpleName()));
 		}
 	}
 
+	/**
+	 * {@inheritDoc}
+	 */
 	@Override
 	public Class<? extends IAction> validFor() {
 		return TagWriteAction.class;

src/be/pw/jexif/internal/util/Cal10nUtil.java

 
 /**
  * A utility for i18n'ing the API's output. <br />
- * Uses Cal10n: {@linkplain http://cal10n.qos.ch/}
+ * Uses Cal10n: <a href="http://cal10n.qos.ch/">http://cal10n.qos.ch/</a>
  *
  * @author phillip
  */

src/be/pw/jexif/internal/util/GPSUtil.java

  ******************************************************************************/
 package be.pw.jexif.internal.util;
 
-import java.text.Format;
 import java.util.Map;
-import java.util.logging.SimpleFormatter;
-
-import com.google.common.annotations.VisibleForTesting;
 
 import be.pw.jexif.enums.Errors;
 import be.pw.jexif.enums.tag.ExifGPS;
 import be.pw.jexif.enums.tag.Tag;
 import be.pw.jexif.exception.JExifValidationException;
 
+import com.google.common.annotations.VisibleForTesting;
+/**
+ * General utility class to work with GPS tags
+ * @author phillip
+ *
+ */
 public class GPSUtil {
 
+	/**
+	 * Validates that the all mandatory GPS values are provided or that they are all empty. The Map must therefore contain the following Tags:
+	 * <ul>
+	 * <li>{@link ExifGPS#GPSALTITUDE}</li>
+	 * <li>{@link ExifGPS#GPSALTITUDEREF}</li>
+	 * <li>{@link ExifGPS#GPSLONGITUDE}</li>
+	 * <li>{@link ExifGPS#GPSLONGITUDEREF}</li>
+	 * <li>{@link ExifGPS#GPSLATITUDE}</li>
+	 * <li>{@link ExifGPS#GPSLATITUDEREF}</li>
+	 * </ul>
+	 * @param valuesToValidate the map with the GPS values
+	 * @throws JExifValidationException
+	 */
 	public static void validateGPSValues(final Map<Tag, String> valuesToValidate) throws JExifValidationException {
 		boolean allEmpty = true;
 		boolean allFilledIn = true;
 		}
 	}
 	
+	/**
+	 * Converts the provided GPS values to decimal format. The following Tags will be converted from DMS format to decimal format if needed:
+	 * <ul>
+	 * <li>{@link ExifGPS#GPSLONGITUDE}</li>
+	 * <li>{@link ExifGPS#GPSLATITUDE}</li>
+	 * </ul>
+	 * 
+	 * @param valuesToAlter the Map with GPS values.
+	 */
 	public static void formatGPSValues(final Map<Tag, String> valuesToAlter) {
 		String lon = valuesToAlter.get(ExifGPS.GPSLONGITUDE);
 		String lat = valuesToAlter.get(ExifGPS.GPSLATITUDE);
 		
 	}
 	
+	/**
+	 * Converts DMS GPS format to decimal GPS format.
+	 * 
+	 * @param DMS the longitude or latitude in DMS format
+	 * @return the longitude or latitude in decimal format.
+	 */
 	@VisibleForTesting
 	static String DMSToDecimal(final String DMS) {
 		String[] split = DMS.split("\\s");

src/be/pw/jexif/internal/util/TagUtil.java

     /**
      * Validates that a given value has to correct format based on the data type of the tag.
      *
+     * @see DataType
      * @param tag   the tag to which the value shall be written.
      * @param value the value to be written.
      * @throws JExifException if the given value is not formatted correctly.