org.gcube.common
Class OAIRepository

java.lang.Object
  org.gcube.common.OAIRepository

public class OAIRepository
extends Object

This class represents an OAI repository.

Field Summary

int	STATE_IDENTIFIED The repository has been identified.
int	STATE_UNIDENTIFIED The repository is not identified yet.
static int	VALIDATION_LOOSE This will attempt to continue processing even if some non-well-formed XML is encountered.
static int	VALIDATION_STRICT This is the default type.
static int	VALIDATION_VERY_STRICT This will cause the XML responses to be initially validated against the XML schemas, as indicated by the xsi:schemaLocation attributes.
static String	XMLNS_DC namespace URIs for metadata formats
static String	XMLNS_EPR
static String	XMLNS_EPR_1_0
static String	XMLNS_ID
static String	XMLNS_ID_1_0
static String	XMLNS_ID_1_0_aps some repositories don't use the correct namespaces (American Physical Society)
static String	XMLNS_ID_2_0
static String	XMLNS_OAI namespaces from the current (1.1) version of the protocol
static String	XMLNS_OAI_1_0 namespaces from the 1.0 version of the protocol
static String	XMLNS_OAI_2_0 namespaces from the 2.0 version of the protocol
static String	XMLNS_OAI_DC_2_0
static String	XMLNS_OAI_MARC
static String	XMLNS_OAI_MARC_1_0
static String	XMLNS_RFC1807

Constructor Summary

OAIRepository()
Construct an empty OAI repository.

Method Summary

