cff-reader-java

cff-reader-java

A Java API for reading software citation metadata files in the Citation File Format The API provides POJO models for software citation metadata for inspection and re-use.

Entry point

The main entry point to the API is via the SoftwareCitationMetadataReader interface. For example:

SoftwareCitationMetadataReader reader = new SoftwareCitationMetadataPojoReader();
		
File cffFile = new File(...);
SoftwareCitationMetadata citationMetadata = reader.readFromFile(cffFile);

/* 
 * Alternatively, e.g., for reading files from the
 * class loader via 
 * `this.getClass().getResourceAsStream("/CITATION.cff")`
 */
InputStream cffInputStream = ...;
citationMetadata = reader.readFromStream(cffInputStream);

// Inspect/re-use
citationMetadata.getTitle();
citationMetadata.getVersion();
...
for (author : citationMetadata.getPersonAuthors()) {
	author.getFamilyNames();
	author.getGivenNames();
	...
}
for (author : citationMetadata.getEntityAuthors()) {
	author.getName();
	...
}
for (reference : citationMetadata.getReferences()) {
	reference.getType();
	reference.getTitle();
	...
	for (author : reference.getPersonAuthors()) {
		author.getFamilyNames();
		author.getGivenNames();
	...
	}
	for (author : reference.getEntityAuthors()) {
		author.getName();
		...
	}
}

Exceptions

Upon errors, the API will throw exceptions:

• InvalidCFFFileNameException – thrown on attempted reads of files with an invalid name (CFF file must be named CITATION.cff)
• InvalidDataException – thrown on encountering invalid data in the CFF file, as specified in the Citation File Format specifications
• ReadException – thrown on encountering errors or exceptions during the read process

InvalidDataException and ReadException may wrap cause exceptions.

Installation

Maven

The API is provided via the usual Sonatype Snapshot Repository (OSSRH) and Maven Central.

<dependencies>
    <dependency>
        <groupId>org.research-software.citation</groupId>
        <artifactId>cff-reader-java</artifactId>
        <version>1.0.1</version>
    </dependency>
</dependencies>

Documentation

General documentation is maintained at https://citation-file-format.github.io/cff-reader-java, including API JavaDocs.

Source code and contribution

The source code for this project is maintained at https://github.com/citation-file-format/cff-reader-java, where you can also find guideliens on contributing.

Build

Build the project locally with mvn {clean} install.

License

Copyright (c) 2018ff. Stephan Druskat

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.