    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    }