protected String	frndGetPassword()
protected String	frndGetRawResponse()
protected String	frndGetUser()
protected String	frndMyEncode(InputStream s) Turn a string into something that can be legally stuffed into an XML CDATA section
protected void	frndSetErrors(NodeList e)
protected void	frndSetNamespaceNode(Element ns)
protected void	frndSetRepositoryID(String id)
protected void	frndSetRequest(Node u)
protected void	frndSetResponseDate(String d)
protected HttpURLConnection	frndTrySend(HttpURLConnection h) Purpose: Attempt to send the request to the repository, honoring 503 Retry statuses Inputs: h the HTTP object to use for the sending NOTE: Not sure if the http object does redirects (302) or not; may have to do these manually also
String	getAdminEmail() Returns the email address of the repository administrator.
String	getAdminEmail(int i) Returns the email address of the repository administrator.
int	getAdminEmailCount() Returns how many admin emails there are for the repository
String	getBaseURL() Returns the BASE-URL of the repository.
String	getCompression() Returns the compression supported by the repository.
String	getCompression(int i) Returns the compression supported by the repository.
int	getCompressionCount() Returns how many compressions are supported by the repository
String	getDeletedRecord() Returns the type of deleted items supported by the repository
Node	getDescription() Returns the first repository description returned by the Identify request as an XML node; if there is no descriptin an empty string is returned.
Node	getDescription(int i) Returns one of the repository descriptions returned by the Identify request as an XML node; the index parameter indicates which description to return: 0 to DescriptionCount-1; if there is no descriptin an empty string is returned.
int	getDescriptionCount() Returns the number of descriptions returned by the Identify request.
String	getEarliestDatestamp() Returns how many compressions are supported by the repository
Node	getEPrintsDescription() If one of the descriptions returned by the Identify request is an eprints, this method will return the eprints description as an XML node.
String	getFrom() Returns the value to be used in the From field of the HTTP request header.
String	getGranularity() Returns the datestamp granularity supported by the repository
OAIError	getLastOAIError() Returns one of the errors returned by the repository
OAIError	getLastOAIError(int i)
int	getLastOAIErrorCount() Returns how many errors were returned by the repository
int	getMaxRetryMinutes() Returns the maximum allowable minutes to wait for a retry without failing.
protected Element	getNamespaceNode()
Node	getOAIIdentifierDescription() If one of the descriptions returned by the Identify request is an oai-identifier, this method will return the oai-identifier description as an XML node.
int	getProtocolMajorVersion() Returns the major version number of the protocol spec supported by the repository currently either 1 or 2.
String	getProtocolVersion() Returns the version of the protocol spec supported by the repository.
OAIRecord	getRecord(String identifier) Returns an OAIRecord object for the given OAI Identifier with default metadataPrefix as oai_dc.
OAIRecord	getRecord(String identifier, String metadataPrefix) Returns an OAIRecord object for the given OAI Identifier and the metadataPrefix.
String	getRepositoryIdentifier() If one of the descriptions returned by the Identify request is an oai-identifier, this parameter will contain the registered identifier of the repository.
String	getRepositoryName() Returns the name of the repository
String	getRequestBaseURL() The Request URL returned by the most recent request.
String	getRequestFrom() Returns the from query param returned by the most recent response
String	getRequestIdentifier() Returns the identifier query param returned by the most recent response
String	getRequestMetadataPrefix() Returns the metadataPrefix query param returned by the most recent response
String	getRequestResumptionToken() Returns the resumptionToken query param returned by the most recent response
String	getRequestSet() Returns the set query param returned by the most recent response
String	getRequestUntil() Returns the until query param returned by the most recent response
String	getRequestURL() Return the complete request url returned by the most recent response.
String	getRequestVerb() Returns the verb query param returned by the most recent response
String	getResponseDate() The Response Date returned by the most recent request.
int	getRetryLimit() Returns the number of times to retry if given a 503 before giving up.
String	getSampleIdentifier() If one of the descriptions returned by the Identify request is an oai-identifier, this parameter will contain the sample OAI identifier contained therein.
String	getUserAgent() Returns the value to be used in the User-Agent field of the HTTP request header.
int	getValidation() Returns the type of validation to perform on the OAI response.
String	identify() Sends an Identify request to a repository with the baseURL previously set; if the Identify request is successful, the RepositoryName will be returned.
OAIRecordList	listIdentifiers() Returns an OAIRecordList object containing the records returned by the repository.
OAIRecordList	listIdentifiers(String untild) Returns an OAIRecordList object containing the records returned by the repository for the given untild.
OAIRecordList	listIdentifiers(String untild, String fromd) Returns an OAIRecordList object containing the records returned by the repository for the given untild and fromd.
OAIRecordList	listIdentifiers(String untild, String fromd, String setSpec) Returns an OAIRecordList object containing the records returned by the repository for the given untild, fromd, and SetSpec.
OAIRecordList	listIdentifiers(String untild, String fromd, String setSpec, String metadataPrefix) Returns an OAIRecordList object containing the records returned by the repository for the given untild, fromd, and SetSpec.
OAIMetadataFormatList	listMetadataFormats() Returns an OAIMetadataFormatList object containing the metadata formats supported by the repository..
OAIMetadataFormatList	listMetadataFormats(String identifier) Returns an OAIMetadataFormatList object containing the metadata formats supported by a specific record.
OAIRecordList	listRecords() Returns an OAIRecordList object containing the records returned by the repository.
OAIRecordList	listRecords(String metadataPrefix) Returns an OAIRecordList object containing the records returned by the repository for the given metadataPrefix.
OAIRecordList	listRecords(String metadataPrefix, String untild) Returns an OAIRecordList object containing the records returned by the repository for the given metadataPrefix and untild.
OAIRecordList	listRecords(String metadataPrefix, String untild, String fromd) Returns an OAIRecordList object containing the records returned by the repository for the given metadataPrefix, untild, and fromd.
OAIRecordList	listRecords(String metadataPrefix, String untild, String fromd, String setSpec) Returns an OAIRecordList object containing the records returned by the repository for the given metadataPrefix, untild, fromd, and SetSpec.
OAISetList	listSets() Returns an OAISetList object containing the sets returned by the repository.
void	setBaseURL(String url) Sets the BASE-URL of the repository; must be set before most other properties or methods can be used.
void	setBasicAuthorization(String usr, String pwd) Set the user and password to use for Basic HTTP Authorization
void	setFrom(String f) Sets the value to be used in the From field of the HTTP request header.
void	setMaxRetryMinutes(int m) Sets the maximum allowable minutes to wait for a retry without failing.
void	setRetryLimit(int rl) Sets the number of times to retry if a HTTP status of 503 is returned by the repository; defaults to 5
void	setUserAgent(String ua) Sets the value to be used in the User-Agent field of the HTTP request header.
void	setValidation(int v) Sets the type of validation to perform on the OAI response.
boolean	usesEPrints() Returns true if the repository uses EPrints descriptions in its Identify request; else false.
boolean	usesOAIIdentifier() Returns true if the repository uses OAIIdentifier descriptions in its Identify request; else false.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

STATE_UNIDENTIFIED

public final int STATE_UNIDENTIFIED

The repository is not identified yet.

See Also:

Constant Field Values

STATE_IDENTIFIED

public final int STATE_IDENTIFIED

The repository has been identified.

See Also:

Constant Field Values

VALIDATION_STRICT

public static final int VALIDATION_STRICT

This is the default type. The only check which is initially performed is if the XML is well-formed. If it is not well-formed, including invalid characters, an error will be generated and processing will stop. However, the program may still generate errors if the XML does not contain certain expected elements.

See Also:

Constant Field Values

