protonj2-client/src/main/java/org/apache/qpid/protonj2/client/Connection.java

/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.qpid.protonj2.client;

import java.util.Map;
import java.util.concurrent.Future;
import java.util.concurrent.TimeUnit;

import org.apache.qpid.protonj2.client.exceptions.ClientException;
import org.apache.qpid.protonj2.client.exceptions.ClientUnsupportedOperationException;

/**
 * Top level {@link Connection} object that can be used as a stand alone API for sending
 * messages and creating {@link Receiver} instances for message consumption. The Connection
 * API also exposes a {@link Session} based API for more advanced messaging use cases.
 *
 * When a Connection is closed all the resources created by the connection are implicitly closed.
 */
public interface Connection extends AutoCloseable {

    /**
     * @return the {@link Client} instance that holds this {@link Connection}
     */
    Client client();

    /**
     * When a {@link Connection} is created it may not be opened on the remote peer, the future returned
     * from this method allows the caller to await the completion of the Connection open by the remote before
     * proceeding on to other messaging operations.  If the open of the connection fails at the remote an
     * {@link Exception} is thrown from the {@link Future#get()} method when called.
     *
     * @return a {@link Future} that will be completed when the remote opens this {@link Connection}.
     */
    Future<Connection> openFuture();

    /**
     * Requests a close of the {@link Connection} at the remote and waits until the Connection has been
     * fully closed or until the configured {@link ConnectionOptions#closeTimeout()} is exceeded.
     */
    @Override
    void close();

    /**
     * Requests a close of the {@link Connection} at the remote and waits until the Connection has been
     * fully closed or until the configured {@link ConnectionOptions#closeTimeout()} is exceeded.
     *
     * @param error
     *      The {@link ErrorCondition} to transmit to the remote along with the close operation.
     */
    void close(ErrorCondition error);

    /**
     * Requests a close of the {@link Connection} at the remote and returns a {@link Future} that will be
     * completed once the Connection has been fully closed.
     *
     * @return a {@link Future} that will be completed when the remote closes this {@link Connection}.
     */
    Future<Connection> closeAsync();

    /**
     * Requests a close of the {@link Connection} at the remote and returns a {@link Future} that will be
     * completed once the Connection has been fully closed.
     *
     * @param error
     * 		The {@link ErrorCondition} to transmit to the remote along with the close operation.
     *
     * @return a {@link Future} that will be completed when the remote closes this {@link Connection}.
     */
    Future<Connection> closeAsync(ErrorCondition error);

    /**
     * Creates a receiver used to consumer messages from the given node address.  The returned receiver will
     * be configured using default options and will take its timeout configuration values from those specified
     * in the parent {@link Connection}.
     *
     * The returned receiver may not have been opened on the remote when it is returned.  Some methods of the
     * {@link Receiver} can block until the remote fully opens the receiver, the user can wait for the remote
     * to respond to the open request by calling the {@link Receiver#openFuture()} method and using the
     * {@link Future#get()} methods to wait for completion.
     *
     * @param address
     *            The source address to attach the consumer to.
     *
     * @return the consumer.
     *
     * @throws ClientException if an internal error occurs.
     */
    Receiver openReceiver(String address) throws ClientException;

    /**
     * Creates a receiver used to consumer messages from the given node address.  The returned receiver
     * will be configured using the options provided in the given {@link ReceiverOptions} instance.
     *
     * The returned receiver may not have been opened on the remote when it is returned.  Some methods of the
     * {@link Receiver} can block until the remote fully opens the receiver, the user can wait for the remote
     * to respond to the open request by calling the {@link Receiver#openFuture()} method and using the
     * {@link Future#get()} methods to wait for completion.
     *
     * @param address
     *            The source address to attach the consumer to.
     * @param receiverOptions
     *            The options for this receiver.
     *
     * @return the newly created {@link Receiver} instance.
     *
     * @throws ClientException if an internal error occurs.
     */
    Receiver openReceiver(String address, ReceiverOptions receiverOptions) throws ClientException;

