001 /*
002 * Copyright 2010 Red Hat, Inc.
003 * Red Hat licenses this file to you under the Apache License, version
004 * 2.0 (the "License"); you may not use this file except in compliance
005 * with the License. You may obtain a copy of the License at
006 * http://www.apache.org/licenses/LICENSE-2.0
007 * Unless required by applicable law or agreed to in writing, software
008 * distributed under the License is distributed on an "AS IS" BASIS,
009 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
010 * implied. See the License for the specific language governing
011 * permissions and limitations under the License.
012 */
013
014 package org.hornetq.api.core.client;
015
016 import org.hornetq.api.core.DiscoveryGroupConfiguration;
017 import org.hornetq.api.core.HornetQException;
018 import org.hornetq.api.core.Interceptor;
019 import org.hornetq.api.core.TransportConfiguration;
020 import org.hornetq.api.core.client.loadbalance.ConnectionLoadBalancingPolicy;
021
022 /**
023 * A ServerLocator
024 *
025 * @author Tim Fox
026 *
027 *
028 */
029 public interface ServerLocator
030 {
031
032 /**
033 * This method will disable any checks when a GarbageCollection happens leaving connections open.
034 * The JMS Layer will make specific usage of this method, since the ConnectionFactory.finalize should release this.
035 *
036 * Warn: You may leave resources unnatended if you call this method and don't take care of cleaning the resources yourself.
037 */
038 void disableFinalizeCheck();
039
040 /**
041 * Create a ClientSessionFactory using whatever load balancing policy is in force
042 * @return The ClientSessionFactory
043 * @throws Exception
044 */
045 ClientSessionFactory createSessionFactory() throws Exception;
046
047 /**
048 * Create a ClientSessionFactory to a specific server. The server must already be known about by this ServerLocator.
049 * This method allows the user to make a connection to a specific server bypassing any load balancing policy in force
050 * @param transportConfiguration
051 * @return The ClientSesionFactory
052 * @throws Exception if a failure happened in creating the ClientSessionFactory or the ServerLocator does not know about the passed in transportConfiguration
053 */
054 ClientSessionFactory createSessionFactory(final TransportConfiguration transportConfiguration) throws Exception;
055
056 /**
057 * Returns the period used to check if a client has failed to receive pings from the server.
058 *
059 * Period is in milliseconds, default value is {@link HornetQClient#DEFAULT_CLIENT_FAILURE_CHECK_PERIOD}.
060 *
061 * @return the period used to check if a client has failed to receive pings from the server
062 */
063 long getClientFailureCheckPeriod();
064
065 /**
066 * Sets the period (in milliseconds) used to check if a client has failed to receive pings from the server.
067 *
068 * Value must be -1 (to disable) or greater than 0.
069 *
070 * @param clientFailureCheckPeriod the period to check failure
071 */
072 void setClientFailureCheckPeriod(long clientFailureCheckPeriod);
073
074 /**
075 * When <code>true</code>, consumers created through this factory will create temporary files to cache large messages.
076 *
077 * There is 1 temporary file created for each large message.
078 *
079 * Default value is {@link HornetQClient#DEFAULT_CACHE_LARGE_MESSAGE_CLIENT}.
080 *
081 * @return <code>true</code> if consumers created through this factory will cache large messages in temporary files, <code>false</code> else
082 */
083 boolean isCacheLargeMessagesClient();
084
085 /**
086 * Sets whether large messages received by consumers created through this factory will be cached in temporary files or not.
087 *
088 * @param cached <code>true</code> to cache large messages in temporary files, <code>false</code> else
089 */
090 void setCacheLargeMessagesClient(boolean cached);
091
092 /**
093 * Returns the connection <em>time-to-live</em>.
094 * This TTL determines how long the server will keep a connection alive in the absence of any data arriving from the client.
095 *
096 * Value is in milliseconds, default value is {@link HornetQClient#DEFAULT_CONNECTION_TTL}.
097 *
098 * @return the connection time-to-live in milliseconds
099 */
100 long getConnectionTTL();
101
102 /**
103 * Sets this factory's connections <em>time-to-live</em>.
104 *
105 * Value must be -1 (to disable) or greater or equals to 0.
106 *
107 * @param connectionTTL period in milliseconds
108 */
109 void setConnectionTTL(long connectionTTL);
110
111 /**
112 * Returns the blocking calls timeout.
113 *
114 * If client's blocking calls to the server take more than this timeout, the call will throw a {@link HornetQException} with the code {@link HornetQException#CONNECTION_TIMEDOUT}.
115 * Value is in milliseconds, default value is {@link HornetQClient#DEFAULT_CALL_TIMEOUT}.
116 *
117 * @return the blocking calls timeout
118 */
119 long getCallTimeout();
120
121 /**
122 * Sets the blocking call timeout.
123 *
124 * Value must be greater or equals to 0
125 *
126 * @param callTimeout blocking call timeout in milliseconds
127 */
128 void setCallTimeout(long callTimeout);
129
130 /**
131 * Returns the large message size threshold.
132 *
133 * Messages whose size is if greater than this value will be handled as <em>large messages</em>.
134 *
135 * Value is in bytes, default value is {@link HornetQClient#DEFAULT_MIN_LARGE_MESSAGE_SIZE}.
136 *
137 * @return the message size threshold to treat messages as large messages.
138 */
139 int getMinLargeMessageSize();
140
141 /**
142 * Sets the large message size threshold.
143 *
144 * Value must be greater than 0.
145 *
146 * @param minLargeMessageSize large message size threshold in bytes
147 */
148 void setMinLargeMessageSize(int minLargeMessageSize);
149
150 /**
151 * Returns the window size for flow control of the consumers created through this factory.
152 *
153 * Value is in bytes, default value is {@link HornetQClient#DEFAULT_CONSUMER_WINDOW_SIZE}.
154 *
155 * @return the window size used for consumer flow control
156 */
157 int getConsumerWindowSize();
158
159 /**
160 * Sets the window size for flow control of the consumers created through this factory.
161 *
162 * Value must be -1 (to disable flow control), 0 (to not buffer any messages) or greater than 0 (to set the maximum size of the buffer)
163 *
164 * @param consumerWindowSize window size (in bytes) used for consumer flow control
165 */
166 void setConsumerWindowSize(int consumerWindowSize);
167
168 /**
169 * Returns the maximum rate of message consumption for consumers created through this factory.
170 *
171 * This value controls the rate at which a consumer can consume messages. A consumer will never consume messages at a rate faster than the rate specified.
172 *
173 * Value is -1 (to disable) or a positive integer corresponding to the maximum desired message consumption rate specified in units of messages per second.
174 * Default value is {@link HornetQClient#DEFAULT_CONSUMER_MAX_RATE}.
175 *
176 * @return the consumer max rate
177 */
178 int getConsumerMaxRate();
179
180 /**
181 * Sets the maximum rate of message consumption for consumers created through this factory.
182 *
183 * Value must -1 (to disable) or a positive integer corresponding to the maximum desired message consumption rate specified in units of messages per second.
184 *
185 * @param consumerMaxRate maximum rate of message consumption (in messages per seconds)
186 */
187 void setConsumerMaxRate(int consumerMaxRate);
188
189 /**
190 * Returns the size for the confirmation window of clients using this factory.
191 *
192 * Value is in bytes or -1 (to disable the window). Default value is {@link HornetQClient#DEFAULT_CONFIRMATION_WINDOW_SIZE}.
193 *
194 * @return the size for the confirmation window of clients using this factory
195 */
196 int getConfirmationWindowSize();
197
198 /**
199 * Sets the size for the confirmation window buffer of clients using this factory.
200 *
201 * Value must be -1 (to disable the window) or greater than 0.
202
203 * @param confirmationWindowSize size of the confirmation window (in bytes)
204 */
205 void setConfirmationWindowSize(int confirmationWindowSize);
206
207 /**
208 * Returns the window size for flow control of the producers created through this factory.
209 *
210 * Value must be -1 (to disable flow control) or greater than 0 to determine the maximum amount of bytes at any give time (to prevent overloading the connection).
211 * Default value is {@link HornetQClient#DEFAULT_PRODUCER_WINDOW_SIZE}.
212 *
213 * @return the window size for flow control of the producers created through this factory.
214 */
215 int getProducerWindowSize();
216
217 /**
218 * Returns the window size for flow control of the producers created through this factory.
219 *
220 * Value must be -1 (to disable flow control) or greater than 0.
221 *
222 * @param producerWindowSize window size (in bytest) for flow control of the producers created through this factory.
223 */
224 void setProducerWindowSize(int producerWindowSize);
225
226 /**
227 * Returns the maximum rate of message production for producers created through this factory.
228 *
229 * This value controls the rate at which a producer can produce messages. A producer will never produce messages at a rate faster than the rate specified.
230 *
231 * Value is -1 (to disable) or a positive integer corresponding to the maximum desired message production rate specified in units of messages per second.
232 * Default value is {@link HornetQClient#DEFAULT_PRODUCER_MAX_RATE}.
233 *
234 * @return maximum rate of message production (in messages per seconds)
235 */
236 int getProducerMaxRate();
237
238 /**
239 * Sets the maximum rate of message production for producers created through this factory.
240 *
241 * Value must -1 (to disable) or a positive integer corresponding to the maximum desired message production rate specified in units of messages per second.
242 *
243 * @param producerMaxRate maximum rate of message production (in messages per seconds)
244 */
245 void setProducerMaxRate(int producerMaxRate);
246
247 /**
248 * Returns whether consumers created through this factory will block while sending message acknowledgements or do it asynchronously.
249 *
250 * Default value is {@link HornetQClient#DEFAULT_BLOCK_ON_ACKNOWLEDGE}.
251 *
252 * @return whether consumers will block while sending message acknowledgements or do it asynchronously
253 */
254 boolean isBlockOnAcknowledge();
255
256 /**
257 * Sets whether consumers created through this factory will block while sending message acknowledgements or do it asynchronously.
258 *
259 * @param blockOnAcknowledge <code>true</code> to block when sending message acknowledgements or <code>false</code> to send them asynchronously
260 */
261 void setBlockOnAcknowledge(boolean blockOnAcknowledge);
262
263 /**
264 * Returns whether producers created through this factory will block while sending <em>durable</em> messages or do it asynchronously.
265 * <br>
266 * If the session is configured to send durable message asynchronously, the client can set a SendAcknowledgementHandler on the ClientSession
267 * to be notified once the message has been handled by the server.
268 *
269 * Default value is {@link HornetQClient#DEFAULT_BLOCK_ON_DURABLE_SEND}.
270 *
271 * @return whether producers will block while sending persistent messages or do it asynchronously
272 */
273 boolean isBlockOnDurableSend();
274
275 /**
276 * Sets whether producers created through this factory will block while sending <em>durable</em> messages or do it asynchronously.
277 *
278 * @param blockOnDurableSend <code>true</code> to block when sending durable messages or <code>false</code> to send them asynchronously
279 */
280 void setBlockOnDurableSend(boolean blockOnDurableSend);
281
282 /**
283 * Returns whether producers created through this factory will block while sending <em>non-durable</em> messages or do it asynchronously.
284 * <br>
285 * If the session is configured to send non-durable message asynchronously, the client can set a SendAcknowledgementHandler on the ClientSession
286 * to be notified once the message has been handled by the server.
287 *
288 * Default value is {@link HornetQClient#DEFAULT_BLOCK_ON_NON_DURABLE_SEND}.
289 *
290 * @return whether producers will block while sending non-durable messages or do it asynchronously
291 */
292 boolean isBlockOnNonDurableSend();
293
294 /**
295 * Sets whether producers created through this factory will block while sending <em>non-durable</em> messages or do it asynchronously.
296 *
297 * @param blockOnNonDurableSend <code>true</code> to block when sending non-durable messages or <code>false</code> to send them asynchronously
298 */
299 void setBlockOnNonDurableSend(boolean blockOnNonDurableSend);
300
301 /**
302 * Returns whether producers created through this factory will automatically
303 * assign a group ID to the messages they sent.
304 *
305 * if <code>true</code>, a random unique group ID is created and set on each message for the property
306 * {@link org.hornetq.api.core.Message#HDR_GROUP_ID}.
307 * Default value is {@link HornetQClient#DEFAULT_AUTO_GROUP}.
308 *
309 * @return whether producers will automatically assign a group ID to their messages
310 */
311 boolean isAutoGroup();
312
313 /**
314 * Sets whether producers created through this factory will automatically
315 * assign a group ID to the messages they sent.
316 *
317 * @param autoGroup <code>true</code> to automatically assign a group ID to each messages sent through this factory, <code>false</code> else
318 */
319 void setAutoGroup(boolean autoGroup);
320
321 /**
322 * Returns the group ID that will be eventually set on each message for the property {@link org.hornetq.api.core.Message#HDR_GROUP_ID}.
323 *
324 * Default value is is <code>null</code> and no group ID will be set on the messages.
325 *
326 * @return the group ID that will be eventually set on each message
327 */
328 String getGroupID();
329
330 /**
331 * Sets the group ID that will be set on each message sent through this factory.
332 *
333 * @param groupID the group ID to use
334 */
335 void setGroupID(String groupID);
336
337 /**
338 * Returns whether messages will pre-acknowledged on the server before they are sent to the consumers or not.
339 *
340 * Default value is {@link HornetQClient#DEFAULT_PRE_ACKNOWLEDGE}
341 */
342 boolean isPreAcknowledge();
343
344 /**
345 * Sets to <code>true</code> to pre-acknowledge consumed messages on the server before they are sent to consumers, else set to <code>false</code> to let
346 * clients acknowledge the message they consume.
347 *
348 * @param preAcknowledge <code>true</code> to enable pre-acknowledgement, <code>false</code> else
349 */
350 void setPreAcknowledge(boolean preAcknowledge);
351
352 /**
353 * Returns the acknowledgements batch size.
354 *
355 * Default value is {@link HornetQClient#DEFAULT_ACK_BATCH_SIZE}.
356 *
357 * @return the acknowledgements batch size
358 */
359 int getAckBatchSize();
360
361 /**
362 * Sets the acknowledgements batch size.
363 *
364 * Value must be equal or greater than 0.
365 *
366 * @param ackBatchSize acknowledgements batch size
367 */
368 void setAckBatchSize(int ackBatchSize);
369
370 /**
371 * Returns an array of TransportConfigurations representing the static list of live servers used when
372 * creating this object
373 * @return
374 */
375 TransportConfiguration[] getStaticTransportConfigurations();
376
377 /**
378 * The discovery group configuration
379 */
380 DiscoveryGroupConfiguration getDiscoveryGroupConfiguration();
381
382 /**
383 * Returns whether this factory will use global thread pools (shared among all the factories in the same JVM)
384 * or its own pools.
385 *
386 * Default value is {@link HornetQClient#DEFAULT_USE_GLOBAL_POOLS}.
387 *
388 * @return <code>true</code> if this factory uses global thread pools, <code>false</code> else
389 */
390 boolean isUseGlobalPools();
391
392 /**
393 * Sets whether this factory will use global thread pools (shared among all the factories in the same JVM)
394 * or its own pools.
395 *
396 * @param useGlobalPools <code>true</code> to let this factory uses global thread pools, <code>false</code> else
397 */
398 void setUseGlobalPools(boolean useGlobalPools);
399
400 /**
401 * Returns the maximum size of the scheduled thread pool.
402 *
403 * Default value is {@link HornetQClient#DEFAULT_SCHEDULED_THREAD_POOL_MAX_SIZE}.
404 *
405 * @return the maximum size of the scheduled thread pool.
406 */
407 int getScheduledThreadPoolMaxSize();
408
409 /**
410 * Sets the maximum size of the scheduled thread pool.
411 *
412 * This setting is relevant only if this factory does not use global pools.
413 * Value must be greater than 0.
414 *
415 * @param scheduledThreadPoolMaxSize maximum size of the scheduled thread pool.
416 */
417 void setScheduledThreadPoolMaxSize(int scheduledThreadPoolMaxSize);
418
419 /**
420 * Returns the maximum size of the thread pool.
421 *
422 * Default value is {@link HornetQClient#DEFAULT_THREAD_POOL_MAX_SIZE}.
423 *
424 * @return the maximum size of the thread pool.
425 */
426 int getThreadPoolMaxSize();
427
428 /**
429 * Sets the maximum size of the thread pool.
430 *
431 * This setting is relevant only if this factory does not use global pools.
432 * Value must be -1 (for unlimited thread pool) or greater than 0.
433 *
434 * @param threadPoolMaxSize maximum size of the thread pool.
435 */
436 void setThreadPoolMaxSize(int threadPoolMaxSize);
437
438 /**
439 * Returns the time to retry connections created by this factory after failure.
440 *
441 * Value is in milliseconds, default is {@link HornetQClient#DEFAULT_RETRY_INTERVAL}.
442 *
443 * @return the time to retry connections created by this factory after failure
444 */
445 long getRetryInterval();
446
447 /**
448 * Sets the time to retry connections created by this factory after failure.
449 *
450 * Value must be greater than 0.
451 *
452 * @param retryInterval time (in milliseconds) to retry connections created by this factory after failure
453 */
454 void setRetryInterval(long retryInterval);
455
456 /**
457 * Returns the multiplier to apply to successive retry intervals.
458 *
459 * Default value is {@link HornetQClient#DEFAULT_RETRY_INTERVAL_MULTIPLIER}.
460 *
461 * @return the multiplier to apply to successive retry intervals
462 */
463 double getRetryIntervalMultiplier();
464
465 /**
466 * Sets the multiplier to apply to successive retry intervals.
467 *
468 * Value must be positive.
469 *
470 * @param retryIntervalMultiplier multiplier to apply to successive retry intervals
471 */
472 void setRetryIntervalMultiplier(double retryIntervalMultiplier);
473
474 /**
475 * Returns the maximum retry interval (in the case a retry interval multiplier has been specified).
476 *
477 * Value is in milliseconds, default value is {@link HornetQClient#DEFAULT_MAX_RETRY_INTERVAL}.
478 *
479 * @return the maximum retry interval
480 */
481 long getMaxRetryInterval();
482
483 /**
484 * Sets the maximum retry interval.
485 *
486 * Value must be greater than 0.
487 *
488 * @param maxRetryInterval maximum retry interval to apply in the case a retry interval multiplier has been specified
489 */
490 void setMaxRetryInterval(long maxRetryInterval);
491
492 /**
493 * Returns the maximum number of attempts to retry connection in case of failure.
494 *
495 * Default value is {@link HornetQClient#DEFAULT_RECONNECT_ATTEMPTS}.
496 *
497 * @return the maximum number of attempts to retry connection in case of failure.
498 */
499 int getReconnectAttempts();
500
501 /**
502 * Sets the maximum number of attempts to retry connection in case of failure.
503 *
504 * Value must be -1 (to retry infinitely), 0 (to never retry connection) or greater than 0.
505 *
506 * @param reconnectAttempts maximum number of attempts to retry connection in case of failure
507 */
508 void setReconnectAttempts(int reconnectAttempts);
509
510 void setInitialConnectAttempts(int reconnectAttempts);
511
512 int getInitialConnectAttempts();
513 /**
514 * Returns true if the client will automatically attempt to connect to the backup server if the initial
515 * connection to the live server fails
516 *
517 * Default value is {@link HornetQClient#DEFAULT_FAILOVER_ON_INITIAL_CONNECTION}.
518 */
519 boolean isFailoverOnInitialConnection();
520
521 /**
522 * Sets the value for FailoverOnInitialReconnection
523 *
524 * @param failover
525 */
526 void setFailoverOnInitialConnection(boolean failover);
527
528 /**
529 * Returns the class name of the connection load balancing policy.
530 *
531 * Default value is "org.hornetq.api.core.client.loadbalance.RoundRobinConnectionLoadBalancingPolicy".
532 *
533 * @return the class name of the connection load balancing policy
534 */
535 String getConnectionLoadBalancingPolicyClassName();
536
537 /**
538 * Sets the class name of the connection load balancing policy.
539 *
540 * Value must be the name of a class implementing {@link ConnectionLoadBalancingPolicy}.
541 *
542 * @param loadBalancingPolicyClassName class name of the connection load balancing policy
543 */
544 void setConnectionLoadBalancingPolicyClassName(String loadBalancingPolicyClassName);
545
546 /**
547 * Returns the initial size of messages created through this factory.
548 *
549 * Value is in bytes, default value is {@link HornetQClient#DEFAULT_INITIAL_MESSAGE_PACKET_SIZE}.
550 *
551 * @return the initial size of messages created through this factory
552 */
553 int getInitialMessagePacketSize();
554
555 /**
556 * Sets the initial size of messages created through this factory.
557 *
558 * Value must be greater than 0.
559 *
560 * @param size initial size of messages created through this factory.
561 */
562 void setInitialMessagePacketSize(int size);
563
564 /**
565 * Adds an interceptor which will be executed <em>after packets are received from the server</em>.
566 *
567 * @param interceptor an Interceptor
568 */
569 void addInterceptor(Interceptor interceptor);
570
571 /**
572 * Removes an interceptor.
573 *
574 * @param interceptor interceptor to remove
575 *
576 * @return <code>true</code> if the interceptor is removed from this factory, <code>false</code> else
577 */
578 boolean removeInterceptor(Interceptor interceptor);
579
580 /**
581 * Closes this factory and release all its resources
582 */
583 void close();
584
585 boolean isHA();
586
587 boolean isCompressLargeMessage();
588
589 void setCompressLargeMessage(boolean compress);
590
591 void addClusterTopologyListener(ClusterTopologyListener listener);
592
593 void removeClusterTopologyListener(ClusterTopologyListener listener);
594 }