JCDF is a pure java library capable of reading files in the Common Data Format defined by NASA. It runs within the J2SE1.5 (or later), but other than that has no dependencies, neither the official CDF C library nor any other java class libraries.
The classes are provided with comprehensive
Start reading at the
for high-level access to CDF data and metadata, or
for low-level access to the CDF internal records.
JCDF is a completely separate implementation from the Java interface to the official CDF library, which uses native code via JNI. It was written mainly with reference to the CDF Internal Format Description document (v3.4). Minor updates at version JCDF 1.1 are believed to bring it into line with CDF v3.6.
The main benefit of using JCDF, and the reason for developing it, is that it's pure java, so it can be deployed using only the JCDF jar file. There is no need to install the system-dependent official CDF library.
The API is very different from that of the official CDF library. JCDF gives you a simple view of the CDF file, in terms of its global attributes, variable attributes and variables. This is fairly easy to use, but may or may not suit your purposes. It's also possible to get a low-level view of the CDF file as a sequence of CDF records.
JCDF offers no capabilities for writing or editing CDF files, it only reads them.
JCDF is based on NIO mapped ByteBuffers, it's expected to be reasonably fast, but I haven't done any benchmarking.
Use of mapped buffers leads to efficient serial and random I/O, but does have some associated problems concerning release of allocated resources. For reasons that are quite complicated, it is hard to release mapped buffers after use, which means that for instance files you have read using JCDF may be hard to delete, and that reading large files may leak significant amounts of virtual memory. There are some more or less nasty ways to work round this in user code or in the library. If these issues cause practical problems for library users, you are encouraged to contact me by email or open a github issue.
Support for the CDF format is almost, but not totally, complete. In particular:
The library comes with a couple of simple utilities for examining CDF files:
cdfdumpcommand in the official CDF distribution. If the
-dataflag is supplied, record data as well as metadata is shown. See CdfList examples.
cdfirsdumpcommand in the official CDF distribution. If the
-fieldsflag is supplied, field information from each record is shown. If the
-htmlflag is supplied, the output is in HTML with files offsets displayed as hyperlinks, which is nice for chasing pointers. See CdfDump examples.
The source code is hosted on github at https://github.com/mbtaylor/jcdf. It comes with a makefile that can be used to build the jar file, javadocs, and this documentation, and to run some tests.
Pre-built copies of the jar file and documentation for the current version (v1.2-4) can be found here:
Previous versions may be available at https://www.star.bristol.ac.uk/mbt/releases/jcdf/.
CDF_LEAPSECONDSTABLEenvironment variable as for NASA library. Internal leap seconds table is updated until 2012-07-01.
rfuDis now renamed as
leapSecondLastUpdated. It is also used when formatting TIME_TT2000 data values for output; if the library leap second table is out of date with respect to the data a warning is issued for information, and if the time values are known to have leap seconds applied invalidly, an error is thrown or a severe log message is issued. This behaviour follows that of the official CDF library.
BankBuf): unsigned bytes could be read wrong in some cases, and data could be read wrong near the boundaries of multi-buffer files (only likely to show up for files >2Gbyte). Thanks to Lukas Kvasnica (Brno) for identifying and fixing these.
leapSecondLastUpdatedfield from the Global Descriptor Record; this could cause a RuntimeException with a message about the library leap second table being out of date during TT2000 date formatting.
This software was written by Mark Taylor at the University of Bristol at the request of, and funded by, the science archive group at ESA's European Space Astronomy Centre (ESAC).
It is used within TOPCAT/STILTS/STIL to enable access to CDF tables alongside other tabular data formats by that software. It is believed to be in some use also at ESAC and elsewhere. If anybody out there is using it and is willing to be listed here, let me know.
It is licenced under the LGPL, though if you need a different licence I can probably fix it.
My thanks to several people who have helped with development and testing, including Christophe Arviset, Robert Candey, Michael Liu, Jeremy Faden and Bogdan Nicula.
Bugs, questions, feedback, enhancement requests welcome to email@example.com.