    /**
     * Creates a receiver used to consume messages from the given node address and configure it
     * such that the remote create a durable node.  The returned receiver will be configured using
     * default options and will take its timeout configuration values from those specified in the
     * parent {@link Connection}.
     *
     * The returned receiver may not have been opened on the remote when it is returned.  Some methods of the
     * {@link Receiver} can block until the remote fully opens the receiver, the user can wait for the remote
     * to respond to the open request by calling the {@link Receiver#openFuture()} method and using the
     * {@link Future#get()} methods to wait for completion.
     *
     * @param address
     * 			The source address to attach the consumer to.
     * @param subscriptionName
     * 			The name to give the subscription (link name).
     *
     * @return the newly created {@link Receiver} instance.
     *
     * @throws ClientException if an internal error occurs.
     */
    Receiver openDurableReceiver(String address, String subscriptionName) throws ClientException;

    /**
     * Creates a receiver used to consume messages from the given node address and configure it
     * such that the remote create a durable node.  The returned receiver will be configured using
     * provided options.
     *
     * The returned receiver may not have been opened on the remote when it is returned.  Some methods of the
     * {@link Receiver} can block until the remote fully opens the receiver, the user can wait for the remote
     * to respond to the open request by calling the {@link Receiver#openFuture()} method and using the
     * {@link Future#get()} methods to wait for completion.
     *
     * @param address
     *            The source address to attach the consumer to.
     * @param subscriptionName
     * 			The name to give the subscription (link name).
     * @param receiverOptions
     *            The options for this receiver.
     *
     * @return the newly created {@link Receiver} instance.
     *
     * @throws ClientException if an internal error occurs.
     */
    Receiver openDurableReceiver(String address, String subscriptionName, ReceiverOptions receiverOptions) throws ClientException;

    /**
     * Creates a dynamic receiver used to consume messages from the given node address.  The returned receiver
     * will be configured using default options and will take its timeout configuration values from those
     * specified in the parent {@link Connection}.
     *
     * The returned receiver may not have been opened on the remote when it is returned.  Some methods of the
     * {@link Receiver} can block until the remote fully opens the receiver, the user can wait for the remote
     * to respond to the open request by calling the {@link Receiver#openFuture()} method and using the
     * {@link Future#get()} methods to wait for completion.
     *
     * @return the newly created {@link Receiver} instance.
     *
     * @throws ClientException if an internal error occurs.
     */
    Receiver openDynamicReceiver() throws ClientException;

    /**
     * Creates a dynamic receiver used to consume messages from a dynamically generated node on the remote..
     *
     * The returned receiver may not have been opened on the remote when it is returned.  Some methods of the
     * {@link Receiver} can block until the remote fully opens the receiver, the user can wait for the remote
     * to respond to the open request by calling the {@link Receiver#openFuture()} method and using the
     * {@link Future#get()} methods to wait for completion.
     *
     * @param dynamicNodeProperties
     * 		The dynamic node properties to be applied to the node created by the remote.
     *
     * @return the newly created {@link Receiver} instance.
     *
     * @throws ClientException if an internal error occurs.
     */
    Receiver openDynamicReceiver(Map<String, Object> dynamicNodeProperties) throws ClientException;

    /**
     * Creates a dynamic receiver used to consume messages from a dynamically generated node on the remote..
     *
     * The returned receiver may not have been opened on the remote when it is returned.  Some methods of the
     * {@link Receiver} can block until the remote fully opens the receiver, the user can wait for the remote
     * to respond to the open request by calling the {@link Receiver#openFuture()} method and using the
     * {@link Future#get()} methods to wait for completion.
     *
     * @param receiverOptions
     * 		The options for this receiver.
     *
     * @return the newly created {@link Receiver} instance.
     *
     * @throws ClientException if an internal error occurs.
     */
    Receiver openDynamicReceiver(ReceiverOptions receiverOptions) throws ClientException;

    /**
     * Creates a dynamic receiver used to consume messages from the given node address.
     *
     * The returned receiver may not have been opened on the remote when it is returned.  Some methods of the
     * {@link Receiver} can block until the remote fully opens the receiver, the user can wait for the remote
     * to respond to the open request by calling the {@link Receiver#openFuture()} method and using the
     * {@link Future#get()} methods to wait for completion.
     *
     * @param dynamicNodeProperties
     * 		The dynamic node properties to be applied to the node created by the remote.
     * @param receiverOptions
     *      The options for this receiver.
     *
     * @return the newly created {@link Receiver} instance.
     *
     * @throws ClientException if an internal error occurs.
     */
    Receiver openDynamicReceiver(Map<String, Object> dynamicNodeProperties, ReceiverOptions receiverOptions) throws ClientException;

