Added some basic Javadocs to all classes in se.kb.oai.ore.* and se.kb.oai.ore.impl.*.

git-svn-id: https://oai4j-client.svn.sourceforge.net/svnroot/oai4j-client/trunk@11 201c9376-5148-0410-b534-98494c770f31

src/main/java/se/kb/oai/OAIException.java

@@ -16,6 +16,12 @@
 
 package se.kb.oai;
 
+/**
+ * A general exception that OAI4J throws. Often used to wrap lower-level
+ * exceptions. 
+ * 
+ * @author Oskar Grenholm, National Library of Sweden
+ */
 public class OAIException extends Exception {
     
     private static final long serialVersionUID = 5926653436917245659L;

src/main/java/se/kb/oai/ore/AggregateBase.java

@@ -22,6 +22,13 @@ import java.util.List;
 
 import org.dom4j.QName;
 
+/**
+ * Abstract base class for those classes that make up an aggregation, i.e.
+ * <code>Aggregation</code> and <code>AggregatedResource</code>. It can be used to
+ * get and set <code>Types</code> and <code>Metadata</code>.
+ * 
+ * @author Oskar Grenholm, National Library of Sweden
+ */
 public abstract class AggregateBase {
 
 	protected URI id;

src/main/java/se/kb/oai/ore/AggregatedResource.java

@@ -22,6 +22,13 @@ import java.io.InputStream;
 import java.net.URI;
 import java.net.URISyntaxException;
 
+/**
+ * An aggregated resource is a resource, that together with other resources, 
+ * create an {@link Aggregation}. This class has the actual content of a 
+ * resource and also metadata about it.
+ * 
+ * @author Oskar Grenholm, National Library of Sweden
+ */
 public class AggregatedResource extends AggregateBase {
 	
 	public AggregatedResource(String id) throws URISyntaxException {

src/main/java/se/kb/oai/ore/Aggregation.java

@@ -21,6 +21,14 @@ import java.net.URISyntaxException;
 import java.util.LinkedList;
 import java.util.List;
 
+/**
+ * An aggregation is a set of related resources (see {@link AggregatedResource}), grouped 
+ * together such that the set can be treated as a single resource. This class is used to 
+ * manage the individual resources and also holds information for the aggregation as 
+ * a whole.
+ * 
+ * @author Oskar Grenholm, National Library of Sweden
+ */
 public class Aggregation extends AggregateBase {
 
 	private List<AggregatedResource> resources;

src/main/java/se/kb/oai/ore/Metadata.java

@@ -20,6 +20,13 @@ import static se.kb.oai.ore.OREConstants.*;
 
 import org.dom4j.QName;
 
+/**
+ * Class that represents metadata that can be set for an <code>Aggregation</code>
+ * or an <code>AggreagatedResource</code>. Only metadata from the Dublin Core elements
+ * (DC) namespace or the Dublin Core terms (DCTERMS) namespace can be created.
+ * 
+ * @author Oskar Grenholm, National Library of Sweden
+ */
 public class Metadata {
 
 	public enum Namespace { DC, DCTERMS }

src/main/java/se/kb/oai/ore/OREConstants.java

@@ -18,6 +18,11 @@ package se.kb.oai.ore;
 
 import org.dom4j.Namespace;
 
+/**
+ * Constants regarding OAI-ORE.
+ * 
+ * @author Oskar Grenholm, National Library of Sweden
+ */
 public class OREConstants {
 
 	public static final String ATOM_NS_PREFIX = "atom";

src/main/java/se/kb/oai/ore/ResourceMap.java

@@ -20,6 +20,14 @@ import java.net.URI;
 import java.net.URISyntaxException;
 import java.util.Date;
 
+/**
+ * A resource map is a description of an {@link Aggregation} according to the OAI-ORE data model. 
+ * <code>ResourceMaps</code> can be serialized to a machine readable format, see {@link ResourceMapSerializer}. 
+ * This class will consist of the <code>Aggregation</code> it describes and some metadata concerning the 
+ * resource map itself. 
+ * 
+ * @author Oskar Grenholm, National Library of Sweden
+ */
 public class ResourceMap {
 
 	private URI id;

src/main/java/se/kb/oai/ore/ResourceMapFactory.java

@@ -24,6 +24,20 @@ import org.dom4j.Element;
 
 import se.kb.oai.OAIException;
 
+/**
+ * A <code>ResourceMapFactory</code> will be used to create a {@link ResourceMap}. 
+ * It can either be a totally new <code>ResourceMap</code> or one that is parsed
+ * from an existing serialization of a <code>ResourceMap</code>. Different
+ * implementations of this interface will handle different serialization formats.
+ * <p>
+ * At the moment the Open Archive Initiative describes two possible formats:
+ * <ul>
+ * 	<li> Atom - <a href="http://www.openarchives.org/ore/0.2/atom-implementation">http://www.openarchives.org/ore/0.2/atom-implementation</a>
+ * 	<li> RDF/XML - <a href="http://www.openarchives.org/ore/0.2/rdfsyntax">http://www.openarchives.org/ore/0.2/rdfsyntax</a>
+ * </ul>
+ * 
+ * @author Oskar Grenholm, National Library of Sweden
+ */
 public interface ResourceMapFactory {
 
 	public ResourceMap newResourceMap(String uri) throws URISyntaxException;

src/main/java/se/kb/oai/ore/ResourceMapSerializer.java

@@ -21,6 +21,19 @@ import java.io.IOException;
 
 import org.dom4j.Element;
 
+/**
+ * A <code>ResourceMapSerializer</code> is used to serialize the content of a 
+ * {@link ResourceMap} to a machine readable format (for example XML). Different
+ * implementations of this interface will handle serialization to different formats.
+ * <p>
+ * At the moment the Open Archive Initiative describes two possible serialization formats:
+ * <ul>
+ * 	<li> Atom - <a href="http://www.openarchives.org/ore/0.2/atom-implementation">http://www.openarchives.org/ore/0.2/atom-implementation</a>
+ * 	<li> RDF/XML - <a href="http://www.openarchives.org/ore/0.2/rdfsyntax">http://www.openarchives.org/ore/0.2/rdfsyntax</a>
+ * </ul>
+ * 
+ * @author Oskar Grenholm, National Library of Sweden
+ */
 public interface ResourceMapSerializer {
 
 	public void serializeToFile(File file, ResourceMap map) throws IOException;

src/main/java/se/kb/oai/ore/Type.java

@@ -16,6 +16,12 @@
 
 package se.kb.oai.ore;
 
+/**
+ * Class that are used for typing <code>Aggreagations</code> and
+ * <code>AggreagatedResources</code>.
+ * 
+ * @author Oskar Grenholm, National Library of Sweden
+ */
 public class Type {
 
 	private String value;

src/main/java/se/kb/oai/ore/impl/AtomConstants.java

@@ -22,6 +22,11 @@ import org.dom4j.QName;
 
 import se.kb.oai.ore.OREConstants;
 
+/**
+ * Constants concerning Atom feeds.
+ * 
+ * @author Oskar Grenholm, National Library of Sweden
+ */
 public class AtomConstants extends OREConstants {
 
 	public static final SimpleDateFormat DATE_FORMAT = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss'Z'");

src/main/java/se/kb/oai/ore/impl/AtomFactory.java

@@ -40,6 +40,13 @@ import static se.kb.oai.ore.OREConstants.RDF_NS_PREFIX;
 import static se.kb.oai.ore.OREConstants.RDF_NS_URI;
 import static se.kb.oai.ore.impl.AtomConstants.*;
 
+/**
+ * The <code>AtomFactory</code> class implements the {@link se.kb.oai.ore.ResourceMapFactory} 
+ * interface to provide the functionality to parse Atom feeds and turn them into
+ * <code>ResourceMap</code> objects.
+ * 
+ * @author Oskar Grenholm, National Library of Sweden
+ */
 public class AtomFactory extends FactoryBase {
 	
 	@Override

src/main/java/se/kb/oai/ore/impl/AtomSerializer.java

@@ -29,6 +29,13 @@ import se.kb.oai.ore.Type;
 
 import static se.kb.oai.ore.impl.AtomConstants.*;
 
+/**
+ * The <code>AtomSerializer</code> class implements the {@link se.kb.oai.ore.ResourceMapSerializer} 
+ * interface to provide the functionality of serializing <code>ResourceMap</code> objects into
+ * Atom feeds.
+ * 
+ * @author Oskar Grenholm, National Library of Sweden
+ */
 public class AtomSerializer extends SerializerBase {
 			
 	@Override

src/main/java/se/kb/oai/ore/impl/FactoryBase.java

@@ -28,6 +28,11 @@ import se.kb.oai.OAIException;
 import se.kb.oai.ore.ResourceMap;
 import se.kb.oai.ore.ResourceMapFactory;
 
+/**
+ * Abstract base class for the different <code>ResourceMapFactory</code> implementations.
+ * 
+ * @author Oskar Grenholm, National Library of Sweden
+ */
 public abstract class FactoryBase implements ResourceMapFactory {
 
 	public ResourceMap newResourceMap(String uri) throws URISyntaxException {

src/main/java/se/kb/oai/ore/impl/SerializerBase.java

@@ -26,6 +26,11 @@ import se.kb.oai.ore.ResourceMap;
 import se.kb.oai.ore.ResourceMapSerializer;
 import se.kb.xml.XMLUtils;
 
+/**
+ * Abstract base class for the different <code>ResourceMapSerializer</code> implementations.
+ * 
+ * @author Oskar Grenholm, National Library of Sweden
+ */
 public abstract class SerializerBase implements ResourceMapSerializer {
 
 	public void serializeToFile(File file, ResourceMap map) throws IOException {