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 }