    /**
     * Creates a streaming message receiver used to consume large messages from the given node address.  The
     * returned {@link StreamReceiver} will be configured using default options and will take its timeout
     * configuration values from those specified in the parent {@link Connection}.
     *
     * The returned stream receiver may not have been opened on the remote when it is returned.  Some methods of
     * the {@link StreamReceiver} can block until the remote fully opens the receiver link, the user can wait for
     * the remote to respond to the open request by calling the {@link StreamReceiver#openFuture()} method and using
     * the {@link Future#get()} methods to wait for completion.
     *
     * @param address
     *            The source address to attach the consumer to.
     *
     * @return the newly created {@link StreamReceiver} instance.
     *
     * @throws ClientException if an internal error occurs.
     */
    StreamReceiver openStreamReceiver(String address) throws ClientException;

    /**
     * Creates a streaming message receiver used to consume large messages from the given node address.  The
     * returned receiver will be configured using the options provided in the given {@link ReceiverOptions}
     * instance.
     *
     * The returned {@link StreamReceiver} may not have been opened on the remote when it is returned.  Some
     * methods of the {@link StreamReceiver} can block until the remote fully opens the receiver link, the user
     * can wait for the remote to respond to the open request by calling the {@link StreamReceiver#openFuture()}
     * method and using the {@link Future#get()} methods to wait for completion.
     *
     * @param address
     *            The source address to attach the consumer to.
     * @param receiverOptions
     *            The options for this receiver.
     *
     * @return the newly created {@link StreamReceiver} instance.
     *
     * @throws ClientException if an internal error occurs.
     */
    StreamReceiver openStreamReceiver(String address, StreamReceiverOptions receiverOptions) throws ClientException;

    /**
     * Returns the default anonymous sender used by this {@link Connection} for {@link #send(Message)}
     * calls.  If the sender has not been created yet this call will initiate its creation and open with
     * the remote peer.
     *
     * @return the sender.
     *
     * @throws ClientException if an internal error occurs opening the default sender.
     * @throws ClientUnsupportedOperationException if the remote did not signal support for anonymous relays.
     */
    Sender defaultSender() throws ClientException;

    /**
     * Creates a sender used to send messages to the given node address.  The returned sender will
     * be configured using default options and will take its timeout configuration values from those
     * specified in the parent {@link Connection}.
     *
     * The returned {@link Sender} may not have been opened on the remote when it is returned.  Some methods
     * of the {@link Sender} can block until the remote fully opens the sender, the user can wait for the
     * remote to respond to the open request by calling the {@link Sender#openFuture()} method and using the
     * {@link Future#get()} methods to wait for completion.
     *
     * @param address
     *            The target address to attach to, cannot be null.
     *
     * @return the sender.
     *
     * @throws ClientException if an internal error occurs.
     */
    Sender openSender(String address) throws ClientException;

    /**
     * Creates a sender used to send messages to the given node address.
     *
     * The returned {@link Sender} may not have been opened on the remote when it is returned.  Some methods
     * of the {@link Sender} can block until the remote fully opens the sender, the user can wait for the
     * remote to respond to the open request by calling the {@link Sender#openFuture()} method and using the
     * {@link Future#get()} methods to wait for completion.
     *
     * @param address
     *            The target address to attach to, cannot be null.
     * @param senderOptions
     *            The options for this sender.
     *
     * @return the sender.
     *
     * @throws ClientException if an internal error occurs.
     */
    Sender openSender(String address, SenderOptions senderOptions) throws ClientException;

    /**
     * Creates a stream sender used to send large messages to the given node address.  The returned sender will
     * be configured using default options and will take its timeout configuration values from those
     * specified in the parent {@link Connection}.
     *
     * The returned {@link StreamSender} may not have been opened on the remote when it is returned.  Some methods
     * of the {@link StreamSender} can block until the remote fully opens the sender, the user can wait for the
     * remote to respond to the open request by calling the {@link StreamSender#openFuture()} method and using the
     * {@link Future#get()} methods to wait for completion.
     *
     * @param address
     *            The target address to attach to, cannot be null.
     *
     * @return the stream sender.
     *
     * @throws ClientException if an internal error occurs.
     */
    StreamSender openStreamSender(String address) throws ClientException;

