IOExitRecordChannel.java interface

IOExitRecordChannel.java

/*
 *   Licensed Materials - Property of IBM
 *
 *   "Restricted Materials of IBM"
 *
 *   5724-H72
 * 
 *    Copyright IBM Corp. 2011, 2020. All Rights Reserved.
 * 
 *   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;

}
Parent topic: Java interfaces for MFT user exits
IOExitRecordChannel.java interface

IOExitRecordChannel.java

Related information
