NexusFile.java

Go to the documentation of this file.

package org.nexusformat;

import java.util.Hashtable;
import java.io.File;
import ncsa.hdf.hdflib.HDFArray;
import ncsa.hdf.hdflib.HDFException;
import ncsa.hdf.hdflib.HDFConstants;

public class NexusFile implements NeXusFileInterface {

    // constants 
    public final static int NXACC_READ = 1;
    public final static int NXACC_RDWR = 2;
    public final static int NXACC_CREATE = 3;
    public final static int NXACC_CREATE4 = 4;
    public final static int NXACC_CREATE5 = 5;
    public final static int NXACC_CREATEXML = 6;
    public final static int NXACC_NOSTRIP = 128;
    
    public final static int NX_UNLIMITED = -1;

    public final static int NX_FLOAT32 = 5; 
    public final static int NX_FLOAT64 = 6; 
    public final static int NX_INT8 = 20; 
    public final static int NX_BINARY = 20;
    public final static int NX_UINT8 = 21; 
    public final static int NX_BOOLEAN = 21; 
    public final static int NX_INT16 = 22; 
    public final static int NX_UINT16 = 23; 
    public final static int NX_INT32 = 24; 
    public final static int NX_UINT32 = 25; 
    public final static int NX_INT64 = 26; 
    public final static int NX_UINT64 = 27; 
    public final static int NX_CHAR   = 4;

    public final static int NX_COMP_NONE = 100;
    public final static int NX_COMP_LZW =  200;
    public final static int NX_COMP_RLE =  300;
    public final static int NX_COMP_HUF =  400;

    protected final static int MAXNAMELEN = 64;

    /*
       This code takes care of loading the static library required for
       this class to work properly. The algorithm first looks for a 
       property org.nexusformat.JNEXUSLIB and loads that file if available,
       else it tries to locate the library in the system shared library 
       path.
    */
     static
     {
        String filename = null;   
        filename = System.getProperty("org.nexusformat.JNEXUSLIB",null);
        if ((filename != null) && (filename.length() > 0))
        {
            File hdfdll = new File(filename);
            if (hdfdll.exists() && hdfdll.canRead() && hdfdll.isFile()) 
            {
                System.load(filename);
             } else {
                 throw (new UnsatisfiedLinkError("Invalid JNEXUS library"));
             }
         }
         else {
            System.loadLibrary("jnexus");
         }
      }

    protected int handle;

    // Construction
    // native methods for this section
    protected native int  init(String filename, int access);
    protected native void close(int handle);
    protected native int  nxflush(int handle);
    
    public NexusFile(String filename, int access) throws NexusException {
         checkForNull(filename);

         handle = init(filename,access);
         if(handle < 0){
            throw new NexusException("Failed to open " + filename);
         }
    }

    public void flush() throws NexusException {
        if(handle < 0) throw new NexusException("NAPI-ERROR: File not open");
         handle = nxflush(handle);
    }

    public void close() throws NexusException {
        if(handle  >= 0) {
           close(handle);
           handle = -1;
        }
    }
    
    public void finalize() throws Throwable {
        close();
    }


    // group functions
    //native methods for this section
    protected native void nxmakegroup(int handle, String name, String nxclass);
    protected native void nxopengroup(int handle, String name, String nxclass);
    protected native void nxopenpath(int handle, String path);
    protected native void nxopengrouppath(int handle, String path);
    protected native void nxclosegroup(int handle);
    protected native String nxgetpath(int handle);

    public void makegroup(String name, String nxclass) throws NexusException {
        checkForNull(name, nxclass);
        if(handle < 0) throw new NexusException("NAPI-ERROR: File not open");
        nxmakegroup(handle, name, nxclass);
    }

    public void opengroup(String name, String nxclass) throws NexusException {
        if(handle < 0) throw new NexusException("NAPI-ERROR: File not open");
        checkForNull(name, nxclass);
        nxopengroup(handle, name, nxclass);
    }

