From fe13c7bc4d9f725e109264ce0f5d78cd2df95ca0 Mon Sep 17 00:00:00 2001 From: bobcat_zed Date: Tue, 18 Mar 2008 14:31:25 +0000 Subject: [PATCH] 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 | 6 ++++++ src/main/java/se/kb/oai/ore/AggregateBase.java | 7 +++++++ .../java/se/kb/oai/ore/AggregatedResource.java | 7 +++++++ src/main/java/se/kb/oai/ore/Aggregation.java | 8 ++++++++ src/main/java/se/kb/oai/ore/Metadata.java | 7 +++++++ src/main/java/se/kb/oai/ore/OREConstants.java | 5 +++++ src/main/java/se/kb/oai/ore/ResourceMap.java | 8 ++++++++ .../java/se/kb/oai/ore/ResourceMapFactory.java | 14 ++++++++++++++ .../java/se/kb/oai/ore/ResourceMapSerializer.java | 13 +++++++++++++ src/main/java/se/kb/oai/ore/Type.java | 6 ++++++ .../java/se/kb/oai/ore/impl/AtomConstants.java | 5 +++++ src/main/java/se/kb/oai/ore/impl/AtomFactory.java | 7 +++++++ .../java/se/kb/oai/ore/impl/AtomSerializer.java | 7 +++++++ src/main/java/se/kb/oai/ore/impl/FactoryBase.java | 5 +++++ .../java/se/kb/oai/ore/impl/SerializerBase.java | 5 +++++ 15 files changed, 110 insertions(+) diff --git a/src/main/java/se/kb/oai/OAIException.java b/src/main/java/se/kb/oai/OAIException.java index 22f134e..10e9581 100644 --- a/src/main/java/se/kb/oai/OAIException.java +++ b/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; diff --git a/src/main/java/se/kb/oai/ore/AggregateBase.java b/src/main/java/se/kb/oai/ore/AggregateBase.java index 5ad28fe..bac3d62 100644 --- a/src/main/java/se/kb/oai/ore/AggregateBase.java +++ b/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. + * Aggregation and AggregatedResource. It can be used to + * get and set Types and Metadata. + * + * @author Oskar Grenholm, National Library of Sweden + */ public abstract class AggregateBase { protected URI id; diff --git a/src/main/java/se/kb/oai/ore/AggregatedResource.java b/src/main/java/se/kb/oai/ore/AggregatedResource.java index 07d8d7e..635d029 100644 --- a/src/main/java/se/kb/oai/ore/AggregatedResource.java +++ b/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 { diff --git a/src/main/java/se/kb/oai/ore/Aggregation.java b/src/main/java/se/kb/oai/ore/Aggregation.java index 6b9621e..c90e361 100644 --- a/src/main/java/se/kb/oai/ore/Aggregation.java +++ b/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 resources; diff --git a/src/main/java/se/kb/oai/ore/Metadata.java b/src/main/java/se/kb/oai/ore/Metadata.java index 4296e6a..8c6a03f 100644 --- a/src/main/java/se/kb/oai/ore/Metadata.java +++ b/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 Aggregation + * or an AggreagatedResource. 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 } diff --git a/src/main/java/se/kb/oai/ore/OREConstants.java b/src/main/java/se/kb/oai/ore/OREConstants.java index 9e53292..7a8d467 100644 --- a/src/main/java/se/kb/oai/ore/OREConstants.java +++ b/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"; diff --git a/src/main/java/se/kb/oai/ore/ResourceMap.java b/src/main/java/se/kb/oai/ore/ResourceMap.java index 66fbaf8..d24a89a 100644 --- a/src/main/java/se/kb/oai/ore/ResourceMap.java +++ b/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. + * ResourceMaps can be serialized to a machine readable format, see {@link ResourceMapSerializer}. + * This class will consist of the Aggregation it describes and some metadata concerning the + * resource map itself. + * + * @author Oskar Grenholm, National Library of Sweden + */ public class ResourceMap { private URI id; diff --git a/src/main/java/se/kb/oai/ore/ResourceMapFactory.java b/src/main/java/se/kb/oai/ore/ResourceMapFactory.java index 10a396b..0f4aee8 100644 --- a/src/main/java/se/kb/oai/ore/ResourceMapFactory.java +++ b/src/main/java/se/kb/oai/ore/ResourceMapFactory.java @@ -24,6 +24,20 @@ import org.dom4j.Element; import se.kb.oai.OAIException; +/** + * A ResourceMapFactory will be used to create a {@link ResourceMap}. + * It can either be a totally new ResourceMap or one that is parsed + * from an existing serialization of a ResourceMap. Different + * implementations of this interface will handle different serialization formats. + *

+ * At the moment the Open Archive Initiative describes two possible formats: + *

+ * + * @author Oskar Grenholm, National Library of Sweden + */ public interface ResourceMapFactory { public ResourceMap newResourceMap(String uri) throws URISyntaxException; diff --git a/src/main/java/se/kb/oai/ore/ResourceMapSerializer.java b/src/main/java/se/kb/oai/ore/ResourceMapSerializer.java index 743a53d..69e3c04 100644 --- a/src/main/java/se/kb/oai/ore/ResourceMapSerializer.java +++ b/src/main/java/se/kb/oai/ore/ResourceMapSerializer.java @@ -21,6 +21,19 @@ import java.io.IOException; import org.dom4j.Element; +/** + * A ResourceMapSerializer 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. + *

+ * At the moment the Open Archive Initiative describes two possible serialization formats: + *

+ * + * @author Oskar Grenholm, National Library of Sweden + */ public interface ResourceMapSerializer { public void serializeToFile(File file, ResourceMap map) throws IOException; diff --git a/src/main/java/se/kb/oai/ore/Type.java b/src/main/java/se/kb/oai/ore/Type.java index 59d12c7..50b72ea 100644 --- a/src/main/java/se/kb/oai/ore/Type.java +++ b/src/main/java/se/kb/oai/ore/Type.java @@ -16,6 +16,12 @@ package se.kb.oai.ore; +/** + * Class that are used for typing Aggreagations and + * AggreagatedResources. + * + * @author Oskar Grenholm, National Library of Sweden + */ public class Type { private String value; diff --git a/src/main/java/se/kb/oai/ore/impl/AtomConstants.java b/src/main/java/se/kb/oai/ore/impl/AtomConstants.java index 5ba0101..8013bb7 100644 --- a/src/main/java/se/kb/oai/ore/impl/AtomConstants.java +++ b/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'"); diff --git a/src/main/java/se/kb/oai/ore/impl/AtomFactory.java b/src/main/java/se/kb/oai/ore/impl/AtomFactory.java index 6847df5..4ef11ed 100644 --- a/src/main/java/se/kb/oai/ore/impl/AtomFactory.java +++ b/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 AtomFactory class implements the {@link se.kb.oai.ore.ResourceMapFactory} + * interface to provide the functionality to parse Atom feeds and turn them into + * ResourceMap objects. + * + * @author Oskar Grenholm, National Library of Sweden + */ public class AtomFactory extends FactoryBase { @Override diff --git a/src/main/java/se/kb/oai/ore/impl/AtomSerializer.java b/src/main/java/se/kb/oai/ore/impl/AtomSerializer.java index 8e3c5b9..eb75376 100644 --- a/src/main/java/se/kb/oai/ore/impl/AtomSerializer.java +++ b/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 AtomSerializer class implements the {@link se.kb.oai.ore.ResourceMapSerializer} + * interface to provide the functionality of serializing ResourceMap objects into + * Atom feeds. + * + * @author Oskar Grenholm, National Library of Sweden + */ public class AtomSerializer extends SerializerBase { @Override diff --git a/src/main/java/se/kb/oai/ore/impl/FactoryBase.java b/src/main/java/se/kb/oai/ore/impl/FactoryBase.java index dfd022b..d82e13d 100644 --- a/src/main/java/se/kb/oai/ore/impl/FactoryBase.java +++ b/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 ResourceMapFactory implementations. + * + * @author Oskar Grenholm, National Library of Sweden + */ public abstract class FactoryBase implements ResourceMapFactory { public ResourceMap newResourceMap(String uri) throws URISyntaxException { diff --git a/src/main/java/se/kb/oai/ore/impl/SerializerBase.java b/src/main/java/se/kb/oai/ore/impl/SerializerBase.java index 420003e..a6a6b76 100644 --- a/src/main/java/se/kb/oai/ore/impl/SerializerBase.java +++ b/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 ResourceMapSerializer implementations. + * + * @author Oskar Grenholm, National Library of Sweden + */ public abstract class SerializerBase implements ResourceMapSerializer { public void serializeToFile(File file, ResourceMap map) throws IOException {