1 /*
2 * Copyright (c) 2001, 2004, 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 com.sun.corba.se.pept.transport;
27
28 import com.sun.corba.se.pept.broker.Broker;
29 import com.sun.corba.se.pept.protocol.MessageMediator;
30 import com.sun.corba.se.pept.encoding.InputObject;
31 import com.sun.corba.se.pept.encoding.OutputObject;
32 import com.sun.corba.se.pept.transport.Connection;
33 import com.sun.corba.se.pept.transport.EventHandler;
34
35 /**
36 * <p>The <b><em>primary</em></b> PEPt server-side plug-in point and enabler
37 * for <b><em>altenate encodings, protocols and transports</em></b>.</p>
38 *
39 * <p><code>Acceptor</code> is a <em>factory</em> for client-side
40 * artifacts used to receive a message (and possibly send a response).</p>
41 *
42 * @author Harold Carr
43 */
44 public interface Acceptor
45 {
46 /**
47 * Used to initialize an <code>Acceptor</code>.
48 *
49 * For example, initialization may mean to create a
50 * {@link java.nio.channels.ServerSocketChannel ServerSocketChannel}.
51 *
52 * Note: this must be prepared to be be called multiple times.
53 *
54 * @return <code>true</code> when it performs initializatin
55 * actions (typically the first call.
56 */
57 public boolean initialize();
58
59 /**
60 * Used to determine if an <code>Acceptor</code> has been initialized.
61 *
62 * @return <code>true</code> if the <code>Acceptor</code> has been
63 * initialized.
64 */
65 public boolean initialized();
66
67 /**
68 * PEPt uses separate caches for each type of <code>Acceptor</code>
69 * as given by <code>getConnectionCacheType</code>.
70 *
71 * @return {@link java.lang.String}
72 */
73 public String getConnectionCacheType();
74
75 /**
76 * Set the
77 * {@link com.sun.corba.se.pept.transport.InboundConnectionCache InboundConnectionCache}
78 * to be used by this <code>Acceptor</code>.
79 *
80 * PEPt uses separate caches for each type of <code>Acceptor</code>
81 * as given by {@link #getConnectionCacheType}.
82 * {@link #setConnectionCache} and {@link #getConnectionCache} support
83 * an optimzation to avoid hashing to find that cache.
84 *
85 * @param connectionCache.
86 */
87 public void setConnectionCache(InboundConnectionCache connectionCache);
88
89 /**
90 * Get the
91 * {@link com.sun.corba.se.pept.transport.InboundConnectionCache InboundConnectionCache}
92 * used by this <code>Acceptor</code>
93 *
94 * PEPt uses separate caches for each type of <code>Acceptor</code>
95 * as given by {@link #getConnectionCacheType}.
96 * {@link #setConnectionCache} and {@link #getConnectionCache} support
97 * an optimzation to avoid hashing to find that cache.
98 *
99 * @return
100 * {@link com.sun.corba.se.pept.transport.ConnectionCache ConnectionCache}
101 */
102 public InboundConnectionCache getConnectionCache();
103
104 /**
105 * Used to determine if the <code>Acceptor</code> should register
106 * with
107 * {@link com.sun.corba.se.pept.transport.Selector Selector}
108 * to handle accept events.
109 *
110 * For example, this may be <em>false</em> in the case of Solaris Doors
111 * which do not actively listen.
112 *
113 * @return <code>true</code> if the <code>Acceptor</code> should be
114 * registered with
115 * {@link com.sun.corba.se.pept.transport.Selector Selector}
116 */
117 public boolean shouldRegisterAcceptEvent();
118
119 /**
120 * Accept a connection request.
121 *
122 * This is called either when the selector gets an accept event
123 * for this <code>Acceptor</code> or by a
124 * {@link com.sun.corba.se.pept.transport.ListenerThread ListenerThread}.
125 *
126 * It results in a
127 * {@link com.sun.corba.se.pept.transport.Connection Connection}
128 * being created.
129 */
130 public void accept();
131
132 /**
133 * Close the <code>Acceptor</code>.
134 */
135 public void close();
136
137 /**
138 * Get the
139 * {@link com.sun.corba.se.pept.transport.EventHandler EventHandler}
140 * associated with this <code>Acceptor</code>.
141 *
142 * @return
143 * {@link com.sun.corba.se.pept.transport.EventHandler EventHandler}
144 */
145 public EventHandler getEventHandler();
146
147 //
148 // Factory methods
149 //
150
151 // REVISIT: Identical to ContactInfo method. Refactor into base interface.
152
153 /**
154 * Used to get a
155 * {@link com.sun.corba.se.pept.protocol.MessageMeidator MessageMediator}
156 * to hold internal data for a message received using the specific
157 * encoding, protocol, transport combination represented by this
158 * <code>Acceptor</code>.
159 *
160 * @return
161 * {@link com.sun.corba.se.pept.protocol.MessageMeidator MessageMediator}
162 */
163 public MessageMediator createMessageMediator(Broker xbroker,
164 Connection xconnection);
165
166 // REVISIT: Identical to ContactInfo method. Refactor into base interface.
167
168 /**
169 * Used to finish creating a
170 * {@link com.sun.corba.se.pept.protocol.MessageMeidator MessageMediator}
171 * to with internal data for a message received using the specific
172 * encoding, protocol, transport combination represented by this
173 * <code>Acceptor</code>.
174 *
175 * @return
176 * {@link com.sun.corba.se.pept.protocol.MessageMediator MessageMediator}
177 */
178
179 public MessageMediator finishCreatingMessageMediator(Broker broker,
180 Connection xconnection,
181 MessageMediator messageMediator);
182
183 /**
184 * Used to get a
185 * {@link com.sun.corba.se.pept.encoding.InputObject InputObject}
186 * for the specific <em>encoding</em> represented by this
187 * <code>Acceptor</code>.
188 *
189 * @return
190 * {@link com.sun.corba.se.pept.encoding.InputObject InputObject}
191 */
192 public InputObject createInputObject(Broker broker,
193 MessageMediator messageMediator);
194
195 /**
196 * Used to get a
197 * {@link com.sun.corba.se.pept.encoding.OutputObject OutputObject}
198 * for the specific <em>encoding</em> represented by this
199 * <code>Acceptor</code>.
200 *
201 * @return
202 * {@link com.sun.corba.se.pept.encoding.OutputObject OutputObject}
203 */
204 public OutputObject createOutputObject(Broker broker,
205 MessageMediator messageMediator);
206
207 //
208 // Usage dictates implementation equals and hashCode.
209 //
210 }
211
212 // End of file.