    public void openpath(String path) throws NexusException {
        if(handle < 0) throw new NexusException("NAPI-ERROR: File not open");
        checkForNull(path);
        nxopenpath(handle,path);
    }

    public void opengrouppath(String path) throws NexusException {
        if(handle < 0) throw new NexusException("NAPI-ERROR: File not open");
        checkForNull(path);
        nxopengrouppath(handle,path);
    }

    public String getpath() throws NexusException {
        if(handle < 0) throw new NexusException("NAPI-ERROR: File not open");
        return nxgetpath(handle);
    }

    public void closegroup() throws NexusException {
        if(handle < 0) throw new NexusException("NAPI-ERROR: File not open");
        nxclosegroup(handle);
    }

    // data set handling
    // native methods for this section
    protected native void nxmakedata(int handle, String name, int type, int rank, int dim[]);
    protected native void nxmakedata64(int handle, String name, int type, int rank, long dim[]);
    protected native void nxmakecompdata(int handle, String name, int type, int rank, int dim[], int iCompress, int iChunk[]);
    protected native void nxmakecompdata64(int handle, String name, int type, int rank, long dim[], int iCompress, long iChunk[]);
    protected native void nxopendata(int handle, String name);
    protected native void nxclosedata(int handle);
    protected native void nxcompress(int handle, int compression_type);

    public void compmakedata(String name, int type, int rank, int dim[],
                   int compression_type, int iChunk[]) throws NexusException {
        if (handle < 0) throw new NexusException("NAPI-ERROR: File not open");
        checkType(type);    
        checkForNull(name, rank, iChunk);
        checkForNegInArray(true, dim, iChunk);
        switch(compression_type) {
        case NexusFile.NX_COMP_NONE:
        case NexusFile.NX_COMP_LZW:
            break;
        default:
            throw new NexusException("Invalid compression code requested");

        }
        nxmakecompdata(handle, name, type, rank, dim, compression_type, iChunk);
    }

    public void compmakedata(String name, int type, int rank, long dim[],
                   int compression_type, long iChunk[]) throws NexusException {
        if (handle < 0) throw new NexusException("NAPI-ERROR: File not open");
        checkType(type);    
        checkForNull(name, rank, iChunk);
        checkForNegInArray(true, dim, iChunk);
        switch(compression_type) {
        case NexusFile.NX_COMP_NONE:
        case NexusFile.NX_COMP_LZW:
            break;
        default:
            throw new NexusException("Invalid compression code requested");

        }
        nxmakecompdata64(handle, name, type, rank, dim, compression_type, iChunk);
    }

    public void makedata(String name, int type, int rank, int dim[]) throws
                           NexusException {
        if(handle < 0) throw new NexusException("NAPI-ERROR: File not open");
        checkType(type);
        checkForNull(name, dim);
        checkForNegInArray(true, dim);
        nxmakedata(handle, name, type, rank, dim);
    }

    public void makedata(String name, int type, int rank, long dim[]) throws
                           NexusException {
        if(handle < 0) throw new NexusException("NAPI-ERROR: File not open");
        checkType(type);
        checkForNull(name, dim);
        checkForNegInArray(true, dim);
        nxmakedata64(handle, name, type, rank, dim);
    }

    public void opendata(String name) throws NexusException {
        if(handle < 0) throw new NexusException("NAPI-ERROR: File not open");
        checkForNull(name);
        nxopendata(handle,name);
    }

    public void closedata() throws NexusException {
        if(handle < 0) throw new NexusException("NAPI-ERROR: File not open");
        nxclosedata(handle);
    }

