ClientMDS (Digital Object Identifier Server 1.0.5 API)

java.lang.Object
- fr.cnes.doi.client.BaseClient
- - fr.cnes.doi.client.ClientMDS

```
@Requirement(reqId="DOI_INTER_010",
             reqName="Interface avec Datacite Metadata Store")
public class ClientMDS
extends BaseClient
```
Client to query Metadata store service at Datacite.

Author:

Jean-Christophe Malapert (jean-christophe.malapert@cnes.fr)

See Also:

"https://mds.datacite.org/static/apidoc"

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`ClientMDS.Context` Options for each context
`static class`	`ClientMDS.DATACITE_API_RESPONSE` Datacite API.
`private static class`	`ClientMDS.MyValidationEventHandler` Metadata Validation.

Field Summary

Fields
Modifier and Type	Field and Description
`private ClientMDS.Context`	`context` Context.
`static String`	`DATA_CITE_MOCK_URL` Metadata store mock service endpoint "http://localhost:1080".
`static String`	`DATA_CITE_TEST_URL` Metadata store test service endpoint "https://mds.test.datacite.org".
`static String`	`DATA_CITE_URL` Metadata store service endpoint "https://mds.datacite.org".
`static String`	`DOI_RESOURCE` DOI resource "doi".
`private static DoiSettings`	`DOI_SETTINGS` Loads DOI settings.
`static String`	`MEDIA_RESOURCE` Media resource "media".
`static String`	`METADATA_RESOURCE` Metadata resource "metadata".
`static String`	`POST_DOI` DOI query parameter "doi".
`static String`	`POST_URL` URL query parameter "url".
`static String`	`SCHEMA_DATACITE` Default XML schema for Datacite: "https://schema.datacite.org/meta/kernel-4-1/metadata.xsd"
`private static SchemaFactory`	`SCHEMA_FACTORY` SCHEMA_FACTORY.
`static String`	`TEST_DOI_PREFIX` Test DOI prefix "10.80163".
`static org.restlet.data.Parameter`	`TEST_MODE` Test mode sets to true.
`private org.restlet.data.Parameter`	`testMode` Selected test mode.

Fields inherited from class fr.cnes.doi.client.BaseClient
DATACITE_MOCKSERVER_PORT

Constructor Summary

Constructors
Constructor and Description
`ClientMDS(ClientMDS.Context context)` Creates a client to handle DataCite server.
`ClientMDS(ClientMDS.Context context, String login, String pwd)` Creates a client to handle DataCite with a HTTP Basic authentication.
`ClientMDS(String login, String pwd)` Creates a client to handle DataCite with a HTTP Basic authentication.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`static void`	`checkIfAllCharsAreValid(String test)` DataCite recommends that only the following characters are used within a DOI name: 0-9 a-z A-Z - (dash) .
`private void`	`checkInputForm(org.restlet.data.Form form)` Checks the input parameters and specially the validity of the DOI name.
`String`	`createDoi(org.restlet.data.Form form)` Will mint new DOI if specified DOI doesn't exist.
`private org.restlet.representation.Representation`	`createEntity(org.restlet.data.Form mediaForm)` Creates an entity based on the form.
`String`	`createMedia(String doiName, org.restlet.data.Form form)` Will add/update media type/urls pairs to a DOI.
`String`	`createMetadata(org.restlet.representation.Representation entity)` This request stores new version of metadata.
`String`	`createMetadata(Resource entity)` Creates metadata with 201 status when operation successful.
`private org.restlet.data.Reference`	`createReference(String segment)` Create reference.
`private org.restlet.data.Reference`	`createReferenceWithDOI(String segment, String doiName)` Creates the URL to query.
`private org.restlet.representation.Representation`	`createRequest(org.restlet.data.Reference url, org.restlet.data.Form form)` Creates the request and requests the DOI creation
`org.restlet.representation.Representation`	`deleteMetadata(String doiName)` This request marks a dataset as 'inactive'.
`Resource`	`deleteMetadataDoiAsObject(String doiName)` This request marks a dataset as 'inactive'.
`String`	`getDoi(String doiName)` This request returns an URL associated with a given DOI.
`private String`	`getDoiAccorgindToContext(String doiName)` Returns the right DOI according to the context (DEV, POST_DEV, ...).
`List<String>`	`getDois()`
`List<String>`	`getDois(String idProject)` Returns only the dois within the specified project from the search result.
`private List<String>`	`getList(String segment)` Returns the response as a list of String of an URI.
`String`	`getMedia(String doiName)` This request returns list of pairs of media type and URLs associated with a given DOI.
`org.restlet.representation.Representation`	`getMetadata(String doiName)` Returns the metadata based on its DOI name.
`Resource`	`getMetadataAsObject(String doiName)` This request returns the most recent version of metadata associated with a given DOI.
`private org.restlet.data.Parameter`	`getTestMode()` Returns the `TEST_MODE` or an empty parameter according to isTestMode
`private String`	`getText(org.restlet.representation.Representation rep)` Returns the text of a response.
`private void`	`initReference()` Init the client to the reference `DATA_CITE_URL` or `DATA_CITE_TEST_URL`
`private Resource`	`parseDataciteResource(org.restlet.representation.Representation rep)` Parses the XML representation that implements the DATACITE schema.
`Resource`	`parseMetadata(org.restlet.representation.Representation entity)` Parses the metadata and returns the Resource object from DataCite.
`private String`	`useTestPrefix(String doiName)` Renames the current DOI prefix by the DOI test prefix.

