IOExitRecordResourcePath.java interface

IOExitRecordResourcePath.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;

/**
 * Represents a path that denotes a record-oriented data resource (for example,
 * a z/OS data set). It allows the data to be located, the record format to be
 * understood, and {@link IOExitRecordChannel} instances to be created for read
 * or write operations.
 */
public interface IOExitRecordResourcePath extends IOExitResourcePath {

	/**
	 * Record formats for record-oriented resources.
	 */
	public enum RecordFormat {
		FIXED, VARIABLE
	}

	/**
	 * Obtains the record length for records that are maintained by the resource
	 * denoted by this abstract path.
	 * <p>
	 * For a resource with fixed-length records, the data for each record read
	 * and written is assumed to be this length.
	 * <p>
	 * For a resource with variable-length records, this is the maximum length
	 * for a record's data.
	 * <p>
	 * This method should return a value greater than zero, otherwise it can
	 * result in the failure of a WMQFTE transfer that involves this abstract
	 * path. 
	 * 
	 * @return The record length, in bytes, for records maintained by the
	 *         resource.
	 */
	int getRecordLength();

	/**
	 * Obtains record format, as a {@link RecordFormat} instance, for records
	 * that are maintained by the resource denoted by this abstract path.
	 * 
	 * @return A {@link RecordFormat} instance for the record format for records
	 *         that are maintained by the resource denoted by this abstract
	 *         path.
	 */
	RecordFormat getRecordFormat();

	/**
	 * Opens a {@link IOExitRecordChannel} instance for reading data from the
	 * resource denoted by this abstract path. The current data byte position
	 * for the resource is expected to be the passed position value, such that
	 * when {@link IOExitRecordChannel#read(java.nio.ByteBuffer)} is called,
	 * data starting from that position is read.
	 * <p>
	 * Note that the data byte read position will be on a record boundary.
	 * 
	 * @param position
	 *            The required data byte read position.
	 * @return A new {@link IOExitRecordChannel} instance allowing data to be
	 *         read from the resource denoted by this abstract path.
	 * @throws RecoverableIOException
	 *             If a recoverable problem occurs while attempting to open the
	 *             resource for reading. This means that WMQFTE can attempt to
	 *             recover the transfer.
	 * @throws IOException
	 *             If some other I/O problem occurs.
	 */
	IOExitRecordChannel openForRead(long position)
			throws RecoverableIOException, IOException;

	/**
	 * Opens a {@link IOExitRecordChannel} instance for writing data to the
	 * resource denoted by this abstract path. Writing of data, using the
	 * {@link IOExitRecordChannel#write(java.nio.ByteBuffer)} method, starts at
	 * either the beginning of the resource or end of the current data for the
	 * resource, depending on the specified append parameter.
	 * 
	 * @param append
	 *            When {@code true} indicates that data written to the resource
	 *            should be appended to the end of the current data. When
	 *            {@code false} indicates that writing of data is to start at
	 *            the beginning of the resource; any existing data is lost.
	 * @return A new {@link IOExitRecordChannel} instance allowing data to be
	 *         written to the resource denoted by this abstract path.
	 * @throws RecoverableIOException
	 *             If a recoverable problem occurs while attempting to open the
	 *             resource for writing. This means that WMQFTE can attempt to
	 *             recover the transfer.
	 * @throws IOException
	 *             If some other I/O problem occurs.
	 */
	IOExitRecordChannel openForWrite(boolean append)
			throws RecoverableIOException, IOException;
}