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.
8 *
9 * This code is distributed in the hope that it will be useful, but WITHOUT
10 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
11 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
12 * version 2 for more details (a copy is included in the LICENSE file that
13 * accompanied this code).
14 *
15 * You should have received a copy of the GNU General Public License version
16 * 2 along with this work; if not, write to the Free Software Foundation,
17 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
18 *
19 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
20 * or visit www.oracle.com if you need additional information or have any
21 * questions.
22 */
23
24 import java.net.InetAddress;
25
26 import sun.misc.IoTrace;
27
28 /**
29 * Implementations of this interface can be registered with
30 * {@link IoTrace#setListener(IoTraceListener)} to receive callbacks when file
31 * and socket operations are performed.
32 * <p>
33 * The xxBegin() methods return a "context". This can be any Object. This
34 * context will be passed to the corresponding xxEnd() method. This way, an
35 * implementation can correlate the beginning of an operation with the end.
36 * <p>
37 * It is possible for a xxEnd() method to be called with a null handle. This
38 * happens if tracing was started between the call to xxBegin() and xxEnd(), in
39 * which case xxBegin() would not have been called. It is the implementation's
40 * responsibility to not throw an exception in this case.
41 * <p>
42 * Implementations should never throw exceptions since this will cause
43 * disruptions to the I/O operations.
44 * <p>
45 * An xxBegin() call is not guaranteed to be followed by an xxEnd() call, since
46 * the listener in IoTrace can be reset at any time.
47 */
48 public interface IoTraceListener {
49
50 /**
51 * Called before data is read from a socket.
52 *
53 * @param address
54 * the remote address the socket is bound to
55 * @param port
56 * the remote port the socket is bound to
57 * @param timeout
58 * the SO_TIMEOUT value of the socket (in milliseconds) or 0 if
59 * there is no timeout set
60 * @return a context object
61 */
62 public Object socketReadBegin(InetAddress address, int port, int timeout);
63
64 /**
65 * Called after data is read from the socket.
66 *
67 * @param context
68 * the context returned by the previous call to socketReadBegin()
69 * @param bytesRead
70 * the number of bytes read from the socket, 0 if there was an
71 * error reading from the socket
72 */
73 public void socketReadEnd(Object context, long bytesRead);
74
75 /**
76 * Called before data is written to a socket.
77 *
78 * @param address
79 * the remote address the socket is bound to
80 * @param port
81 * the remote port the socket is bound to
82 * @return a context object
83 */
84 public Object socketWriteBegin(InetAddress address, int port);
85
86 /**
87 * Called after data is written to a socket.
88 *
89 * @param context
90 * the context returned by the previous call to
91 * socketWriteBegin()
92 * @param bytesWritten
93 * the number of bytes written to the socket, 0 if there was an
94 * error writing to the socket
95 */
96 public void socketWriteEnd(Object context, long bytesWritten);
97
98 /**
99 * Called before data is read from a file.
100 *
101 * @param path
102 * the path of the file
103 * @return a context object
104 */
105 public Object fileReadBegin(String path);
106
107 /**
108 * Called after data is read from a file.
109 *
110 * @param context
111 * the context returned by the previous call to fileReadBegin()
112 * @param bytesRead
113 * the number of bytes written to the file, 0 if there was an
114 * error writing to the file
115 */
116 public void fileReadEnd(Object context, long bytesRead);
117
118 /**
119 * Called before data is written to a file.
120 *
121 * @param path
122 * the path of the file
123 * @return a context object
124 */
125 public Object fileWriteBegin(String path);
126
127 /**
128 * Called after data is written to a file.
129 *
130 * @param context
131 * the context returned by the previous call to fileReadBegin()
132 * @param bytesWritten
133 * the number of bytes written to the file, 0 if there was an
134 * error writing to the file
135 */
136 public void fileWriteEnd(Object context, long bytesWritten);
137 }