Package org.jmonks.batch.io

Defines API for the clients to read records from the file and write records into the file.

See:
Description

Class Summary

FieldSpec	FieldSpec represents the <field-spec> element in file spec.
FileReader	FileReader reads the specified file based on the given file spec and returns the data in the form of ReaderRecord's to read the required values referring the field names.
FileSpec	FileSpec represents the file contains specification (spec for short) of any file to read or write using this package.
FileType	FileType defines different kinds of file formats this package supports for reading and writing.
FileWriter	FileWriter writes the specified file based on the given file spec with the data written in the form of WriterRecord's.
ReaderRecord	ReaderRecord provides the methods to read the values of the fields from a record.
Record	Record represents the map of field names and values based on the record spec defined in the file spec.
RecordSpec	RecordSpec represents the <record-spec> element in file spec.
RecordType	RecordType defines the different kind of records can be available in a file.
WriterRecord	WriterRecord provides the methods to write the values of the fields into the record.

Exception Summary

FileParseException	FileParseException is a runtime exception thrown when there is a problem reading the records from the file or writing the records into the file.
FileSpecException	FileSpecException is a runtime exception thrown when there is a problem creating the FileSpec object from the given file contains the file specification.

Package org.jmonks.batch.io Description

Defines API for the clients to read records from the file and write records into the file.

This package provides the API for the client programs to work with the files easily irrespective of the file format. This API is based on the analogy that all the files to be read and write have some data in the form of records and each record consists of a set of fields. Structure of these files, records and fields can be defined or configured using xml format. API allows the client programs to reads the records in an iterative manner from the file by specifying the xml file defined the file structure (It will be called as file spec here onwards) and file to read. API allows the client programs to create the record and write that record into the file.

Defining file structure

API expects the file consists of the data in the form of mulitple records and each record consists of multiple fields. Structure of the file will be defined using the root tag <file-spec> accepts the attribute file-type which signifies the kind of format of the file it is defining. Allowed values for the file-type attribute should be from FileType class. This class defines all the available file types can be used. Using the value doesnt exist in the FileType class results FileSpecException being thrown. Implementations may expects other attributes along with the file-type attribute for better file reading and file writing. These additional attributes will be mentioned by the FileSpec impelementors.

       <file-spec file-type="file-format">
           <!-- Record specs will go on here -->
       </file-spec>
    

As every file will have its data in the form of records, each record will be defined using the tag <record-spec> in the <file-spec> tag. Every record-spec will have a record-type attribute which signifies the kind of record it is configuring like header record or detail record or trailer record. This record-type should be unique across the file spec and the value can be taken from RecordType class. Allowed to use other record types not defined in the RecordType class. Along with the record-type attribute each implementation will require additional attributes to idnetify the records in the file and to write the records into the file. These additional attributes will be mentioned by the RecordSpec implementations.

        <file-spec file-type="file-format">
            <record-spec record-type="detail">
                <!-- Record specs will go on here -->
            </record-spec>
        </file-spec>
     

As every record spec consists of set of fields, each field is defined using the tag <field-spec> in <record-spec> tag. Each field-spec should have an attribute field-name identifies the name of the field, which will be used to populate the field values into the record. Based on the implementation, additional attributes will be required along with the field-name to identify the field. Some implementations might not require field-spec elements at all. Whether clients neeeds to define the field-spec elements or not will be decided by RecordSpec implementations.

        <file-spec file-type="file-format">
            <record-spec record-type="detail">
                <field-spec field-name="field-name1"/>
            </record-spec>
        </file-spec>
     

Reading records from the file

FileReader class helps us in obtaining the FileReader instance through various factory methods by accepting the file to be read and file spec in different forms. FileReader reads data from the file according to the given file spec and when it finds a match to any of the provided record spec, it reads that record and returns field values as ReaderRecord instance. ReaderRecord instance has a method to read the field values by passing the field names. FileReader implementations provides ReaderRecord implementations, which allow additional methods to read the field values. Look at the FileReader implementation javadoc for the additional methods. Reader records can be read from FileReader in an iterative manner. When file reader doesnt have any more records, it returns null indicating that reader doenst have any more records. At this point client can stop requesting for further records. Once done reading all the records, client should close the reader.

Folloing example indicates how to obtain a file reader instance and how to obtain reader record and how to read field values from the reader records.

    
        InputStream fileSpecInputStream= // Get the input stream for the XML file contains the file structure.
        InputStream fileInputStream= // Get the input stream of the file to be read.
        FileReader reader=FileReader.getFileReader(fileInputStream,fileSpecInputStream);
        ReaderRecord record=null;
        while((record=reader.getNextRecord())!=null)
        {
            if(record.getRecordType().equals(RecordType.DETAIL))
            {
                String fieldValue1=record.readField("field-name1");
                // Read the rest of the field and does the processing.
            }
        }
        reader.close();
    
    

Writing records into the file

FileWriter class helps us in obtaining the FileWriter instance through various factory methods by accepting the file to be written and file spec in different forms. FileWriter accepts WriterRecord instances which actually consists of the field values to write the data into the file. WriterRecord instances can be obtained from FileWriter instances. WriterRecord instances provides the method to write the field values associated to field name. FileWriter implementation classes will provide additional methods to write the field values in an effective way into the writer record. Once all the required field values have been pushed into the writer record, this record needs to be submitted to the FileWriter instance. This will writes that record according to the file spec provided while obtaining the file writer instance. Once done writing all the records, file writer needs to be closed.

Folloing example indicates how to obtain a file writer instance and how to obtain writer record and how to write field values into the writer records and how to submit that record to the file writer.

    
        InputStream fileSpecInputStream= // Get the input stream for the XML file contains the file structure.
        OutputStream fileOutputStream= // Get the output stream of the file to be written/generated.
        FileWriter writer=FileWriter.getFileWriter(fileOutputStream,fileSpecInputStream);
        WriterRecord record=writer.createWriterRecord(RecordType.DETAIL);
        record.writeField("field-name1","field-value1");
        // Write all the other field values into the writer record.
        writer.writeRecord(record);
        writer.close();