VALIDATION_VERY_STRICT

public static final int VALIDATION_VERY_STRICT

This will cause the XML responses to be initially validated against the XML schemas, as indicated by the xsi:schemaLocation attributes. If the validation passes, this program should encounter no further errors.

See Also:

Constant Field Values

VALIDATION_LOOSE

public static final int VALIDATION_LOOSE

This will attempt to continue processing even if some non-well-formed XML is encountered. In most case a dummy record will be created which contains the invalid record in some fashion. If there is a resumptionToken, basic string parsing techniques will be used to get the value, so it can be used to continue with the next chunk of data.

See Also:

Constant Field Values

XMLNS_DC

public static String XMLNS_DC

namespace URIs for metadata formats

XMLNS_RFC1807

public static String XMLNS_RFC1807

XMLNS_OAI_MARC

public static String XMLNS_OAI_MARC

XMLNS_OAI

public static String XMLNS_OAI

namespaces from the current (1.1) version of the protocol

XMLNS_ID

public static String XMLNS_ID

XMLNS_EPR

public static String XMLNS_EPR

XMLNS_OAI_2_0

public static String XMLNS_OAI_2_0

namespaces from the 2.0 version of the protocol

XMLNS_OAI_DC_2_0

public static String XMLNS_OAI_DC_2_0

XMLNS_ID_2_0

public static String XMLNS_ID_2_0

XMLNS_OAI_1_0

public static String XMLNS_OAI_1_0

namespaces from the 1.0 version of the protocol

XMLNS_ID_1_0

public static String XMLNS_ID_1_0

XMLNS_EPR_1_0

public static String XMLNS_EPR_1_0

XMLNS_OAI_MARC_1_0

public static String XMLNS_OAI_MARC_1_0

XMLNS_ID_1_0_aps

public static String XMLNS_ID_1_0_aps

some repositories don't use the correct namespaces (American Physical Society)

Constructor Detail

OAIRepository

public OAIRepository()

Construct an empty OAI repository.

Method Detail

setBaseURL

public void setBaseURL(String url)
                throws OAIException

Sets the BASE-URL of the repository; must be set before most other properties or methods can be used.

Throws:

OAIException

getBaseURL

public String getBaseURL()
                  throws OAIException

Returns the BASE-URL of the repository.

Throws:

OAIException

frndSetErrors

protected void frndSetErrors(NodeList e)

frndSetRepositoryID

protected void frndSetRepositoryID(String id)

frndSetRequest

protected void frndSetRequest(Node u)

frndSetResponseDate

protected void frndSetResponseDate(String d)

frndGetRawResponse

protected String frndGetRawResponse()

frndGetUser

protected String frndGetUser()

frndGetPassword

protected String frndGetPassword()

setBasicAuthorization

public void setBasicAuthorization(String usr,
                                  String pwd)

Set the user and password to use for Basic HTTP Authorization

getLastOAIError

public OAIError getLastOAIError()
                         throws OAIException

Returns one of the errors returned by the repository

Throws:

OAIException

getLastOAIError

public OAIError getLastOAIError(int i)
                         throws OAIException

Throws:

OAIException

getLastOAIErrorCount

public int getLastOAIErrorCount()

Returns how many errors were returned by the repository

getRequestVerb

public String getRequestVerb()

Returns the verb query param returned by the most recent response

getRequestIdentifier

public String getRequestIdentifier()

Returns the identifier query param returned by the most recent response

getRequestMetadataPrefix

public String getRequestMetadataPrefix()

Returns the metadataPrefix query param returned by the most recent response

getRequestFrom

public String getRequestFrom()

Returns the from query param returned by the most recent response

getRequestUntil

public String getRequestUntil()

Returns the until query param returned by the most recent response

getRequestSet

public String getRequestSet()

Returns the set query param returned by the most recent response

getRequestResumptionToken

public String getRequestResumptionToken()

Returns the resumptionToken query param returned by the most recent response

getAdminEmailCount

public int getAdminEmailCount()
                       throws OAIException

Returns how many admin emails there are for the repository

Throws:

OAIException

getCompressionCount

public int getCompressionCount()
                        throws OAIException

Returns how many compressions are supported by the repository

Throws:

OAIException

getEarliestDatestamp

public String getEarliestDatestamp()
                            throws OAIException

Returns how many compressions are supported by the repository

Throws:

OAIException

getDeletedRecord

public String getDeletedRecord()
                        throws OAIException

Returns the type of deleted items supported by the repository

Throws:

OAIException

getGranularity

public String getGranularity()
                      throws OAIException

Returns the datestamp granularity supported by the repository

Throws:

OAIException

