1 /* 2 * Copyright (c) 2012, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package sun.misc; 27 28 import java.net.InetAddress; 29 30 /** 31 * Utility class used to identify trace points for I/O calls. 32 * <p> 33 * To use this class, a diagnostic tool must redefine this class with a version 34 * that contains calls to the the diagnostic tool. This implementation will then 35 * receive callbacks when file and socket operations are performed. The reason 36 * for requiring a redefine of the class is to avoid any overhead caused by the 37 * instrumentation. 38 * <p> 39 * The xxBegin() methods return a "context". This can be any Object. This 40 * context will be passed to the corresponding xxEnd() method. This way, an 41 * implementation can correlate the beginning of an operation with the end. 42 * <p> 43 * It is possible for a xxEnd() method to be called with a null handle. This 44 * happens if tracing was started between the call to xxBegin() and xxEnd(), in 45 * which case xxBegin() would not have been called. It is the implementation's 46 * responsibility to not throw an exception in this case. 47 * <p> 48 * Only blocking I/O operations are identified with this facility. 49 * <p> 50 * <b>Warning</b> 51 * <p> 52 * These methods are called from sensitive points in the I/O subsystem. Great 53 * care must be taken to not interfere with ongoing operations or cause 54 * deadlocks. In particular: 55 * <ul> 56 * <li>Implementations must not throw exceptions since this will cause 57 * disruptions to the I/O operations. 58 * <li>Implementations must not do I/O operations since this will lead to an 59 * endless loop. 60 * <li>Since the hooks may be called while holding low-level locks in the I/O 61 * subsystem, implementations must be careful with synchronization or 62 * interaction with other threads to avoid deadlocks in the VM. 63 * </ul> 64 */ 65 public final class IoTrace { IoTrace()66 private IoTrace() { 67 } 68 69 /** 70 * Called before data is read from a socket. 71 * 72 * @return a context object 73 */ socketReadBegin()74 public static Object socketReadBegin() { 75 return null; 76 } 77 78 /** 79 * Called after data is read from the socket. 80 * 81 * @param context 82 * the context returned by the previous call to socketReadBegin() 83 * @param address 84 * the remote address the socket is bound to 85 * @param port 86 * the remote port the socket is bound to 87 * @param timeout 88 * the SO_TIMEOUT value of the socket (in milliseconds) or 0 if 89 * there is no timeout set 90 * @param bytesRead 91 * the number of bytes read from the socket, 0 if there was an 92 * error reading from the socket 93 */ socketReadEnd(Object context, InetAddress address, int port, int timeout, long bytesRead)94 public static void socketReadEnd(Object context, InetAddress address, int port, 95 int timeout, long bytesRead) { 96 } 97 98 /** 99 * Called before data is written to a socket. 100 * 101 * @return a context object 102 */ socketWriteBegin()103 public static Object socketWriteBegin() { 104 return null; 105 } 106 107 /** 108 * Called after data is written to a socket. 109 * 110 * @param context 111 * the context returned by the previous call to 112 * socketWriteBegin() 113 * @param address 114 * the remote address the socket is bound to 115 * @param port 116 * the remote port the socket is bound to 117 * @param bytesWritten 118 * the number of bytes written to the socket, 0 if there was an 119 * error writing to the socket 120 */ socketWriteEnd(Object context, InetAddress address, int port, long bytesWritten)121 public static void socketWriteEnd(Object context, InetAddress address, int port, 122 long bytesWritten) { 123 } 124 125 /** 126 * Called before data is read from a file. 127 * 128 * @param path 129 * the path of the file 130 * @return a context object 131 */ fileReadBegin(String path)132 public static Object fileReadBegin(String path) { 133 return null; 134 } 135 136 /** 137 * Called after data is read from a file. 138 * 139 * @param context 140 * the context returned by the previous call to fileReadBegin() 141 * @param bytesRead 142 * the number of bytes written to the file, 0 if there was an 143 * error writing to the file 144 */ fileReadEnd(Object context, long bytesRead)145 public static void fileReadEnd(Object context, long bytesRead) { 146 } 147 148 /** 149 * Called before data is written to a file. 150 * 151 * @param path 152 * the path of the file 153 * @return a context object 154 */ fileWriteBegin(String path)155 public static Object fileWriteBegin(String path) { 156 return null; 157 } 158 159 /** 160 * Called after data is written to a file. 161 * 162 * @param context 163 * the context returned by the previous call to fileReadBegin() 164 * @param bytesWritten 165 * the number of bytes written to the file, 0 if there was an 166 * error writing to the file 167 */ fileWriteEnd(Object context, long bytesWritten)168 public static void fileWriteEnd(Object context, long bytesWritten) { 169 } 170 } 171