Sun Adapter for Batch/FTP

com.stc.eways.batchext
Interface BatchRecordParser

All Known Implementing Classes:
BatchDelimitedRecordParser, BatchFixedRecordParser, BatchSingleRecordParser

public interface BatchRecordParser

The BatchRecordParser interface defines the interface used by all record parsers in the e*Way. If you want to provide your own parser, you must override each method defined in this interface and adhere to the signature and semantics of these methods. The BatchRecordParser interface is used for either parsing a payload or for creating a payload made up of records. The e*Way supplies parsers that know how to parse or create payloads of delimited records, fixed-sized records, and single records. A single instance of a record-processing parser in a Collaboration is not designed to be used for parsing and creating at the same time. That is, each instance is used for parsing a payload only or for creating a payload only. This usage dictates that two interfaces must be defined; one for parsing and one for creating. The parse/create features of the e*Way operate in this way allowing you to easily implement your own parser, if desired. Also, this operation makes setting the configuration parameters of the e*Way easier. You are configuring a parsing ETD or a creating ETD and not having to configure the complexities of an ETD that does both at the same time. Set up payload parsing as follows: 1. Configure the parser in the e*Way Configuration Editor. Be sure to specify the record type. 2. Create a Collaboration that contains the parser. 3. Call setPayload() on the source data to parse it. 4. Call get() multiple times to extract the records from the data payload. Set the source data for parsing using either: o setPayload() o setInputStreamAdapter() These methods are mutually exclusive, that is, you can call one or the other but not both. The setPayload() method is used when the source data is already in memory as a byte array, for example, when the source data is of a relatively small size. You must use the setInputStreamAdapter() method when the source data is relatively large, and you do not want to load the entire payload into e*Gate's memory. This method employs the e*Way's data-streaming feature. In this case, the source can be any object that implements the com.stc.eways.common.eway.streaming.InputStreamAdapter interface, as long as the InputStream provided by that implementation supports the ability to seek backward, as the FileInputStream does. The ByteArrayInputStream does not. To use a ByteArrayInputStream, use the extension class BatchByteArrayInputStream instead. Create a payload as follows: 1. Configure the parser in the e*Way Configuration Editor. Be sure to specify the record type. 2. Create a Collaboration that contains the parser. 3. Call put() multiple times to add records to the data payload. 4. Call getPayload() to get the buffer containing all the records. The setOutputStreamAdapter() method can be called to specify the stream- based destination of the data payload. This method also employs data streaming. The object instance retrieved can be any object that implements the com.stc.eways.common.eway.streaming.OutputStreamAdapter interface. This method is normally used if the payload created is of substantial size, and you do not want to create the data payload in e*Gate's memory. If this method is not called, the payload is created in an internal buffer, and you must call the getPayload() method to retrieve it, once all records have been added. Each method declares that an exception of the base javaException can be thrown. If an exception is thrown, it is caught by the ETD implementation code and sent to the e*Gate system to be logged. It is recommended that you provide a meaningful error message for the text of any of your exceptions. In general, the e*Way-supplied implementations do not throw these exceptions. In cases where they do, it is noted. NOTE: The code that creates an instance of your object looks for a constructor that takes void. Your object must, therefore, provide a default, public constructor taking void, that is, a constructor with no parameters.


Method Summary
 void finish(java.io.OutputStream output, java.io.InputStream input)
          You must call this method when you are done with a transfer, to clean up resources, finish processing, and so on.
 byte[] get(java.io.InputStream input)
          The get() method in the ETD calls this method to do the desired task.
 void initialize(BatchRecordConfiguration conf)
          This method is called by the underlying implementation immediately after the instance of the class is created.
 void put(java.io.OutputStream output, byte[] data)
          The put() method in the ETD calls this method to do the desired task.
 

Method Detail

initialize

void initialize(BatchRecordConfiguration conf)
                throws java.lang.Exception
This method is called by the underlying implementation immediately after the instance of the class is created. Aside from the constructor, it is guaranteed to be the first method called on this object. This method allows to configure your own internals.

Parameters:
conf - An instance of the BatchRecordConfiguration class, which contains configuration-specific information for the parser.
Throws:
java.lang.Exception - If there is a problem with the properties passed in. The e*Way-supplied parsers can throw an exception if the configuration properties are incorrect.

get

byte[] get(java.io.InputStream input)
           throws java.lang.Exception
The get() method in the ETD calls this method to do the desired task. The semantics of the method mean, "Get the next record whatever that might be." For example, for fixed-sized records, this method returns the next record in the input of that size. This usage means that you have already dragged and dropped the data payload onto the Payload node in the ETD or set up a data-streaming link with another ETD. Also, the semantics of this method mean that it can, and usually is, called multiple times to extract records one by one from the data payload. No destructive actions are performed on the input data.

Parameters:
input - Specifies the input to get the next record from.
Returns:
Returns the extracted record or a null when the input has been "consumed." A consumed input means that get has been called multiple times, and there are no more records left to get. The e*Way-supplied parsers do not throw an exception in this case.
Throws:
java.lang.Exception - If there is an error in parsing the input.

put

void put(java.io.OutputStream output,
         byte[] data)
         throws java.lang.Exception
The put() method in the ETD calls this method to do the desired task. The semantics of this method mean, "Here is another record to be appended to the output file". For example, for fixed-sized records, the payload data is assumed to be a blob of data of that size, and that blob must be appended to the payload buffer. Also, the semantics of this method mean that it is the parser's responsibility to inspect the data being passed in, for validity. Ultimately, after you have called this method and built an output file, you then generally use the Payload ETD node to access that output. Alternatively, you can direct that output to another ETD using data streaming.

Parameters:
output - Specifies the output file or ETD (for data streaming) where a given record goes.
data - The data to be included in the record.
Throws:
java.lang.Exception - If there is a problem processing the data. The e*Way-supplied parsers throw exceptions from this method if there is a problem with the data, for example, for the fixed-size record parser if the data is not the correct size.

finish

void finish(java.io.OutputStream output,
            java.io.InputStream input)
            throws java.lang.Exception
You must call this method when you are done with a transfer, to clean up resources, finish processing, and so on. Once this method is called, the parser must not be used again.

Parameters:
output - Specifies the output where the records go.
input - Specifies the input where the records come from.
Throws:
java.lang.Exception - If there is a problem finishing.

Sun Adapter for Batch/FTP