1 /*
2 Copyright (C) 2000 - 2007 Grid Systems, S.A.
3
4 This program is free software; you can redistribute it and/or modify
5 it under the terms of the GNU General Public License, version 2, as
6 published by the Free Software Foundation.
7
8 This program is distributed in the hope that it will be useful,
9 but WITHOUT ANY WARRANTY; without even the implied warranty of
10 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
11 GNU General Public License for more details.
12
13 You should have received a copy of the GNU General Public License
14 along with this program; if not, write to the Free Software
15 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
16 */
17 package com.gridsystems.innergrid.api;
18
19 import java.net.URL;
20
21 import org.apache.axis.client.Call;
22
23 import com.gridsystems.innergrid.kernel.KernelException;
24
25 /**
26 * Classes implementing this interface hold all the necessary data to establish
27 * an authenticated connection to a Server.
28 *
29 * @author Rodrigo Ruiz
30 * @version 1.0
31 */
32 public interface Connection {
33
34 /**
35 * DIME attachment format.
36 */
37 String DIME = Call.ATTACHMENT_ENCAPSULATION_FORMAT_DIME;
38
39 /**
40 * MIME attachment format.
41 */
42 String MIME = Call.ATTACHMENT_ENCAPSULATION_FORMAT_MIME;
43
44 /**
45 * MTOM attachment format.
46 */
47 String MTOM = Call.ATTACHMENT_ENCAPSULATION_FORMAT_MTOM;
48
49 /**
50 * Default connection timeout.
51 */
52 int DEFAULT_TIMEOUT = 300000;
53
54 /**
55 * Gets the Host to connect to.
56 * @return the Host to connect to.
57 */
58 String getHost();
59
60 /**
61 * Gets Port to connect.
62 * @return Port to connect.
63 */
64 int getPort();
65
66 /**
67 * Use a secured connection.
68 * @return <tt>true</tt> if this connection uses SSL;
69 * <tt>false</tt> otherwise.
70 */
71 boolean isSecured();
72
73 /**
74 * Gets the connection context path.
75 * <p>
76 * By default, Kernel services are located in <tt>/kernel/api</tt>.
77 *
78 * @return The connection base context path
79 */
80 String getContextPath();
81
82 /**
83 * Gets the value of the chunked transfer control flag.
84 * <p>
85 * This flag is set to <tt>true</tt> by default.
86 *
87 * @return The current transfer control flag value
88 */
89 boolean isChunkedTransferEnabled();
90
91 /**
92 * Enables or disables chunked transfer encoding (it is enabled by default).
93 * <p>
94 * This flag must be set to <tt>false</tt> when connecting to servers that
95 * do not support this transfer encoding. In particular, simple servers used
96 * by MUSE for event notification require this flag to be disabled.
97 * <p>
98 * Embedded servers used during unit tests will usually require this
99 * encoding to be disabled too.
100 *
101 * @param enabled The new flag value
102 */
103 void setChunkedTransferEnabled(boolean enabled);
104
105 /**
106 * Gets the keep-alive control flag value.
107 *
108 * @return The current flag value
109 */
110 boolean isKeepAliveEnabled();
111
112 /**
113 * Sets the keep-alive control flag value.
114 * <p>
115 * Keep-alive is disabled by default for scalability reasons. However, if
116 * several calls must be performed in a short time period, enabling it can
117 * drastically improve the performance.
118 *
119 * @param enabled The new flag value
120 */
121 void setKeepAliveEnabled(boolean enabled);
122
123 /**
124 * Gets the connection timeout.
125 *
126 * @return The connection timeout in milliseconds
127 */
128 int getTimeout();
129
130 /**
131 * Sets the connection timeout. By default, it is 30 seconds.
132 *
133 * @param timeout The connection timeout in milliseconds
134 */
135 void setTimeout(int timeout);
136
137 /**
138 * Gets the attachment format (DIME, MIME or MTOM).
139 *
140 * @return The attachment format to use
141 */
142 String getAttachmentFormat();
143
144 /**
145 * Sets the attachment format (DIME, MIME or MTOM). By default, the format
146 * is automatically selected through the Service deployment meta-data. By
147 * setting this value, the user can override these default values.
148 *
149 * @param format The attachment format to use
150 */
151 void setAttachmentFormat(String format);
152
153 /**
154 * Gets a target URL to the SOAP service for the specified API (Internal use only).
155 *
156 * @param apiName the name of the API
157 * @return the target URL to apiName
158 * @throws KernelException <code>CLT008</code> if the resulting URL is invalid
159 */
160 URL getUrl(String apiName) throws KernelException;
161
162 /**
163 * Gets the credentials for the connection.
164 *
165 * @return the needed Credentials. They can be null.
166 */
167 Credentials getCredentials();
168
169 /**
170 * Manages exceptions (Internal use only).
171 *
172 * @param ke KernelException captured
173 * @param retry number of retries
174 * @throws KernelException the <code>ke</code> exception if it passes along the
175 * exception without managing
176 *
177 */
178 void manageException(KernelException ke, int retry) throws KernelException;
179
180 /**
181 * Notifies to the Connection instance that the target API has been reached.
182 */
183 void success();
184
185 /**
186 * Checks that the connection is directed to an open port with the proper protocol.
187 *
188 * @throws KernelException <code>CLT060</code> if the port cannot be reached.
189 * @throws KernelException <code>CLT061</code> if the port can be reached but the
190 * protocol is not valid.
191 * @throws KernelException <code>CLT062</code> if a valid URL to the port to check
192 * cannot be created.
193 */
194 void checkConnection() throws KernelException;
195
196 /**
197 * Disposes the object and releases kept resources.
198 */
199 void close();
200 }