diff --git a/src/main/java/se/kb/oai/pmh/ErrorResponseException.java b/src/main/java/se/kb/oai/pmh/ErrorResponseException.java
index 217cdd1..776e188 100644
--- a/src/main/java/se/kb/oai/pmh/ErrorResponseException.java
+++ b/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 <error>
elements in it.
+ *
+ * There are eight different error codes returned:
+ *
+ *
ErrorResponseException
with
+ * the returned error code and error message.
+ *
+ * @param error the <error>
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;
}
diff --git a/src/main/java/se/kb/oai/pmh/Header.java b/src/main/java/se/kb/oai/pmh/Header.java
index bce1608..e0b7edf 100644
--- a/src/main/java/se/kb/oai/pmh/Header.java
+++ b/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 <header>
+ * part of a response. The verbs that has responses that includes a header
+ * are GetRecord
, ListRecords
and ListIdentifiers
.
+ *
+ * @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 ListHeader
object.
+ *
+ * @param node the <header>
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 ListIdentify
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 ListIdentification
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 ListYYYY-MM-DD
, meaning day granularity
+ * YYYY-MM-DDThh:mm:ssZ
, meaning second granularity
+ * ListIdentifiers
request.
+ *
+ * @author Oskar Grenholm, National Library of Sweden
+ */
public class IdentifiersList extends ResponseBase {
private static final String HEADER_XPATH = "oai:ListIdentifiers/oai:header";
private ListIdentifiersList
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 Headers
.
+ *
+ * @return a list of identifiers
+ */
public ListResumptionToken
, if any, for this response.
+ *
+ * @return the ResumptionToken
, or null
+ * if none available
+ */
public ResumptionToken getResumptionToken() {
if (super.resumptionToken == null
|| super.resumptionToken.getId() == null
diff --git a/src/main/java/se/kb/oai/pmh/MetadataFormat.java b/src/main/java/se/kb/oai/pmh/MetadataFormat.java
index 8837968..41776b9 100644
--- a/src/main/java/se/kb/oai/pmh/MetadataFormat.java
+++ b/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 MetadataFormat
from a <metadataFormat>
+ * node from the response.
+ *
+ * @param node a metadataFormat
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;
}
diff --git a/src/main/java/se/kb/oai/pmh/MetadataFormatsList.java b/src/main/java/se/kb/oai/pmh/MetadataFormatsList.java
index 39695e6..863f2e1 100644
--- a/src/main/java/se/kb/oai/pmh/MetadataFormatsList.java
+++ b/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 ListMetadataFormats
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 ListMetadataFormatsList
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 MetadataFormats
.
+ *
+ * @return a list of metadata formats
+ */
public List
+ * For more about the different verbs, requests and responses in the OAI-PMH specification,
+ * see
+ * http://www.openarchives.org/OAI/openarchivesprotocol.html.
*
- * 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
+ * The verbs that has responses that can contain a resumption token are:
+ * OaiPmhServer
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 OaiPmhServer
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 null
)
+ * @param until a stop date, optional (may be null
)
+ * @param set a specific set, optional (may be null
)
+ *
+ * @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 null
)
+ * @param until a stop date, optional (may be null
)
+ * @param set a specific set, optional (may be null
)
+ *
+ * @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);
diff --git a/src/main/java/se/kb/oai/pmh/QueryBuilder.java b/src/main/java/se/kb/oai/pmh/QueryBuilder.java
index b957643..888b4de 100644
--- a/src/main/java/se/kb/oai/pmh/QueryBuilder.java
+++ b/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 QueryBuilder
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 GetRecord
request.
+ *
+ * @param identifier the identifier
+ * @param metadataPrefix the metadata prefix
+ *
+ * @return the full query URL as a String
+ */
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 Identify
request.
+ *
+ * @return the full query URL as a String
+ */
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 ListIdentifiers
request.
+ *
+ * @param metadataPrefix which metadata format
+ * @param from a start date, optional (may be null
)
+ * @param until a stop date, optional (may be null
)
+ * @param set a specific set, optional (may be null
)
+ *
+ * @return the full query URL as a String
+ */
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 ListIdentifiers
request
+ * with a ResumptionToken
.
+ *
+ * @param token a resumption token returned from a previous request
+ * @return the full query URL as a String
+ */
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 ListMetadtaFormats
request.
+ *
+ * @param identifier the id, optional (may be null
)
+ *
+ * @return the full query URL as a String
+ */
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 ListRecords
request.
+ *
+ * @param metadataPrefix which metadata format
+ * @param from a start date, optional (may be null
)
+ * @param until a stop date, optional (may be null
)
+ * @param set a specific set, optional (may be null
)
+ *
+ * @return the full query URL as a String
+ */
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 ListRecords
request
+ * with a ResumptionToken
.
+ *
+ * @param token a resumption token returned from a previous request
+ * @return the full query URL as a String
+ */
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 ListSets
request.
+ *
+ * @return the full query URL as a String
+ */
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 ListSets
request
+ * with a ResumptionToken
.
+ *
+ * @param token a resumption token returned from a previous request
+ * @return the full query URL as a String
+ */
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();
diff --git a/src/main/java/se/kb/oai/pmh/Record.java b/src/main/java/se/kb/oai/pmh/Record.java
index 2b0438d..4753e44 100644
--- a/src/main/java/se/kb/oai/pmh/Record.java
+++ b/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 Record
class represents the data returned for a
+ * GetRecord
or ListRecords
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 Record
from the response from a
+ * GetRecord
request.
+ *
+ * @param document the response
+ * @throws ErrorResponseException
+ */
public Record(Document document) throws ErrorResponseException {
this(document, null);
}
+ /**
+ * Creates a Record
from from a ListRecords
+ * response and a specific <record>
element in that
+ * response.
+ *
+ * @param document the response
+ * @param record a <record>
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 Header
with the information
+ * about this Record
.
+ *
+ * @return a Header
+ */
public Header getHeader() {
return header;
}
+ /**
+ * Get the metadata contained in the metadata
element
+ * of this Record
.
+ *
+ * @return the metadata as xml
+ */
public Element getMetadata() {
return metadata;
}
+ /**
+ * Get the xml representation of the metadata as a String
.
+ *
+ * @return the metadata as a String
+ */
public String getMetadataAsString() throws IOException {
return XMLUtils.xmlToString(getMetadata());
}
+ /**
+ * Get the information about this Record
.
+ *
+ * @return the about information
+ */
public Element getAbout() {
return about;
}
diff --git a/src/main/java/se/kb/oai/pmh/RecordsList.java b/src/main/java/se/kb/oai/pmh/RecordsList.java
index b4b1e3d..a11c80f 100644
--- a/src/main/java/se/kb/oai/pmh/RecordsList.java
+++ b/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 ListRecords
request.
+ *
+ * @author Oskar Grenholm, National Library of Sweden
+ */
public class RecordsList extends ResponseBase {
private static final String RECORD_XPATH = "oai:ListRecords/oai:record";
private ListRecordsList
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 Records
.
+ *
+ * @return a list of records
+ */
public ListResumptionToken
, if any, for this response.
+ *
+ * @return the ResumptionToken
, or null
+ * if none available
+ */
public ResumptionToken getResumptionToken() {
if (super.resumptionToken == null
|| super.resumptionToken.getId() == null
diff --git a/src/main/java/se/kb/oai/pmh/ResponseBase.java b/src/main/java/se/kb/oai/pmh/ResponseBase.java
index 2583c34..04da124 100644
--- a/src/main/java/se/kb/oai/pmh/ResponseBase.java
+++ b/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 ResponseBase
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;
}
diff --git a/src/main/java/se/kb/oai/pmh/ResumptionToken.java b/src/main/java/se/kb/oai/pmh/ResumptionToken.java
index a6f41e5..e5eaae7 100644
--- a/src/main/java/se/kb/oai/pmh/ResumptionToken.java
+++ b/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 resumption token
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.)
+ *
+ *
+ *
+ * @author Oskar Grenholm, National Library of Sweden
+ *
+ */
public class ResumptionToken {
private String id;
private String expirationDate;
+ /**
+ * Create a ListIdentifiers
+ * ListRecords
+ * ListSets
+ * ResumptionToken
from the <resumptionToken>
+ * 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;
}
diff --git a/src/main/java/se/kb/oai/pmh/Set.java b/src/main/java/se/kb/oai/pmh/Set.java
index 40d97c5..c3591dc 100644
--- a/src/main/java/se/kb/oai/pmh/Set.java
+++ b/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 ListSet
from the <set>
element
+ * of a ListSets
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 ListListSets
request.
+ *
+ * @author Oskar Grenholm, National Library of Sweden
+ */
public class SetsList extends ResponseBase {
private static final String SET_XPATH = "oai:ListSets/oai:set";
private ListSetsList
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 Sets
.
+ *
+ * @return a list of sets
+ */
public ListResumptionToken
, if any, for this response.
+ *
+ * @return the ResumptionToken
, or null
+ * if none available
+ */
+ public ResumptionToken getResumptionToken() {
+ if (super.resumptionToken == null
+ || super.resumptionToken.getId() == null
+ || super.resumptionToken.getId().length() == 0)
+ return null;
+
+ return super.resumptionToken;
+ }
}