    /**
     * Creates a streaming sender used to send large messages to the given node address.
     * <p>
     * The returned {@link StreamSender} may not have been opened on the remote when it is returned.  Some methods
     * of the {@link StreamSender} can block until the remote fully opens the sender, the user can wait for the
     * remote to respond to the open request by calling the {@link StreamSender#openFuture()} method and using the
     * {@link Future#get()} methods to wait for completion.
     *
     * @param address
     *            The target address to attach to, cannot be null.
     * @param senderOptions
     *            The options for this sender.
     *
     * @return the sender.
     *
     * @throws ClientException if an internal error occurs.
     */
    StreamSender openStreamSender(String address, StreamSenderOptions senderOptions) throws ClientException;

    /**
     * Creates a sender that is established to the 'anonymous relay' and as such each message
     * that is sent using this sender must specify an address in its destination address field.
     * The returned sender will be configured using default options and will take its timeout
     * configuration values from those specified in the parent {@link Connection}.
     *
     * The returned {@link Sender} may not have been opened on the remote when it is returned.  Some methods
     * of the {@link Sender} can block until the remote fully opens the sender, the user can wait for the
     * remote to respond to the open request by calling the {@link Sender#openFuture()} method and using the
     * {@link Future#get()} methods to wait for completion.
     *
     * @return the sender.
     *
     * @throws ClientException if an internal error occurs.
     * @throws ClientUnsupportedOperationException if the remote did not signal support for anonymous relays.
     */
    Sender openAnonymousSender() throws ClientException;

    /**
     * Creates a sender that is established to the 'anonymous relay' and as such each
     * message that is sent using this sender must specify an address in its destination
     * address field.
     *
     * The returned {@link Sender} may not have been opened on the remote when it is returned.  Some methods
     * of the {@link Sender} can block until the remote fully opens the sender, the user can wait for the
     * remote to respond to the open request by calling the {@link Sender#openFuture()} method and using the
     * {@link Future#get()} methods to wait for completion.
     *
     * @param senderOptions
     *            The options for this sender.
     *
     * @return the sender.
     *
     * @throws ClientException if an internal error occurs.
     * @throws ClientUnsupportedOperationException if the remote did not signal support for anonymous relays.
     */
    Sender openAnonymousSender(SenderOptions senderOptions) throws ClientException;

    /**
     * Returns the default {@link Session} instance that is used by this Connection to
     * create the default anonymous connection {@link Sender} as well as creating those
     * resources created from the {@link Connection} such as {@link Sender} and {@link Receiver}
     * instances not married to a specific {@link Session}.
     *
     * @return a new {@link Session} instance.
     *
     * @throws ClientException if an internal error occurs.
     */
    Session defaultSession() throws ClientException;

    /**
     * Creates a new {@link Session} instance for use by the client application.  The returned session
     * will be configured using default options and will take its timeout configuration values from those
     * specified in the parent {@link Connection}.
     *
     * The returned {@link Session} may not have been opened on the remote when it is returned.  Some methods
     * of the {@link Session} can block until the remote fully opens the session, the user can wait for the
     * remote to respond to the open request by calling the {@link Session#openFuture()} method and using the
     * {@link Future#get()} methods to wait for completion.
     *
     * @return a new {@link Session} instance.
     *
     * @throws ClientException if an internal error occurs.
     */
    Session openSession() throws ClientException;

    /**
     * Creates a new {@link Session} instance for use by the client application.
     *
     * The returned {@link Session} may not have been opened on the remote when it is returned.  Some methods
     * of the {@link Session} can block until the remote fully opens the session, the user can wait for the
     * remote to respond to the open request by calling the {@link Session#openFuture()} method and using the
     * {@link Future#get()} methods to wait for completion.
     *
     * @param options
     *      The {@link SessionOptions} that control properties of the created session.
     *
     * @return a new {@link Session} instance.
     *
     * @throws ClientException if an internal error occurs.
     */
    Session openSession(SessionOptions options) throws ClientException;