getResponseDate

public String getResponseDate()

The Response Date returned by the most recent request. If validation is loose and there is a missing responseDate, an empty string will be returned; otherwise, an error will be raised.

getRequestBaseURL

public String getRequestBaseURL()

The Request URL returned by the most recent request. If validation is loose and there is a missing requestURL, an empty string will be returned; otherwise, an error will be raised.

getMaxRetryMinutes

public int getMaxRetryMinutes()

Returns the maximum allowable minutes to wait for a retry without failing.

setMaxRetryMinutes

public void setMaxRetryMinutes(int m)

Sets the maximum allowable minutes to wait for a retry without failing. If a repository returns a 503 status with a retry-after field which specifies a retry period which exceeds this value, an error will be raised. The default value is 60 minutes.

frndMyEncode

protected String frndMyEncode(InputStream s)
                       throws OAIException

Turn a string into something that can be legally stuffed into an XML CDATA section

Throws:

OAIException

frndSetNamespaceNode

protected void frndSetNamespaceNode(Element ns)

getNamespaceNode

protected Element getNamespaceNode()

getDescription

public Node getDescription()
                    throws OAIException

Returns the first repository description returned by the Identify request as an XML node; if there is no descriptin an empty string is returned.

Throws:

OAIException

getDescription

public Node getDescription(int i)
                    throws OAIException

Returns one of the repository descriptions returned by the Identify request as an XML node; the index parameter indicates which description to return: 0 to DescriptionCount-1; if there is no descriptin an empty string is returned.

Throws:

OAIException

getDescriptionCount

public int getDescriptionCount()

Returns the number of descriptions returned by the Identify request.

getRecord

public OAIRecord getRecord(String identifier)
                    throws OAIException

Returns an OAIRecord object for the given OAI Identifier with default metadataPrefix as oai_dc.

Throws:

OAIException

getRecord

public OAIRecord getRecord(String identifier,
                           String metadataPrefix)
                    throws OAIException

Returns an OAIRecord object for the given OAI Identifier and the metadataPrefix.

Throws:

OAIException

identify

public String identify()
                throws OAIException

Sends an Identify request to a repository with the baseURL previously set; if the Identify request is successful, the RepositoryName will be returned.

Throws:

OAIException

listIdentifiers

public OAIRecordList listIdentifiers()
                              throws OAIException

Returns an OAIRecordList object containing the records returned by the repository.

Throws:

OAIException

listIdentifiers

public OAIRecordList listIdentifiers(String untild)
                              throws OAIException

Returns an OAIRecordList object containing the records returned by the repository for the given untild.

Throws:

OAIException

listIdentifiers

public OAIRecordList listIdentifiers(String untild,
                                     String fromd)
                              throws OAIException

Returns an OAIRecordList object containing the records returned by the repository for the given untild and fromd.

Throws:

OAIException

listIdentifiers

public OAIRecordList listIdentifiers(String untild,
                                     String fromd,
                                     String setSpec)
                              throws OAIException

Returns an OAIRecordList object containing the records returned by the repository for the given untild, fromd, and SetSpec.

Throws:

OAIException

listIdentifiers

public OAIRecordList listIdentifiers(String untild,
                                     String fromd,
                                     String setSpec,
                                     String metadataPrefix)
                              throws OAIException

Returns an OAIRecordList object containing the records returned by the repository for the given untild, fromd, and SetSpec.

Throws:

OAIException

listRecords

public OAIRecordList listRecords()
                          throws OAIException

Returns an OAIRecordList object containing the records returned by the repository.

Throws:

OAIException

listRecords

public OAIRecordList listRecords(String metadataPrefix)
                          throws OAIException

Returns an OAIRecordList object containing the records returned by the repository for the given metadataPrefix.

Throws:

OAIException

listRecords

public OAIRecordList listRecords(String metadataPrefix,
                                 String untild)
                          throws OAIException

Returns an OAIRecordList object containing the records returned by the repository for the given metadataPrefix and untild.

Throws:

OAIException

listRecords

public OAIRecordList listRecords(String metadataPrefix,
                                 String untild,
                                 String fromd)
                          throws OAIException

Returns an OAIRecordList object containing the records returned by the repository for the given metadataPrefix, untild, and fromd.

Throws:

OAIException

listRecords

public OAIRecordList listRecords(String metadataPrefix,
                                 String untild,
                                 String fromd,
                                 String setSpec)
                          throws OAIException

Returns an OAIRecordList object containing the records returned by the repository for the given metadataPrefix, untild, fromd, and SetSpec.

Throws:

OAIException

getRepositoryIdentifier

public String getRepositoryIdentifier()
                               throws OAIException

