nceas / ezid

Implementation of the EZID identifier services in a Java library

EZID Service Library

EZID is a service for creating and managing unique identifiers for use in scholarly publishing that is provided by the California Digital Library. This software library, ezid, provides a Java class that encapsulates the EZID service to simplify writing client applications that use the EZID service. ezid provides methods for authenticating against the EZID service and then managing identifiers. Using the service requires an account with the EZID service. For more information, see: http://ezid.cdlib.org/doc/apidoc.html

Once you have added the library to your project classpath (see below), you can generate identifiers with EZID with simple Java calls. Here's a simple example to mint a new identifier using a DataCite 4.0 compliant metadata file in the current directory:

import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.util.HashMap;
import edu.ucsb.nceas.ezid.EZIDService;
import edu.ucsb.nceas.ezid.EZIDException;

public class EZIDExample {
    public static void main(String args[]) {
        try {
            String USERNAME = "apitest";
            String PASSWORD = "apitest";
            String DOISHOULDER = "doi:10.5072/FK2";

            EZIDService ezid = new EZIDService();
            ezid.login(USERNAME, PASSWORD);

            HashMap<String, String> metadata = new HashMap<String, String>();
            String xml = new String(Files.readAllBytes((Paths.get("datacite.xml"))));
            metadata.put("datacite", xml);
            String testId = ezid.mintIdentifier(DOISHOULDER, metadata);
            System.out.println("Generated: " + testId);
        } catch (EZIDException e) {
            System.err.println("Identifier minting failed: " + e.getMessage());
        } catch (IOException e) {
            System.err.println("Reading DataCiteXML failed: " + e.getMessage());
        }
    }
}

See the javadoc documentation for an overview of usage, as well as the EZIDServiceTest.java JUnit class for more examples of usage.

See the License section below and LICENSE.txt for the details of distributing this software.

Contributors

• Matthew B. Jones, NCEAS
• Ben Leinfelder, NCEAS

Using the library

To use the library in your Java application, you can add it to your pom.xml configuration if you are using Maven. You can access the ezid jar files through Maven by adding the appropriate maven repository to your pom. Something like this snippet should work:

    ...
    <repositories>
        <repository>
            <id>dataone.org</id>
            <url>http://dev-testing.dataone.org/maven</url>
            <releases>
                <enabled>true</enabled>
            </releases>
            <snapshots>
                <enabled>true</enabled>
            </snapshots>
        </repository>
    </repositories>
    <dependencies>
    	<dependency>
    		<groupId>edu.ucsb.nceas</groupId>
			<artifactId>ezid</artifactId>
			<version>1.0.3</version>
			<type>jar</type>
    	</dependency>
    </dependencies>

We plan to publish the ezid artifacts to Maven Central repositories, but have not gotten there yet.

Building the library

The library is a standard Maven2 project. To build the library, install Maven2, and then run:

$ mvn package

which will create the jar file in the target directory. The jar file can then be included in applications that wish to access EZID.

Contact us: [email protected]

Contributions

We welcome contributions to the project, and will incorporate pull requests after code review as long as the code requests are licensed acceptably and provide improvements that would generally be useful to the community of EZID users. Please submit pull request via GitHub.

Issue Tracking

Bugs, new features, and comments on the EZID library are handled through the ezid issue tracker.

License

This work was created by the National Center for Ecological Analysis and
Synthesis at the University of California Santa Barbara (UCSB).

  Copyright 2011-2104 Regents of the University of California

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

ezid's Issues

EZID Ships with a log4j.properties File

Good Afternoon,

I would like to request that the log4j.properties file be removed from your build if possible.

The shipped log4j.properties file is clashing with our logging properties file and causing our application to spew a ton of unwanted log messages.

Thank you for your time,

Regards,

Nate

add instructions for pulling release from maven

Need to explain how to get the release from Maven.

publish version 1.0.0 to Maven Central

The library would be more accessible from a common, public maven repo. Publish it there.

