IOExitChannel.java interface

IOExitChannel.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 data to be read from or written to an
 * {@link IOExitResourcePath} resource.
 */
public interface IOExitChannel {

	/**
	 * Obtains the data size for the associated {@link IOExitResourcePath} in
	 * bytes.
	 * 
	 * @return The data size in bytes.
	 * @throws IOException
	 *             If a problem occurs while attempting obtain the size.
	 */
	long size() throws IOException;

	/**
	 * Closes the channel, flushing any buffered write data to the resource and
	 * releasing any locks.
	 * 
	 * @throws RecoverableIOException
	 *             If a recoverable problem occurs while closing the resource.
	 *             This means that WMQFTE can attempt to recover the transfer.
	 * @throws IOException
	 *             If some other I/O problem occurs. For example, the channel might
	 *             already be closed.
	 */
	void close() throws RecoverableIOException, IOException;

	/**
	 * Reads data 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>
	 * 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.
	 * 
	 * @param buffer
	 *            The buffer that the 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 a WMQFTE transfer this
	 *             means that it will be failed.
	 */
	int read(ByteBuffer buffer) throws RecoverableIOException, IOException;

	/**
	 * Writes data 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>
	 * 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.
	 * 
	 * @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;

	/**
	 * Forces any updates to this channel's resource to be written to its
	 * storage device.
	 * <p>
	 * This method is required to force changes to both the resource's content
	 * and any associated metadata to be written to storage.
	 * 
	 * @throws RecoverableIOException
	 *             If a recoverable problem occurs while performing the force.
	 *             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.
	 */
	void force() throws RecoverableIOException, IOException;

	/**
	 * Attempts to lock the entire resource associated with the channel for
	 * shared or exclusive access.
	 * <p>
	 * The intention is for this method not to block if the lock is currently
	 * unavailable.
	 * 
	 * @param shared
	 *            {@code true} if a shared lock is required, {@code false} if an
	 *            exclusive lock is required.
	 * @return A {@link IOExitLock} instance representing the newly acquired
	 *         lock or null if the lock cannot be obtained.
	 * @throws IOException
	 *             If a problem occurs while attempting to acquire the lock.
	 */
	IOExitLock tryLock(boolean shared) throws IOException;
}