ContactInfo.java revision 608:7e06bf1dcb09 
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
26package com.sun.corba.se.pept.transport;
27
28import com.sun.corba.se.pept.broker.Broker;
29import com.sun.corba.se.pept.encoding.InputObject;
30import com.sun.corba.se.pept.encoding.OutputObject;
31import com.sun.corba.se.pept.protocol.MessageMediator;
32import com.sun.corba.se.pept.protocol.ClientRequestDispatcher;
33import com.sun.corba.se.pept.transport.ConnectionCache;
34
35/**
36 * <p>The <b><em>primary</em></b> PEPt client-side plug-in point and enabler
37 * for <b><em>altenate encodings, protocols and transports</em></b>.</p>
38 *
39 * <p><code>ContactInfo</code> is a <em>factory</em> for client-side
40 * artifacts used
41 * to construct and send a message (and possibly receive and process a
42 * response).</p>
43 *
44 * @author Harold Carr
45 */
46public interface ContactInfo
47{
48    /**
49     * The {@link com.sun.corba.se.pept.broker.Broker Broker} associated
50     * with an invocation.
51     *
52     * @return {@link com.sun.corba.se.pept.broker.Broker Broker}
53     */
54    public Broker getBroker();
55
56    /**
57     * The parent
58     * {@link com.sun.corba.se.pept.broker.ContactInfoList ContactInfoList}
59     * for this <code>ContactInfo</code>.
60     *
61     * @return
62     * {@link com.sun.corba.se.pept.broker.ContactInfoList ContactInfoList}
63     */
64    public ContactInfoList getContactInfoList();
65
66    /**
67     * Used to get a
68     * {@link com.sun.corba.se.pept.protocol.ClientRequestDispatcher
69     * ClientRequestDispatcher}
70     * used to handle the specific <em>protocol</em> represented by this
71     * <code>ContactInfo</code>.
72     *
73     * @return
74     * {@link com.sun.corba.se.pept.protocol.ClientRequestDispatcher
75     * ClientRequestDispatcher} */
76    public ClientRequestDispatcher getClientRequestDispatcher();
77
78    /**
79     * Used to determine if a
80     * {@link com.sun.corba.se.pept.transport.Connection Connection}
81     * will be present in an invocation.
82     *
83     * For example, it may be
84     * <code>false</code> in the case of shared-memory
85     * <code>Input/OutputObjects</code>.
86     *
87     * @return <code>true</code> if a
88     * {@link com.sun.corba.se.pept.transport.Connection Connection}
89     * will be used for an invocation.
90     */
91    public boolean isConnectionBased();
92
93    /**
94     * Used to determine if the
95     * {@link com.sun.corba.se.pept.transport.Connection Connection}
96     * used for a request should be cached.
97     *
98     * If <code>true</code> then PEPt will attempt to reuse an existing
99     * {@link com.sun.corba.se.pept.transport.Connection Connection}. If
100     * one is not found it will create a new one and cache it for future use.
101     *
102     *
103     * @return <code>true</code> if
104     * {@link com.sun.corba.se.pept.transport.Connection Connection}s
105     * created by this <code>ContactInfo</code> should be cached.
106     */
107    public boolean shouldCacheConnection();
108
109    /**
110     * PEPt uses separate caches for each type of <code>ContactInfo</code>
111     * as given by <code>getConnectionCacheType</code>.
112     *
113     * @return {@link java.lang.String}
114     */
115    public String getConnectionCacheType();
116
117    /**
118     * Set the
119     * {@link com.sun.corba.se.pept.transport.Outbound.ConnectionCache OutboundConnectionCache}
120     * to be used by this <code>ContactInfo</code>.
121     *
122     * PEPt uses separate caches for each type of <code>ContactInfo</code>
123     * as given by {@link #getConnectionCacheType}.
124     * {@link #setConnectionCache} and {@link #getConnectionCache} support
125     * an optimzation to avoid hashing to find that cache.
126     *
127     * @param connectionCache.
128     */
129    public void setConnectionCache(OutboundConnectionCache connectionCache);
130
131    /**
132     * Get the
133     * {@link com.sun.corba.se.pept.transport.Outbound.ConnectionCache OutboundConnectionCache}
134     * used by this <code>ContactInfo</code>
135     *
136     * PEPt uses separate caches for each type of <code>ContactInfo</code>
137     * as given by {@link #getConnectionCacheType}.
138     * {@link #setConnectionCache} and {@link #getConnectionCache} support
139     * an optimzation to avoid hashing to find that cache.
140     *
141     * @return
142     * {@link com.sun.corba.se.pept.transport.ConnectionCache ConnectionCache}
143     */
144    public OutboundConnectionCache getConnectionCache();
145
146    /**
147     * Used to get a
148     * {@link com.sun.corba.se.pept.transport.Connection Connection}
149     * to send and receive messages on the specific <em>transport</em>
150     * represented by this <code>ContactInfo</code>.
151     *
152     * @return
153     * {@link com.sun.corba.se.pept.transport.Connection Connection}
154     */
155    public Connection createConnection();
156
157    /**
158     * Used to get a
159     * {@link com.sun.corba.se.pept.protocol.MessageMeidator MessageMediator}
160     * to hold internal data for a message to be sent using the specific
161     * encoding, protocol, transport combination represented by this
162     * <code>ContactInfo</code>.
163     *
164     * @return
165     * {@link com.sun.corba.se.pept.protocol.MessageMediator MessageMediator}
166     */
167    public MessageMediator createMessageMediator(Broker broker,
168                                                 ContactInfo contactInfo,
169                                                 Connection connection,
170                                                 String methodName,
171                                                 boolean isOneWay);
172
173    /**
174     * Used to get a
175     * {@link com.sun.corba.se.pept.protocol.MessageMeidator MessageMediator}
176     * to hold internal data for a message received using the specific
177     * encoding, protocol, transport combination represented by this
178     * <code>ContactInfo</code>.
179     *
180     * @return
181     * {@link com.sun.corba.se.pept.protocol.MessageMeidator MessageMediator}
182     */
183    public MessageMediator createMessageMediator(Broker broker,
184                                                 Connection connection);
185
186    /**
187     * Used to finish creating a
188     * {@link com.sun.corba.se.pept.protocol.MessageMeidator MessageMediator}
189     * with internal data for a message received using the specific
190     * encoding, protocol, transport combination represented by this
191     * <code>ContactInfo</code>.
192     *
193     * @return
194     * {@link com.sun.corba.se.pept.protocol.MessageMediator MessageMediator}
195     */
196    public MessageMediator finishCreatingMessageMediator(Broker broker,
197                                                         Connection connection,
198                                                         MessageMediator messageMediator);
199
200    /**
201     * Used to get a
202     * {@link com.sun.corba.se.pept.encoding.InputObject InputObject}
203     * for the specific <em>encoding</em> represented by this
204     * <code>ContactInfo</code>.
205     *
206     * @return
207     * {@link com.sun.corba.se.pept.encoding.InputObject InputObject}
208     */
209    public InputObject createInputObject(Broker broker,
210                                         MessageMediator messageMediator);
211
212    /**
213     * Used to get a
214     * {@link com.sun.corba.se.pept.encoding.OutputObject OutputObject}
215     * for the specific <em>encoding</em> represented by this
216     * <code>ContactInfo</code>.
217     *
218     * @return
219     * {@link com.sun.corba.se.pept.encoding.OutputObject OutputObject}
220     */
221    public OutputObject createOutputObject(MessageMediator messageMediator);
222
223    /**
224     * Used to lookup artifacts associated with this <code>ContactInfo</code>.
225     *
226     * @return the hash value.
227     */
228    public int hashCode();
229}
230
231// End of file.
232