IOExitRecordChannel.java
/*
* Licensed Materials - Property of IBM
*
* “Restricted Materials of IBM”
*
* 5724-H72
*
* Copyright IBM Corp. 2011, 2024. All Rights Reserved.
*
* US Government Users Restricted Rights - Use, duplication or
* disclosure restricted by GSA ADP Schedule Contract with
* IBM Corp.
*/
package com.ibm.wmqfte.exitroutine.api;
import java.io.IOException;
import java.nio.ByteBuffer;
/**
* Represents a channel that enables records of data to be read from or written
* to an {@link IOExitRecordResourcePath} resource.
* <p>
* This is an extension of the {@link IOExitChannel} interface such that the
* {@link #read(java.nio.ByteBuffer)} and {@link #write(java.nio.ByteBuffer)}
* methods are expected to deal in whole records of data only. That is, the
* {@link java.nio.ByteBuffer} returned from the read method and passed to the
* write method is assumed to contain one or more complete records.
*/
public interface IOExitRecordChannel extends IOExitChannel {
/**
* Reads records from this channel into the given buffer, starting at this
* channel's current position, and updates the current position by the
* amount of data read.
* <p>
* Record data is copied into the buffer starting at its current position
* and up to its limit. On return, the buffer's position is updated to
* reflect the number of bytes read.
* <p>
* Only whole records are copied into the buffer.
* <p>
* For a fixed-record-format resource, this might be multiple records. The
* amount of data in the return buffer does not necessarily need to be a
* multiple of the record length, but the last record is still to be treated
* as a complete record and padded as required by the caller.
* <p>
* For a variable-format resource, this is a single whole record of a size
* corresponding to the amount of return data or multiple whole records with
* all except the last being treated as records of maximum size.
*
* @param buffer
* The buffer that the record data is to be copied into.
* @return The number of bytes read, which might be zero, or -1 if the end of
* data has been reached.
* @throws RecoverableIOException
* If a recoverable problem occurs while reading the data. For a
* WMQFTE transfer this means that it will attempt to recover.
* @throws IOException
* If some other I/O problem occurs, for example, if the passed
* buffer is insufficient to contain at least one complete
* record). For a WMQFTE transfer this means that it will be
* failed.
*/
int read(ByteBuffer buffer) throws RecoverableIOException, IOException;
/**
* Writes records to this channel from the given buffer, starting at this
* channel's current position, and updates the current position by the
* amount of data written. The channel's resource is grown to accommodate
* the data, if necessary.
* <p>
* Record data is copied from the buffer starting at its current position
* and up to its limit. On return, the buffer's position is updated to
* reflect the number of bytes written.
* <p>
* The buffer is expected to contain only whole records.
* <p>
* For a fixed-record-format resource, this might be multiple records and if
* there is insufficient data in the buffer for a complete record, the
* record is to be padded as required to complete the record.
* <p>
* For a variable-record format resource the buffer is normally expected to
* contain a single record of length corresponding to the amount of data
* within the buffer. However, if the amount of data within the buffer
* exceeds the maximum record length, the implementation can either:
* <ol>
* <li>throw an {@link IOException} indicating that it cannot handle the
* situation.</li>
* <li>Consume a record's worth of data from the buffer, leaving the remaining
* data within the buffer.</li>
* <li>Consume all the buffer data and just write what it can to the current
* record. This effectively truncates the data.</li>
* <li>Consume all the buffer data and write to multiple records.</li>
* </ol>
*
* @param buffer
* The buffer containing the data to be written.
* @return The number of bytes written, which might be zero.
* @throws RecoverableIOException
* If a recoverable problem occurs while writing the data. For a
* WMQFTE transfer this means that it will attempt to recover.
* @throws IOException
* If some other I/O problem occurs. For a WMQFTE transfer this
* means that it will be failed.
*/
int write(ByteBuffer buffer) throws RecoverableIOException, IOException;
}