Mercurial > hg > blitz_stable
comparison src/com/go/trove/net/SocketFactory.java @ 0:3dc0c5604566
Initial checkin of blitz 2.0 fcs - no installer yet.
author | Dan Creswell <dan.creswell@gmail.com> |
---|---|
date | Sat, 21 Mar 2009 11:00:06 +0000 |
parents | |
children |
comparison
equal
deleted
inserted
replaced
-1:000000000000 | 0:3dc0c5604566 |
---|---|
1 /* ==================================================================== | |
2 * Trove - Copyright (c) 1997-2000 Walt Disney Internet Group | |
3 * ==================================================================== | |
4 * The Tea Software License, Version 1.1 | |
5 * | |
6 * Copyright (c) 2000 Walt Disney Internet Group. All rights reserved. | |
7 * | |
8 * Redistribution and use in source and binary forms, with or without | |
9 * modification, are permitted provided that the following conditions | |
10 * are met: | |
11 * | |
12 * 1. Redistributions of source code must retain the above copyright | |
13 * notice, this list of conditions and the following disclaimer. | |
14 * | |
15 * 2. Redistributions in binary form must reproduce the above copyright | |
16 * notice, this list of conditions and the following disclaimer in | |
17 * the documentation and/or other materials provided with the | |
18 * distribution. | |
19 * | |
20 * 3. The end-user documentation included with the redistribution, | |
21 * if any, must include the following acknowledgment: | |
22 * "This product includes software developed by the | |
23 * Walt Disney Internet Group (http://opensource.go.com/)." | |
24 * Alternately, this acknowledgment may appear in the software itself, | |
25 * if and wherever such third-party acknowledgments normally appear. | |
26 * | |
27 * 4. The names "Tea", "TeaServlet", "Kettle", "Trove" and "BeanDoc" must | |
28 * not be used to endorse or promote products derived from this | |
29 * software without prior written permission. For written | |
30 * permission, please contact opensource@dig.com. | |
31 * | |
32 * 5. Products derived from this software may not be called "Tea", | |
33 * "TeaServlet", "Kettle" or "Trove", nor may "Tea", "TeaServlet", | |
34 * "Kettle", "Trove" or "BeanDoc" appear in their name, without prior | |
35 * written permission of the Walt Disney Internet Group. | |
36 * | |
37 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED | |
38 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES | |
39 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE | |
40 * DISCLAIMED. IN NO EVENT SHALL THE WALT DISNEY INTERNET GROUP OR ITS | |
41 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, | |
42 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, | |
43 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR | |
44 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY | |
45 * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT | |
46 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE | |
47 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. | |
48 * ==================================================================== | |
49 * | |
50 * For more information about Tea, please see http://opensource.go.com/. | |
51 */ | |
52 | |
53 package com.go.trove.net; | |
54 | |
55 import java.net.*; | |
56 | |
57 /****************************************************************************** | |
58 * Allows client sockets to be created or recycled. | |
59 * | |
60 * @author Brian S O'Neill | |
61 * @version | |
62 * <!--$$Revision: 1.1 $-->, <!--$$JustDate:--> 00/12/05 <!-- $--> | |
63 */ | |
64 public interface SocketFactory { | |
65 /** | |
66 * Returns the InetAddress and port that this factory will most likely | |
67 * connect to. If the address isn't precisely known, its value is 0.0.0.0. | |
68 * If the port isn't known, its value is -1. | |
69 */ | |
70 public InetAddressAndPort getInetAddressAndPort(); | |
71 | |
72 /** | |
73 * Returns the InetAddress and port that this factory will most likely | |
74 * connect to. If the address isn't precisely known, its value is 0.0.0.0. | |
75 * If the port isn't known, its value is -1. | |
76 * | |
77 * @param session Object whose hashcode might be used to select a specific | |
78 * connection if factory is distributed. If null, then no session is used. | |
79 */ | |
80 public InetAddressAndPort getInetAddressAndPort(Object session); | |
81 | |
82 /** | |
83 * Returns the default timeout for creating or getting sockets or -1 if | |
84 * infinite. | |
85 */ | |
86 public long getDefaultTimeout(); | |
87 | |
88 /** | |
89 * Must always return a new socket connection. When the socket is no longer | |
90 * needed, call {@link recycleSocket} so that it be used again. | |
91 * | |
92 * @throws ConnectException if timeout has elapsed and no socket is | |
93 * available or factory is closed | |
94 */ | |
95 public CheckedSocket createSocket() | |
96 throws ConnectException, SocketException; | |
97 | |
98 /** | |
99 * Returns a new socket connection. When the socket is no longer | |
100 * needed, call {@link recycleSocket} so that it be used again. | |
101 * | |
102 * @param session Object whose hashcode might be used to select a specific | |
103 * connection if factory is distributed. If null, then no session is used. | |
104 * @throws ConnectException if timeout has elapsed and no socket is | |
105 * available or factory is closed | |
106 */ | |
107 public CheckedSocket createSocket(Object session) | |
108 throws ConnectException, SocketException; | |
109 | |
110 /** | |
111 * Returns a new socket connection. When the socket is no longer | |
112 * needed, call {@link recycleSocket} so that it be used again. | |
113 * | |
114 * @param timeout Maximum time to wait (in milliseconds) for a connection | |
115 * to be created before throwing a ConnectException | |
116 * @throws ConnectException if timeout has elapsed and no socket is | |
117 * available or factory is closed | |
118 */ | |
119 public CheckedSocket createSocket(long timeout) | |
120 throws ConnectException, SocketException; | |
121 | |
122 /** | |
123 * Returns a new socket connection. When the socket is no longer | |
124 * needed, call {@link recycleSocket} so that it be used again. | |
125 * | |
126 * @param session Object whose hashcode might be used to select a specific | |
127 * connection if factory is distributed. If null, then no session is used. | |
128 * @param timeout Maximum time to wait (in milliseconds) for a connection | |
129 * to become available before throwing an exception | |
130 * @throws ConnectException if timeout has elapsed and no socket is | |
131 * available or factory is closed | |
132 */ | |
133 public CheckedSocket createSocket(Object session, long timeout) | |
134 throws ConnectException, SocketException; | |
135 | |
136 /** | |
137 * Returns a new or recycled socket connection. When the socket is no | |
138 * longer needed, call {@link recycleSocket} so that it be used again. | |
139 * | |
140 * @throws ConnectException if timeout has elapsed and no socket is | |
141 * available or factory is closed | |
142 */ | |
143 public CheckedSocket getSocket() throws ConnectException, SocketException; | |
144 | |
145 /** | |
146 * Returns a new or recycled socket connection. When the socket is no | |
147 * longer needed, call {@link recycleSocket} so that it be used again. | |
148 * | |
149 * @param session Object whose hashcode might be used to select a specific | |
150 * connection if factory is distributed. If null, then no session is used. | |
151 * @throws ConnectException if timeout has elapsed and no socket is | |
152 * available or factory is closed | |
153 */ | |
154 public CheckedSocket getSocket(Object session) | |
155 throws ConnectException, SocketException; | |
156 | |
157 /** | |
158 * Returns a new or recycled socket connection. When the socket is no | |
159 * longer needed, call {@link recycleSocket} so that it be used again. | |
160 * | |
161 * @param timeout Maximum time to wait (in milliseconds) for a connection | |
162 * to be returned before throwing a ConnectException | |
163 * @throws ConnectException if timeout has elapsed and no socket is | |
164 * available or factory is closed | |
165 */ | |
166 public CheckedSocket getSocket(long timeout) | |
167 throws ConnectException, SocketException; | |
168 | |
169 /** | |
170 * Returns a new or recycled socket connection. When the socket is no | |
171 * longer needed, call {@link recycleSocket} so that it be used again. | |
172 * | |
173 * @param session Object whose hashcode might be used to select a specific | |
174 * connection if factory is distributed. If null, then no session is used. | |
175 * @param timeout Maximum time to wait (in milliseconds) for a connection | |
176 * to be returned before throwing a ConnectException | |
177 * @throws ConnectException if timeout has elapsed and no socket is | |
178 * available or factory is closed | |
179 */ | |
180 public CheckedSocket getSocket(Object session, long timeout) | |
181 throws ConnectException, SocketException; | |
182 | |
183 /** | |
184 * Recycle a socket connection that was returned from the {@link getSocket} | |
185 * or {@link createSocket} methods. Since SocketFactory has no knowledge of | |
186 * any protocol being used on the socket, it is the responsibility of the | |
187 * caller to ensure the socket is in a "clean" state. Depending on | |
188 * implementation, the recycled socket may simply be closed. | |
189 * | |
190 * @param socket Socket which must have come from this factory. Passing in | |
191 * null is ignored. | |
192 */ | |
193 public void recycleSocket(CheckedSocket socket) | |
194 throws SocketException, IllegalArgumentException; | |
195 | |
196 /** | |
197 * Closes all recycled connections, but does not prevent new connections | |
198 * from being created and recycled. | |
199 */ | |
200 public void clear(); | |
201 | |
202 /** | |
203 * Returns the number of recycled sockets currently available. | |
204 */ | |
205 public int getAvailableCount(); | |
206 } |