All Downloads are FREE. Search and download functionalities are using the official Maven repository.

com.rabbitmq.client.Connection Maven / Gradle / Ivy

Go to download

The RabbitMQ Java client library allows Java applications to interface with RabbitMQ.

There is a newer version: 5.22.0
Show newest version
// Copyright (c) 2007-Present Pivotal Software, Inc.  All rights reserved.
//
// This software, the RabbitMQ Java client library, is triple-licensed under the
// Mozilla Public License 1.1 ("MPL"), the GNU General Public License version 2
// ("GPL") and the Apache License version 2 ("ASL"). For the MPL, please see
// LICENSE-MPL-RabbitMQ. For the GPL, please see LICENSE-GPL2.  For the ASL,
// please see LICENSE-APACHE2.
//
// This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND,
// either express or implied. See the LICENSE file for specific language governing
// rights and limitations of this software.
//
// If you have any questions regarding licensing, please contact us at
// [email protected].

package com.rabbitmq.client;

import java.io.Closeable;
import java.io.IOException;
import java.net.InetAddress;
import java.util.Map;
import java.util.Optional;
import java.util.concurrent.ExecutorService;

/**
 * Public API: Interface to an AMQ connection. See the see the spec for details.
 * 

* To connect to a broker, fill in a {@link ConnectionFactory} and use a {@link ConnectionFactory} as follows: * *

 * ConnectionFactory factory = new ConnectionFactory();
 * factory.setHost(hostName);
 * factory.setPort(portNumber);
 * factory.setVirtualHost(virtualHost);
 * factory.setUsername(username);
 * factory.setPassword(password);
 * Connection conn = factory.newConnection();
 *
 * // Then open a channel:
 *
 * Channel channel = conn.createChannel();
 * 
* Or, more compactly: * *
 * ConnectionFactory factory = new ConnectionFactory();
 * factory.setUri("amqp://username:password@hostName:portNumber/virtualHost");
 * Connection conn = factory.newConnection();
 * Channel channel = conn.createChannel()
 * 
* * Current implementations are thread-safe for code at the client API level, * and in fact thread-safe internally except for code within RPC calls. */ public interface Connection extends ShutdownNotifier, Closeable { // rename to AMQPConnection later, this is a temporary name /** * Retrieve the host. * @return the hostname of the peer we're connected to. */ InetAddress getAddress(); /** * Retrieve the port number. * @return the port number of the peer we're connected to. */ int getPort(); /** * Get the negotiated maximum channel number. Usable channel * numbers range from 1 to this number, inclusive. * * @return the maximum channel number permitted for this connection. */ int getChannelMax(); /** * Get the negotiated maximum frame size. * * @return the maximum frame size, in octets; zero if unlimited */ int getFrameMax(); /** * Get the negotiated heartbeat interval. * * @return the heartbeat interval, in seconds; zero if none */ int getHeartbeat(); /** * Get a copy of the map of client properties sent to the server * * @return a copy of the map of client properties */ Map getClientProperties(); /** * Returns client-provided connection name, if any. Note that the value * returned does not uniquely identify a connection and cannot be used * as a connection identifier in HTTP API requests. * * * * @return client-provided connection name, if any * @see ConnectionFactory#newConnection(Address[], String) * @see ConnectionFactory#newConnection(ExecutorService, Address[], String) */ String getClientProvidedName(); /** * Retrieve the server properties. * @return a map of the server properties. This typically includes the product name and version of the server. */ Map getServerProperties(); /** * Create a new channel, using an internally allocated channel number. * If automatic connection recovery * is enabled, the channel returned by this method will be {@link Recoverable}. *

* Use {@link #openChannel()} if you want to use an {@link Optional} to deal * with a {@null} value. * * @return a new channel descriptor, or null if none is available * @throws IOException if an I/O problem is encountered */ Channel createChannel() throws IOException; /** * Create a new channel, using the specified channel number if possible. *

* Use {@link #openChannel(int)} if you want to use an {@link Optional} to deal * with a {@null} value. * * @param channelNumber the channel number to allocate * @return a new channel descriptor, or null if this channel number is already in use * @throws IOException if an I/O problem is encountered */ Channel createChannel(int channelNumber) throws IOException; /** * Create a new channel wrapped in an {@link Optional}. * The channel number is allocated internally. *

* If automatic connection recovery * is enabled, the channel returned by this method will be {@link Recoverable}. *

* Use {@link #createChannel()} to return directly a {@link Channel} or {@code null}. * * @return an {@link Optional} containing the channel; * never {@code null} but potentially empty if no channel is available * @throws IOException if an I/O problem is encountered * @see #createChannel() * @since 5.6.0 */ default Optional openChannel() throws IOException { return Optional.ofNullable(createChannel()); } /** * Create a new channel, using the specified channel number if possible. *

* Use {@link #createChannel(int)} to return directly a {@link Channel} or {@code null}. * * @param channelNumber the channel number to allocate * @return an {@link Optional} containing the channel, * never {@code null} but potentially empty if this channel number is already in use * @throws IOException if an I/O problem is encountered * @see #createChannel(int) * @since 5.6.0 */ default Optional openChannel(int channelNumber) throws IOException { return Optional.ofNullable(createChannel(channelNumber)); } /** * Close this connection and all its channels * with the {@link com.rabbitmq.client.AMQP#REPLY_SUCCESS} close code * and message 'OK'. * * Waits for all the close operations to complete. * * @throws IOException if an I/O problem is encountered */ @Override void close() throws IOException; /** * Close this connection and all its channels. * * Waits for all the close operations to complete. * * @param closeCode the close code (See under "Reply Codes" in the AMQP specification) * @param closeMessage a message indicating the reason for closing the connection * @throws IOException if an I/O problem is encountered */ void close(int closeCode, String closeMessage) throws IOException; /** * Close this connection and all its channels * with the {@link com.rabbitmq.client.AMQP#REPLY_SUCCESS} close code * and message 'OK'. * * This method behaves in a similar way as {@link #close()}, with the only difference * that it waits with a provided timeout for all the close operations to * complete. When timeout is reached the socket is forced to close. * * @param timeout timeout (in milliseconds) for completing all the close-related * operations, use -1 for infinity * @throws IOException if an I/O problem is encountered */ void close(int timeout) throws IOException; /** * Close this connection and all its channels. * * Waits with the given timeout for all the close operations to complete. * When timeout is reached the socket is forced to close. * * @param closeCode the close code (See under "Reply Codes" in the AMQP specification) * @param closeMessage a message indicating the reason for closing the connection * @param timeout timeout (in milliseconds) for completing all the close-related * operations, use -1 for infinity * @throws IOException if an I/O problem is encountered */ void close(int closeCode, String closeMessage, int timeout) throws IOException; /** * Abort this connection and all its channels * with the {@link com.rabbitmq.client.AMQP#REPLY_SUCCESS} close code * and message 'OK'. * * Forces the connection to close. * Any encountered exceptions in the close operations are silently discarded. */ void abort(); /** * Abort this connection and all its channels. * * Forces the connection to close and waits for all the close operations to complete. * Any encountered exceptions in the close operations are silently discarded. * * @param closeCode the close code (See under "Reply Codes" in the AMQP specification) * @param closeMessage a message indicating the reason for closing the connection */ void abort(int closeCode, String closeMessage); /** * Abort this connection and all its channels * with the {@link com.rabbitmq.client.AMQP#REPLY_SUCCESS} close code * and message 'OK'. * * This method behaves in a similar way as {@link #abort()}, with the only difference * that it waits with a provided timeout for all the close operations to * complete. When timeout is reached the socket is forced to close. * * @param timeout timeout (in milliseconds) for completing all the close-related * operations, use -1 for infinity */ void abort(int timeout); /** * Abort this connection and all its channels. * * Forces the connection to close and waits with the given timeout * for all the close operations to complete. When timeout is reached * the socket is forced to close. * Any encountered exceptions in the close operations are silently discarded. * * @param closeCode the close code (See under "Reply Codes" in the AMQP specification) * @param closeMessage a message indicating the reason for closing the connection * @param timeout timeout (in milliseconds) for completing all the close-related * operations, use -1 for infinity */ void abort(int closeCode, String closeMessage, int timeout); /** * Add a {@link BlockedListener}. * @param listener the listener to add */ void addBlockedListener(BlockedListener listener); /** * Add a lambda-based {@link BlockedListener}. * @see BlockedListener * @see BlockedCallback * @see UnblockedCallback * @param blockedCallback the callback when the connection is blocked * @param unblockedCallback the callback when the connection is unblocked * @return the listener that wraps the callback */ BlockedListener addBlockedListener(BlockedCallback blockedCallback, UnblockedCallback unblockedCallback); /** * Remove a {@link BlockedListener}. * @param listener the listener to remove * @return true if the listener was found and removed, * false otherwise */ boolean removeBlockedListener(BlockedListener listener); /** * Remove all {@link BlockedListener}s. */ void clearBlockedListeners(); /** * Get the exception handler. * * @see com.rabbitmq.client.ExceptionHandler */ ExceptionHandler getExceptionHandler(); /** * Returns a unique ID for this connection. * * This ID must be unique, otherwise some services * like the metrics collector won't work properly. * This ID doesn't have to be provided by the client, * services that require it will be assigned automatically * if not set. * * @return unique ID for this connection. */ String getId(); /** * Sets a unique ID for this connection. * * This ID must be unique, otherwise some services * like the metrics collector won't work properly. * This ID doesn't have to be provided by the client, * services that require it will be assigned automatically * if not set. */ void setId(String id); }





© 2015 - 2024 Weber Informatics LLC | Privacy Policy