Add package comments, tweak doc comments in classes for better formatting.

git-svn-id: http://scm.dspace.org/svn/repo/dspace/trunk@5342 9c30dcfa-912a-0410-8fc2-9e0234be79fd

dspace-api/src/main/java/org/dspace/embargo/DefaultEmbargoLifter.java

@@ -46,7 +46,7 @@ import org.dspace.content.Item;
 import org.dspace.core.Context;
 
 /**
- * Plugin interface for the embargo lifting function.
+ * Default plugin implementation of the embargo lifting function.
  *
  * @author Larry Stone
  * @author Richard Rodgers

dspace-api/src/main/java/org/dspace/embargo/DefaultEmbargoSetter.java

@@ -121,8 +121,7 @@ public class DefaultEmbargoSetter implements EmbargoSetter
     }
 
     /**
-     * Check that embargo is properly set on Item, e.g. no read access
-     * to bitstreams.
+     * Check that embargo is properly set on Item: no read access to bitstreams.
      *
      * @param context the DSpace context
      * @param item the item to embargo

dspace-api/src/main/java/org/dspace/embargo/EmbargoLifter.java

@@ -56,7 +56,8 @@ public interface EmbargoLifter
 {
     /**
      * Implement the lifting of embargo in the "resource policies"
-     * (access control) by e.g. turning on default read access to all Bitstreams.
+     * (access control) by (for example) turning on default read access to all
+     * Bitstreams.
      *
      * @param context the DSpace context
      * @param item the Item on which to lift the embargo

dspace-api/src/main/java/org/dspace/embargo/EmbargoManager.java

@@ -38,48 +38,43 @@
  */
 package org.dspace.embargo;
 
+import java.io.IOException;
 import java.sql.SQLException;
 import java.util.Date;
-import java.io.IOException;
 
-import org.apache.log4j.Logger;
 import org.apache.commons.cli.CommandLine;
-import org.apache.commons.cli.CommandLineParser;
 import org.apache.commons.cli.HelpFormatter;
-import org.apache.commons.cli.Option;
-import org.apache.commons.cli.OptionBuilder;
 import org.apache.commons.cli.Options;
-import org.apache.commons.cli.PosixParser;
 import org.apache.commons.cli.ParseException;
-
+import org.apache.commons.cli.PosixParser;
+import org.apache.log4j.Logger;
 import org.dspace.authorize.AuthorizeException;
-import org.dspace.content.Item;
-import org.dspace.content.ItemIterator;
 import org.dspace.content.DCDate;
 import org.dspace.content.DCValue;
 import org.dspace.content.DSpaceObject;
+import org.dspace.content.Item;
+import org.dspace.content.ItemIterator;
 import org.dspace.content.MetadataSchema;
 import org.dspace.core.ConfigurationManager;
 import org.dspace.core.Constants;
 import org.dspace.core.Context;
