Getting started

The basic stuff:

To use the library you need to:

create POJO classes that contains all the fields in the native structs
put annotations on the class and the fields that tell the library how the data are mapped to the native structs
write the code that uses the library and the new POJO classes

Note:

the POJO classes should have a no args constructor
under certain circumstances the POJO classes are required to be serializable (it is recommended always to make them so)
the library does not care whether you use private fields and public getters/setters or public fields (the first is Java best practice)
all fields except static and transient fields must be annotated

Examples:

POJO class:

import java.io.Serializable;

import dk.vajhoej.isam.KeyField;
import dk.vajhoej.record.FieldType;
import dk.vajhoej.record.Struct;
import dk.vajhoej.record.StructField;

@Struct
public class Data implements Serializable {
    @KeyField(n=0)
    @StructField(n=0,type=FieldType.INT4)
    private int iv;
    @StructField(n=1,type=FieldType.FP8)
    private double xv;
    @StructField(n=2,type=FieldType.FIXSTR,length=8,encoding="ISO-8859-1")
    private String sv;
	public int getIv() {
        return iv;
    }
    public void setIv(int iv) {
        this.iv = iv;
    }
    public double getXv() {
        return xv;
    }
    public void setXv(double xv) {
        this.xv = xv;
    }
    public String getSv() {
        return sv;
    }
    public void setSv(String sv) {
        this.sv = sv;
    }
}

The class got a @Struct annotation. Each field in the class got a @StructField annotation with an element n that determines the order of the fields and an element type that describes the datatype in the native struct plus some optional elements that are needed for some field types. Each key field in the class got a @KeyField annotation with an element n that determines the order of the key fields.

code fragments:

Examples of simple CRUD operations:

// open 
IsamSource isam = new LocalIsamSource(filename, providername, readonly);
// create record
Data obj = new Data();
...
isam.create(obj);
// read record
Data obj = isam.read(Data.class, new Key0<Integer>(123));
// update record
Data obj = new Data();
...
isam.update(obj);
// delete record
isam.delete(Data.class, new Key0<Integer>(123));
// close
isam.close();

The providername is:

OpenVMS index-sequential files: dk.vajhoej.vms.rms.IndexSequential
BDB: dk.vajhoej.bdb.BDB
VBISAM: dk.vajhoej.vbisam.VBISAM

The advanced stuff:

Arrays:

To specify a field as an array put an @Array annotation on the field and make the Java type an array.

Sub structs:

To specify a field as a sub struct just specify type=FieldType.STRUCT in the @StructField annotation.

Polymorphism:

The ISAM library supports polymorphism in records.

You must use the @Selector annotation on the last field in the super class.

import java.io.Serializable;

import dk.vajhoej.isam.KeyField;
import dk.vajhoej.record.Alignment;
import dk.vajhoej.record.FieldType;
import dk.vajhoej.record.Struct;
import dk.vajhoej.record.StructField;
import dk.vajhoej.record.Selector;
import dk.vajhoej.record.SubType;

@Struct
public class Data implements Serializable {
    @KeyField(n=0)
    @StructField(n=0,type=FieldType.INT4)
    protected int id;
    @StructField(n=1,type=FieldType.INT4)
    @Selector(subtypes={@SubType(value=1,type=DataX.class),
                        @SubType(value=3,type=DataY.class)})
    protected int typ;
    public int getId() {
        return id;
    }
    public void setId(int id) {
        this.id = id;
    }
    public int getTyp() {
        return typ;
    }
    public void setTyp(int typ) {
        this.typ = typ;
    }
}

Usage is as simple as:

Data obj = isam.read(Data.class, new Key0<Integer>(123));

This will actually read DataX or DataY instances depending on the value of the typ field.

Note that the numbering of the struct fields continue in the sub class - it does not reset to zero.

Cache:

To cache objects in memory simply replace:

IsamSource isam = new LocalIsamSource(filename, providername, readonly);

with:

IsamSource isam = new CacheIsamSource(new LocalIsamSource(filename, providername, readonly));

It is possible to replace the standard cache with another cache - the library ships with a wrapper for EHCache.

Remote:

To access a remote ISAM source use:

IsamSource isam = new RemoteIsamSource(hostname, port);

And run the server dk.vajhoej.isam.remote.Server with a configuration file like:

<sources>
    <source file="foo.isq" impl="dk.vajhoej.vms.rms.IndexSequential" ro="false" port="10001" cache="true"/>
    <source file="bar.isq" impl="dk.vajhoej.vms.rms.IndexSequential" ro="false" port="10002" cache="true"/>
</sources>

More info about defining structs:

Struct: documentation
StructField: documentation
FieldType: documentation
ArrayField: documentation
Selector: documentation
SubType: documentation
KeyField: documentation

More examples:

I have used this code in many articles including:

NoSQL - Key Value Store (including ISAM/index-sequential files)
Cobol files
VMS Tech Demo 3 - from index-sequential file to SQLite database