IOExit.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.util.Map;
import com.ibm.wmqfte.exitroutine.api.IOExitRecordResourcePath.RecordFormat;
/**
* An interface that is implemented by classes that you want to be invoked as
* part of user exit routine processing. This interface defines methods that
* will be invoked during transfers to perform the underlying file system I/O
* work for WMQFTE transfers.
* <p>
* The {@link #initialize(Map)} method will be called once when the exit is
* first installed. The WMQFTE agent properties are passed to this method, thus
* enabling the exit to understand its environment.
* <p>
* The {@link #isSupported(String)} method will be invoked during WMQFTE
* transfers to determine whether the user exit should be used. If the
* {@link #isSupported(String)} method returns a value of {@code true}, the
* {@link #newPath(String)} method will be invoked for the paths specified for
* the transfer request. The returned {@link IOExitPath} instance from a
* {@link #newPath(String)} method invocation will then be used by the WMQFTE
* transfer to obtain information about the resource and to transfer data to or
* from the resource.
* <p>
* To obtain transfer context for an I/O exit, a {@link SourceTransferStartExit}
* or {@link DestinationTransferStartExit} as appropriate, should be installed
* to enable information to be seen by this exit. The
* {@link SourceTransferStartExit} or {@link DestinationTransferStartExit} are
* passed the transfer's environment, metadata, and a list of file
* specifications for the transfer. The paths for the file specifications are
* the paths passed to the I/O exit's {@link #newPath(String)} method.
* <p>
* Note also that the {@link #isSupported(String)} and {@link #newPath(String)}
* methods might be called at other times by a WMQFTE agent and not just during
* transfers. For example, at transfer setup time the I/O system is queried to
* resolve the full resource paths for transfer.
*/
public interface IOExit {
/**
* Invoked once when the I/O exit is first required for use. It is intended
* to initialize any resources that are required by the exit.
*
* @param agentProperties
* The values of properties defined for the WMQFTE agent. These
* values can only be read, they cannot be updated by the
* implementation.
* @return {@code true} if the initialization is successful and {@code
* false} if unsuccessful. If {@code false} is returned from an
* exit, the exit will not be used.
*/
boolean initialize(final Map<String, String> agentProperties);
/**
* Indicates whether this I/O user exit supports the specified path.
* <p>
* This method is used by WMQFTE to determine whether the I/O user exit
* should be used within a transfer. If no I/O user exit returns true for
* this method, the default WMQFTE file I/O function will be used.
*
* @param path
* The path to the required I/O resource.
* @return {@code true} if the specified path is supported by the I/O exit,
* {@code false} otherwise
*/
boolean isSupported(String path);
/**
* Obtains a new {@link IOExitPath} instance for the specified I/O resource
* path.
* <p>
* This method will be invoked by WMQFTE only if the
* {@link #isSupported(String)} method has been called for the path and
* returned {@code true}.
*
* @param path
* The path to the required I/O resource.
* @return A {@link IOExitPath} instance for the specified path.
* @throws IOException
* If the path cannot be created for any reason.
*/
IOExitPath newPath(String path) throws IOException;
/**
* Obtains a new {@link IOExitPath} instance for the specified I/O resource
* path and passes record format and length information required by the
* WMQFTE transfer.
* <p>
* Typically this method will be called for the following cases:
* <ul>
* <li>A path where a call to {@link #newPath(String)} has previously
* returned a {@link IOExitRecordResourcePath} instance and WMQFTE is
* re-establishing a new {@link IOExitPath} instance for the path, from an
* internally-serialized state. The passed recordFormat and recordLength
* will be the same as those for the original
* {@link IOExitRecordResourcePath} instance.</li>
* <li>A transfer destination path where the source of the transfer is
* record oriented. The passed recordFormat and recordLength will be the
* same as those for the source.</li>
* </ul>
* The implementation can act on the record format and length information as
* deemed appropriate. For example, for a destination agent if the
* destination does not already exist and the source of the transfer is
* record oriented, the passed recordFormat and recordLength information
* could be used to create an appropriate record-oriented destination path.
* If the destination path already exists, the passed recordFormat and
* recordLength information could be used to perform a compatibility check
* and throw an {@link IOException} if the path is not compatible. A
* compatibility check could ensure that a record oriented path's record
* format is the same as the passed record format or that the record length
* is greater or equal to the passed record length.
* <p>
* This method will be invoked by WMQFTE only if the
* {@link #isSupported(String)} method has been called for the path and
* returned {@code true}.
*
* @param path
* The path to the required I/O resource.
* @param recordFormat
* The advised record format.
* @param recordLength
* The advised record length.
* @return A {@link IOExitPath} instance for the specified path.
* @throws IOException
* If the path cannot be created for any reason. For example,
* the passed record format or length is incompatible with the
* path's actual record format or length.
*/
IOExitPath newPath(String path, RecordFormat recordFormat, int recordLength)
throws IOException;