Methods inherited from class fr.cnes.doi.client.BaseClient
getClient, getLog

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - DATA_CITE_URL
```
public static final String DATA_CITE_URL
```
    Metadata store service endpoint "https://mds.datacite.org".
    
    See Also:
    
    Constant Field Values
  - DATA_CITE_MOCK_URL
```
public static final String DATA_CITE_MOCK_URL
```
    Metadata store mock service endpoint "http://localhost:1080".
    
    See Also:
    
    Constant Field Values
  - DATA_CITE_TEST_URL
```
public static final String DATA_CITE_TEST_URL
```
    Metadata store test service endpoint "https://mds.test.datacite.org".
    
    See Also:
    
    Constant Field Values
  - DOI_RESOURCE
```
public static final String DOI_RESOURCE
```
    DOI resource "doi".
    
    See Also:
    
    Constant Field Values
  - METADATA_RESOURCE
```
public static final String METADATA_RESOURCE
```
    Metadata resource "metadata".
    
    See Also:
    
    Constant Field Values
  - MEDIA_RESOURCE
```
public static final String MEDIA_RESOURCE
```
    Media resource "media".
    
    See Also:
    
    Constant Field Values
  - TEST_MODE
```
public static final org.restlet.data.Parameter TEST_MODE
```
    Test mode sets to true.
  - TEST_DOI_PREFIX
```
public static final String TEST_DOI_PREFIX
```
    Test DOI prefix "10.80163".
    
    See Also:
    
    Constant Field Values
  - POST_DOI
```
public static final String POST_DOI
```
    DOI query parameter "doi".
    
    See Also:
    
    Constant Field Values
  - POST_URL
```
public static final String POST_URL
```
    URL query parameter "url".
    
    See Also:
    
    Constant Field Values
  - SCHEMA_DATACITE
```
public static final String SCHEMA_DATACITE
```
    Default XML schema for Datacite: "https://schema.datacite.org/meta/kernel-4-1/metadata.xsd"
    
    See Also:
    
    Constant Field Values
  - SCHEMA_FACTORY
```
private static final SchemaFactory SCHEMA_FACTORY
```
    SCHEMA_FACTORY.
  - DOI_SETTINGS
```
private static final DoiSettings DOI_SETTINGS
```
    Loads DOI settings.
  - testMode
```
private final org.restlet.data.Parameter testMode
```
    Selected test mode.
  - context
```
private final ClientMDS.Context context
```
    Context.
- Constructor Detail
  - ClientMDS