    public void compress(int compression_type) throws NexusException {
        if(handle < 0) throw new NexusException("NAPI-ERROR: File not open");
        switch(compression_type) {
        case NexusFile.NX_COMP_NONE:
        case NexusFile.NX_COMP_LZW:
        case NexusFile.NX_COMP_RLE:
        case NexusFile.NX_COMP_HUF:
            break;
        default:
            throw new NexusException("Invalid compression code requested");

        }
        nxcompress(handle,compression_type);
    }

    // data set reading
    // native methods in this section
    protected native void nxgetdata(int handle, byte bdata[]);
    protected native void nxgetslab(int handle, int Start[], int size[], byte bdata[]);
    protected native void nxgetslab64(int handle, long Start[], long size[], byte bdata[]);
    protected native void nxgetattr(int handle, String name, byte bdata[], int args[]);

    public void getdata(Object array) throws NexusException {
        byte bdata[];
        if(handle < 0) throw new NexusException("NAPI-ERROR: File not open");
        checkForNull(array);
        try{
            HDFArray ha = new HDFArray(array);
            bdata = ha.emptyBytes();
            nxgetdata(handle,bdata);
            array = ha.arrayify(bdata);
         }catch(HDFException he) {
           throw new NexusException(he.getMessage());
         }
    }

    public void getslab(int start[], int size[], Object array) throws NexusException {
        byte bdata[];
        if(handle < 0) throw new NexusException("NAPI-ERROR: File not open");
        checkForNull(start, size, array);
        checkForNegInArray(false, start, size);
        try{
            HDFArray ha = new HDFArray(array);
            bdata = ha.emptyBytes();
            nxgetslab(handle,start,size,bdata);
            array = ha.arrayify(bdata);
         }catch(HDFException he) {
           throw new NexusException(he.getMessage());
         }
    }

    public void getslab(long start[], long size[], Object array) throws NexusException {
        byte bdata[];
        if(handle < 0) throw new NexusException("NAPI-ERROR: File not open");
        checkForNull(start, size, array);
        checkForNegInArray(false, start, size);
        try{
            HDFArray ha = new HDFArray(array);
            bdata = ha.emptyBytes();
            nxgetslab64(handle,start,size,bdata);
            array = ha.arrayify(bdata);
         }catch(HDFException he) {
           throw new NexusException(he.getMessage());
         }
    }

    public void getattr(String name, Object array, int args[]) throws NexusException {
        byte bdata[];
        if(handle < 0) throw new NexusException("NAPI-ERROR: File not open");
        checkType(args[1]);
        checkForNull(name, array);
        try{
            HDFArray ha = new HDFArray(array);
            bdata = ha.emptyBytes();
            nxgetattr(handle, name, bdata,args);
            array = ha.arrayify(bdata);
         }catch(HDFException he) {
           throw new NexusException(he.getMessage());
         }
    }

    // data set writing
    // native methods for this section
    protected native void nxputdata(int handle, byte array[]); 
    protected native void nxputslab(int handle, byte array[], int start[], int size[]); 
    protected native void nxputslab64(int handle, byte array[], long start[], long size[]); 
    protected native void nxputattr(int handle, String name, byte array[], int type); 

    public void putdata(Object array) throws NexusException {
       byte data[];

       if(handle < 0) throw new NexusException("NAPI-ERROR: File not open");
           checkForNull(array);

       try {
           HDFArray ha =  new HDFArray(array);
           data = ha.byteify();
           ha = null;
       } catch (HDFException he) {
           throw new NexusException(he.getMessage());
       }
       nxputdata(handle,data);
       data = null;
    }

    public void putslab(Object array, int start[], int size[]) throws NexusException {
       byte data[];

       if(handle < 0) throw new NexusException("NAPI-ERROR: File not open");
       checkForNull(array, start, size);
       checkForNegInArray(false, start, size);
       try {
           HDFArray ha =  new HDFArray(array);
           data = ha.byteify();
           ha = null;
       } catch(HDFException he) {
           throw new NexusException(he.getMessage());
       }
       nxputslab(handle,data,start,size);
       data = null;
    }

