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    public 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    }