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 {
66 private IoTrace() {
67 }
68
69 /**
70 * Called before data is read from a socket.
71 *
72 * @param address
73 * the remote address the socket is bound to
74 * @param port
75 * the remote port the socket is bound to
76 * @param timeout
77 * the SO_TIMEOUT value of the socket (in milliseconds) or 0 if
78 * there is no timeout set
79 * @return a context object
80 */
81 public static Object socketReadBegin(InetAddress address, int port,
82 int timeout) {
83 return null;
84 }
85
86 /**
87 * Called after data is read from the socket.
88 *
89 * @param context
90 * the context returned by the previous call to socketReadBegin()
91 * @param bytesRead
92 * the number of bytes read from the socket, 0 if there was an
93 * error reading from the socket
94 */
95 public static void socketReadEnd(Object context, long bytesRead) {
96 }
97
98 /**
99 * Called before data is written to a socket.
100 *
101 * @param address
102 * the remote address the socket is bound to
103 * @param port
104 * the remote port the socket is bound to
105 * @return a context object
106 */
107 public static Object socketWriteBegin(InetAddress address, int port) {
108 return null;
109 }
110
111 /**
112 * Called after data is written to a socket.
113 *
114 * @param context
115 * the context returned by the previous call to
116 * socketWriteBegin()
117 * @param bytesWritten
118 * the number of bytes written to the socket, 0 if there was an
119 * error writing to the socket
120 */
121 public static void socketWriteEnd(Object context, long bytesWritten) {
122 }
123
124 /**
125 * Called before data is read from a file.
126 *
127 * @param path
128 * the path of the file
129 * @return a context object
130 */
131 public static Object fileReadBegin(String path) {
132 return null;
133 }
134
135 /**
136 * Called after data is read from a file.
137 *
138 * @param context
139 * the context returned by the previous call to fileReadBegin()
140 * @param bytesRead
141 * the number of bytes written to the file, 0 if there was an
142 * error writing to the file
143 */
144 public static void fileReadEnd(Object context, long bytesRead) {
145 }
146
147 /**
148 * Called before data is written to a file.
149 *
150 * @param path
151 * the path of the file
152 * @return a context object
153 */
154 public static Object fileWriteBegin(String path) {
155 return null;
156 }
157
158 /**
159 * Called after data is written to a file.
160 *
161 * @param context
162 * the context returned by the previous call to fileReadBegin()
163 * @param bytesWritten
164 * the number of bytes written to the file, 0 if there was an
165 * error writing to the file
166 */
167 public static void fileWriteEnd(Object context, long bytesWritten) {
168 }
169 }