document SSL certificate configuration

When n2t.net changed its SSL certificate, it no longer became trusted by Java by default. To make the ezid library work, one has to configure java to recognize the new SSL certificate. We need to document this process in the library configuration. Greg Janée describes the issues from an email thread:

Anyway, I downloaded this Java client and found two problems. First, Java (even Java 7) does not recognize n2t.net's new SSL certificate, hence the "peer not authenticated" errors. To correct this, 1) download n2t.net's certificate, 2) create a local truststore and insert the certificate in the truststore, and 3) run the test again. To download n2t.net's certificate, follow the instructions in this message sent on the EZID list: http://listserv.ucop.edu/cgi-bin/wa.exe?A2=ind1307E&L=EZID-L&F=&S=&P=1524. To create a local truststore, I did this:

% keytool -import -file certificateFile.crt -keystore keystore.ks

To rerun Maven and recognize the new truststore, I did this:

% mvn -Djavax.net.ssl.trustStore=keystore.ks package

Rename the master branch to main

From an inclusivity perspective, I suggest we rename the master branch to main and generally use more welcoming terms as we describe our software architectures. The use of the the terms master and slave in computing are not welcoming. For context, see the Inclusive Naming project and this repo.

Fix issues with SNI support in SSL

Need to update httpclient to fix SNI.

EZID updating web target

Following message from John Kunze affects this codebase as there are hard-coded references to http://n2t.net/ezid.... Just an FYI :)

John Deck

Message from John Kunze:
As previously announced, EZID's URL was switched from http://n2t.net/ezid
to http://ezid.cdlib.org last night. If you have not already done so,
please update your bookmarks and API clients. As before, this means that

1. The URL for EZID's home page changed from http://n2t.net/ezid to
   http://ezid.cdlib.org .
2. The URL to EZID's API changed to http://ezid.cdlib.org .
3. The persistent links, expressed as URLs, of the ARKs and DOIs
   that EZID creates will not change.

While browsers will be redirected from the old URL to the new URL for at
least 1 year, the situation is different for API clients.

For API clients, direct PUT and POST requests against the old URL will be
supported for 1 month. If your API client is experiencing difficulty in
establishing a secure connection to the old URL, it is likely due to your
client's SSL library not supporting a feature called "TLS server name
indication support (RFC 4366)". The easiest remedy is simply to switch
your client to use the new URL, although it is also possible to configure
your client to be able to connect anyway, such as setting up a local
"trust store".

Document and tag 1.0.0 release

When all issues are resolved, need to document and tag the release. The ezid lib has been working well in production for us for about 6 months so we can move forward with a 1.0.0 release.

Should metadata be automatically created for DOIs?

From email thread from Steve Kraffmiller and Greg Janée:

With that problem out of the way, I ran into the next problem, which is that the test code attempts to create a DOI identifier without supplying the required metadata. (This software was apparently written before metadata requirements were put in place some time ago.)

The bottom line is that this client code works, and is probably a good starting point if you're trying to develop a Java solution, but the code is a little dated and needs some updating. You might consider contacting the author of the code.

At this point I don't see a bug here, but I could be convinced otherwise. The EZID library provides a method to submit the metadata along with the create request, so the user of the library is able to submit the required metadata along with the request for the DOI by passing in a hash array of the metadata to be submitted. We don't automatically do this, nor do we require it, because the other schemes like ARKs don't have the same requirements, so we want to maintain the flexibility for users to create identifiers without metadata while supporting the submission of required metadata as well. Is there really anything that needs to be changed here?

Clients can't catch exceptions when they call some methods in the EZIDClient class which run in different threads

In the EZIDClient class, methods such as, create, createOrUpdate, setMetadata, and delete run on a different thread. When errors happen in another thread, it only logs in a file. So this cause clients can't capture the exception. Here is a ticket to describe the issue in Metacat:
NCEAS/metacat#1545

We need provide a mechanism for client to catch the exceptions even though we still keep the multi-thread feature.