au.csiro.pidclient.AndsPidClient
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||
java.lang.Object
public class AndsPidClient
This is the main interface to the ANDS PID Client library. It allows the caller to interact with the Persistent IDentifier Service provided by the Australian National Data Service. You will need to register with ANDS to be able to use the service.
Usage:
Create a new instance of the class using either the empty constructor and then calling the four setters, or using the constructors. This should be compatible with use as a singleton bean in Spring or other DI (dependency injection) frameworks. Example:
You can then mint new handles using the mintHandle
method, and manage the properties associated with the handle
addValue,
modifyValueByIndex and
deleteValueByIndex methods. Note that these
methods return the raw XML response as a string. You can also use the FormattedResponse
versions to get back an interpreted result as a standard Java bean.
| Nested Class Summary | |
|---|---|
static class |
AndsPidClient.HandleType
The possible types of properties that can be associated with a handle. |
| Constructor Summary | |
|---|---|
AndsPidClient()
Default constructor. |
|
AndsPidClient(String pidServiceHost,
int pidServicePort,
String pidServicePath,
AndsPidIdentity requestorIdentity)
|
|
AndsPidClient(String pidServiceHost,
int pidServicePort,
String pidServicePath,
String appId,
String identifier,
String authDomain)
|
|
| Method Summary | |
|---|---|
String |
addValue(String handle,
AndsPidClient.HandleType type,
String value)
Adds a value to an existing handle. |
String |
addValueByIndex(String handle,
int index,
AndsPidClient.HandleType type,
String value)
Adds a value to a particular index of an existing handle. |
AndsPidResponse |
addValueByIndexFormattedResponse(String handle,
int index,
AndsPidClient.HandleType type,
String value)
Adds a value to a particular index of an existing handle. |
AndsPidResponse |
addValueFormattedResponse(String handle,
AndsPidClient.HandleType type,
String value)
Adds a value to an existing handle. |
String |
deleteValueByIndex(String handle,
int index)
Deletes a value associated with an existing handle. |
AndsPidResponse |
deleteValueByIndexFormattedResponse(String handle,
int index)
Deletes a value associated with an existing handle. |
String |
getHandle(String handle)
Retrieves the values associated with a given handle. |
AndsPidResponse |
getHandleFormattedResponse(String handle)
Retrieves the values associated with a given handle. |
String |
getPidServiceHost()
Retrieve the current ANDS Persistent Identifier host name |
String |
getPidServicePath()
Retrieve the current ANDS Persistent Identifier path name (web application context name) |
int |
getPidServicePort()
Retrieve the ANDS Persistent Identifier port number |
AndsPidIdentity |
getRequestorIdentity()
Retrieve the identity information of the calling application/organisation. |
String |
listHandles()
List the handles owned by the caller of the ANDS PID service. |
AndsPidResponse |
listHandlesFormattedResponse()
List the handles owned by the caller of the ANDS PID service. |
String |
mintHandle(AndsPidClient.HandleType type,
int index,
String value)
Responsible for the creation of a handle with a value at a specific index. |
String |
mintHandle(AndsPidClient.HandleType type,
String value)
Responsible for the creation of a handle. |
AndsPidResponse |
mintHandleFormattedResponse(AndsPidClient.HandleType type,
int index,
String value)
Responsible for the creation of a handle with a value at a specific index. |
AndsPidResponse |
mintHandleFormattedResponse(AndsPidClient.HandleType type,
String value)
Responsible for the creation of a handle. |
String |
modifyValueByIndex(String handle,
int index,
String newValue)
Changes a value associated with an existing handle. |
AndsPidResponse |
modifyValueByIndexFormattedResponse(String handle,
int index,
String newValue)
Changes a value associated with an existing handle. |
void |
setPidServiceHost(String pidServiceHost)
Set the ANDS Persistent Identifier host name. |
void |
setPidServicePath(String pidServicePath)
Set the current ANDS Persistent Identifier path name (web application context name) |
void |
setPidServicePort(int pidServicePort)
Set the ANDS Persistent Identifier port number |
void |
setRequestorIdentity(AndsPidIdentity requestorIdentity)
Set the identity information of the calling application/organisation. |
| Methods inherited from class java.lang.Object |
|---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Constructor Detail |
|---|
public AndsPidClient()
public AndsPidClient(String pidServiceHost,
int pidServicePort,
String pidServicePath,
String appId,
String identifier,
String authDomain)
pidServiceHost - the ANDS Persistent Identifier host name.pidServicePort - the ANDS Persistent Identifier port number.pidServicePath - the ANDS Persistent Identifier path name (web application context name).appId - the unique Id provided to the caller upon IP registration with the ANDS Persistent Identifier service.identifier - the identifier or name of the repository calling the service.authDomain - the domain of the organisation calling the service.
public AndsPidClient(String pidServiceHost,
int pidServicePort,
String pidServicePath,
AndsPidIdentity requestorIdentity)
pidServiceHost - the ANDS Persistent Identifier host name.pidServicePort - the ANDS Persistent Identifier port number.pidServicePath - the ANDS Persistent Identifier path name (web application context name).requestorIdentity - represents the identity information of the caller AndsPidIdentity.| Method Detail |
|---|
public String mintHandle(AndsPidClient.HandleType type,
String value)
throws IllegalStateException,
IllegalArgumentException,
org.apache.commons.httpclient.HttpException,
IOException
If the type and value arguments are both empty, a handle with no values is created. The handle is assigned to an
owner, specified by the AndsPidIdentity.getAppId() value. If the owner is not known to the handle system,
an owner is created from the AndsPidIdentity.getIdentifier() and AndsPidIdentity.getIdentifier()
values.
type - the type AndsPidClient.HandleType of value which will be associated with the newly minted handle.value - the value which will be associated with the newly minted handle.
IllegalStateException - thrown if the parameters need to call the ANDS PID service have not been provided.
IllegalArgumentException - thrown when method is called with invalid arguments.
IOException - thrown when attempting to read response.
org.apache.commons.httpclient.HttpException - thrown when attempting to execute method call.
public AndsPidResponse mintHandleFormattedResponse(AndsPidClient.HandleType type,
String value)
throws IllegalStateException,
IllegalArgumentException,
org.apache.commons.httpclient.HttpException,
IOException,
XPathExpressionException,
ParserConfigurationException,
SAXException
If the type and value arguments are both empty, a handle with no values is created. The handle is assigned to an
owner, specified by the AndsPidIdentity.getAppId() value. If the owner is not known to the handle system,
an owner is created from the AndsPidIdentity.getIdentifier() and AndsPidIdentity.getIdentifier()
values.
The XML response is parsed and returned by the object AndsPidResponse.
type - the type AndsPidClient.HandleType of value which will be associated with the newly minted handle.value - the value which will be associated with the newly minted handle.
AndsPidResponse.
IllegalStateException - thrown if the parameters need to call the ANDS PID service have not been provided.
IllegalArgumentException - thrown when method is called with invalid arguments.
org.apache.commons.httpclient.HttpException - thrown when attempting to execute method call.
IOException - thrown when attempting to read response.
XPathExpressionException - thrown when attempting to execute XPath on XML response.
ParserConfigurationException - thrown when attempting to convert response to an XML document.
SAXException - thrown when attempting to convert response to an XML document.
public String mintHandle(AndsPidClient.HandleType type,
int index,
String value)
throws IllegalStateException,
IllegalArgumentException,
org.apache.commons.httpclient.HttpException,
IOException
If the type and value arguments are both empty, a handle with no values is created. The handle is assigned
to an owner, specified by the AndsPidIdentity.getAppId() value. If the owner is not known to the handle
system, an owner is created from the AndsPidIdentity.getIdentifier() and
AndsPidIdentity.getIdentifier() values.
type - the type AndsPidClient.HandleType of value which will be associated with the newly minted handle.index - the index of the value which will be associated with the newly minted handle.value - the value which will be associated with the newly minted handle.
IllegalStateException - thrown if the parameters need to call the ANDS PID service have not been provided.
IllegalArgumentException - thrown when method is called with invalid arguments.
IOException - thrown when attempting to read response.
org.apache.commons.httpclient.HttpException - thrown when attempting to execute method call.
public AndsPidResponse mintHandleFormattedResponse(AndsPidClient.HandleType type,
int index,
String value)
throws IllegalStateException,
IllegalArgumentException,
org.apache.commons.httpclient.HttpException,
IOException,
XPathExpressionException,
ParserConfigurationException,
SAXException
If the type and value arguments are both empty, a handle with no values is created. The handle is assigned
to an owner, specified by the AndsPidIdentity.getAppId() value. If the owner is not known to the handle
system, an owner is created from the AndsPidIdentity.getIdentifier() and
AndsPidIdentity.getIdentifier() values.
The XML response is parsed and returned by the object AndsPidResponse.
type - the type AndsPidClient.HandleType of value which will be associated with the newly minted handle.index - the index of the value which will be associated with the newly minted handle.value - the value which will be associated with the newly minted handle.
AndsPidResponse.
IllegalStateException - thrown if the parameters need to call the ANDS PID service have not been provided.
IllegalArgumentException - thrown when method is called with invalid arguments.
org.apache.commons.httpclient.HttpException - thrown when attempting to execute method call.
IOException - thrown when attempting to read response.
XPathExpressionException - thrown when attempting to execute XPath on XML response.
ParserConfigurationException - thrown when attempting to convert response to an XML document.
SAXException - thrown when attempting to convert response to an XML document.
public String addValue(String handle,
AndsPidClient.HandleType type,
String value)
throws IllegalStateException,
IllegalArgumentException,
org.apache.commons.httpclient.HttpException,
IOException
Only the owner of the handle is able to add a value to the handle and only values of type AndsPidClient.HandleType.URL
or AndsPidClient.HandleType.DESC can be added.
handle - the handle to which a new value is to be associated.type - the type of the value to be added to the handle, must be either AndsPidClient.HandleType.URL or
AndsPidClient.HandleType.DESC.value - the value to be added to the handle.
IllegalStateException - thrown if the parameters need to call the ANDS PID service have not been provided.
IllegalArgumentException - thrown when method is called with invalid arguments.
IOException - thrown when attempting to read response.
org.apache.commons.httpclient.HttpException - thrown when attempting to execute method call.
public AndsPidResponse addValueFormattedResponse(String handle,
AndsPidClient.HandleType type,
String value)
throws IllegalStateException,
IllegalArgumentException,
org.apache.commons.httpclient.HttpException,
IOException,
XPathExpressionException,
ParserConfigurationException,
SAXException
Only the owner of the handle is able to add a value to the handle and only values of type AndsPidClient.HandleType.URL
or AndsPidClient.HandleType.DESC can be added.
The XML response is parsed and returned by the object AndsPidResponse.
handle - the handle to which a new value is to be associated.type - the type of the value to be added to the handle, must be either AndsPidClient.HandleType.URL or
AndsPidClient.HandleType.DESC.value - the value to be minted.
AndsPidResponse.
IllegalStateException - thrown if the parameters need to call the ANDS PID service have not been provided.
IllegalArgumentException - thrown when method is called with invalid arguments.
org.apache.commons.httpclient.HttpException - thrown when attempting to execute method call.
IOException - thrown when attempting to read response.
XPathExpressionException - thrown when attempting to execute XPath on XML response.
ParserConfigurationException - thrown when attempting to convert response to an XML document.
SAXException - thrown when attempting to convert response to an XML document.
public String addValueByIndex(String handle,
int index,
AndsPidClient.HandleType type,
String value)
throws IllegalStateException,
IllegalArgumentException,
org.apache.commons.httpclient.HttpException,
IOException
Only the owner of the handle is able to add a value to the handle and only values of type AndsPidClient.HandleType.URL
or AndsPidClient.HandleType.DESC can be added.
handle - the handle to which a new value is to be associated.index - the index in which to add the value.type - the type of the value to be added to the handle, must be either AndsPidClient.HandleType.URL or
AndsPidClient.HandleType.DESC.value - the value to be added to the handle.
IllegalStateException - thrown if the parameters need to call the ANDS PID service have not been provided.
IllegalArgumentException - thrown when method is called with invalid arguments.
IOException - thrown when attempting to read response.
org.apache.commons.httpclient.HttpException - thrown when attempting to execute method call.
public AndsPidResponse addValueByIndexFormattedResponse(String handle,
int index,
AndsPidClient.HandleType type,
String value)
throws IllegalStateException,
IllegalArgumentException,
org.apache.commons.httpclient.HttpException,
IOException,
XPathExpressionException,
ParserConfigurationException,
SAXException
Only the owner of the handle is able to add a value to the handle and only values of type AndsPidClient.HandleType.URL
or AndsPidClient.HandleType.DESC can be added.
The XML response is parsed and returned by the object AndsPidResponse.
handle - the handle to which a new value is to be associated.index - the index in which to add the value.type - the type of the value to be added to the handle, must be either AndsPidClient.HandleType.URL or
AndsPidClient.HandleType.DESC.value - the value to be minted.
AndsPidResponse.
IllegalStateException - thrown if the parameters need to call the ANDS PID service have not been provided.
IllegalArgumentException - thrown when method is called with invalid arguments.
org.apache.commons.httpclient.HttpException - thrown when attempting to execute method call.
IOException - thrown when attempting to read response.
XPathExpressionException - thrown when attempting to execute XPath on XML response.
ParserConfigurationException - thrown when attempting to convert response to an XML document.
SAXException - thrown when attempting to convert response to an XML document.
public String modifyValueByIndex(String handle,
int index,
String newValue)
throws IllegalStateException,
IllegalArgumentException,
org.apache.commons.httpclient.HttpException,
IOException
Only the owner of the handle is able to modify a value associated with the handle and only values with the type
AndsPidClient.HandleType.URL or AndsPidClient.HandleType.DESC can be modified.
handle - the handle that is to have one of its values modified.index - the index of the value to modify.newValue - the new value.
IllegalStateException - thrown if the parameters need to call the ANDS PID service have not been provided.
IllegalArgumentException - thrown when method is called with invalid arguments.
org.apache.commons.httpclient.HttpException - thrown when attempting to execute method call.
IOException - thrown when attempting to read response.
public AndsPidResponse modifyValueByIndexFormattedResponse(String handle,
int index,
String newValue)
throws IllegalStateException,
IllegalArgumentException,
org.apache.commons.httpclient.HttpException,
IOException,
XPathExpressionException,
ParserConfigurationException,
SAXException
Only the owner of the handle is able to modify a value associated with the handle and only values with the type
AndsPidClient.HandleType.URL or AndsPidClient.HandleType.DESC can be modified.
The XML response is parsed and returned by the object AndsPidResponse.
handle - the handle that is to have one of its values modified.index - the index of the value to modify.newValue - the new value.
AndsPidResponse.
IllegalStateException - thrown if the parameters need to call the ANDS PID service have not been provided.
IllegalArgumentException - thrown when method is called with invalid arguments.
org.apache.commons.httpclient.HttpException - thrown when attempting to execute method call.
IOException - thrown when attempting to read response.
XPathExpressionException - thrown when attempting to execute XPath on XML response.
ParserConfigurationException - thrown when attempting to convert response to an XML document.
SAXException - thrown when attempting to convert response to an XML document.
public String deleteValueByIndex(String handle,
int index)
throws IllegalStateException,
IllegalArgumentException,
org.apache.commons.httpclient.HttpException,
IOException
Only the owner of the handle is able to delete a value associated to the handle and only values of type
AndsPidClient.HandleType.URL or AndsPidClient.HandleType.DESC can be deleted.
handle - the handle that is to have one of its values deleted.index - the index of the value to be deleted.
IllegalStateException - thrown if the parameters need to call the ANDS PID service have not been provided.
IllegalArgumentException - thrown when method is called with invalid arguments.
org.apache.commons.httpclient.HttpException - thrown when attempting to execute method call.
IOException - thrown when attempting to read response.
public AndsPidResponse deleteValueByIndexFormattedResponse(String handle,
int index)
throws IllegalStateException,
IllegalArgumentException,
org.apache.commons.httpclient.HttpException,
IOException,
XPathExpressionException,
ParserConfigurationException,
SAXException
AndsPidClient.HandleType.URL or
AndsPidClient.HandleType.DESC can be deleted.
Only the owner of the handle is able to delete a value associated to the handle and only values of type
AndsPidClient.HandleType.URL or AndsPidClient.HandleType.DESC can be deleted.
The XML response is parsed and returned by the object AndsPidResponse.
handle - the handle that is to have one of its indexes deleted.index - the index to be deleted.
AndsPidResponse.
IllegalStateException - thrown if the parameters need to call the ANDS PID service have not been provided.
IllegalArgumentException - thrown when method is called with invalid arguments.
org.apache.commons.httpclient.HttpException - thrown when attempting to execute method call.
IOException - thrown when attempting to read response.
XPathExpressionException - thrown when attempting to execute XPath on XML response.
ParserConfigurationException - thrown when attempting to convert response to an XML document.
SAXException - thrown when attempting to convert response to an XML document.
public String listHandles()
throws IllegalStateException,
org.apache.commons.httpclient.HttpException,
IOException
This service is intended for listing a small number of handles in a GUI environment, therefore its response is limited in the number of handles returned.
IllegalStateException - thrown if the parameters need to call the ANDS PID service have not been provided.
org.apache.commons.httpclient.HttpException - thrown when attempting to execute method call.
IOException - thrown when attempting to read response.
public AndsPidResponse listHandlesFormattedResponse()
throws IllegalStateException,
org.apache.commons.httpclient.HttpException,
IOException,
XPathExpressionException,
ParserConfigurationException,
SAXException
This service is intended for listing a small number of handles in a GUI environment, therefore its response is limited in the number of handles returned.
The XML response is parsed and returned by the object AndsPidResponse.
AndsPidResponse.
IllegalStateException - thrown if the parameters need to call the ANDS PID service have not been provided.
org.apache.commons.httpclient.HttpException - thrown when attempting to execute method call.
IOException - thrown when attempting to read response.
XPathExpressionException - thrown when attempting to execute XPath on XML response.
ParserConfigurationException - thrown when attempting to convert response to an XML document.
SAXException - thrown when attempting to convert response to an XML document.
public String getHandle(String handle)
throws IllegalStateException,
IllegalArgumentException,
org.apache.commons.httpclient.HttpException,
IOException
handle - the handle whose details are to be retrieved.
IllegalStateException - thrown if the parameters need to call the ANDS PID service have not been provided.
IllegalArgumentException - thrown when method is called with invalid arguments.
org.apache.commons.httpclient.HttpException - thrown when attempting to execute method call.
IOException - thrown when attempting to read response.
public AndsPidResponse getHandleFormattedResponse(String handle)
throws IllegalStateException,
IllegalArgumentException,
org.apache.commons.httpclient.HttpException,
IOException,
XPathExpressionException,
ParserConfigurationException,
SAXException
The XML response is parsed and returned by the object AndsPidResponse.
handle - the handle whose details are to be retrieved.
AndsPidResponse.
IllegalStateException - thrown if the parameters need to call the ANDS PID service have not been provided.
IllegalArgumentException - thrown when method is called with invalid arguments.
org.apache.commons.httpclient.HttpException - thrown when attempting to execute method call.
IOException - thrown when attempting to read response.
XPathExpressionException - thrown when attempting to execute XPath on XML response.
ParserConfigurationException - thrown when attempting to convert response to an XML document.
SAXException - thrown when attempting to convert response to an XML document.public String getPidServiceHost()
public void setPidServiceHost(String pidServiceHost)
pidServiceHost - the ANDS Persistent Identifier host name to setpublic int getPidServicePort()
public void setPidServicePort(int pidServicePort)
pidServicePort - the ANDS Persistent Identifier port number to setpublic String getPidServicePath()
public void setPidServicePath(String pidServicePath)
pidServicePath - the ANDS Persistent Identifier path name to setpublic AndsPidIdentity getRequestorIdentity()
public void setRequestorIdentity(AndsPidIdentity requestorIdentity)
requestorIdentity - the identity object to set
|
||||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | |||||||||