IOExit.java interface
IOExit.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.util.Map; import com.ibm.wmqfte.exitroutine.api.IOExitRecordResourcePath.RecordFormat; /** * An interface that is implemented by classes 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;