+ * To use this class, a diagnostic tool must redefine this class with a version + * that contains calls to the the diagnostic tool. This implementation will then + * receive callbacks when file and socket operations are performed. The reason + * for requiring a redefine of the class is to avoid any overhead caused by the + * instrumentation. + *
+ * The xxBegin() methods return a "context". This can be any Object marked with + * the {@link IoTraceContext} empty interface. This context will be passed to + * the corresponding xxEnd() method. This way, an implementation can correlate + * the beginning of an operation with the end. + *
+ * It is possible for a xxEnd() method to be called with a null handle. This + * happens if tracing was started between the call to xxBegin() and xxEnd(), in + * which case xxBegin() would not have been called. It is the implementation's + * responsibility to not throw an exception in this case. + *
+ * Implementations must not throw exceptions since this will cause disruptions + * to the I/O operations. + *
+ * Implementations must not do I/O operations since this will lead to an endless + * loop. + *
+ * Only blocking I/O operations are identified with this facility. + */ +public final class IoTrace { + private IoTrace() { + } + + /** + * Called before data is read from a socket. + * + * @param address + * the remote address the socket is bound to + * @param port + * the remote port the socket is bound to + * @param timeout + * the SO_TIMEOUT value of the socket (in milliseconds) or 0 if + * there is no timeout set + * @return an IoTraceContext object + */ + public static IoTraceContext socketReadBegin(InetAddress address, int port, + int timeout) { + return null; + } + + /** + * Called after data is read from the socket. + * + * @param context + * the context returned by the previous call to socketReadBegin() + * @param bytesRead + * the number of bytes read from the socket, 0 if there was an + * error reading from the socket + */ + public static void socketReadEnd(IoTraceContext context, long bytesRead) { + } + + /** + * Called before data is written to a socket. + * + * @param address + * the remote address the socket is bound to + * @param port + * the remote port the socket is bound to + * @return an IoTraceContext object + */ + public static IoTraceContext socketWriteBegin(InetAddress address, int port) { + return null; + } + + /** + * Called after data is written to a socket. + * + * @param context + * the context returned by the previous call to + * socketWriteBegin() + * @param bytesWritten + * the number of bytes written to the socket, 0 if there was an + * error writing to the socket + */ + public static void socketWriteEnd(IoTraceContext context, long bytesWritten) { + } + + /** + * Called before data is read from a file. + * + * @param path + * the path of the file + * @return an IoTraceContext object + */ + public static IoTraceContext fileReadBegin(String path) { + return null; + } + + /** + * Called after data is read from a file. + * + * @param context + * the context returned by the previous call to fileReadBegin() + * @param bytesRead + * the number of bytes written to the file, 0 if there was an + * error writing to the file + */ + public static void fileReadEnd(IoTraceContext context, long bytesRead) { + } + + /** + * Called before data is written to a file. + * + * @param path + * the path of the file + * @return an IoTraceContext object + */ + public static IoTraceContext fileWriteBegin(String path) { + return null; + } + + /** + * Called after data is written to a file. + * + * @param context + * the context returned by the previous call to fileReadBegin() + * @param bytesWritten + * the number of bytes written to the file, 0 if there was an + * error writing to the file + */ + public static void fileWriteEnd(IoTraceContext context, long bytesWritten) { + } +}