IOExitResourcePath.java interface
IOExitResourcePath.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 data resource (for example, a file,
* directory, or group of database records). It allows the data to be located
* and {@link IOExitChannel} instances to be created for read or write
* operations.
* <p>
* There are two types of data resources as follows:
* <ul>
* <li>Directory - a container for other data resources. The
* {@link #isDirectory()} method returns {@code true} for these.</li>
* <li>File - a data container. This allows data to be read from or written to
* it. The {@link #isFile()} method returns {@code true} for these.</li>
* </ul>
*/
public interface IOExitResourcePath extends IOExitPath {
/**
* Creates a new {@link IOExitResourcePath} instance for a child path of the
* resource denoted by this abstract path.
* <p>
* For example, with a UNIX-style path, {@code
* IOExitResourcePath("/home/fteuser/test").newPath("subtest")} could be
* equivalent to: {@code IOExitResourcePath("/home/fteuser/test/subtest")}
*
* @param child
* The child path name.
* @return A new {@link IOExitResourcePath} instance that represents a child
* of this path.
*/
IOExitResourcePath newPath(final String child);
/**
* Creates the directory path for the resource denoted by this abstract
* path, including any necessary but nonexistent parent directories. If the
* directory path already exists, this method has no effect.
* <p>
* If this operation fails, it might have succeeded in creating some of the
* necessary parent directories.
*
* @throws IOException
* If the directory path cannot be fully created, when it does
* not already exist.
*/
void makePath() throws IOException;
/**
* Obtains the canonical path of the abstract path as a {@link String}.
* <p>
* A canonical path is defined as being absolute and unique. For example,
* the path can be represented as UNIX-style relative path: {@code
* test/file.txt} but the absolute and unique canonical path representation
* is: {@code /home/fteuser/test/file.txt}
*
* @return The canonical path as a {@link String}.
* @throws IOException
* If the canonical path cannot be determined for any reason.
*/
String getCanonicalPath() throws IOException;
/**
* Tests if this abstract path is an absolute path.
* <p>
* For example, a UNIX-style path, {@code /home/fteuser/test} is an absolute
* path, whereas {@code fteuser/test} is not.
*
* @return {@code true} if this abstract path is an absolute path, {@code
* false} otherwise.
*/
boolean isAbsolute();
/**
* Tests if the resource denoted by this abstract path exists.
*
* @return {@code true} if the resource denoted by this abstract path
* exists, {@code false} otherwise.
* @throws IOException
* If the existence of the resource cannot be determined for any
* reason.
*/
boolean exists() throws IOException;
/**
* Tests whether the calling application can read the resource denoted by
* this abstract path.
*
* @return {@code true} if the resource for this path exists and can be
* read, {@code false} otherwise.
* @throws IOException
* If a problem occurs while attempting to determine if the
* resource can be read.
*/
boolean canRead() throws IOException;
/**
* Tests whether the calling application can modify the resource denoted by
* this abstract path.
*
* @return {@code true} if the resource for this path exists and can be
* modified, {@code false} otherwise.
* @throws IOException
* If a problem occurs while attempting to determine if the
* resource can be modified.
*/
boolean canWrite() throws IOException;
/**
* Tests whether the specified user is permitted to read the resource
* denoted by this abstract path.
* <p>
* When WMQFTE invokes this method, the user identifier is the MQMD user
* identifier for the requesting transfer.
*
* @param userId
* User identifier to test for access.
* @return {@code true} if the resource for this abstract path exists and is
* permitted to be read by the specified user, {@code false}
* otherwise.
* @throws IOException
* If a problem occurs while attempting to determine if the user
* is permitted to read the resource.
*/
boolean readPermitted(String userId) throws IOException;
/**
* Tests whether the specified user is permitted to modify the resource
* denoted by this abstract path.
* <p>
* When WMQFTE invokes this method, the user identifier is the MQMD user
* identifier for the requesting transfer.
*
* @param userId
* User identifier to test for access.
* @return {@code true} if the resource for this abstract path exists and is
* permitted to be modified by the specified user, {@code false}
* otherwise.
* @throws IOException
* If a problem occurs while attempting to determine if the user
* is permitted to modify the resource.
*/
boolean writePermitted(String userId) throws IOException;
/**
* Tests if the resource denoted by this abstract path is a directory-type
* resource.
*
* @return {@code true} if the resource denoted by this abstract path is a
* directory type resource, {@code false} otherwise.
*/
boolean isDirectory();
/**
* Creates the resource denoted by this abstract path, if it does not
* already exist.
*
* @return {@code true} if the resource does not exist and was successfully
* created, {@code false} if the resource already existed.
* @throws RecoverableIOException
* If a recoverable problem occurs while attempting to create
* the resource. This means that WMQFTE can attempt to recover
* the transfer.
* @throws IOException
* If some other I/O problem occurs.
*/
boolean createNewPath() throws RecoverableIOException, IOException;
/**
* Tests if the resource denoted by this abstract path is a file-type
* resource.
*
* @return {@code true} if the resource denoted by this abstract path is a
* file type resource, {@code false} otherwise.
*/
boolean isFile();
/**
* Obtains the last modified time for the resource denoted by this abstract
* path.
* <p>
* This time is measured in milliseconds since the epoch (00:00:00 GMT,
* January 1, 1970).
*
* @return The last modified time for the resource denoted by this abstract
* path, or a value of 0L if the resource does not exist or a
* problem occurs.
*/
long lastModified();
/**
* Deletes the resource denoted by this abstract path.
* <p>
* If the resource is a directory, it must be empty for the delete to work.
*
* @throws IOException
* If the delete of the resource fails for any reason.
*/
void delete() throws IOException;
/**
* Renames the resource denoted by this abstract path to the specified
* destination abstract path.
* <p>
* The rename should still be successful if the resource for the specified
* destination abstract path already exists and it is possible to replace
* it.
*
* @param destination
* The new abstract path for the resource denoted by this
* abstract path.
* @throws IOException
* If the rename of the resource fails for any reason.
*/
void renameTo(IOExitResourcePath destination) throws IOException;
/**
* Creates a new path to use for writing to a temporary resource that did
* not previously exist.
* <p>
* The implementation can choose the abstract path name for the temporary
* resource. However, for clarity and problem diagnosis, the abstract path
* name for the temporary resource should be based on this abstract path
* name with the specified suffix appended and additional characters to make
* the path unique (for example, sequence numbers), as required.
* <p>
* When WMQFTE transfers data to a destination it normally attempts to first
* write to a temporary resource then on transfer completion renames the
* temporary resource to the required destination. This method is called by
* WMQFTE to create a new temporary resource path. The returned path should
* be new and the resource should not previously exist.
*
* @param suffix
* Recommended suffix to use for the generated temporary path.
*
* @return A new {@link IOExitResourcePath} instance for the temporary
* resource path, that did not previously exist.
* @throws RecoverableIOException
* If a recoverable problem occurs whilst attempting to create
* the temporary resource. This means that WMQFTE can attempt to
* recover the transfer.
* @throws IOException
* If some other I/O problem occurs.
*/
IOExitResourcePath createTempPath(String suffix)
throws RecoverableIOException, IOException;
/**
* Opens a {@link IOExitChannel} 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 IOExitChannel#read(java.nio.ByteBuffer)} is called, data starting
* from that position is read.
*
* @param position
* The required data byte read position.
* @return A new {@link IOExitChannel} 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.
*/
IOExitChannel openForRead(long position) throws RecoverableIOException,
IOException;
/**
* Opens a {@link IOExitChannel} instance for writing data to the resource
* denoted by this abstract path. Writing of data, using the
* {@link IOExitChannel#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 IOExitChannel} instance allowing data to be written
* to the resource denoted by this abstract path.
* @throws RecoverableIOException
* If a recoverable problem occurs whilst 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.
*/
IOExitChannel openForWrite(boolean append) throws RecoverableIOException,
IOException;
/**
* Tests if the resource denoted by this abstract path is in use by another
* application. Typically, this is because another application has a lock on
* the resource either for shared or exclusive access.
*
* @return {code true} if resource denoted by this abstract path is in use
* by another application, {@code false} otherwise.
*/
boolean inUse();
/**
* Obtains a {@link IOExitProperties} instance for properties associated
* with the resource denoted by this abstract path.
* <p>
* WMQFTE will read these properties to govern how a transfer behaves when
* interacting with the resource.
*
* @return A {@link IOExitProperties} instance for properties associated
* with the resource denoted by this abstract path.
*/
IOExitProperties getProperties();
}
Parent topic: Java interfaces for MFT user exits
Related information