    public void putslab(Object array, long start[], long size[]) throws NexusException {
       byte data[];

       if(handle < 0) throw new NexusException("NAPI-ERROR: File not open");
       checkForNull(array, start, size);
       checkForNegInArray(false, start, size);
       try {
           HDFArray ha =  new HDFArray(array);
           data = ha.byteify();
           ha = null;
       } catch(HDFException he) {
           throw new NexusException(he.getMessage());
       }
       nxputslab64(handle,data,start,size);
       data = null;
    }

    public void putattr(String name, Object array, int iType) throws NexusException {
       byte data[];

       if(handle < 0) throw new NexusException("NAPI-ERROR: File not open");
       checkType(iType);
       checkForNull(name, array);
       try{
           HDFArray ha =  new HDFArray(array);
           data = ha.byteify();
           ha = null;
       }catch(HDFException he) {
           throw new NexusException(he.getMessage());
       }
       nxputattr(handle,name,data,iType);
       data = null;
    }

    // inquiry
    //native methods for this section
    protected native void nxgetinfo(int handle, int iDim[], int args[]);
    protected native void nxgetinfo64(int handle, long iDim[], int args[]);
    protected native void nxsetnumberformat(int handle, int type, 
                                            String format);
    protected native int nextentry(int handle, String names[]);
    protected native int nextattr(int handle, String names[], int args[]);
    protected native void initattrdir(int handle);
    protected native void initgroupdir(int handle);

    public void setnumberformat(int type, String format) throws NexusException {
       if(handle < 0) throw new NexusException("NAPI-ERROR: File not open");
       checkType(type);
       checkForNull(format);
       nxsetnumberformat(handle,type,format);
    }

    public void getinfo(int iDim[], int args[]) throws NexusException {
       if(handle < 0) throw new NexusException("NAPI-ERROR: File not open");
       nxgetinfo(handle,iDim,args);
    }

    public void getinfo(long iDim[], int args[]) throws NexusException {
       if(handle < 0) throw new NexusException("NAPI-ERROR: File not open");
       nxgetinfo64(handle,iDim,args);
    }

    public Hashtable groupdir() throws NexusException {
        if(handle < 0) throw new NexusException("NAPI-ERROR: File not open");
        Hashtable h = new Hashtable();
        String names[] = new String[2];

        initgroupdir(handle);
        while(nextentry(handle,names) != -1) {
           h.put(names[0],names[1]);
        }
        return h;
    }

    public Hashtable attrdir()throws NexusException {
        int args[] = new int[2];
        AttributeEntry at;
        String names[] = new String[1];

        Hashtable h = new Hashtable();
        if(handle < 0) throw new NexusException("NAPI-ERROR: File not open");
        initattrdir(handle);
        while(nextattr(handle,names,args) != -1)
        {
          at = new AttributeEntry();
          at.length = args[0];
          at.type   = args[1];
          h.put(names[0], at);
        } 
        return h;
    }
    
    // linking 
    // native methods for this section
    protected native void nxgetgroupid(int handle, NXlink link);
    protected native void nxgetdataid(int handle, NXlink link);
    protected native void nxmakelink(int handle, NXlink target); 
    protected native void nxmakenamedlink(int handle, String name, NXlink target); 
    protected native void nxopensourcepath(int handle); 

    public NXlink getgroupID() throws NexusException {
      if(handle < 0) throw new NexusException("NAPI-ERROR: File not open");
      NXlink l = new NXlink();
      nxgetgroupid(handle,l);
      return l;
    }

    public NXlink getdataID()throws NexusException {
      if(handle < 0) throw new NexusException("NAPI-ERROR: File not open");
      NXlink l = new NXlink();
      nxgetdataid(handle,l);
      return l;
    }

    public void makelink(NXlink target) throws NexusException {
      if(handle < 0) throw new NexusException("NAPI-ERROR: File not open");
      checkForNull(target);
      nxmakelink(handle, target);
    }

