001    /*
002     * Copyright 2009 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 java.util.List;
017    
018    import org.hornetq.api.core.HornetQException;
019    import org.hornetq.api.core.Interceptor;
020    import org.hornetq.api.core.Pair;
021    import org.hornetq.api.core.TransportConfiguration;
022    import org.hornetq.api.core.client.loadbalance.ConnectionLoadBalancingPolicy;
023    
024    /**
025     * A ClientSessionFactory is the entry point to create and configure HornetQ resources to produce and consume messages.
026     * <br>
027     * It is possible to configure a factory using the setter methods only if no session has been created.
028     * Once a session is created, the configuration is fixed and any call to a setter method will throw a IllegalStateException.
029     * 
030     * @author <a href="mailto:tim.fox@jboss.com">Tim Fox</a>
031     */
032    public interface ClientSessionFactory
033    {
034       /**
035        * Creates a session with XA transaction semantics.
036        * 
037        * @return a ClientSession with XA transaction semantics
038        * 
039        * @throws HornetQException if an exception occurs while creating the session
040        */
041       ClientSession createXASession() throws HornetQException;
042    
043       /**
044        * Creates a <em>transacted</em> session.
045        * 
046        * It is up to the client to commit when sending and acknowledging messages.
047    
048        * @return a transacted ClientSession
049        * @throws HornetQException if an exception occurs while creating the session
050        * 
051        * @see ClientSession#commit()
052        */
053       ClientSession createTransactedSession() throws HornetQException;
054    
055    
056       /**
057        * Creates a <em>non-transacted</em> session.
058        * Message sends and acknowledgements are automatically committed by the session. <em>This does not
059        * mean that messages are automatically acknowledged</em>, only that when messages are acknowledged, 
060        * the session will automatically commit the transaction containing the acknowledgements.
061    
062        * @return a non-transacted ClientSession
063        * @throws HornetQException if an exception occurs while creating the session
064        */
065       ClientSession createSession() throws HornetQException;
066    
067       /**
068        * Creates a session.
069        * 
070        * @param autoCommitSends <code>true</code> to automatically commit message sends, <code>false</code> to commit manually
071        * @param autoCommitAcks <code>true</code> to automatically commit message acknowledgement, <code>false</code> to commit manually
072        * @return a ClientSession
073        * @throws HornetQException if an exception occurs while creating the session
074        */
075       ClientSession createSession(boolean autoCommitSends, boolean autoCommitAcks) throws HornetQException;
076    
077       /**
078        * Creates a session.
079        * 
080        * @param autoCommitSends <code>true</code> to automatically commit message sends, <code>false</code> to commit manually
081        * @param autoCommitAcks <code>true</code> to automatically commit message acknowledgement, <code>false</code> to commit manually
082        * @param ackBatchSize the batch size of the acknowledgements
083        * @return a ClientSession
084        * @throws HornetQException if an exception occurs while creating the session
085        */
086       ClientSession createSession(boolean autoCommitSends, boolean autoCommitAcks, int ackBatchSize) throws HornetQException;
087    
088       /**
089        * Creates a session.
090        * 
091        * @param xa whether the session support XA transaction semantic or not
092        * @param autoCommitSends <code>true</code> to automatically commit message sends, <code>false</code> to commit manually
093        * @param autoCommitAcks <code>true</code> to automatically commit message acknowledgement, <code>false</code> to commit manually
094        * @return a ClientSession
095        * @throws HornetQException if an exception occurs while creating the session
096        */
097       ClientSession createSession(boolean xa, boolean autoCommitSends, boolean autoCommitAcks) throws HornetQException;
098    
099       /**
100        * Creates a session.
101        * 
102        * It is possible to <em>pre-acknowledge messages on the server</em> so that the client can avoid additional network trip
103        * to the server to acknowledge messages. While this increase performance, this does not guarantee delivery (as messages
104        * can be lost after being pre-acknowledged on the server). Use with caution if your application design permits it.
105        * 
106        * @param xa whether the session support XA transaction semantic or not
107        * @param autoCommitSends <code>true</code> to automatically commit message sends, <code>false</code> to commit manually
108        * @param autoCommitAcks <code>true</code> to automatically commit message acknowledgement, <code>false</code> to commit manually
109        * @param preAcknowledge <code>true</code> to pre-acknowledge messages on the server, <code>false</code> to let the client acknowledge the messages
110        * @return a ClientSession
111        * @throws HornetQException if an exception occurs while creating the session
112        */
113       ClientSession createSession(boolean xa, boolean autoCommitSends, boolean autoCommitAcks, boolean preAcknowledge) throws HornetQException;
114    
115       /**
116        * Creates an <em>authenticated</em> session.
117        * 
118        * It is possible to <em>pre-acknowledge messages on the server</em> so that the client can avoid additional network trip
119        * to the server to acknowledge messages. While this increase performance, this does not guarantee delivery (as messages
120        * can be lost after being pre-acknowledged on the server). Use with caution if your application design permits it.
121        * 
122        * @param username the user name
123        * @param password the user password
124        * @param xa whether the session support XA transaction semantic or not
125        * @param autoCommitSends <code>true</code> to automatically commit message sends, <code>false</code> to commit manually
126        * @param autoCommitAcks <code>true</code> to automatically commit message acknowledgement, <code>false</code> to commit manually
127        * @param preAcknowledge <code>true</code> to pre-acknowledge messages on the server, <code>false</code> to let the client acknowledge the messages
128        * @return a ClientSession
129        * @throws HornetQException if an exception occurs while creating the session
130        */
131       ClientSession createSession(String username,
132                                   String password,
133                                   boolean xa,
134                                   boolean autoCommitSends,
135                                   boolean autoCommitAcks,
136                                   boolean preAcknowledge,
137                                   int ackBatchSize) throws HornetQException;
138    
139       /**
140        * Returns the list of <em>live - backup</em> connectors pairs configured 
141        * that sessions created by this factory will use to connect
142        * to HornetQ servers or <code>null</code> if the factory is using discovery group.
143        * 
144        * The backup configuration (returned by {@link org.hornetq.api.core.Pair#b}) can be <code>null</code> if there is no
145        * backup for the corresponding live configuration (returned by {@link org.hornetq.api.core.Pair#a})
146        * 
147        * @return a list of pair of TransportConfiguration corresponding to the live - backup nodes
148        */
149       List<Pair<TransportConfiguration, TransportConfiguration>> getStaticConnectors();
150    
151       /**
152        * Sets the static list of live - backup connectors pairs that sessions created by this factory will use to connect
153        * to HornetQ servers.
154        * 
155        * The backup configuration (returned by {@link Pair#b}) can be <code>null</code> if there is no
156        * backup for the corresponding live configuration (returned by {@link Pair#a})
157        * 
158        * @param staticConnectors a list of pair of TransportConfiguration corresponding to the live - backup nodes
159        */
160       void setStaticConnectors(List<Pair<TransportConfiguration, TransportConfiguration>> staticConnectors);
161    
162       /**
163        * Returns the period used to check if a client has failed to receive pings from the server.
164        *   
165        * Period is in milliseconds, default value is {@link HornetQClient#DEFAULT_CLIENT_FAILURE_CHECK_PERIOD}.
166        * 
167        * @return the period used to check if a client has failed to receive pings from the server
168        */
169       long getClientFailureCheckPeriod();
170    
171       /**
172        * Sets the period (in milliseconds) used to check if a client has failed to receive pings from the server.
173        * 
174        * Value must be -1 (to disable) or greater than 0.
175        * 
176        * @param clientFailureCheckPeriod the period to check failure
177        */
178       void setClientFailureCheckPeriod(long clientFailureCheckPeriod);
179    
180       /**
181        * When <code>true</code>, consumers created through this factory will create temporary files to cache large messages.
182        * 
183        * There is 1 temporary file created for each large message.
184        * 
185        * Default value is {@link HornetQClient#DEFAULT_CACHE_LARGE_MESSAGE_CLIENT}.
186        * 
187        * @return <code>true</code> if consumers created through this factory will cache large messages in temporary files, <code>false</code> else
188        */
189       boolean isCacheLargeMessagesClient();
190    
191       /**
192        * Sets whether large messages received by consumers created through this factory will be cached in temporary files or not.
193        * 
194        * @param cached <code>true</code> to cache large messages in temporary files, <code>false</code> else
195        */
196       void setCacheLargeMessagesClient(boolean cached);
197    
198       /**
199        * Returns the connection <em>time-to-live</em>.
200        * This TTL determines how long the server will keep a connection alive in the absence of any data arriving from the client.
201        * 
202        * Value is in milliseconds, default value is {@link HornetQClient#DEFAULT_CONNECTION_TTL}.
203        * 
204        * @return the connection time-to-live in milliseconds
205        */
206       long getConnectionTTL();
207    
208       /**
209        * Sets this factory's connections <em>time-to-live</em>.
210        * 
211        * Value must be -1 (to disable) or greater or equals to 0.
212        * 
213        * @param connectionTTL period in milliseconds
214        */
215       void setConnectionTTL(long connectionTTL);
216    
217       /**
218        * Returns the blocking calls timeout.
219        * 
220        * 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}.
221        * Value is in milliseconds, default value is {@link HornetQClient#DEFAULT_CALL_TIMEOUT}.
222        * 
223        * @return the blocking calls timeout
224        */
225       long getCallTimeout();
226    
227       /**
228        * Sets the blocking call timeout.
229        * 
230        * Value must be greater or equals to 0
231        * 
232        * @param callTimeout blocking call timeout in milliseconds
233        */
234       void setCallTimeout(long callTimeout);
235    
236       /**
237        * Returns the large message size threshold.
238        * 
239        * Messages whose size is if greater than this value will be handled as <em>large messages</em>.
240        * 
241        * Value is in bytes, default value is {@link HornetQClient#DEFAULT_MIN_LARGE_MESSAGE_SIZE}.
242        * 
243        * @return the message size threshold to treat messages as large messages.
244        */
245       int getMinLargeMessageSize();
246    
247       /**
248        * Sets the large message size threshold.
249        * 
250        * Value must be greater than 0.
251        * 
252        * @param minLargeMessageSize large message size threshold in bytes
253        */
254       void setMinLargeMessageSize(int minLargeMessageSize);
255    
256       /**
257        * Returns the window size for flow control of the consumers created through this factory.
258        * 
259        * Value is in bytes, default value is {@link HornetQClient#DEFAULT_CONSUMER_WINDOW_SIZE}.
260        * 
261        * @return the window size used for consumer flow control
262        */
263       int getConsumerWindowSize();
264    
265       /**
266        * Sets the window size for flow control of the consumers created through this factory.
267        * 
268        * 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)
269        *
270        * @param consumerWindowSize window size (in bytes) used for consumer flow control
271        */
272       void setConsumerWindowSize(int consumerWindowSize);
273    
274       /**
275        * Returns the maximum rate of message consumption for consumers created through this factory.
276        * 
277        * 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.
278        * 
279        * Value is -1 (to disable) or a positive integer corresponding to the maximum desired message consumption rate specified in units of messages per second.
280        * Default value is {@link HornetQClient#DEFAULT_CONSUMER_MAX_RATE}.
281        * 
282        * @return the consumer max rate
283        */
284       int getConsumerMaxRate();
285    
286       /**
287        * Sets the maximum rate of message consumption for consumers created through this factory.
288        * 
289        * Value must -1 (to disable) or a positive integer corresponding to the maximum desired message consumption rate specified in units of messages per second.
290        * 
291        * @param consumerMaxRate maximum rate of message consumption (in messages per seconds)
292        */
293       void setConsumerMaxRate(int consumerMaxRate);
294    
295       /**
296        * Returns the size for the confirmation window of clients using this factory.
297        * 
298        * Value is in bytes or -1 (to disable the window). Default value is {@link HornetQClient#DEFAULT_CONFIRMATION_WINDOW_SIZE}.
299        * 
300        * @return the size for the confirmation window of clients using this factory
301        */
302       int getConfirmationWindowSize();
303    
304       /**
305        * Sets the size for the confirmation window buffer of clients using this factory.
306        * 
307        * Value must be -1 (to disable the window) or greater than 0.
308    
309        * @param confirmationWindowSize size of the confirmation window (in bytes)
310        */
311       void setConfirmationWindowSize(int confirmationWindowSize);
312    
313       /**
314        * Returns the window size for flow control of the producers created through this factory.
315        * 
316        * 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).
317        * Default value is {@link HornetQClient#DEFAULT_PRODUCER_WINDOW_SIZE}.
318        * 
319        * @return the window size for flow control of the producers created through this factory.
320        */
321       int getProducerWindowSize();
322    
323       /**
324        * Returns the window size for flow control of the producers created through this factory.
325        * 
326        * Value must be -1 (to disable flow control) or greater than 0.
327        * 
328        * @param producerWindowSize window size (in bytest) for flow control of the producers created through this factory.
329        */
330       void setProducerWindowSize(int producerWindowSize);
331    
332       /**
333        * Returns the maximum rate of message production for producers created through this factory.
334        * 
335        * 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.
336        * 
337        * Value is -1 (to disable) or a positive integer corresponding to the maximum desired message production rate specified in units of messages per second.
338        * Default value is {@link HornetQClient#DEFAULT_PRODUCER_MAX_RATE}.
339        * 
340        * @return  maximum rate of message production (in messages per seconds)
341        */
342       int getProducerMaxRate();
343    
344       /**
345        * Sets the maximum rate of message production for producers created through this factory.
346        * 
347        * Value must -1 (to disable) or a positive integer corresponding to the maximum desired message production rate specified in units of messages per second.
348        * 
349        * @param producerMaxRate maximum rate of message production (in messages per seconds)
350        */
351       void setProducerMaxRate(int producerMaxRate);
352    
353       /**
354        * Returns whether consumers created through this factory will block while sending message acknowledgements or do it asynchronously.
355        * 
356        * Default value is {@link HornetQClient#DEFAULT_BLOCK_ON_ACKNOWLEDGE}.
357        * 
358        * @return whether consumers will block while sending message acknowledgements or do it asynchronously
359        */
360       boolean isBlockOnAcknowledge();
361    
362       /**
363        * Sets whether consumers created through this factory will block while sending message acknowledgements or do it asynchronously.
364        *
365        * @param blockOnAcknowledge <code>true</code> to block when sending message acknowledgements or <code>false</code> to send them asynchronously
366        */
367       void setBlockOnAcknowledge(boolean blockOnAcknowledge);
368    
369       /**
370        * Returns whether producers created through this factory will block while sending <em>durable</em> messages or do it asynchronously.
371        * <br>
372        * If the session is configured to send durable message asynchronously, the client can set a SendAcknowledgementHandler on the ClientSession
373        * to be notified once the message has been handled by the server.
374        * 
375        * Default value is {@link HornetQClient#DEFAULT_BLOCK_ON_DURABLE_SEND}.
376        *
377        * @return whether producers will block while sending persistent messages or do it asynchronously
378        */
379       boolean isBlockOnDurableSend();
380    
381       /**
382        * Sets whether producers created through this factory will block while sending <em>durable</em> messages or do it asynchronously.
383        * 
384        * @param blockOnDurableSend <code>true</code> to block when sending durable messages or <code>false</code> to send them asynchronously
385        */
386       void setBlockOnDurableSend(boolean blockOnDurableSend);
387    
388       /**
389        * Returns whether producers created through this factory will block while sending <em>non-durable</em> messages or do it asynchronously.
390        * <br>
391        * If the session is configured to send non-durable message asynchronously, the client can set a SendAcknowledgementHandler on the ClientSession
392        * to be notified once the message has been handled by the server.
393        * 
394        * Default value is {@link HornetQClient#DEFAULT_BLOCK_ON_NON_DURABLE_SEND}.
395        *
396        * @return whether producers will block while sending non-durable messages or do it asynchronously
397        */
398       boolean isBlockOnNonDurableSend();
399    
400       /**
401        * Sets whether producers created through this factory will block while sending <em>non-durable</em> messages or do it asynchronously.
402        * 
403        * @param blockOnNonDurableSend <code>true</code> to block when sending non-durable messages or <code>false</code> to send them asynchronously
404        */
405       void setBlockOnNonDurableSend(boolean blockOnNonDurableSend);
406    
407       /**
408        * Returns whether producers created through this factory will automatically
409        * assign a group ID to the messages they sent.
410        * 
411        * if <code>true</code>, a random unique group ID is created and set on each message for the property
412        * {@link org.hornetq.api.core.Message#HDR_GROUP_ID}.
413        * Default value is {@link HornetQClient#DEFAULT_AUTO_GROUP}.
414        * 
415        * @return whether producers will automatically assign a group ID to their messages
416        */
417       boolean isAutoGroup();
418    
419       /**
420        * Sets whether producers created through this factory will automatically
421        * assign a group ID to the messages they sent.
422        * 
423        * @param autoGroup <code>true</code> to automatically assign a group ID to each messages sent through this factory, <code>false</code> else
424        */
425       void setAutoGroup(boolean autoGroup);
426    
427       /**
428        * Returns the group ID that will be eventually set on each message for the property {@link org.hornetq.api.core.Message#HDR_GROUP_ID}.
429        * 
430        * Default value is is <code>null</code> and no group ID will be set on the messages.
431        * 
432        * @return the group ID that will be eventually set on each message
433        */
434       String getGroupID();
435       
436       /**
437        * Sets the group ID that will be  set on each message sent through this factory.
438        * 
439        * @param groupID the group ID to use
440        */
441       void setGroupID(String groupID);
442    
443       /**
444        * Returns whether messages will pre-acknowledged on the server before they are sent to the consumers or not.
445        *
446        * Default value is {@link HornetQClient#DEFAULT_PRE_ACKNOWLEDGE}
447        */
448       boolean isPreAcknowledge();
449    
450       /**
451        * 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
452        * clients acknowledge the message they consume.
453        * 
454        * @param preAcknowledge <code>true</code> to enable pre-acknowledgement, <code>false</code> else
455        */
456       void setPreAcknowledge(boolean preAcknowledge);
457    
458       /**
459        * Returns the acknowledgements batch size.
460        * 
461        * Default value is  {@link HornetQClient#DEFAULT_ACK_BATCH_SIZE}.
462        * 
463        * @return the acknowledgements batch size
464        */
465       int getAckBatchSize();
466    
467       /**
468        * Sets the acknowledgements batch size.
469        * 
470        * Value must be equal or greater than 0.
471        * 
472        * @param ackBatchSize acknowledgements batch size
473        */
474       void setAckBatchSize(int ackBatchSize);
475    
476       /**
477        * Returns the local bind address to which the multicast socket is bound for discovery.
478        * 
479        * This is null if the multicast socket is not bound, or no discovery is being used
480        * 
481        * @return the local bind address to which the multicast socket is bound for discovery
482        */
483       String getLocalBindAddress();
484    
485       /**
486        * Sets the local bind address to which the multicast socket is bound for discovery.
487        * 
488        * @param localBindAddress the local bind address
489        */
490       void setLocalBindAddress(String localBindAddress);
491       
492       /**
493        * Returns the address to listen to discover which connectors this factory can use.
494        * The discovery address must be set to enable this factory to discover HornetQ servers.
495        * 
496        * @return the address to listen to discover which connectors this factory can use
497        */
498       String getDiscoveryAddress();
499    
500       /**
501        * Sets the address to listen to discover which connectors this factory can use.
502        * 
503        * @param discoveryAddress address to listen to discover which connectors this factory can use
504        */
505       void setDiscoveryAddress(String discoveryAddress);
506    
507       /**
508        * Returns the port to listen to discover which connectors this factory can use.
509        * The discovery port must be set to enable this factory to discover HornetQ servers.
510        * 
511        * @return the port to listen to discover which connectors this factory can use
512        */   
513       int getDiscoveryPort();
514    
515    
516       /**
517        * Sets the port to listen to discover which connectors this factory can use.
518        * 
519        * @param discoveryPort port to listen to discover which connectors this factory can use
520        */
521       void setDiscoveryPort(int discoveryPort);
522    
523       /**
524        * Returns the refresh timeout for discovered HornetQ servers.
525        * 
526        * If this factory uses discovery to find HornetQ servers, the list of discovered servers
527        * will be refreshed according to this timeout.
528        * 
529        * Value is in milliseconds, default value is {@link HornetQClient#DEFAULT_DISCOVERY_REFRESH_TIMEOUT}.
530        * 
531        * @return the refresh timeout for discovered HornetQ servers
532        */
533       long getDiscoveryRefreshTimeout();
534    
535       /**
536        * Sets the refresh timeout for discovered HornetQ servers.
537        * 
538        * Value must be greater than 0.
539        * 
540        * @param discoveryRefreshTimeout refresh timeout (in milliseconds) for discovered HornetQ servers
541        */
542       void setDiscoveryRefreshTimeout(long discoveryRefreshTimeout);
543    
544       /**
545        * Returns the initial wait timeout if this factory is configured to use discovery.
546        * 
547        * Value is in milliseconds, default value is  {@link HornetQClient#DEFAULT_DISCOVERY_INITIAL_WAIT_TIMEOUT}.
548        * 
549        * @return the initial wait timeout if this factory is configured to use discovery 
550        */
551       long getDiscoveryInitialWaitTimeout();
552    
553       /**
554        * Sets the initial wait timeout if this factory is configured to use discovery.
555        * 
556        * Value is in milliseconds and must be greater than 0.
557        * 
558        * @param initialWaitTimeout initial wait timeout when using discovery 
559        */
560       void setDiscoveryInitialWaitTimeout(long initialWaitTimeout);
561    
562       /**
563        * Returns whether this factory will use global thread pools (shared among all the factories in the same JVM)
564        * or its own pools.
565        * 
566        * Default value is {@link HornetQClient#DEFAULT_USE_GLOBAL_POOLS}.
567        * 
568        * @return <code>true</code> if this factory uses global thread pools, <code>false</code> else
569        */
570       boolean isUseGlobalPools();
571    
572       /**
573        * Sets whether this factory will use global thread pools (shared among all the factories in the same JVM)
574        * or its own pools.
575        * 
576        * @param useGlobalPools <code>true</code> to let this factory uses global thread pools, <code>false</code> else
577        */
578       void setUseGlobalPools(boolean useGlobalPools);
579    
580       /**
581        * Returns the maximum size of the scheduled thread pool.
582        * 
583        * Default value is {@link HornetQClient#DEFAULT_SCHEDULED_THREAD_POOL_MAX_SIZE}.
584        * 
585        * @return the maximum size of the scheduled thread pool.
586        */
587       int getScheduledThreadPoolMaxSize();
588    
589       /**
590        * Sets the maximum size of the scheduled thread pool.
591        * 
592        * This setting is relevant only if this factory does not use global pools.
593        * Value must be greater than 0.
594        * 
595        * @param scheduledThreadPoolMaxSize  maximum size of the scheduled thread pool.
596        */
597       void setScheduledThreadPoolMaxSize(int scheduledThreadPoolMaxSize);
598    
599       /**
600        * Returns the maximum size of the thread pool.
601        * 
602        * Default value is {@link HornetQClient#DEFAULT_THREAD_POOL_MAX_SIZE}.
603        * 
604        * @return the maximum size of the thread pool.
605        */
606       int getThreadPoolMaxSize();
607    
608       /**
609        * Sets the maximum size of the thread pool.
610        * 
611        * This setting is relevant only if this factory does not use global pools.
612        * Value must be -1 (for unlimited thread pool) or greater than 0.
613        * 
614        * @param threadPoolMaxSize  maximum size of the thread pool.
615        */
616       void setThreadPoolMaxSize(int threadPoolMaxSize);
617    
618       /**
619        * Returns the time to retry connections created by this factory after failure. 
620        * 
621        * Value is in milliseconds, default is {@link HornetQClient#DEFAULT_RETRY_INTERVAL}.
622        * 
623        * @return the time to retry connections created by this factory after failure
624        */
625       long getRetryInterval();
626    
627       /**
628        * Sets the time to retry connections created by this factory after failure.
629        * 
630        * Value must be greater than 0.
631        * 
632        * @param retryInterval time (in milliseconds) to retry connections created by this factory after failure 
633        */
634       void setRetryInterval(long retryInterval);
635    
636       /**
637        * Returns the multiplier to apply to successive retry intervals.
638        * 
639        * Default value is  {@link HornetQClient#DEFAULT_RETRY_INTERVAL_MULTIPLIER}.
640        * 
641        * @return the multiplier to apply to successive retry intervals
642        */
643       double getRetryIntervalMultiplier();
644    
645       /**
646        * Sets the multiplier to apply to successive retry intervals.
647        * 
648        * Value must be positive.
649        * 
650        * @param retryIntervalMultiplier multiplier to apply to successive retry intervals
651        */
652       void setRetryIntervalMultiplier(double retryIntervalMultiplier);
653    
654       /**
655        * Returns the maximum retry interval (in the case a retry interval multiplier has been specified).
656        * 
657        * Value is in milliseconds, default value is  {@link HornetQClient#DEFAULT_MAX_RETRY_INTERVAL}.
658        * 
659        * @return the maximum retry interval
660        */
661       long getMaxRetryInterval();
662    
663       /**
664        * Sets the maximum retry interval.
665        * 
666        * Value must be greater than 0.
667        * 
668        * @param maxRetryInterval maximum retry interval to apply in the case a retry interval multiplier has been specified
669        */
670       void setMaxRetryInterval(long maxRetryInterval);
671    
672       /**
673        * Returns the maximum number of attempts to retry connection in case of failure.
674        * 
675        * Default value is {@link HornetQClient#DEFAULT_RECONNECT_ATTEMPTS}.
676        * 
677        * @return the maximum number of attempts to retry connection in case of failure.
678        */
679       int getReconnectAttempts();
680    
681       /**
682        * Sets the maximum number of attempts to retry connection in case of failure.
683        * 
684        * Value must be -1 (to retry infinitely), 0 (to never retry connection) or greater than 0.
685        * 
686        * @param reconnectAttempts maximum number of attempts to retry connection in case of failure
687        */
688       void setReconnectAttempts(int reconnectAttempts);
689       
690       /**
691        * Returns true if the client will automatically attempt to connect to the backup server if the initial
692        * connection to the live server fails
693        * 
694        * Default value is {@link HornetQClient#DEFAULT_FAILOVER_ON_INITIAL_CONNECTION}.
695        */
696       boolean isFailoverOnInitialConnection();
697       
698       /**
699        * Sets the value for FailoverOnInitialReconnection
700        * 
701        * @param failover
702        */
703       void setFailoverOnInitialConnection(boolean failover);
704    
705       /**
706        * Returns whether connections created by this factory must failover in case the server they are
707        * connected to <em>has normally shut down</em>.
708        * 
709        * Default value is {@link HornetQClient#DEFAULT_FAILOVER_ON_SERVER_SHUTDOWN}.
710        * 
711        * @return <code>true</code> if connections must failover if the server has normally shut down, else <code>false</code>
712        */
713       boolean isFailoverOnServerShutdown();
714    
715       /**
716        * Sets whether connections created by this factory must failover in case the server they are
717        * connected to <em>has normally shut down</em>
718        * 
719        * @param failoverOnServerShutdown <code>true</code> if connections must failover if the server has normally shut down, <code>false</code> else
720        */
721       void setFailoverOnServerShutdown(boolean failoverOnServerShutdown);
722    
723       /**
724        * Returns the class name of the connection load balancing policy.
725        * 
726        * Default value is "org.hornetq.api.core.client.loadbalance.RoundRobinConnectionLoadBalancingPolicy".
727        * 
728        * @return the class name of the connection load balancing policy
729        */
730       String getConnectionLoadBalancingPolicyClassName();
731    
732       /**
733        * Sets the class name of the connection load balancing policy.
734        * 
735        * Value must be the name of a class implementing {@link ConnectionLoadBalancingPolicy}.
736        * 
737        * @param loadBalancingPolicyClassName class name of the connection load balancing policy
738        */
739       void setConnectionLoadBalancingPolicyClassName(String loadBalancingPolicyClassName);
740    
741       /**
742        * Returns the initial size of messages created through this factory.
743        * 
744        * Value is in bytes, default value is  {@link HornetQClient#DEFAULT_INITIAL_MESSAGE_PACKET_SIZE}.
745        * 
746        * @return the initial size of messages created through this factory
747        */
748       int getInitialMessagePacketSize();
749    
750       /**
751        * Sets the initial size of messages created through this factory.
752        * 
753        * Value must be greater than 0.
754        * 
755        * @param size initial size of messages created through this factory.
756        */
757       void setInitialMessagePacketSize(int size);
758       
759       /**
760        * Adds an interceptor which will be executed <em>after packets are received from the server</em>.
761        * 
762        * @param interceptor an Interceptor
763        */
764       void addInterceptor(Interceptor interceptor);
765    
766       /**
767        * Removes an interceptor.
768        * 
769        * @param interceptor interceptor to remove
770        * 
771        * @return <code>true</code> if the interceptor is removed from this factory, <code>false</code> else
772        */
773       boolean removeInterceptor(Interceptor interceptor);
774    
775       /**
776        * Closes this factory and release all its resources
777        */
778       void close();
779    
780       /**
781        * Creates a copy of this factory.
782        * 
783        * @return a copy of this factory with the same parameters values
784        */
785       ClientSessionFactory copy();
786    
787    }