-import org.dspace.core.Utils;
 import org.dspace.core.PluginManager;
 import org.dspace.handle.HandleManager;
 
 /**
  * Public interface to the embargo subsystem.
- *
+ * <p>
  * Configuration properties: (with examples)
- *   # DC metadata field to hold the user-supplied embargo terms
- *   embargo.field.terms = dc.embargo.terms
- *   # DC metadata field to hold computed "lift date" of embargo
- *   embargo.field.lift = dc.date.available
- *   # String to indicate indefinite (forever) embargo in terms
- *   embargo.terms.open = Indefinite
- *   # implementation of embargo setter plugin
- *   plugin.single.org.dspace.embargo.EmbargoSetter = edu.my.Setter
- *   # implementation of embargo lifter plugin
- *   plugin.single.org.dspace.embargo.EmbargoLifter = edu.my.Lifter
+ *   <br/># DC metadata field to hold the user-supplied embargo terms
+ *   <br/>embargo.field.terms = dc.embargo.terms
+ *   <br/># DC metadata field to hold computed "lift date" of embargo
+ *   <br/>embargo.field.lift = dc.date.available
+ *   <br/># String to indicate indefinite (forever) embargo in terms
+ *   <br/>embargo.terms.open = Indefinite
+ *   <br/># implementation of embargo setter plugin
+ *   <br/>plugin.single.org.dspace.embargo.EmbargoSetter = edu.my.Setter
+ *   <br/># implementation of embargo lifter plugin
+ *   <br/>plugin.single.org.dspace.embargo.EmbargoLifter = edu.my.Lifter
  *
  * @author Larry Stone
  * @author Richard Rodgers
@@ -194,22 +189,31 @@ public class EmbargoManager
     }
 
     /**
-     * Command-line service to scan for every Items with an expired embargo,
+     * Command-line service to scan for every Item with an expired embargo,
      * and then lift that embargo.
-     *
+     * <p>
      * Options:
-     *   -c,--check         Function: ONLY check the state of embargoed Items, do
-     *                      NOT lift any embargoes.
-     *   -h,--help          help
-     *   -i,--identifier    Process ONLY this Handle identifier(s), which must be
-     *                      an Item.  Can be repeated.
-     *   -l,--lift          Function: ONLY lift embargoes, do NOT check the state
-     *                      of any embargoed Items.
-     *   -n,--dryrun        Do not change anything in the data model, print
-     *                      message instead.
-     *   -v,--verbose       Print a line describing action taken for each
-     *                      embargoed Item found.
-     *   -q,--quiet         No output except upon error
+     * <dl>
+     *   <dt>-c,--check</dt>
+     *   <dd>         Function: ONLY check the state of embargoed Items, do
+     *                      NOT lift any embargoes.</dd>
+     *   <dt>-h,--help</dt>
+     *   <dd>         Help.</dd>
+     *   <dt>-i,--identifier</dt>
+     *   <dd>         Process ONLY this Handle identifier(s), which must be
+     *                      an Item.  Can be repeated.</dd>
+     *   <dt>-l,--lift</dt>
+     *   <dd>         Function: ONLY lift embargoes, do NOT check the state
+     *                      of any embargoed Items.</dd>
+     *   <dt>-n,--dryrun</dt>
+     *   <dd>         Do not change anything in the data model; print
+     *                      message instead.</dd>
+     *   <dt>-v,--verbose</dt>
+     *   <dd>         Print a line describing action taken for each
+     *                      embargoed Item found.</dd>
+     *   <dt>-q,--quiet</dt>
+     *   <dd>         No output except upon error.</dd>
+     * </dl>
      */
     public static void main(String argv[])
     {

dspace-api/src/main/java/org/dspace/embargo/EmbargoSetter.java

@@ -79,8 +79,8 @@ public interface EmbargoSetter
         throws SQLException, AuthorizeException, IOException;
 
     /**
-     * Enforce embargo by e.g. turning off all read access to bitstreams in
-     * this Item.
+     * Enforce embargo by (for example) turning off all read access to
+     * bitstreams in this Item.
      *
      * @param context the DSpace context
      * @param item the item to embargo
@@ -89,7 +89,7 @@ public interface EmbargoSetter
         throws SQLException, AuthorizeException, IOException;
 
     /**
-     * Check that embargo is properly set on Item, e.g. no read access
+     * Check that embargo is properly set on Item.  For example: no read access
      * to bitstreams.  It is expected to report any noteworthy
      * discrepencies by writing on the stream System.err, although
      * logging is also encouraged.  Only report conditions that

dspace-api/src/main/java/org/dspace/embargo/package-info.java

@@ -0,0 +1,47 @@
+/**
+ * <p>
+ * Embargo allows the deposit of Items whose content should not be made visible
+ * until later.  Some journals, for example, permit self-publication after a
+ * period of exclusive access through the journal.
+ * </p>
+ * <p>
+ * Embargo policy is applied through a pair of pluggable classes:  an
+ * {@link org.dspace.embargo.EmbargoSetter} and an
+ * {@link org.dspace.embargo.EmbargoLifter}.  The {@link org.dspace.embargo.EmbargoManager}
+ * must be configured to specify these classes, as well as names of two metadata
+ * fields for use by the embargo facility:  an embargo lift date (when the
+ * content will be released) and the embargo terms (which the EmbargoSetter will
+ * use to calculate the lift date).  You must select or create appropriate
+ * metadata fields for this purpose.
+ * </p>
+ * <p>
+ * See {@link org.dspace.embargo.DefaultEmbargoSetter},
+ * {@link org.dspace.embargo.DayTableEmbargoSetter}, and
+ * {@link org.dspace.embargo.DefaultEmbargoLifter} for simple policy classes
+ * which ship with DSpace.  You can supply your own classes to implement more
+ * elaborate policies.
+ * </p>
+ * <p>
+ * Embargo is applied when an Item is installed in a Collection.  An Item subject
+ * to embargo passes through several stages:
+ * </p>
+ * <ol>
+ *  <li>During submission, the metadata field established for embargo terms must
+ *  be set to a value which is interpretable by the selected setter.  Typically
+ *  this will be a date or an interval.  There is no specific mechanism for
+ *  requesting embargo; you must customize your submission forms as needed,
+ *  create a template Item which applies a standard value, or in some other way
+ *  cause the specified metadata field to be set.
+ *  </li>
+ *  <li>When the Item is accepted into a Collection, the setter will apply the
+ *  embargo, making the content inaccessible.
+ *  </li>
+ *  <li>The site should run the embargo lifter tool ({@code dspace embargo-lifter})
+ *  from time to time, for example using an automatic daily job.  This discovers
+ *  Items which have passed their embargo lift dates and makes their content
+ *  accessible.
+ *  </li>
+ * </ol>
+ */
+
+package org.dspace.embargo;