View Javadoc
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.encoding.InputObject;
30  import com.sun.corba.se.pept.encoding.OutputObject;
31  import com.sun.corba.se.pept.protocol.MessageMediator;
32  import com.sun.corba.se.pept.protocol.ClientRequestDispatcher;
33  import 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   */
46  public 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.