Fleshed out the Javadocs for a bunch of classes in se.kb.oai.ore.* and se.kb.xml.*.

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

pom.xml

@@ -38,6 +38,19 @@
               <target>1.5</target>
           </configuration>
       </plugin>
+      <plugin>
+    	<groupId>org.apache.maven.plugins</groupId>
+    	<artifactId>maven-jar-plugin</artifactId>
+    	<version>2.2</version>
+    	<configuration>
+    		<includes>
+    			<include>**/oai/*.class</include>
+    			<include>**/oai/ore/**</include>
+    			<include>**/oai/pmh/**</include>
+    			<include>**/xml/**</include>
+    		</includes>
+    	</configuration>
+	   </plugin>
     </plugins>
   </build>
   
@@ -51,6 +64,7 @@
         		<value>http://java.sun.com/javase/6/docs/api/</value>
         		<value>http://www.dom4j.org/apidocs/</value>
         	</links>
+        	<excludePackageNames>se.kb.oai.main</excludePackageNames>
         </configuration>
       </plugin>
     </plugins>

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

@@ -35,36 +35,79 @@ public abstract class AggregateBase {
 	protected List<Type> types; 
 	protected List<Metadata> metadata;
 	
+	/**
+	 * Creates an <code>AggregateBase</code> with the specified id.
+	 * 
+	 * @param id the id
+ 	 */
 	public AggregateBase(URI id) {
 		this.id = id;
 		this.types = new LinkedList<Type>();
 		this.metadata = new LinkedList<Metadata>();
 	}
 	
+	/**
+	 * Get the id.
+	 * 
+	 * @return the id
+	 */
 	public URI getId() {
 		return id;
 	}
 	
+	/**
+	 * Set the id.
+	 * 
+	 * @param id the id
+	 */
 	public void setId(URI id) {
 		this.id = id;
 	}
 		
+	/**
+	 * Get all types associated with this object. 
+	 * 
+	 * @return a list of types
+	 */
 	public List<Type> getTypes() {
 		return types;
 	}
 
+	/**
+	 * Set the types associated with this object.
+	 * 
+	 * @param types a list of types
+	 */
 	public void setTypes(List<Type> types) {
 		this.types = types;
 	}
 
+	/**
+	 * Add a <code>Type</code> to this object.
+	 * 
+	 * @param type a type
+	 */
 	public void addType(Type type) {
 		types.add(type);
 	}
 	
+	/**
+	 * Get a list of all the <code>Metadata</code> for this object.
+	 * 
+	 * @return a list with metadata
+	 */
 	public List<Metadata> getMetadata() {
 		return metadata;
 	}
 	