    public void makenamedlink(String name, NXlink target) throws NexusException {
      if(handle < 0) throw new NexusException("NAPI-ERROR: File not open");
      checkForNull(name, target);
      nxmakenamedlink(handle, name, target);
    }     

    public void opensourcepath() throws NexusException {
      if(handle < 0) throw new NexusException("NAPI-ERROR: File not open");
      nxopensourcepath(handle);
    }
        
    private void checkForNull(Object... args) {
        for (Object o : args)
                if (o==null) throw new NullPointerException();
    }
    
    private void checkForNegInArray(boolean allowUnlimited, int[]... args) {
        for (int[] array : args)
                for (int value: array) {
                        if (value<0)
                                if (value == this.NX_UNLIMITED && allowUnlimited) {
                                        // all ok this time
                                } else
                                        throw new IllegalArgumentException("negative dimension received");
                }
    }

    private void checkForNegInArray(boolean allowUnlimited, long[]... args) {
        for (long[] array : args)
                for (long value: array) {
                        if (value<0)
                                if (value == this.NX_UNLIMITED && allowUnlimited) {
                                        // all ok this time
                                } else
                                        throw new IllegalArgumentException("negative dimension received");
                }
    }

    private void checkType(int type) throws NexusException {
        switch(type) {
        case NexusFile.NX_FLOAT32:
        case NexusFile.NX_FLOAT64:
        case NexusFile.NX_INT8:
        case NexusFile.NX_UINT8:
        case NexusFile.NX_INT16:
        case NexusFile.NX_UINT16:
        case NexusFile.NX_INT32:
        case NexusFile.NX_UINT32:
        case NexusFile.NX_INT64:
        case NexusFile.NX_UINT64:
        case NexusFile.NX_CHAR:
            break;
        default:
            throw new NexusException("Illegal number type requested");
        }
    } 

    // external file interface
    // native methods for this section
    protected native void nxinquirefile(int handle, String names[]);
    protected native void nxlinkexternal(int handle, String name, String nxclass, String nxurl);
    protected native void nxlinkexternaldataset(int handle, String name, String nxurl);
    protected native int nxisexternalgroup(int handle, String name, String nxclass, String nxurl[]); 
    protected native int nxisexternaldataset(int handle, String name, String nxurl[]); 

    public String inquirefile() throws NexusException {
        if(handle < 0) throw new NexusException("NAPI-ERROR: File not open");
        String names[] = new String[1];
        nxinquirefile(handle,names);
        return names[0];
    }

    public void linkexternal(String name, String nxclass, String nxurl) throws NexusException {
        if(handle < 0) throw new NexusException("NAPI-ERROR: File not open");
        checkForNull(name, nxclass, nxurl);
        nxlinkexternal(handle,name,nxclass,nxurl);
    }

    public void linkexternaldataset(String name, String nxurl) throws NexusException {
        if(handle < 0) throw new NexusException("NAPI-ERROR: File not open");
        checkForNull(name, nxurl);
        nxlinkexternaldataset(handle,name,nxurl);
    }

    public String isexternalgroup(String name, String nxclass) throws NexusException {
        if (handle < 0) throw new NexusException("NAPI-ERROR: File not open");
        checkForNull(name, nxclass);
        String nxurl[] = new String[1];

        int status = nxisexternalgroup(handle,name,nxclass,nxurl);
        if (status == 1) {
            return nxurl[0];
        } else {
            return null;
        }
    }

    public String isexternaldataset(String name) throws NexusException {
        if (handle < 0) throw new NexusException("NAPI-ERROR: File not open");
        checkForNull(name);
        String nxurl[] = new String[1];

        int status = nxisexternaldataset(handle,name,nxurl);
        if (status == 1) {
            return nxurl[0];
        } else {
            return null;
        }
    }

    public native void debugstop();
}