Added Javadocs for all classes in se.kb.oai.pmh.*

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

src/main/java/se/kb/oai/pmh/ErrorResponseException.java

@@ -16,12 +16,35 @@
 
 package se.kb.oai.pmh;
 
+import org.dom4j.Element;
+
 import se.kb.oai.OAIException;
 
+/**
+ * Exception that is thrown when the response from the OAI-PMH server
+ * has <code>&lt;error&gt;</code> elements in it.
+ * 
+ * There are eight different error codes returned:
+ * 
+ * <ul>
+ * 	<li> badArgument
+ * 	<li> badResumptionToken
+ * 	<li> badVerb
+ * 	<li> cannotDisseminateFormat
+ * 	<li> idDoesNotExist
+ * 	<li> noRecordsMatch
+ * 	<li> noMetadataFormats
+ * 	<li> noSetHierarchy
+ * </ul>
+ * 
+ * @author Oskar Grenholm, National Library of Sweden
+ */
 public class ErrorResponseException extends OAIException {
 	
 	private static final long serialVersionUID = -2010182612617642664L;
 	
+	private static final String ERROR_CODE_ATTR = "code";
+	
 	public static final String BAD_ARGUMENT = "badArgument";
 	public static final String BAD_RESUMPTION_TOKEN = "badResumptionToken";
 	public static final String BAD_VERB = "badVerb";
@@ -34,16 +57,32 @@ public class ErrorResponseException extends OAIException {
 	private String code;
 	private String message;
 	
-	public ErrorResponseException(String code, String message) {
+	/**
+	 * Creates an <code>ErrorResponseException</code> with 
+	 * the returned error code and error message.
+	 * 
+	 * @param error the <code>&lt;error&gt;</code> element
+	 */
+	public ErrorResponseException(Element error) {
 		super();
-		this.code = code;
-		this.message = message;
+		this.code = error.attributeValue(ERROR_CODE_ATTR);
+		this.message = error.getTextTrim();
 	}
 
+	/**
+	 * Get the error code.
+	 * 
+	 * @return the error code
+	 */
 	public String getCode() {
 		return code;
 	}
 
+	/**
+	 * Get the error message.
+	 * 
+	 * @return the error message
+	 */
 	public String getMessage() {
 		return message;
 	}	

src/main/java/se/kb/oai/pmh/Header.java

@@ -16,7 +16,6 @@
 
 package se.kb.oai.pmh;
 
-
 import static se.kb.oai.pmh.ResponseBase.*;
 
 import java.util.List;
@@ -26,6 +25,13 @@ import org.dom4j.Node;
 
 import se.kb.xml.XPathWrapper;
 
+/**
+ * Class that holds the information returned in the <code>&lt;header&gt;</code> 
+ * part of a response. The verbs that has responses that includes a header
+ * are <code>GetRecord</code>, <code>ListRecords</code> and <code>ListIdentifiers</code>.
+ * 
+ * @author Oskar Grenholm, National Library of Sweden
+ */
 public class Header {
     
     private static final String IDENTIFIER_XPATH = "oai:identifier";
@@ -36,6 +42,11 @@ public class Header {
     private String datestamp;
     private List<String> setSpecs;
     
+    /**
+     * Creates a <code>Header</code> object.
+     * 
+     * @param node the <code>&lt;header&gt;</code> node
+     */
     public Header(Node node) {
         XPathWrapper xpath = new XPathWrapper(node);
         xpath.addNamespace(OAI_NS_PREFIX, OAI_NS_URI);
@@ -48,14 +59,29 @@ public class Header {
         }
     }
 
+    /**
+     * Get the identifier.
+     * 
+     * @return the identifier
+     */
     public String getIdentifier() {
         return identifier;
     }
     
+    /**
+     * Get the datestamp.
+     * 
+     * @return the datestamp
+     */
     public String getDatestamp() {
         return datestamp;
     }    
 
+    /**
+     * Get a list of sets.
+     * 
+     * @return a list of sets
+     */
     public List<String> getSetSpecs() {
         return setSpecs;
     }

src/main/java/se/kb/oai/pmh/Identification.java

@@ -23,6 +23,11 @@ import org.dom4j.Document;
 import org.dom4j.Element;
 import org.dom4j.Node;
 
+/**
+ * Class that represents the information returned from an <code>Identify</code> request.
+ *  
+ * @author Oskar Grenholm, National Library of Sweden
+ */
 public class Identification extends ResponseBase {
 
     private static final String REPOSITORYNAME_XPATH = "oai:Identify/oai:repositoryName";
@@ -45,6 +50,13 @@ public class Identification extends ResponseBase {
     private List<Element> descriptions;
     private List<String> adminEmails;
     
+    /**
+     * Creates an <code>Identification</code> from the returned response.
+     * 
+     * @param document the response
+     * 
+     * @throws ErrorResponseException
+     */
     public Identification(Document document) throws ErrorResponseException {
         super(document);
         
@@ -67,38 +79,93 @@ public class Identification extends ResponseBase {
         }
     }
 
+    /**
+     * Get a list of e-mails to the administrators of this repository.
+     * 
+     * @return a list of e-mails
+     */
     public List<String> getAdminEmails() {
         return adminEmails;
     }
 
+    /**
+     * Get the base URL of the repository.
+     * 
+     * @return the base URL
+     */
     public String getBaseUrl() {
         return baseUrl;
     }
 
+    /**
+     * Get the compression type supported by this repository.
+     * 
+     * @return the compression
+     */
     public String getCompression() {
         return compression;
     }
 
+    /**
+     * Get the support for deletes this repository has.
+     * Legitimate values are: 
+     * <ul>
+     * 	<li>no 
+     * 	<li>transient
+     * 	<li>persistent
+     * </ul>
+     * 
+     * @return the deleted record support
+     */
     public String getDeletedRecord() {
         return deletedRecord;
     }
 
+    /**
+     * Get a list of descriptions of this repositories. Can be in any xml-format.
+     * 
+     * @return a list of descriptions
+     */
     public List<Element> getDescriptions() {
         return descriptions;
     }
 
+    /**
+     * Get the earliest datestamp that exists in the repository.
+     * 
+     * @return the earliest datestamp
+     */
     public String getEarliestDatestamp() {
         return earliestDatestamp;
     }
 
+    /**
+     * Get the granularity for datestamps in the repository. Two possible values:
+     * <ul>
+     * 	<li> <code>YYYY-MM-DD</code>, meaning day granularity 
+     * 	<li> <code>YYYY-MM-DDThh:mm:ssZ</code>, meaning second granularity
+     * </ul>
+     * 
+     * @return the granularity
+     */
     public String getGranularity() {
         return granularity;
     }
 
+    /**
+     * Get the protocol version of OAI-PMH this repository supports.
+     * 
+     * @return the version
+     */
     public String getProtocolVersion() {
         return protocolVersion;
     }
 
+    /**
+     * Get the name of this repository.
+     * 
+     * @return the name
+     */
     public String getRepositoryName() {
         return repositoryName;
     }    

src/main/java/se/kb/oai/pmh/IdentifiersList.java

@@ -22,12 +22,23 @@ import java.util.List;
 import org.dom4j.Document;
 import org.dom4j.Node;
 
+/**
+ * Class that represents the response from a <code>ListIdentifiers</code> request.
+ * 
+ * @author Oskar Grenholm, National Library of Sweden
+ */
 public class IdentifiersList extends ResponseBase {
 
     private static final String HEADER_XPATH = "oai:ListIdentifiers/oai:header";
       
     private List<Header> headers;
     
+    /**
+     * Creates an <code>IdentifiersList</code> from the returned response.
+     * 
+     * @param document the response
+     * @throws ErrorResponseException
+     */
     public IdentifiersList(Document document) throws ErrorResponseException {
         super(document);
 
@@ -37,14 +48,30 @@ public class IdentifiersList extends ResponseBase {
         } 
     }
     
+    /**
+     * Get the size of the list.
+     * 
+     * @return the size
+     */
     public int size() {
         return headers.size();
     }
     
+    /**
+     * Get the identifiers as a list of <code>Headers</code>.
+     * 
+     * @return a list of identifiers
+     */
     public List<Header> asList() {
         return headers;
     }
     
+    /**
+     * Get the <code>ResumptionToken</code>, if any, for this response.
+     * 
+     * @return the <code>ResumptionToken</code>, or <code>null</code>
+     * if none available
+     */
     public ResumptionToken getResumptionToken() {
         if (super.resumptionToken == null 
                 || super.resumptionToken.getId() == null  

src/main/java/se/kb/oai/pmh/MetadataFormat.java

@@ -22,6 +22,12 @@ import org.dom4j.Node;
 
 import se.kb.xml.XPathWrapper;
 
+/**
+ * This class has the information for a specific metadata format that 
+ * exists in the repository.
+ * 
+ * @author Oskar Grenholm, National Library of Sweden
+ */
 public class MetadataFormat {
 
     private static final String PREFIX_XPATH = "oai:metadataPrefix";
@@ -31,7 +37,13 @@ public class MetadataFormat {
     private String prefix;
     private String schema;
     private String namespace;
-    
+   
+    /**
+     * Create a <code>MetadataFormat</code> from a <code>&lt;metadataFormat&gt;</code> 
+     * node from the response.
+     * 
+     * @param node a <code>metadataFormat</code> node
+     */
     public MetadataFormat(Node node) {
         XPathWrapper xpath = new XPathWrapper(node);
         xpath.addNamespace(OAI_NS_PREFIX, OAI_NS_URI);
@@ -41,14 +53,29 @@ public class MetadataFormat {
         this.namespace = xpath.valueOf(NAMESPACE_XPATH);
     }   
 
+    /**
+     * Get the prefix for the metadata format in the repository.
+     * 
+     * @return the prefix
+     */
     public String getPrefix() {
         return prefix;
     }
 
+    /**
+     * Get the schema for the metadata format.
+     * 
+     * @return the schema
+     */
     public String getSchema() {
         return schema;
     }
     
+    /**
+     * Get the namespace for the metadata format.
+     * 
+     * @return the namespace
+     */
     public String getNamespace() {
         return namespace;
     }   

src/main/java/se/kb/oai/pmh/MetadataFormatsList.java

@@ -22,12 +22,24 @@ import java.util.List;
 import org.dom4j.Document;
 import org.dom4j.Node;
 
+/**
+ * This class represents the response from a <code>ListMetadataFormats</code> request 
+ * to the OAI-PMH server.
+ * 
+ * @author Oskar Grenholm, National Library of Sweden
+ */
 public class MetadataFormatsList extends ResponseBase {
 
     private static final String METADATAFORMAT_XPATH = "oai:ListMetadataFormats/oai:metadataFormat";
     
     private List<MetadataFormat> metadataFormats;
     
+    /**
+     * Creates a <code>MetadataFormatsList</code> from the returned response.
+     * 
+     * @param document the response
+     * @throws ErrorResponseException
+     */
     public MetadataFormatsList(Document document) throws ErrorResponseException {
         super(document);
         
@@ -37,10 +49,20 @@ public class MetadataFormatsList extends ResponseBase {
         }
     }
     
+    /**
+     * Get the size of the list.
+     * 
+     * @return the size
+     */
     public int size() {
         return metadataFormats.size();
     }
     
+    /**
+     * Get the metadata formats as a list of <code>MetadataFormats</code>.
+     * 
+     * @return a list of metadata formats
+     */
     public List<MetadataFormat> asList() {
         return metadataFormats;
     } 

src/main/java/se/kb/oai/pmh/OaiPmhServer.java

@@ -24,13 +24,15 @@ import org.dom4j.io.SAXReader;
 import se.kb.oai.OAIException;
 
 /**
- * Class that acts as a facade for an OAI-PMH server. 
+ * Class that acts as a facade for an OAI-PMH server. Has methods 
+ * that corresponds to the different verbs in the OAI-PMH specification 
+ * and that will return appropriate objects based on the response.
+ * <p>
+ * For more about the different verbs, requests and responses in the OAI-PMH specification,
+ * see <a href="http://www.openarchives.org/OAI/openarchivesprotocol.html">
+ * http://www.openarchives.org/OAI/openarchivesprotocol.html</a>. 
  * 
- * Has methods that corresponds to the different verbs in the OAI-PMH 
- * specification and that will return appropriate objects based on 
- * the response.
- * 
- * @author oskar
+ * @author Oskar Grenholm, National Library of Sweden
  */
 public class OaiPmhServer {
     
@@ -40,7 +42,7 @@ public class OaiPmhServer {
     /**
      * Creates an <code>OaiPmhServer</code> with the given base URL.
      * 
-     * @param url Base URL that points to an OAI-PMH server.
+     * @param url base URL that points to an OAI-PMH server
      */
     public OaiPmhServer(String url) {
         this.builder = new QueryBuilder(url);
@@ -50,16 +52,31 @@ public class OaiPmhServer {
     /**
      * Creates an <code>OaiPmhServer</code> with the given base URL.
      * 
-     * @param url Base URL that points to an OAI-PMH server.
+     * @param url base URL that points to an OAI-PMH server
      */
     public OaiPmhServer(URL url) {
         this(url.toString());
     }
     
+    /**
+     * Get the base URL to the OAI-PMH server.
+     * 
+     * @return the base URL
+     */
     public String getBaseUrl() {
-        return builder.getBasesurl();
+        return builder.getBaseUrl();
     }
     
+    /**
+     * Send a GetRecord request to the OAI-PMH server with
+     * the specified parameters.
+     * 
+     * @param identifier id to get a Record for
+     * @param metadataPrefix which metadata format 
+     * 
+     * @return the response from the server
+     * @throws OAIException
+     */
     public Record getRecord(String identifier, String metadataPrefix) throws OAIException {
         try {
         	String query = builder.buildGetRecordQuery(identifier, metadataPrefix);
@@ -72,6 +89,12 @@ public class OaiPmhServer {
         }
     }
     
+    /**
+     * Send a request for the OAI-PMH server to Identify it self.
+     * 
+     * @return the response from the server
+     * @throws OAIException
+     */
     public Identification identify() throws OAIException {
         try {
         	String query = builder.buildIdentifyQuery();
@@ -84,10 +107,31 @@ public class OaiPmhServer {
         }   
     }
     
+    /**
+     * Send a request to the OAI-PMH server that it should list all 
+     * identifiers that has metadata in the specified format.
+     * 
+     * @param metadataPrefix which metadata format
+     * 
+     * @return a list of identifiers
+     * @throws OAIException
+     */
     public IdentifiersList listIdentifiers(String metadataPrefix) throws OAIException {
         return listIdentifiers(metadataPrefix, null, null, null);
     }
            
+    /**
+     * Send a request to the OAI-PMH server that it should list all 
+     * identifiers that matches the given parameters.
+     * 
+     * @param metadataPrefix which metadata format
+     * @param from a start date, optional (may be <code>null</code>)
+     * @param until a stop date, optional (may be <code>null</code>)
+     * @param set a specific set, optional (may be <code>null</code>)
+     * 
+     * @return a list of identifiers
+     * @throws OAIException
+     */
     public IdentifiersList listIdentifiers(String metadataPrefix, String from, String until, String set) throws OAIException {
         try {
         	String query = builder.buildListIdentifiersQuery(metadataPrefix, from, until, set);
@@ -100,6 +144,15 @@ public class OaiPmhServer {
         }   
     }
     
+    /**
+     * List next set of identifiers not returned in the previous response from 
+     * a call to listIdentifiers().  
+     * 
+     * @param resumptionToken a resumption token returned from a previous call
+     * 
+     * @return a list of identifiers
+     * @throws OAIException
+     */
     public IdentifiersList listIdentifiers(ResumptionToken resumptionToken) throws OAIException {
         try {
         	String query = builder.buildListIdentifiersQuery(resumptionToken);
@@ -112,10 +165,29 @@ public class OaiPmhServer {
         }   
     }
     
+    /**
+     * Send a request for the OAI-PMH server to return a list of Records.
+     * 
+     * @param metadataPrefix which metadata format
+     * 
+     * @return a list of records
+     * @throws OAIException
+     */
     public RecordsList listRecords(String metadataPrefix) throws OAIException {
         return listRecords(metadataPrefix, null, null, null);
     }
     
+    /**
+     * Send a request for the OAI-PMH server to return a list of Records.
+     * 
+     * @param metadataPrefix which metadata format
+     * @param from a start date, optional (may be <code>null</code>)
+     * @param until a stop date, optional (may be <code>null</code>)
+     * @param set a specific set, optional (may be <code>null</code>)
+     * 
+     * @return a lsit of records
+     * @throws OAIException
+     */
     public RecordsList listRecords(String metadataPrefix, String from, String until, String set) throws OAIException {
         try {
         	String query = builder.buildListRecordsQuery(metadataPrefix, from, until, set);
@@ -128,6 +200,15 @@ public class OaiPmhServer {
         }
     }
     
+    /**
+     * List next set of records not returned in the previous response from 
+     * a call to listRecords().  
+     * 
+     * @param resumptionToken a resumption token returned from a previous call
+     * 
+     * @return a list of records
+     * @throws OAIException
+     */
     public RecordsList listRecords(ResumptionToken resumptionToken) throws OAIException {
         try {
         	String query = builder.buildListRecordsQuery(resumptionToken);
@@ -140,10 +221,23 @@ public class OaiPmhServer {
         }
     }
     
+    /**
+     * Ask the OAI-PMH server to list all metadata formats it holds.
+     * 
+     * @return a list of available metadata formats 
+     * @throws OAIException
+     */
     public MetadataFormatsList listMetadataFormats() throws OAIException {
         return listMetadataFormats(null);
     }
     
+    /**
+     * Ask the OAI-PMH server to list all metadata formats it holds
+     * for the specified identifier.
+     * 
+     * @return a list of available metadata formats 
+     * @throws OAIException
+     */
     public MetadataFormatsList listMetadataFormats(String identifier) throws OAIException {
         try {
         	String query = builder.buildListMetadataFormatsQuery(identifier);
@@ -156,6 +250,12 @@ public class OaiPmhServer {
         }   
     }
     
+    /**
+     * List all sets the OAI-PMH server has.
+     * 
+     * @return a list of sets
+     * @throws OAIException
+     */
     public SetsList listSets() throws OAIException {
         try {
         	String query = builder.buildListSetsQuery();
@@ -168,6 +268,15 @@ public class OaiPmhServer {
         }   
     }    
     
+    /**
+     * List next set of sets not returned in the previous response from 
+     * a call to listSets().  
+     * 
+     * @param resumptionToken
+     * 
+     * @return a list of sets
+     * @throws OAIException
+     */
     public SetsList listSets(ResumptionToken resumptionToken) throws OAIException {
         try {
         	String query = builder.buildListSetsQuery(resumptionToken);

src/main/java/se/kb/oai/pmh/QueryBuilder.java

@@ -16,6 +16,12 @@
 
 package se.kb.oai.pmh;
 
+/**
+ * Helper class that builds the URL:s that corresponds to the different requests to the 
+ * OAI-PMH server.
+ * 
+ * @author Oskar Grenholm, National Library of Sweden
+ */
 public class QueryBuilder {
 
 	private enum Verb { Identify, GetRecord, ListIdentifiers, ListMetadataFormats, ListRecords, ListSets }
@@ -33,31 +39,66 @@ public class QueryBuilder {
 	private static final String RESUMPTION_TOKEN = "resumptionToken";
 	
 	private String basesurl;
+	private String extendedBasesurl;
 	
+	/**
+	 * Creates a <code>QueryBuilder</code> for a specific OAI-PMH server.
+	 * 
+	 * @param baseurl the base URL to the OAI-PMH server
+	 */
 	public QueryBuilder(String baseurl) {
-		this.basesurl = baseurl + QUESTION_MARK + VERB + EQUAL_SIGN;
+		this.basesurl = baseurl;
+		this.extendedBasesurl = baseurl + QUESTION_MARK + VERB + EQUAL_SIGN;
 	}
 	
-	public String getBasesurl() {
+	/**
+	 * Get the base URL.
+	 * 
+	 * @return the base URL
+	 */
+	public String getBaseUrl() {
 		return basesurl;
 	}
 
+	/**
+	 * Build the query for a <code>GetRecord</code> request.
+	 * 
+	 * @param identifier the identifier
+	 * @param metadataPrefix the metadata prefix
+	 * 
+	 * @return the full query URL as a <code>String</code>
+	 */
 	public String buildGetRecordQuery(String identifier, String metadataPrefix) {
-		StringBuffer buffer = new StringBuffer(basesurl);
+		StringBuffer buffer = new StringBuffer(extendedBasesurl);
 		buffer.append(Verb.GetRecord);
 		buffer.append(AMPERSAND).append(IDENTIFIER).append(EQUAL_SIGN).append(identifier);
 		buffer.append(AMPERSAND).append(METADATA_PREFIX).append(EQUAL_SIGN).append(metadataPrefix);
 		return buffer.toString();
 	}
 	
+	/**
+	 * Build the query for a <code>Identify</code> request.
+	 * 
+	 * @return the full query URL as a <code>String</code>
+	 */
 	public String buildIdentifyQuery() {
-		StringBuffer buffer = new StringBuffer(basesurl);
+		StringBuffer buffer = new StringBuffer(extendedBasesurl);
 		buffer.append(Verb.Identify);
 		return buffer.toString();
 	}
 	
+	/**
+	 * Build the query for a <code>ListIdentifiers</code> request.
+	 * 
+	 * @param metadataPrefix which metadata format
+     * @param from a start date, optional (may be <code>null</code>)
+     * @param until a stop date, optional (may be <code>null</code>)
+     * @param set a specific set, optional (may be <code>null</code>)
+     * 
+	 * @return the full query URL as a <code>String</code>
+	 */
 	public String buildListIdentifiersQuery(String metadataPrefix, String from, String until, String set) {
-		StringBuffer buffer = new StringBuffer(basesurl);
+		StringBuffer buffer = new StringBuffer(extendedBasesurl);
 		buffer.append(Verb.ListIdentifiers);
 		buffer.append(AMPERSAND).append(METADATA_PREFIX).append(EQUAL_SIGN).append(metadataPrefix);
 		if (from != null)
@@ -69,23 +110,47 @@ public class QueryBuilder {
 		return buffer.toString();
 	}
 	
+	/**
+	 * Build the query for an additional <code>ListIdentifiers</code> request 
+	 * with a <code>ResumptionToken</code>. 
+	 * 
+	 * @param token a resumption token returned from a previous request
+	 * @return the full query URL as a <code>String</code>
+	 */
 	public String buildListIdentifiersQuery(ResumptionToken token) {
-		StringBuffer buffer = new StringBuffer(basesurl);
+		StringBuffer buffer = new StringBuffer(extendedBasesurl);
 		buffer.append(Verb.ListIdentifiers);
 		buffer.append(AMPERSAND).append(RESUMPTION_TOKEN).append(EQUAL_SIGN).append(token.getId());
 		return buffer.toString();
 	}
 	
+	/**
+	 * Build the query for a <code>ListMetadtaFormats</code> request.
+	 * 
+	 * @param identifier the id, optional (may be <code>null</code>)
+	 * 
+	 * @return the full query URL as a <code>String</code>
+	 */
 	public String buildListMetadataFormatsQuery(String identifier) {
-		StringBuffer buffer = new StringBuffer(basesurl);
+		StringBuffer buffer = new StringBuffer(extendedBasesurl);
 		buffer.append(Verb.ListMetadataFormats);
 		if (identifier != null)
 			buffer.append(AMPERSAND).append(IDENTIFIER).append(EQUAL_SIGN).append(identifier);
 		return buffer.toString();
 	}
 	
+	/**
+	 * Build the query for a <code>ListRecords</code> request.
+	 * 
+	 * @param metadataPrefix which metadata format
+     * @param from a start date, optional (may be <code>null</code>)
+     * @param until a stop date, optional (may be <code>null</code>)
+     * @param set a specific set, optional (may be <code>null</code>)
+	 * 
+	 * @return the full query URL as a <code>String</code>
+	 */
 	public String buildListRecordsQuery(String metadataPrefix, String from, String until, String set) {
-		StringBuffer buffer = new StringBuffer(basesurl);
+		StringBuffer buffer = new StringBuffer(extendedBasesurl);
 		buffer.append(Verb.ListRecords);
 		buffer.append(AMPERSAND).append(METADATA_PREFIX).append(EQUAL_SIGN).append(metadataPrefix);
 		if (from != null)
@@ -97,21 +162,40 @@ public class QueryBuilder {
 		return buffer.toString();
 	}
 	
+	/**
+	 * Build the query for an additional <code>ListRecords</code> request 
+	 * with a <code>ResumptionToken</code>. 
+	 * 
+	 * @param token a resumption token returned from a previous request
+	 * @return the full query URL as a <code>String</code>
+	 */
 	public String buildListRecordsQuery(ResumptionToken token) {
-		StringBuffer buffer = new StringBuffer(basesurl);
+		StringBuffer buffer = new StringBuffer(extendedBasesurl);
 		buffer.append(Verb.ListRecords);
 		buffer.append(AMPERSAND).append(RESUMPTION_TOKEN).append(EQUAL_SIGN).append(token.getId());
 		return buffer.toString();
 	}
 	
+	/**
+	 * Build the query for a <code>ListSets</code> request.
+	 * 
+	 * @return the full query URL as a <code>String</code>
+	 */
 	public String buildListSetsQuery() {
-		StringBuffer buffer = new StringBuffer(basesurl);
+		StringBuffer buffer = new StringBuffer(extendedBasesurl);
 		buffer.append(Verb.ListSets);
 		return buffer.toString();
 	}
 	
+	/**
+	 * Build the query for an additional <code>ListSets</code> request 
+	 * with a <code>ResumptionToken</code>. 
+	 * 
+	 * @param token a resumption token returned from a previous request
+	 * @return the full query URL as a <code>String</code>
+	 */
 	public String buildListSetsQuery(ResumptionToken token) {
-		StringBuffer buffer = new StringBuffer(basesurl);
+		StringBuffer buffer = new StringBuffer(extendedBasesurl);
 		buffer.append(Verb.ListSets);
 		buffer.append(AMPERSAND).append(RESUMPTION_TOKEN).append(EQUAL_SIGN).append(token.getId());
 		return buffer.toString();

src/main/java/se/kb/oai/pmh/Record.java

@@ -25,6 +25,13 @@ import org.dom4j.Node;
 import se.kb.xml.XMLUtils;
 import se.kb.xml.XPathWrapper;
 
+/**
+ * The <code>Record</code> class represents the data returned for a 
+ * <code>GetRecord</code> or <code>ListRecords</code> request. It 
+ * holds the actual metadata content.
+ * 
+ * @author Oskar Grenholm, National Library of Sweden
+ */
 public class Record extends ResponseBase {
 
     private static final String RECORD_XPATH = "oai:GetRecord/oai:record";
@@ -36,10 +43,26 @@ public class Record extends ResponseBase {
     private Element metadata;
     private Element about;
     
+    /**
+     * Creates a <code>Record</code> from the response from a 
+     * <code>GetRecord</code> request.
+     * 
+     * @param document the response
+     * @throws ErrorResponseException
+     */
     public Record(Document document) throws ErrorResponseException {               
         this(document, null); 
     }  
     
+    /**
+     * Creates a <code>Record</code> from  from a <code>ListRecords</code> 
+     * response and a specific <code>&lt;record&gt;</code> element in that
+     * response. 
+     * 
+     * @param document the response
+     * @param record a <code>&lt;record&gt;</code> element
+     * @throws ErrorResponseException
+     */
     public Record(Document document, Node record) throws ErrorResponseException {
         super(document);
         
@@ -55,18 +78,40 @@ public class Record extends ResponseBase {
         this.about = xpath.selectSingleElement(ABOUT_XPATH);  
     }    
     
+    /**
+     * Get the <code>Header</code> with the information 
+     * about this <code>Record</code>.
+     * 
+     * @return a <code>Header</code> 
+     */
     public Header getHeader() {
         return header;
     }
 
+    /**
+     * Get the metadata contained in the <code>metadata</code> element
+     * of this <code>Record</code>.
+     * 
+     * @return the metadata as xml
+     */
     public Element getMetadata() {
         return metadata;
     }
     
+    /**
+    * Get the xml representation of the metadata as a <code>String</code>.
+    * 
+    * @return the metadata as a <code>String</code>
+    */
     public String getMetadataAsString() throws IOException {
     	return XMLUtils.xmlToString(getMetadata());
     }
 
+    /**
+     * Get the information about this <code>Record</code>.
+     * 
+     * @return the about information
+     */
     public Element getAbout() {
         return about;
     }    

src/main/java/se/kb/oai/pmh/RecordsList.java

@@ -22,12 +22,23 @@ import java.util.List;
 import org.dom4j.Document;
 import org.dom4j.Node;
 
+/**
+ * Class that represents the response from a <code>ListRecords</code> request.
+ * 
+ * @author Oskar Grenholm, National Library of Sweden
+ */
 public class RecordsList extends ResponseBase {
 
     private static final String RECORD_XPATH = "oai:ListRecords/oai:record";
     
     private List<Record> records;
-    
+
+    /**
+     * Creates a <code>RecordsList</code> from the returned response.
+     * 
+     * @param document the response
+     * @throws ErrorResponseException
+     */    
     public RecordsList(Document document) throws ErrorResponseException {
         super(document);
         
@@ -37,14 +48,30 @@ public class RecordsList extends ResponseBase {
         }      
     }
     
+    /**
+     * Get the size of the list.
+     * 
+     * @return the size
+     */
     public int size() {
         return records.size();
     }
     
+    /**
+     * Get the records as a list of <code>Records</code>.
+     * 
+     * @return a list of records
+     */
     public List<Record> asList() {
         return records;
     }
     
+    /**
+     * Get the <code>ResumptionToken</code>, if any, for this response.
+     * 
+     * @return the <code>ResumptionToken</code>, or <code>null</code>
+     * if none available
+     */
     public ResumptionToken getResumptionToken() {
         if (super.resumptionToken == null 
                 || super.resumptionToken.getId() == null  

src/main/java/se/kb/oai/pmh/ResponseBase.java

@@ -21,13 +21,18 @@ import org.dom4j.Element;
 
 import se.kb.xml.XPathWrapper;
 
+/**
+ * Abstract base class that represents a response from the OAI-PMH server.
+ * 
+ * @author Oskar Grenholm, National Library of Sweden
+ */
 public abstract class ResponseBase {
 
     public static final String OAI_NS_PREFIX = "oai";
     public static final String OAI_NS_URI = "http://www.openarchives.org/OAI/2.0/";
     
-    private static final String RESPONSEDATE_XPATH = "oai:responseDate";
-    private static final String RESUMPTIONTOKEN_XPATH = "*/oai:resumptionToken";
+    private static final String RESPONSE_DATE_XPATH = "oai:responseDate";
+    private static final String RESUMPTION_TOKEN_XPATH = "*/oai:resumptionToken";
     private static final String ERROR_XPATH = "oai:error";
     
     
@@ -36,27 +41,43 @@ public abstract class ResponseBase {
     protected String responseDate;
     protected ResumptionToken resumptionToken;
     
+    /**
+     * Create a <code>ResponseBase</code> from a response. 
+     * 
+     * @param document the response
+     * @throws ErrorResponseException
+     */
     public ResponseBase(Document document) throws ErrorResponseException {
         Element root = document.getRootElement();
         
         this.xpath = new XPathWrapper(root);
         xpath.addNamespace(OAI_NS_PREFIX, OAI_NS_URI);
         this.response = document;        
-        this.responseDate = xpath.valueOf(RESPONSEDATE_XPATH);
+        this.responseDate = xpath.valueOf(RESPONSE_DATE_XPATH);
                 
-        Element token = xpath.selectSingleElement(RESUMPTIONTOKEN_XPATH);
+        Element token = xpath.selectSingleElement(RESUMPTION_TOKEN_XPATH);
         this.resumptionToken = token != null ? new ResumptionToken(token) : null; 
         
         Element error = xpath.selectSingleElement(ERROR_XPATH);
         if (error != null) {
-        	throw new ErrorResponseException(error.attributeValue("code"), error.getTextTrim());
+        	throw new ErrorResponseException(error);
         }
     }    
     
+    /**
+     * Get the xml-document of the full response from the server.
+     * 
+     * @return the response
+     */
     public Document getResponse() {
         return response;
     }
     
+    /**
+     * Get the date the response was returned.
+     * 
+     * @return the response date
+     */
     public String getResponseDate() {
         return responseDate;
     }

src/main/java/se/kb/oai/pmh/ResumptionToken.java

@@ -18,20 +18,52 @@ package se.kb.oai.pmh;
 
 import org.dom4j.Element;
 
+/**
+ * This class represents the <code>resumption token</code> returned from a 
+ * list request when not all of the content of the query fits in one response. 
+ * You can use it to get another response that has the next set of content 
+ * returned from the query. (Which in turn may have a new resumption token.)
+ * <p>
+ * The verbs that has responses that can contain a resumption token are:
+ * <ul>
+ * 	<li> <code>ListIdentifiers</code>
+ * 	<li> <code>ListRecords</code>
+ * 	<li> <code>ListSets</code>
+ * </ul>
+ * 
+ * @author Oskar Grenholm, National Library of Sweden
+ *
+ */
 public class ResumptionToken {
 
     private String id;
     private String expirationDate;
     
+    /**
+     * Create a <code>ResumptionToken</code> from the <code>&lt;resumptionToken&gt;</code>
+     * element of a response.
+     * 
+     * @param element
+     */
     public ResumptionToken(Element element) {
         this.id = element.getTextTrim();
         this.expirationDate = element.attributeValue("expirationDate");
     }    
 
+    /**
+     * Get the id of this resumption token.
+     * 
+     * @return the id
+     */
     public String getId() {
         return id;
     }
     
+    /**
+     * Get the date when this resumption token expires.
+     * 
+     * @return the date
+     */
     public String getExpirationDate() {
         return expirationDate;
     }

src/main/java/se/kb/oai/pmh/Set.java

@@ -26,6 +26,12 @@ import org.dom4j.Node;
 
 import se.kb.xml.XPathWrapper;
 
+/**
+ * A set is a tool for selective harvesting from a repository. A record can
+ * be a member of one or more sets. This class represents a specific set.
+ * 
+ * @author Oskar Grenholm, National Library of Sweden
+ */
 public class Set {
 
     private static final String SPEC_XPATH = "oai:setSpec";
@@ -36,6 +42,12 @@ public class Set {
     private String name;
     private List<Element> descriptions;
     
+    /**
+     * Create a <code>Set</code> from the <code>&lt;set&gt;</code> element 
+     * of a <code>ListSets</code> response.
+     * 
+     * @param node
+     */
     public Set(Node node) {
         XPathWrapper xpath = new XPathWrapper(node);
         xpath.addNamespace(OAI_NS_PREFIX, OAI_NS_URI);
@@ -48,14 +60,30 @@ public class Set {
         }
     }
 
+    /**
+     * Get the set spec (a short name or id for the set).
+     * This is used in the queries that take a set parameter.
+     * 
+     * @return the set spec
+     */
     public String getSpec() {
         return spec;
     }
 
+    /**
+     * Get the name of this set.
+     * 
+     * @return the name
+     */
     public String getName() {
         return name;
     }
     
+    /**
+     * Get the descriptions of this set.
+     * 
+     * @return a list of descriptions
+     */
     public List<Element> getDescriptions() {
         return descriptions;
     }

src/main/java/se/kb/oai/pmh/SetsList.java

@@ -22,12 +22,23 @@ import java.util.List;
 import org.dom4j.Document;
 import org.dom4j.Node;
 
+/**
+ * Class that represents the response from a <code>ListSets</code> request.
+ * 
+ * @author Oskar Grenholm, National Library of Sweden
+ */
 public class SetsList extends ResponseBase {
 
     private static final String SET_XPATH = "oai:ListSets/oai:set";
     
     private List<Set> sets;
     
+    /**
+     * Creates an <code>SetsList</code> from the returned response.
+     * 
+     * @param document the response
+     * @throws ErrorResponseException
+     */
     public SetsList(Document document) throws ErrorResponseException {
         super(document);
         
@@ -37,11 +48,36 @@ public class SetsList extends ResponseBase {
         }
     }
     
+    /**
+     * Get the size of the list.
+     * 
+     * @return the size
+     */
     public int size() {
         return sets.size();
     }
 
+    /**
+     * Get the sets as a list of <code>Sets</code>.
+     * 
+     * @return a list of sets
+     */    
     public List<Set> asList() {
         return sets;
     }
+    
+    /**
+     * Get the <code>ResumptionToken</code>, if any, for this response.
+     * 
+     * @return the <code>ResumptionToken</code>, or <code>null</code>
+     * if none available
+     */
+    public ResumptionToken getResumptionToken() {
+        if (super.resumptionToken == null 
+                || super.resumptionToken.getId() == null  
+                || super.resumptionToken.getId().length() == 0)
+            return null;
+        
+        return super.resumptionToken;
+    }
 }