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