    /**
     * Sends the given {@link Message} using the internal connection sender.
     * <p>
     * The connection {@link Sender} is an anonymous AMQP sender which requires that the
     * given message has a valid to value set.
     *
     * @param message
     * 		The message to send
     *
     * @return a {@link Tracker} that allows the client to track settlement of the message.
     *
     * @throws ClientException if an internal error occurs.
     */
    Tracker send(Message<?> message) throws ClientException;

    /**
     * Waits indefinitely for a receiver created from the connection default session to have a
     * delivery ready for receipt. The selection of the next receiver when more than one exists
     * which has pending deliveries is based upon the configured value of the
     * {@link ConnectionOptions#defaultNextReceiverPolicy()}.
     *
     * @return the next receiver that has a pending delivery available based on policy.
     *
     * @throws ClientException if an internal error occurs.
     */
    Receiver nextReceiver() throws ClientException;

    /**
     * Waits indefinitely for a receiver created from the connection default session to have a
     * delivery ready for receipt. The selection of the next receiver when more than one exists
     * which has pending deliveries is based upon the value of the {@link NextReceiverPolicy}
     * that is provided by the caller.
     *
     * @param policy
     *      The policy to apply when selecting the next receiver.
     *
     * @return the next receiver that has a pending delivery available based on policy.
     *
     * @throws ClientException if an internal error occurs.
     */
    Receiver nextReceiver(NextReceiverPolicy policy) throws ClientException;

    /**
     * Waits for the configured time interval for a receiver created from the connection default
     * session to have a delivery ready for receipt. The selection of the next receiver when more
     * than one exists which has pending deliveries is based upon the configured value of the
     * {@link ConnectionOptions#defaultNextReceiverPolicy()}. If no receiver has an incoming delivery
     * before the given timeout expires the method returns null.
     *
     * @param timeout
     *      The timeout value used to control how long the method waits for a new {@link Delivery} to be available.
     * @param unit
     *      The unit of time that the given timeout represents.
     *
     * @return the next receiver that has a pending delivery available based on policy or null if the timeout is reached.
     *
     * @throws ClientException if an internal error occurs.
     */
    Receiver nextReceiver(long timeout, TimeUnit unit) throws ClientException;

    /**
     * Waits for the configured time interval for a receiver created from the connection default
     * session to have a delivery ready for receipt. The selection of the next receiver when more
     * than one exists which has pending deliveries is based upon the {@link NextReceiverPolicy}
     * provided by the caller. If no receiver has an incoming delivery before the given timeout
     * expires the method returns null.
     *
     * @param policy
     *      The policy to apply when selecting the next receiver.
     * @param timeout
     *      The timeout value used to control how long the method waits for a new {@link Delivery} to be available.
     * @param unit
     *      The unit of time that the given timeout represents.
     *
     * @return the next receiver that has a pending delivery available based on policy or null if the timeout is reached.
     *
     * @throws ClientException if an internal error occurs.
     */
    Receiver nextReceiver(NextReceiverPolicy policy, long timeout, TimeUnit unit) throws ClientException;

    /**
     * Returns the properties that the remote provided upon successfully opening the {@link Connection}.  If the
     * open has not completed yet this method will block to await the open response which carries the remote
     * properties.  If the remote provides no properties this method will return null.
     *
     * @return any properties provided from the remote once the connection has successfully opened.
     *
     * @throws ClientException if an error occurs while obtaining the {@link Connection} remote properties.
     */
    Map<String, Object> properties() throws ClientException;

    /**
     * Returns the offered capabilities that the remote provided upon successfully opening the {@link Connection}.
     * If the open has not completed yet this method will block to await the open response which carries the
     * remote offered capabilities.  If the remote provides no capabilities this method will return null.
     *
     * @return any capabilities provided from the remote once the connection has successfully opened.
     *
     * @throws ClientException if an error occurs while obtaining the {@link Connection} remote offered capabilities.
     */
    String[] offeredCapabilities() throws ClientException;

    /**
     * Returns the desired capabilities that the remote provided upon successfully opening the {@link Connection}.
     * If the open has not completed yet this method will block to await the open response which carries the
     * remote desired capabilities.  If the remote provides no capabilities this method will return null.
     *
     * @return any desired capabilities provided from the remote once the connection has successfully opened.
     *
     * @throws ClientException if an error occurs while obtaining the {@link Connection} remote desired capabilities.
     */
    String[] desiredCapabilities() throws ClientException;

}