+	/**
+	 * Get a list of only the <code>Metadata</code> that matches 
+	 * the qualified name for this object.
+	 * 
+	 * @param name a qualified name
+	 * 
+	 * @return a list with metadata
+	 */
 	public List<Metadata> getMetadata(QName name) {
 		List<Metadata> list = new LinkedList<Metadata>();
 		for (Metadata meta : metadata) {
@@ -75,10 +118,20 @@ public abstract class AggregateBase {
 		return list;
 	}
 
+	/**
+	 * Set the metadata for this object.
+	 * 
+	 * @param metadata a list with metadata
+	 */
 	public void setMetadata(List<Metadata> metadata) {
 		this.metadata = metadata;
 	}
 	
+	/**
+	 * Add a <code>Metadata</code> to the list of metadata.
+	 * 
+	 * @param meta a metadata
+	 */
 	public void addMetadata(Metadata meta) {
 		metadata.add(meta);
 	}	

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

@@ -31,17 +31,45 @@ import java.net.URISyntaxException;
  */
 public class AggregatedResource extends AggregateBase {
 	
+	/**
+	 * Create an <code>AggreagatedResource</code> with the specified id.
+	 * 
+	 * @param id the id
+	 * 
+	 * @throws URISyntaxException
+	 */
 	public AggregatedResource(String id) throws URISyntaxException {
 		this(new URI(id));
 	}
 	
+
+	/**
+	 * Create an <code>AggreagatedResource</code> with the specified id.
+	 * 
+	 * @param id the id
+	 */
 	public AggregatedResource(URI id) {
 		super(id);
 	}
 		
+	/**
+	 * Get an <code>InputStream</code> for the content held in this 
+	 * <code>AggreagatedResource</code>. 
+	 * 
+	 * @return a stream to the content
+	 * @throws IOException
+	 */
 	public InputStream getContent() throws IOException {
 		return id.toURL().openStream();
 	}
+	
+	/**
+	 * Get a <code>String</code> containing the content for this 
+	 * <code>AggreagatedResource</code>. 
+	 * 
+	 * @return a stream to the content
+	 * @throws IOException
+	 */
 	public String getContentAsString() throws IOException {
 		InputStream in = getContent();
 		ByteArrayOutputStream out = new ByteArrayOutputStream();

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

@@ -33,31 +33,76 @@ public class Aggregation extends AggregateBase {
 
 	private List<AggregatedResource> resources;
 	
+	/**
+	 * Create an <code>Aggregation</code> with the specified id.
+	 * 
+	 * @param id the id
+	 * 
+	 * @throws URISyntaxException
+	 */
 	public Aggregation(String id) throws URISyntaxException {
 		this(new URI(id));
 	}
 	
+	/**
+	 * Create an <code>Aggregation</code> with the specified id.
+	 * 
+	 * @param id the id
+	 */
 	public Aggregation(URI id) {
 		super(id);
 		this.resources = new LinkedList<AggregatedResource>();
 	}
 		
+	/**
+	 * Get the number of resources that this <code>Aggregation</code> has.
+	 * 
+	 * @return the number of resources
+	 */
 	public int numberOfResources() {
 		return resources.size();
 	}
 	
+	/**
+	 * Get this <code>Aggregations</code> list of <code>AggreagatedResources</code>.
+	 * 
+	 * @return a list of resources
+	 */
 	public List<AggregatedResource> getResources() {
 		return resources;
 	}
 		
+	/**
+	 * Get the <code>AggreagatedResource</code> at the specified index.
+	 * (There is no guarantee of the ordering of the resources for different
+	 * parsings of the same resource map!)
+	 * 
+	 * @param index the index
+	 *
+	 * @return the resource
+	 */
 	public AggregatedResource getResource(int index) {
 		return resources.get(index);
 	}
 	
+	/**
+	 * Get the <code>AggreagatedResource</code> with the given id.
+	 * 
+	 * @param id the id of the resource
+	 *
+	 * @return the resource
+	 */
 	public AggregatedResource getResource(String id) throws URISyntaxException {
 		return getResource(new URI(id));
 	}
 	
+	/**
+	 * Get the <code>AggreagatedResource</code> with the given id.
+	 * 
+	 * @param id the id of the resource
+	 *
+	 * @return the resource, or <code>null</code> if no match
+	 */
 	public AggregatedResource getResource(URI id) {
 		for (AggregatedResource resource : resources) {
 			if (resource.getId().equals(id)) {
@@ -67,10 +112,20 @@ public class Aggregation extends AggregateBase {
 		return null;
 	}
 	
+	/**
+	 * Set the list of resources.
+	 * 
+	 * @param resources the list of resources
+	 */
 	public void setResources(List<AggregatedResource> resources) {
 		this.resources = resources;
 	}
 	
+	/**
+	 * Add an <code>AggreagatedResource</code> to this <code>Aggregation</code>.
+	 * 
+	 * @param resource a resource
+	 */
 	public void addResource(AggregatedResource resource) {
 		resources.add(resource);
 	}

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

@@ -21,7 +21,7 @@ import static se.kb.oai.ore.OREConstants.*;
 import org.dom4j.QName;
 
 /**
- * Class that represents metadata that can be set for an <code>Aggregation</code>
+ * Class that represents a metadata element 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.
  * 
@@ -34,23 +34,54 @@ public class Metadata {
 	private QName qname;
 	private String value;
 	
+	/**
+	 * Create a <code>Metadata</code>.
+	 * 
+	 * @param ns a namespace, can only be DC or DCTERMS
+	 * @param name the name of the metadata element
+	 * @param value the value of the metadata
+	 */
 	public Metadata(Namespace ns, String name, String value) {
 		this.qname = getName(ns, name);
 		this.value = value;
 	}
 	
+	/**
+	 * Get the qualified name of this metadata.
+	 * 
+	 * @return the name
+	 */
 	public QName getName() {
 		return qname;
 	}
 	
+	/**
+	 * Get the value of this metadata.
+	 * 
+	 * @return the value
+	 */
 	public String getValue() {
 		return value;
 	}
 	
+	/**
+	 * Set the value.
+	 * 
+	 * @param value the value
+	 */
 	public void setValue(String value) {
 		this.value = value;
 	}
 	
+	/**
+	 * Helper method that creates a qualified name with the given
+	 * namespace and name.
+	 * 
+	 * @param ns a namespace, can only be DC or DCTERMS
+	 * @param name the name
+	 * 
+	 * @return a qualified name
+	 */
 	public static QName getName(Namespace ns, String name) {
 		switch (ns) {
 			case DC: 		

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

@@ -37,59 +37,140 @@ public class ResourceMap {
 	private Date modified;
 	private Aggregation aggregation;
 	
+	/**
+	 * Create an <code>ResourceMap</code> with the specified id.
+	 * 
+	 * @param id the id
+	 * 
+	 * @throws URISyntaxException
+	 */
 	public ResourceMap(String id) throws URISyntaxException {
 		this(new URI(id));
 	}
 	
+	/**
+	 * Create an <code>ResourceMap</code> with the specified id.
+	 * 
+	 * @param id the id
+	 */
 	public ResourceMap(URI id) {
 		this.id = id;
 		this.aggregation = new Aggregation(id.resolve("#aggregation"));
 	}
 	
+	/**
+	 * Get the id.
+	 * 
+	 * @return the id
+	 */
 	public URI getId() {
 		return id;
 	}
 	
+	/**
+	 * Set the id.
+	 * 
+	 * @param id the id
+	 */
 	public void setId(URI id) {
 		this.id = id;
 	}
 	
+	/**
+	 * Get the creator of this resource map. 
+	 * (Note: NOT the creator of the aggregation or the resources.)
+	 * 
+	 * @return the creator
+	 */
 	public String getCreator() {
 		return creator;
 	}
 	
+	/**
+	 * Set the creator of this resource map.
+	 * (Note: NOT the creator of the aggregation or the resources.)
+	 * 
+	 * @param creator the creator
+	 */
 	public void setCreator(String creator) {
 		this.creator = creator;
 	}
 	
+	/**
+	 * Get the rights of this resource map. 
+	 * (Note: NOT the rights of the aggregation or the resources.)
+	 * 
+	 * @return the rights
+	 */
 	public String getRights() {
 		return rights;
 	}
 	
+	/**
+	 * Set the rights of this resource map. 
+	 * (Note: NOT the rights of the aggregation or the resources.)
+	 * 
+	 * @param rights the rights
+	 */
 	public void setRights(String rights) {
 		this.rights = rights;
 	}
 	
+	/**
+	 * Get the creation date of this resource map. 
+	 * (Note: NOT the creation date of the aggregation or the resources.)
+	 * 
+	 * @return the creation date
+	 */
 	public Date getCreated() {
 		return created;
 	}
 	
+	/**
+	 * Set the creation date of this resource map. 
+	 * (Note: NOT the creation date of the aggregation or the resources.)
+	 * 
+	 * @param created the creation date
+	 */
 	public void setCreated(Date created) {
 		this.created = created;
 	}
 	
+
+	/**
+	 * Get the modification date of this resource map. 
+	 * (Note: NOT the modification date of the aggregation or the resources.)
+	 * 
+	 * @return the modification date
+	 */
 	public Date getModified() {
 		return modified;
 	}
 	
+	/**
+	 * Set the modification date of this resource map. 
+	 * (Note: NOT the modification date of the aggregation or the resources.)
+	 * 
+	 * @param modified he modification date
+	 */
 	public void setModified(Date modified) {
 		this.modified = modified;
 	}
 
+	/**
+	 * Get the aggregation that this resource map describes.
+	 * 
+	 * @return the aggregation
+	 */
 	public Aggregation getAggregation() {
 		return aggregation;
 	}
 
+	/**
+	 * Set the aggregation that this resource map describes.
+	 * 
+	 * @param aggregation the aggregation
+	 */
 	public void setAggregation(Aggregation aggregation) {
 		this.aggregation = aggregation;
 	}		

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

@@ -40,13 +40,56 @@ import se.kb.oai.OAIException;
  */
 public interface ResourceMapFactory {
 
+	/**
+	 * Create a new <code>ResourceMap</code> with this id.
+	 * 
+	 * @param uri the id
+	 * 
+	 * @return a new resource map
+	 * @throws URISyntaxException
+	 */
 	public ResourceMap newResourceMap(String uri) throws URISyntaxException;
 	
+	/**
+	 * Create a new <code>ResourceMap</code> with this id.
+	 * 
+	 * @param uri the id
+	 * 
+	 * @return a new resource map
+	 */
 	public ResourceMap newResourceMap(URI uri);
 	
+	/**
+	 * Parse the content of the URL and create a <code>ResourceMap</code>
+	 * from it.
+	 * 
+	 * @param url a URL
+	 * 
+	 * @return a resource map representing the content of the URL
+	 * @throws OAIException
+	 */
 	public ResourceMap getResourceMap(URL url) throws OAIException;
 	
+
+	/**
+	 * Parse the content of the URL and create a <code>ResourceMap</code>
+	 * from it.
+	 * 
+	 * @param url a URL
+	 * 
+	 * @return a resource map representing the content of the URL
+	 * @throws OAIException
+	 */
 	public ResourceMap getResourceMap(String url) throws OAIException;
 	
+
+	/**
+	 * Parse the XML and create a <code>ResourceMap</code> from it.
+	 * 
+	 * @param root a XML element
+	 * 
+	 * @return a resource map representing the content of the XML
+	 * @throws OAIException
+	 */
 	public ResourceMap getResourceMap(Element root) throws OAIException;
 }

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

@@ -36,9 +36,32 @@ import org.dom4j.Element;
  */
 public interface ResourceMapSerializer {
 
+	/**
+	 * Serialize the resource map to the given file.
+	 * 
+	 * @param file a file
+	 * @param map a resource map
+	 * 
+	 * @throws IOException
+	 */
 	public void serializeToFile(File file, ResourceMap map) throws IOException;
 	
+	/**
+	 * Serialize the resource map and return it as a <code>String</code>.
+	 * 
+	 * @param map a resource map
+	 * 
+	 * @return a <code>String</code> with the serialized resource map
+	 * @throws IOException
+	 */
 	public String serializeToString(ResourceMap map) throws IOException;	
 
+	/**
+	 * Serialize the resource map into XML.
+	 * 
+	 * @param map a resource map
+	 * 
+	 * @return an <code>Element</code> containing the result of the serialization
+	 */
 	public Element serializeToXml(ResourceMap map);
 }

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

@@ -17,7 +17,7 @@
 package se.kb.oai.ore;
 
 /**
- * Class that are used for typing <code>Aggreagations</code> and
+ * Class that are used for typing <code>Aggregations</code> and
  * <code>AggreagatedResources</code>.
  * 
  * @author Oskar Grenholm, National Library of Sweden
@@ -26,10 +26,20 @@ public class Type {
 
 	private String value;
 	
+	/**
+	 * Create a typing with this value.
+	 * 
+	 * @param value a value
+	 */
 	public Type(String value) {
 		this.value = value;
 	}
 
+	/**
+	 * Get the value.
+	 * 
+	 * @return the value
+	 */
 	public String getValue() {
 		return value;
 	}

src/main/java/se/kb/xml/XMLUtils.java

@@ -25,10 +25,27 @@ import org.dom4j.Element;
 import org.dom4j.io.OutputFormat;
 import org.dom4j.io.XMLWriter;
 
+/**
+ * Utility class that has some static helper methods for handling XML.
+ * 
+ * @author Oskar Grenholm, National Library of Sweden
+ */
 public class XMLUtils {
 
 	public static final String ENCODING = "UTF-8"; 
 	
+	/* No need for a constructor. */
+	private XMLUtils() {}
+	
+	/**
+	 * Writes the XML contained in the <code>Element</code> to the specified
+	 * <code>OutputStream</code>.
+	 * 
+	 * @param element the XML element to write
+	 * @param stream the stream to write to
+	 * 
+	 * @throws IOException
+	 */
 	public static void writeXmlTo(Element element, OutputStream stream) throws IOException {
 		OutputStreamWriter writer = new OutputStreamWriter(stream, ENCODING);
         OutputFormat format = OutputFormat.createPrettyPrint();
@@ -40,6 +57,14 @@ public class XMLUtils {
         writer.flush();
 	}
 	
+	/**
+	 * Converts an <code>Element</code> to a <code>String</code>. 
+	 * 
+	 * @param xml the XML element to write
+	 * 
+	 * @return a <code>String</code> with the XML
+	 * @throws IOException
+	 */
 	public static String xmlToString(Element xml) throws IOException {
 		ByteArrayOutputStream stream = new ByteArrayOutputStream();
         writeXmlTo(xml, stream);        

src/main/java/se/kb/xml/XPathWrapper.java

@@ -25,41 +25,96 @@ import org.dom4j.Element;
 import org.dom4j.Node;
 import org.dom4j.XPath;
 
+/**
+ * Helper class that eases the job of handling XPath queries and
+ * getting the different results. It wraps a {@link org.dom4j.Node}
+ * and then performs the XPath queries on that.
+ * 
+ * @author Oskar Grenholm, National Library of Sweden
+ */
 public class XPathWrapper {
 
     private Node node;
     private Map<String, String> namespaces;
     
+    /**
+     * Wraps a <code>Node</code> for easier XPath handling.
+     * 
+     * @param node the <code>Node</code> to wrap
+     */
     public XPathWrapper(Node node) {
         this(node, new HashMap<String, String>());
     }
     
+    /**
+     * Creates a <code>XPathWrapper</code> that should be aware of all
+     * the namespaces in the Map when handling XPath queries.
+     * 
+     * @param node the <code>Node</code> to wrap
+     * @param namespaces the namespaces
+     */
     public XPathWrapper(Node node, Map<String, String> namespaces) {
         this.node = node;
         this.namespaces = namespaces;
     }
     
+    /**
+     * Adds a namespace that the wrapper should be aware of when performing 
+     * XPath queries.
+     * 
+     * @param prefix the prefix of the namespace
+     * @param uri the uri of the namespace
+     */
     public void addNamespace(String prefix, String uri) {
         namespaces.put(prefix, uri);
     }
     
+    /**
+     * Selects a single node that matches the given XPath.
+     * 
+     * @param xpathExpression the xpath
+     * 
+     * @return a single <code>Node</code> or <code>null</code> if no match
+     */
     public Node selectSingleNode(String xpathExpression) {
         XPath xpath = createXPath(xpathExpression);
         return xpath.selectSingleNode(node);
     }
     
+    /**
+     * Selects all <code>Nodes</code> that matches the given XPath.
+     * 
+     * @param xpathExpression the xpath
+     * 
+     * @return a list of nodes (can be empty if no matches)
+     */
     @SuppressWarnings("unchecked")
     public List<Node> selectNodes(String xpathExpression) {
         XPath xpath = createXPath(xpathExpression);
         return xpath.selectNodes(node);
     }
     
+    /**
+     * Selects a single result that matches the given XPath and
+     * then casts it into a <code>Element</code>.
+     * 
+     * @param xpathExpression the xpath
+     * 
+     * @return a single <code>Element</code> or <code>null</code> if no match
+     */
     public Element selectSingleElement(String xpathExpression) {
         return (Element) selectSingleNode(xpathExpression);
     }
     
+    /**
+     * Selects the value of the given XPath.
+     * 
+     * @param xpathExpression the xpath
+     * 
+     * @return the value or <code>null</code> if no match 
+     */
     public String valueOf(String xpathExpression) {
-        XPath xpath =createXPath(xpathExpression);
+        XPath xpath = createXPath(xpathExpression);
         return xpath.valueOf(node);
     }