```
public ClientMDS(ClientMDS.Context context)
          throws ClientMdsException
```
    Creates a client to handle DataCite server. There is special test prefix 10.5072 available to all datacentres. Please use it for all your testing DOIs. Your real prefix should not be used for test DOIs. Note that DOIs with test prefix will behave like any other DOI, e.g. they can be normally resolved. They will not be exposed by upcoming services like search and OAI, though. Periodically we purge * all 10.5072 datasets from the system.
    It is important to understand that the Handle System (the technical infrastructure for DOIs) is a distributed network system. The consequence of this manifests is its inherent latency. For example, DOIs have TTL (time to live) defaulted to 24 hours, so your changes will be visible to the resolution infrastructure only when the TTL expires. Also, if you create a DOI and then immediately try to update its URL, you might get the error message HANDLE NOT EXISTS. This is because it takes some time for the system to register a handle for a DOI. Each API call can have optional query parametertestMode. If set to "true" or "1" the request will not change the database nor will the DOI handle will be registered or updated, e.g. POST /doi?testMode=true and the testing prefix will be used instead of the provided prefix
    
    Parameters:
    
    context - Context using
    
    Throws:
    
    ClientMdsException - Cannot the Datacite schema
  - ClientMDS
```
public ClientMDS(ClientMDS.Context context,
                 String login,
                 String pwd)
          throws ClientMdsException
```
    Creates a client to handle DataCite with a HTTP Basic authentication. All the traffic goes via HTTPS - please remember we do not support bare HTTP. All the requests to this system require HTTP Basic authentication header. You will get your username and password from your local DataCite allocator. Each account have some constraints associated with it:
    - you will be allowed to mint DOIs only with prefix assigned to you
    - you will be allowed to mint DOIs only with URLs in host domains assigned to you
    - you might not be able to mint unlimited number of DOIs, there is a quota assigned to you by your allocator (the quota can be extended or lifted though)
    Each API call can have optional query parametertestMode. If set to "true" or "1" the request will not change the database nor will the DOI handle will be registered or updated, e.g. POST /doi?testMode=true.
    Parameters:
    
    context - Context using
    
    login - Login
    
    pwd - password
    
    Throws:
    
    ClientMdsException - Cannot the Datacite schema
  - ClientMDS
```
public ClientMDS(String login,
                 String pwd)
          throws ClientMdsException
```
    Creates a client to handle DataCite with a HTTP Basic authentication.
    
    Parameters:
    
    login - Login
    
    pwd - password
    
    Throws:
    
    ClientMdsException - Cannot the Datacite schema
- Method Detail
  - checkIfAllCharsAreValid
```
public static void checkIfAllCharsAreValid(String test)
```
    DataCite recommends that only the following characters are used within a DOI name:
    - 0-9
    - a-z
    - A-Z
    - - (dash)
    - . (dot)
    - _ (underscore)
    - + (plus)
    - : (colon)
    - / (slash)
    Parameters:
    
    test - DOI name to test
    
    Throws:
    
    IllegalArgumentException - An exception is thrown when at least one character is not part of 0-9a-zA-Z\\-._+:/ of a DOI name
  - getTestMode
```
private org.restlet.data.Parameter getTestMode()
```
    Returns the TEST_MODE or an empty parameter according to isTestMode
    
    Returns:
    
    the test mode
  - useTestPrefix
```
private String useTestPrefix(String doiName)
```
    Renames the current DOI prefix by the DOI test prefix.
    
    Parameters:
    
    doiName - real DOI name
    
    Returns:
    
    the renamed DOI with the test prefix
  - initReference
```
private void initReference()
```
    Init the client to the reference DATA_CITE_URL or DATA_CITE_TEST_URL
  - createReference
```
private org.restlet.data.Reference createReference(String segment)
```
    Create reference. The parameter ?testMode=true is added in DEV context
    
    Parameters:
    
    segment - segment to add to the end point
    
    Returns:
    
    new URL
  - createReferenceWithDOI
```
private org.restlet.data.Reference createReferenceWithDOI(String segment,
                                                          String doiName)
```
    Creates the URL to query.
    
    Parameters:
    
    segment - segment to add to the end point service
    
    doiName - doi name
    
    Returns:
    
    the URL to query
  - getDoiAccorgindToContext
```
private String getDoiAccorgindToContext(String doiName)
```
    Returns the right DOI according to the context (DEV, POST_DEV, ...). When the context has a DOI test prefix, the real DOI prefix is replaced by the DOI test prefix.
    
    Parameters:
    
    doiName - DOI name
    
    Returns:
    
    the right DOI
  - checkInputForm
