IOExitChannel.java
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;
}