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: + * + * + * + * @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 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 List setSpecs; + /** + * Creates a Header 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 List getSetSpecs() { return setSpecs; } diff --git a/src/main/java/se/kb/oai/pmh/Identification.java b/src/main/java/se/kb/oai/pmh/Identification.java index 502984a..b609808 100644 --- a/src/main/java/se/kb/oai/pmh/Identification.java +++ b/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 Identify 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 descriptions; private List adminEmails; + /** + * Creates an Identification 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 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: + *
    + *
  • no + *
  • transient + *
  • persistent + *
+ * + * @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 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: + *
    + *
  • YYYY-MM-DD, meaning day granularity + *
  • YYYY-MM-DDThh:mm:ssZ, meaning second granularity + *
+ * + * @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; } diff --git a/src/main/java/se/kb/oai/pmh/IdentifiersList.java b/src/main/java/se/kb/oai/pmh/IdentifiersList.java index 3b923dd..f57cbdb 100644 --- a/src/main/java/se/kb/oai/pmh/IdentifiersList.java +++ b/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 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 List
headers; + /** + * Creates an IdentifiersList 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 List
asList() { return headers; } + /** + * Get the ResumptionToken, 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 List metadataFormats; + /** + * Creates a MetadataFormatsList 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 asList() { return metadataFormats; } diff --git a/src/main/java/se/kb/oai/pmh/OaiPmhServer.java b/src/main/java/se/kb/oai/pmh/OaiPmhServer.java index 73191f9..cebb55d 100644 --- a/src/main/java/se/kb/oai/pmh/OaiPmhServer.java +++ b/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. + *

+ * 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 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 List records; - + + /** + * Creates a RecordsList 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 List asList() { return records; } + /** + * Get the ResumptionToken, 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.) + *

+ * The verbs that has responses that can contain a resumption token are: + *

    + *
  • ListIdentifiers + *
  • ListRecords + *
  • ListSets + *
+ * + * @author Oskar Grenholm, National Library of Sweden + * + */ public class ResumptionToken { private String id; private String expirationDate; + /** + * Create a 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 List descriptions; + /** + * Create a Set 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 List getDescriptions() { return descriptions; } diff --git a/src/main/java/se/kb/oai/pmh/SetsList.java b/src/main/java/se/kb/oai/pmh/SetsList.java index e265174..27d644e 100644 --- a/src/main/java/se/kb/oai/pmh/SetsList.java +++ b/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 ListSets 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 sets; + /** + * Creates an SetsList 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 List asList() { return sets; } + + /** + * Get the ResumptionToken, 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; + } }