```
private void checkInputForm(org.restlet.data.Form form)
                     throws IllegalArgumentException
```
    Checks the input parameters and specially the validity of the DOI name. The real prefix is replaced by the test prefix in DEV, POST_DEV and PRE_PROD context. The DOI prefix may replace according to the context.
    
    Parameters:
    
    form - query form
    
    Throws:
    
    IllegalArgumentException - An exception is thrown when doi and url are not provided or when one character at least in the DOI name is not valid
  - getText
```
private String getText(org.restlet.representation.Representation rep)
                throws ClientMdsException
```
    Returns the text of a response.
    
    Parameters:
    
    rep - Response of the server
    
    Returns:
    
    the text of the response
    
    Throws:
    
    ClientMdsException - An exception is thrown when cannot convert the Representation to text
  - getList
```
private List<String> getList(String segment)
                      throws ClientMdsException
```
    Returns the response as a list of String of an URI.
    
    Parameters:
    
    segment - resource name
    
    Returns:
    
    the response
    
    Throws:
    
    ClientMdsException - - if an error happens when requesting CrossCite
  - getDoi
```
public String getDoi(String doiName)
              throws ClientMdsException
```
    This request returns an URL associated with a given DOI. A 200 status is an operation successful. A 204 status means no content (DOI is known to MDS, but is not minted (or not resolvable e.g. due to handle's latency) The DOI prefix may replace according to the context.
    Parameters:
    
    doiName - DOI name
    
    Returns:
    
    an URL or no content (DOI is known to MDS, but is not minted (or not resolvable e.g. due to handle's latency))
    
    Throws:
    ClientMdsException - - if an error happens
    
    401 Unauthorized - no login
    
    403 - login problem or dataset belongs to another party
    
    404 Not Found - DOI does not exist in our database
    
    500 Internal Server Error - server internal error, try later and if problem persists please contact us
    See Also:
    
    "https://mds.datacite.org/static/apidoc#tocAnchor-13"
  - getDois
```
public List<String> getDois()
                     throws ClientMdsException
```
    Throws:
    
    ClientMdsException
  - getDois
```
public List<String> getDois(String idProject)
                     throws ClientMdsException
```
    Returns only the dois within the specified project from the search result.
    
    Parameters:
    
    idProject - project ID
    
    Returns:
    
    the search result
    
    Throws:
    
    ClientMdsException - When an error happens with Datacite
  - createDoi
```
public String createDoi(org.restlet.data.Form form)
                 throws ClientMdsException
```
    Will mint new DOI if specified DOI doesn't exist. This method will attempt to update URL if you specify existing DOI. Standard domains and quota restrictions check will be performed. A Datacentre's doiQuotaUsed will be increased by 1. A new record in Datasets will be created when 201 Created status is returned. The DOI prefix may replace according to the context.
    Parameters:
    
    form - A form with the following attributes doi and url
    
    Returns:
    
    short explanation of status code e.g. CREATED, HANDLE_ALREADY_EXISTS etc
    
    Throws:
    ClientMdsException - - if an error happens
    
    400 Bad Request - request body must be exactly two lines: DOI and URL; wrong domain, wrong prefix
    
    401 Unauthorized - no login
    
    403 Forbidden - login problem, quota exceeded
    
    412 Precondition failed - metadata must be uploaded first
    
    500 Internal Server Error - server internal error, try later and if problem persists please contact us
    See Also:
    
    "https://mds.datacite.org/static/apidoc#tocAnchor-15"
  - createRequest
```
private org.restlet.representation.Representation createRequest(org.restlet.data.Reference url,
                                                                org.restlet.data.Form form)
```
    Creates the request and requests the DOI creation
    
    Parameters:
    
    url - url
    
    form - form
    
    Returns:
    
    representation of the response
  - parseDataciteResource
```
private Resource parseDataciteResource(org.restlet.representation.Representation rep)
                                throws ClientMdsException
```
    Parses the XML representation that implements the DATACITE schema.
    
    Parameters:
    
    rep - XML representation
    
    Returns:
    
    the Resource object
    
    Throws:
    
    ClientMdsException - Will throw when a problem happens during the parsing
  - getMetadataAsObject
```
public Resource getMetadataAsObject(String doiName)
                             throws ClientMdsException
```
    This request returns the most recent version of metadata associated with a given DOI. A status of 200 is an operation successful. The DOI prefix may replace according to the context.
    Parameters:
    
    doiName - DOI name
    
    Returns:
    
    XML representing a dataset
    
    Throws:
    ClientMdsException - - if an error happens
    
    401 Unauthorized - no login
    
    403 Forbidden - login problem or dataset belongs to another party
    
    404 Not Found - DOI does not exist in our database
    
    410 Gone - the requested dataset was marked inactive (using DELETE method)
    
    500 Internal Server Error - server internal error, try later and if problem persists please contact us
  - getMetadata
```
public org.restlet.representation.Representation getMetadata(String doiName)
                                                      throws ClientMdsException
```
    Returns the metadata based on its DOI name. A status of 200 is an operation successful. The DOI prefix may replace according to the context.
    Parameters:
    
    doiName - DOI name
    
    Returns:
    
    the metadata as XML
    
    Throws:
    ClientMdsException - - if an error happens
    
    200 OK - operation successful
    
    401 Unauthorized - no login
    
    403 Forbidden - login problem or dataset belongs to another party
    
    404 Not Found - DOI does not exist in our database
    
    410 Gone - the requested dataset was marked inactive (using DELETE method)
    
    500 Internal Server Error - server internal error, try later and if problem persists please contact us
    See Also:
    
    "https://mds.datacite.org/static/apidoc#tocAnchor-15"
  - createMetadata
```
public String createMetadata(org.restlet.representation.Representation entity)
                      throws ClientMdsException
```
    This request stores new version of metadata. Creates metadata with 201 status when operation successful. The DOI prefix may replace according to the context.
    Parameters:
    
    entity - A valid XML
    
    Returns:
    
    short explanation of status code e.g. CREATED,HANDLE_ALREADY_EXISTS etc
    
    Throws:
    ClientMdsException - - if an error happens
    
    400 Bad Request - invalid XML, wrong prefix
    
    401 Unauthorized - no login
    
    403 Forbidden - login problem, quota exceeded
    
    500 Internal Server Error - server internal error, try later and if problem persists please contact us
    See Also:
    
    "https://mds.datacite.org/static/apidoc#tocAnchor-18"
  - createMetadata
```
public String createMetadata(Resource entity)
                      throws ClientMdsException
```
    Creates metadata with 201 status when operation successful. The DOI prefix may replace according to the context. The method is synchronized because marshall method is not thread-safe.
    Parameters:
    
    entity - Metadata
    
    Returns:
    
    short explanation of status code e.g. CREATED, HANDLE_ALREADY_EXISTS etc
    
    Throws:
    ClientMdsException - - if an error happens
    
    400 Bad Request - invalid XML, wrong prefix
    
    401 Unauthorized - no login
    
    403 Forbidden - login problem, quota exceeded
    
    500 Internal Server Error - server internal error, try later and if problem persists please contact us
    See Also:
    
    "https://mds.datacite.org/static/apidoc#tocAnchor-18"
  - parseMetadata
```
public Resource parseMetadata(org.restlet.representation.Representation entity)
                       throws ValidationException
```
    Parses the metadata and returns the Resource object from DataCite. The method is synchronized because unmarshall method is not thread-safe.
    
    Parameters:
    
    entity - metadata
    
    Returns:
    
    the Resource object from DataCite
    
    Throws:
    
    ValidationException - When validation failed
  - deleteMetadataDoiAsObject
```
public Resource deleteMetadataDoiAsObject(String doiName)
                                   throws ClientMdsException
```
    This request marks a dataset as 'inactive'. To activate it again, POST new metadata or set the isActive-flag in the user interface. A status of 200 is an operation successful. The DOI prefix may replace according to the context.
    Parameters:
    
    doiName - DOI name
    
    Returns:
    
    XML representing a dataset
    
    Throws:
    ClientMdsException - - if an error happens
    
    401 Unauthorized - no login
    
    403 Forbidden - login problem or dataset belongs to another party
    
    404 Not Found - DOI does not exist in our database
    
    500 Internal Server Error - server internal error, try later and if problem persists please contact us
    See Also:
    
    "https://mds.datacite.org/static/apidoc#tocAnchor-19"
  - deleteMetadata
```
public org.restlet.representation.Representation deleteMetadata(String doiName)
                                                         throws ClientMdsException
```
    This request marks a dataset as 'inactive'. To activate it again, POST new metadata or set the isActive-flag in the user interface. A status of 200 is an operation successful The DOI prefix may replace according to the context.
    Parameters:
    
    doiName - DOI name
    
    Returns:
    
    the deleted metadata
    
    Throws:
    ClientMdsException - - if an error happens
    
    401 Unauthorized - no login
    
    403 Forbidden - login problem or dataset belongs to another party
    
    404 Not Found - DOI does not exist in our database
    
    500 Internal Server Error - server internal error, try later and if problem persists please contact us
    See Also:
    
    "https://mds.datacite.org/static/apidoc#tocAnchor-19"
  - getMedia
```
public String getMedia(String doiName)
                throws ClientMdsException
```
    This request returns list of pairs of media type and URLs associated with a given DOI. A status of 200 is an operation successful. The DOI prefix may replace according to the context.
    Parameters:
    
    doiName - DOI name
    
    Returns:
    
    list of pairs of media type and URLs
    
    Throws:
    ClientMdsException - - if an error happens
    
    401 Unauthorized - no login
    
    403 login problem or dataset belongs to another party
    
    404 Not Found - No media attached to the DOI or DOI does not exist in our database
    
    500 Internal Server Error - server internal error, try later and if problem persists please contact us
    See Also:
    
    "https://mds.datacite.org/static/apidoc#tocAnchor-21"
  - createMedia
```
public String createMedia(String doiName,
                          org.restlet.data.Form form)
                   throws ClientMdsException
```
    Will add/update media type/urls pairs to a DOI. A status of 200 is an operation successful.Standard domain restrictions check will be performed. The DOI prefix may replace according to the context.
    Parameters:
    
    doiName - DOI identifier
    
    form - Multiple lines in the following format{mime-type}={url} where {mime-type} and {url} have to be replaced by your mime type and URL, UFT-8 encoded.
    
    Returns:
    
    short explanation of status code
    
    Throws:
    ClientMdsException - - if an error happens
    
    400 Bad Request - one or more of the specified mime-types or urls are invalid (e.g. non supported mime-type, not allowed url domain, etc.)
    
    401 Unauthorized - no login
    
    403 Forbidden - login problem
    
    500 Internal Server Error - server internal error, try later and if problem persists please contact us
    See Also:
    
    "https://mds.datacite.org/static/apidoc#tocAnchor-22"
  - createEntity
```
private org.restlet.representation.Representation createEntity(org.restlet.data.Form mediaForm)
```
    Creates an entity based on the form. The form contains a set of mime-type/url
    
    Parameters:
    
    mediaForm - form
    
    Returns:
    
    Text entity

Class ClientMDS

Nested Class Summary

Field Summary

Fields inherited from class fr.cnes.doi.client.BaseClient

Constructor Summary

Method Summary

Methods inherited from class fr.cnes.doi.client.BaseClient

Methods inherited from class java.lang.Object

Field Detail

DATA_CITE_URL

DATA_CITE_MOCK_URL

DATA_CITE_TEST_URL

DOI_RESOURCE

METADATA_RESOURCE

MEDIA_RESOURCE

TEST_MODE

TEST_DOI_PREFIX

POST_DOI

POST_URL

SCHEMA_DATACITE

SCHEMA_FACTORY

DOI_SETTINGS

testMode

context

Constructor Detail

ClientMDS

ClientMDS

ClientMDS

Method Detail

checkIfAllCharsAreValid

getTestMode

useTestPrefix

initReference

createReference

createReferenceWithDOI

getDoiAccorgindToContext

checkInputForm

getText

getList

getDoi

getDois

getDois

createDoi

createRequest

parseDataciteResource

getMetadataAsObject

getMetadata

createMetadata

createMetadata

parseMetadata

deleteMetadataDoiAsObject

deleteMetadata

getMedia

createMedia

createEntity