Connection.java revision 608:7e06bf1dcb09 
1/*
2 * Copyright (c) 2001, 2003, 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
26package com.sun.corba.se.pept.transport;
27
28import java.io.IOException;
29
30import com.sun.corba.se.pept.encoding.InputObject;
31import com.sun.corba.se.pept.encoding.OutputObject;
32import com.sun.corba.se.pept.protocol.MessageMediator;
33import com.sun.corba.se.pept.transport.EventHandler;
34
35
36/**
37 * <p><code>Connection</code> represents a <em>transport</em> in the
38 * PEPt architecture.</p>
39 *
40 * @author Harold Carr
41*/
42public interface Connection
43{
44    /**
45     * Used to determine if the <code>Connection</code> should register
46     * with the
47     * {@link com.sun.corba.se.pept.transport.TransportManager
48     * TransportManager}
49     * {@link com.sun.corba.se.pept.transport.Selector Selector}
50     * to handle read events.
51     *
52     * For example, an HTTP transport would not register since the requesting
53     * thread would just block on read when waiting for the reply.
54     *
55     * @return <code>true</code> if it should be registered.
56     */
57    public boolean shouldRegisterReadEvent();
58
59    /**
60     * Used to determine if the <code>Connection</code> should register
61     * with the
62     * {@link com.sun.corba.se.pept.transport.TransportManager
63     * TransportManager}
64     * {@link com.sun.corba.se.pept.transport.Selector Selector}
65     * to handle read events.
66     *
67     * For example, an HTTP transport would not register since the requesting
68     * thread would just block on read when waiting for the reply.
69     *
70     * @return <code>true</code> if it should be registered.
71     */
72    public boolean shouldRegisterServerReadEvent(); // REVISIT - why special?
73
74    /**
75     * Called to read incoming messages.
76     *
77     * @return <code>true</code> if the thread calling read can be released.
78     */
79    public boolean read();
80
81    /**
82     * Close the <code>Connection</code>.
83     *
84     */
85    public void close();
86
87    // REVISIT: replace next two with PlugInFactory (implemented by ContactInfo
88    // and Acceptor).
89
90    /**
91     * Get the
92     * {@link com.sun.corba.se.pept.transport.Acceptor Acceptor}
93     * that created this <code>Connection</code>.
94     *
95     * @return
96     * {@link com.sun.corba.se.pept.transport.Acceptor Acceptor}
97     */
98    public Acceptor getAcceptor();
99
100    /**
101     * Get the
102     * {@link com.sun.corba.se.pept.transport.ContactInfo ContactInfo}
103     * that created this <code>Connection</code>.
104     *
105     * @return
106     * {@link com.sun.corba.se.pept.transport.ContactInfo ContactInfo}
107     */
108    public ContactInfo getContactInfo();
109
110    /**
111     * Get the
112     * {@link com.sun.corba.se.pept.transport.EventHandler EventHandler}
113     * associated with this <code>Acceptor</code>.
114     *
115     * @return
116     * {@link com.sun.corba.se.pept.transport.EventHandler EventHandler}
117     */
118    public EventHandler getEventHandler();
119
120    /**
121     * Indicates whether a
122     * {@link com.sun.corba.se.pept.transport.ContactInfo ContactInfo}
123     * or a
124     * {@link com.sun.corba.se.pept.transport.Acceptor Acceptor}
125     * created the
126     * <code>Connection</code>.
127     *
128     * @return <code>true</code> if <code>Connection</code> an
129     * {@link com.sun.corba.se.pept.transport.Acceptor Acceptor}
130     * created the <code>Connection</code>.
131     */
132    public boolean isServer();
133
134    /**
135     * Indicates if the <code>Connection</code> is in the process of
136     * sending or receiving a message.
137     *
138     * @return <code>true</code> if the <code>Connection</code> is busy.
139     */
140    public boolean isBusy();
141
142    /**
143     * Timestamps are used for connection management, in particular, for
144     * reclaiming idle <code>Connection</code>s.
145     *
146     * @return the "time" the <code>Connection</code> was last used.
147     */
148    public long getTimeStamp();
149
150    /**
151     * Timestamps are used for connection management, in particular, for
152     * reclaiming idle <code>Connection</code>s.
153     *
154     * @param time - the "time" the <code>Connection</code> was last used.
155     */
156    public void setTimeStamp(long time);
157
158    /**
159     * The "state" of the <code>Connection</code>.
160     *
161     * param state
162     */
163    public void setState(String state);
164
165    /**
166     * Grab a write lock on the <code>Connection</code>.
167     *
168     * If another thread already has a write lock then the calling
169     * thread will block until the lock is released.  The calling
170     * thread must call
171     * {@link #writeUnlock}
172     * when it is done.
173     */
174    public void writeLock();
175
176    /**
177     * Release a write lock on the <code>Connection</code>.
178     */
179    public void writeUnlock();
180
181    /*
182     * Send the data encoded in
183     * {@link com.sun.corba.se.pept.encoding.OutputObject OutputObject}
184     * on the <code>Connection</code>.
185     *
186     * @param outputObject
187     */
188    public void sendWithoutLock(OutputObject outputObject);
189
190    /**
191     * Register an invocation's
192     * {@link com.sun.corba.se.pept.protocol.MessageMediator MessageMediator}
193     * with the <code>Connection</code>.
194     *
195     * This is useful in protocols which support fragmentation.
196     *
197     * @param messageMediator
198     */
199    public void registerWaiter(MessageMediator messageMediator);
200
201    /**
202     * If a message expect's a response then this method is called.
203     *
204     * This method might block on a read (e.g., HTTP), put the calling
205     * thread to sleep while another thread read's the response (e.g., GIOP),
206     * or it may use the calling thread to perform the server-side work
207     * (e.g., Solaris Doors).
208     *
209     * @param messageMediator
210     */
211    public InputObject waitForResponse(MessageMediator messageMediator);
212
213    /**
214     * Unregister an invocation's
215     * {@link com.sun.corba.se.pept.protocol.MessageMediator MessageMediator}
216     * with the <code>Connection</code>.
217     *
218     * @param messageMediator
219     */
220    public void unregisterWaiter(MessageMediator messageMediator);
221
222    public void setConnectionCache(ConnectionCache connectionCache);
223
224    public ConnectionCache getConnectionCache();
225}
226
227// End of file.
228