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 import java.net.InetAddress;
27
28 import sun.misc.IoTrace;
29 import sun.misc.IoTraceContext;
30
31 /**
32 * Implementations of this interface can be registered with
33 * {@link IoTrace#setListener(IoTraceListener)} to receive callbacks when file
34 * and socket operations are performed.
35 * <p>
36 * The xxBegin() methods return a "context". This can be any Object marked with
37 * the {@link IoTraceContext} empty interface. This context will be passed to
38 * the corresponding xxEnd() method. This way, an implementation can correlate
39 * the beginning of an operation with the end.
40 * <p>
41 * It is possible for a xxEnd() method to be called with a null handle. This
42 * happens if tracing was started between the call to xxBegin() and xxEnd(), in
43 * which case xxBegin() would not have been called. It is the implementation's
44 * responsibility to not throw an exception in this case.
45 * <p>
46 * Implementations should never throw exceptions since this will cause
47 * disruptions to the I/O operations.
48 * <p>
49 * An xxBegin() call is not guaranteed to be followed by an xxEnd() call, since
50 * the listener in IoTrace can be reset at any time.
51 */
52 public interface IoTraceListener {
53
54 /**
55 * Called before data is read from a socket.
56 *
57 * @param address
58 * the remote address the socket is bound to
59 * @param port
60 * the remote port the socket is bound to
61 * @param timeout
62 * the SO_TIMEOUT value of the socket (in milliseconds) or 0 if
63 * there is no timeout set
64 * @return an IoTraceContext object
65 */
66 public IoTraceContext socketReadBegin(InetAddress address, int port,
67 int timeout);
68
69 /**
70 * Called after data is read from the socket.
71 *
72 * @param context
73 * the context returned by the previous call to socketReadBegin()
74 * @param bytesRead
75 * the number of bytes read from the socket, 0 if there was an
76 * error reading from the socket
77 */
78 public void socketReadEnd(IoTraceContext context, long bytesRead);
79
80 /**
81 * Called before data is written to a socket.
82 *
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 * @return an IoTraceContext object
88 */
89 public IoTraceContext socketWriteBegin(InetAddress address, int port);
90
91 /**
92 * Called after data is written to a socket.
93 *
94 * @param context
95 * the context returned by the previous call to
96 * socketWriteBegin()
97 * @param bytesWritten
98 * the number of bytes written to the socket, 0 if there was an
99 * error writing to the socket
100 */
101 public void socketWriteEnd(IoTraceContext context, long bytesWritten);
102
103 /**
104 * Called before data is read from a file.
105 *
106 * @param path
107 * the path of the file
108 * @return an IoTraceContext object
109 */
110 public IoTraceContext fileReadBegin(String path);
111
112 /**
113 * Called after data is read from a file.
114 *
115 * @param context
116 * the context returned by the previous call to fileReadBegin()
117 * @param bytesRead
118 * the number of bytes written to the file, 0 if there was an
119 * error writing to the file
120 */
121 public void fileReadEnd(IoTraceContext context, long bytesRead);
122
123 /**
124 * Called before data is written to a file.
125 *
126 * @param path
127 * the path of the file
128 * @return an IoTraceContext object
129 */
130 public IoTraceContext fileWriteBegin(String path);
131
132 /**
133 * Called after data is written to a file.
134 *
135 * @param context
136 * the context returned by the previous call to fileReadBegin()
137 * @param bytesWritten
138 * the number of bytes written to the file, 0 if there was an
139 * error writing to the file
140 */
141 public void fileWriteEnd(IoTraceContext context, long bytesWritten);
142 }