If one of the descriptions returned by the Identify request is an oai-identifier, this parameter will contain the registered identifier of the repository. If there is no oai-identifier description, then an empty string will be returned, or if Validation is Very Strict an error.

Throws:

OAIException

getOAIIdentifierDescription

public Node getOAIIdentifierDescription()
                                 throws OAIException

If one of the descriptions returned by the Identify request is an oai-identifier, this method will return the oai-identifier description as an XML node. Nothing is returned if there is no OAI-Identifier description.

Throws:

OAIException

getEPrintsDescription

public Node getEPrintsDescription()
                           throws OAIException

If one of the descriptions returned by the Identify request is an eprints, this method will return the eprints description as an XML node. Nothing is returned if there is no E-Prints description.

Throws:

OAIException

setRetryLimit

public void setRetryLimit(int rl)

Sets the number of times to retry if a HTTP status of 503 is returned by the repository; defaults to 5

getRetryLimit

public int getRetryLimit()

Returns the number of times to retry if given a 503 before giving up.

getSampleIdentifier

public String getSampleIdentifier()
                           throws OAIException

If one of the descriptions returned by the Identify request is an oai-identifier, this parameter will contain the sample OAI identifier contained therein. If there is no oai-identifier description, then an empty string will be returned, or if Validation is Very Strict an error.

Throws:

OAIException

getRepositoryName

public String getRepositoryName()
                         throws OAIException

Returns the name of the repository

Throws:

OAIException

getAdminEmail

public String getAdminEmail()
                     throws OAIException

Returns the email address of the repository administrator.

Throws:

OAIException

getAdminEmail

public String getAdminEmail(int i)
                     throws OAIException

Returns the email address of the repository administrator.

Throws:

OAIException

getCompression

public String getCompression()
                      throws OAIException

Returns the compression supported by the repository.

Throws:

OAIException

getCompression

public String getCompression(int i)
                      throws OAIException

Returns the compression supported by the repository.

Throws:

OAIException

getProtocolMajorVersion

public int getProtocolMajorVersion()
                            throws OAIException

Returns the major version number of the protocol spec supported by the repository currently either 1 or 2.

Throws:

OAIException

getProtocolVersion

public String getProtocolVersion()
                          throws OAIException

Returns the version of the protocol spec supported by the repository.

Throws:

OAIException

getRequestURL

public String getRequestURL()

Return the complete request url returned by the most recent response. This includes the baseURL and all of the parameters shown as a concatenated query string.

getUserAgent

public String getUserAgent()

Returns the value to be used in the User-Agent field of the HTTP request header.

setUserAgent

public void setUserAgent(String ua)

Sets the value to be used in the User-Agent field of the HTTP request header. This is usually the name of the harvester. Defaults to 'OAIHarvester University of Illinois Library'.

getFrom

public String getFrom()

Returns the value to be used in the From field of the HTTP request header.

setFrom

public void setFrom(String f)

Sets the value to be used in the From field of the HTTP request header. This is usually the email address of the person running the harvester. Defaults to 'ytseng1@uiuc.edu'. This property should be reset to email address of the person responsible for harvester.

frndTrySend

protected HttpURLConnection frndTrySend(HttpURLConnection h)
                                 throws OAIException

Purpose: Attempt to send the request to the repository, honoring 503 Retry statuses Inputs: h the HTTP object to use for the sending NOTE: Not sure if the http object does redirects (302) or not; may have to do these manually also

Throws:

OAIException

usesOAIIdentifier

public boolean usesOAIIdentifier()
                          throws OAIException

Returns true if the repository uses OAIIdentifier descriptions in its Identify request; else false.

Throws:

OAIException

usesEPrints

public boolean usesEPrints()
                    throws OAIException

Returns true if the repository uses EPrints descriptions in its Identify request; else false.

Throws:

OAIException

getValidation

public int getValidation()

Returns the type of validation to perform on the OAI response.

setValidation

public void setValidation(int v)

Sets the type of validation to perform on the OAI response. VALIDATION_STRICT is the default.

listMetadataFormats

public OAIMetadataFormatList listMetadataFormats()
                                          throws OAIException

Returns an OAIMetadataFormatList object containing the metadata formats supported by the repository..

Throws:

OAIException

listMetadataFormats

public OAIMetadataFormatList listMetadataFormats(String identifier)
                                          throws OAIException

Returns an OAIMetadataFormatList object containing the metadata formats supported by a specific record.

Throws:

OAIException

listSets

public OAISetList listSets()
                    throws OAIException

Returns an OAISetList object containing the sets returned by the repository.

Throws:

OAIException