Package org.apache.qpid.protonj2.client.impl

Class ClientStreamReceiver

java.lang.Object

org.apache.qpid.protonj2.client.impl.ClientStreamReceiver

All Implemented Interfaces:

java.lang.AutoCloseable, Receiver, StreamReceiver

public final class ClientStreamReceiver
extends java.lang.Object
implements StreamReceiver

Client implementation of a StreamReceiver.

Method Summary

Modifier and Type	Method	Description
StreamReceiver	addCredit(int credits)	Adds credit to the Receiver link for use when there receiver has not been configured with a credit window.
java.lang.String	address()	Returns the address that the Receiver instance will be subscribed to.
ClientInstance	client()
void	close()	Requests a close of the Receiver at the remote and waits until the Receiver has been fully closed or until the configured ReceiverOptions.closeTimeout() is exceeded.
void	close(ErrorCondition error)	Requests a close of the Receiver at the remote and waits until the Receiver has been fully closed or until the configured ReceiverOptions.closeTimeout() is exceeded.
ClientFuture<Receiver>	closeAsync()	Requests a close of the Receiver link at the remote and returns a Future that will be completed once the link has been closed.
ClientFuture<Receiver>	closeAsync(ErrorCondition error)	Requests a close of the Receiver link at the remote and returns a Future that will be completed once the link has been closed.
ClientConnection	connection()
java.lang.String[]	desiredCapabilities()	Returns the desired capabilities that the remote provided upon successfully opening the Receiver.
void	detach()	Requests a detach of the Receiver at the remote and waits until the Receiver has been fully detached or until the configured SenderOptions.closeTimeout() is exceeded.
void	detach(ErrorCondition error)	Requests a detach of the Receiver at the remote and waits until the Receiver has been fully detached or until the configured SenderOptions.closeTimeout() is exceeded.
ClientFuture<Receiver>	detachAsync()	Requests a detach of the Receiver link at the remote and returns a Future that will be completed once the link has been detached.
ClientFuture<Receiver>	detachAsync(ErrorCondition error)	Requests a detach of the Receiver link at the remote and returns a Future that will be completed once the link has been detached.
java.util.concurrent.Future<Receiver>	drain()	Requests the remote to drain previously granted credit for this Receiver link.
java.lang.String[]	offeredCapabilities()	Returns the offered capabilities that the remote provided upon successfully opening the Receiver.
ClientFuture<Receiver>	openFuture()
java.util.Map<java.lang.String,java.lang.Object>	properties()	Returns the properties that the remote provided upon successfully opening the Receiver.
long	queuedDeliveries()	Returns the number of Deliveries that are currently held in the Receiver delivery queue.
StreamDelivery	receive()	Blocking receive method that waits forever for the remote to provide a StreamReceiverMessage for consumption.
StreamDelivery	receive(long timeout, java.util.concurrent.TimeUnit unit)	Blocking receive method that waits the given time interval for the remote to provide a StreamReceiverMessage for consumption.
ClientSession	session()
Source	source()	Returns an immutable view of the remote Source object assigned to this receiver link.
Target	target()	Returns an immutable view of the remote Target object assigned to this receiver link.
StreamDelivery	tryReceive()	Non-blocking receive method that either returns a message is one is immediately available or returns null if none is currently at hand.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

client

public ClientInstance client()

Specified by:

client in interface Receiver

Returns:

the Client instance that holds this session's Receiver

connection

public ClientConnection connection()

Specified by:

connection in interface Receiver

Returns:

the Connection instance that holds this session's Receiver

session

public ClientSession session()

Specified by:

session in interface Receiver

Returns:

the Session that created and holds this Receiver.

openFuture

public ClientFuture<Receiver> openFuture()

Specified by:

openFuture in interface Receiver

Returns:

a Future that will be completed when the remote opens this Receiver.

close

public void close()

Description copied from interface: Receiver

Requests a close of the Receiver at the remote and waits until the Receiver has been fully closed or until the configured ReceiverOptions.closeTimeout() is exceeded.

Specified by:

close in interface java.lang.AutoCloseable

Specified by:

close in interface Receiver

close

public void close(ErrorCondition error)

Description copied from interface: Receiver

Requests a close of the Receiver at the remote and waits until the Receiver has been fully closed or until the configured ReceiverOptions.closeTimeout() is exceeded.

Specified by:

close in interface Receiver

Parameters:

error - The ErrorCondition to transmit to the remote along with the close operation.

detach

public void detach()

Description copied from interface: Receiver

Requests a detach of the Receiver at the remote and waits until the Receiver has been fully detached or until the configured SenderOptions.closeTimeout() is exceeded.

Specified by:

detach in interface Receiver

detach

public void detach(ErrorCondition error)

Description copied from interface: Receiver

Requests a detach of the Receiver at the remote and waits until the Receiver has been fully detached or until the configured SenderOptions.closeTimeout() is exceeded.

Specified by:

detach in interface Receiver

Parameters:

error - The ErrorCondition to transmit to the remote along with the detach operation.

closeAsync

public ClientFuture<Receiver> closeAsync()

Description copied from interface: Receiver

Requests a close of the Receiver link at the remote and returns a Future that will be completed once the link has been closed.

Specified by:

closeAsync in interface Receiver

Returns:

a Future that will be completed when the remote closes this Receiver link.

closeAsync

public ClientFuture<Receiver> closeAsync(ErrorCondition error)

Description copied from interface: Receiver

Requests a close of the Receiver link at the remote and returns a Future that will be completed once the link has been closed.

Specified by:

closeAsync in interface Receiver

Parameters:

error - The ErrorCondition to transmit to the remote along with the close operation.

Returns:

a Future that will be completed when the remote closes this Receiver link.

detachAsync

public ClientFuture<Receiver> detachAsync()

Description copied from interface: Receiver

Requests a detach of the Receiver link at the remote and returns a Future that will be completed once the link has been detached.

Specified by:

detachAsync in interface Receiver

Returns:

a Future that will be completed when the remote detaches this Receiver link.

detachAsync

public ClientFuture<Receiver> detachAsync(ErrorCondition error)

Description copied from interface: Receiver

Requests a detach of the Receiver link at the remote and returns a Future that will be completed once the link has been detached.

Specified by:

detachAsync in interface Receiver

Parameters:

error - The ErrorCondition to transmit to the remote along with the detach operation.

Returns:

a Future that will be completed when the remote detaches this Receiver link.

receive

public StreamDelivery receive()
                       throws ClientException

Description copied from interface: StreamReceiver

Blocking receive method that waits forever for the remote to provide a StreamReceiverMessage for consumption.

Receive calls will only grant credit on their own if a credit window is configured in the StreamReceiverOptions which is done by default. If the client application has configured no credit window than this method will not grant any credit when it enters the wait for new incoming messages.

Specified by:

receive in interface Receiver

Specified by:

receive in interface StreamReceiver

Returns:

a new Delivery received from the remote.

Throws:

ClientException - if the StreamReceiver or its parent is closed when the call to receive is made.

receive

public StreamDelivery receive(long timeout,
                              java.util.concurrent.TimeUnit unit)
                       throws ClientException

Description copied from interface: StreamReceiver

Blocking receive method that waits the given time interval for the remote to provide a StreamReceiverMessage for consumption. The amount of time this method blocks is based on the timeout value. If timeout is equal to -1 then it blocks until a Delivery is received. If timeout is equal to zero then it will not block and simply return a StreamReceiverMessage if one is available locally. If timeout value is greater than zero then it blocks up to timeout amount of time.

Receive calls will only grant credit on their own if a credit window is configured in the StreamReceiverOptions which is done by default. If the client application has not configured a credit window or granted credit manually this method will not automatically grant any credit when it enters the wait for a new incoming StreamReceiverMessage.

Specified by:

receive in interface Receiver

Specified by:

receive in interface StreamReceiver

Parameters:

timeout - The timeout value used to control how long the receive method waits for a new Delivery.

unit - The unit of time that the given timeout represents.

Returns:

a new StreamReceiverMessage received from the remote.

Throws:

ClientException - if the StreamReceiver or its parent is closed when the call to receive is made.

tryReceive

public StreamDelivery tryReceive()
                          throws ClientException

Description copied from interface: StreamReceiver

Non-blocking receive method that either returns a message is one is immediately available or returns null if none is currently at hand.

Specified by:

tryReceive in interface Receiver

Specified by:

tryReceive in interface StreamReceiver

Returns:

a new StreamReceiverMessage received from the remote or null if no pending deliveries are available.

Throws:

ClientException - if the StreamReceiver or its parent is closed when the call to try to receive is made.

addCredit

public StreamReceiver addCredit(int credits)
                         throws ClientException

Description copied from interface: StreamReceiver

Adds credit to the Receiver link for use when there receiver has not been configured with a credit window. When credit window is configured credit replenishment is automatic and calling this method will result in an exception indicating that the operation is invalid.

If the Receiver is draining and this method is called an exception will be thrown to indicate that credit cannot be replenished until the remote has drained the existing link credit.

Specified by:

addCredit in interface Receiver

Specified by:

addCredit in interface StreamReceiver

Parameters:

credits - credit The number of credits to add to the StreamReceiver link.

Returns:

this StreamReceiver instance.

Throws:

ClientException - if an error occurs while attempting to add new StreamReceiver link credit.

drain

public java.util.concurrent.Future<Receiver> drain()
                                            throws ClientException

Description copied from interface: Receiver

Requests the remote to drain previously granted credit for this Receiver link.

Specified by:

drain in interface Receiver

Returns:

a Future that will be completed when the remote drains this Receiver link.

Throws:

ClientException - if an error occurs while attempting to drain the link credit.

properties

public java.util.Map<java.lang.String,java.lang.Object> properties()
                                                                  throws ClientException

Description copied from interface: Receiver

Returns the properties that the remote provided upon successfully opening the Receiver. If the attach has not completed yet this method will block to await the attach response which carries the remote properties. If the remote provides no properties this method will return null.

Specified by:

properties in interface Receiver

Returns:

any properties provided from the remote once the receiver has successfully opened.

Throws:

ClientException - if an error occurs while obtaining the Receiver remote properties.

offeredCapabilities

public java.lang.String[] offeredCapabilities()
                                       throws ClientException

Description copied from interface: Receiver

Returns the offered capabilities that the remote provided upon successfully opening the Receiver. If the attach has not completed yet this method will block to await the attach response which carries the remote offered capabilities. If the remote provides no capabilities this method will return null.

Specified by:

offeredCapabilities in interface Receiver

Returns:

any capabilities provided from the remote once the receiver has successfully opened.

Throws:

ClientException - if an error occurs while obtaining the Receiver remote offered capabilities.

desiredCapabilities

public java.lang.String[] desiredCapabilities()
                                       throws ClientException

Description copied from interface: Receiver

Returns the desired capabilities that the remote provided upon successfully opening the Receiver. If the attach has not completed yet this method will block to await the attach response which carries the remote desired capabilities. If the remote provides no capabilities this method will return null.

Specified by:

desiredCapabilities in interface Receiver

Returns:

any desired capabilities provided from the remote once the receiver has successfully opened.

Throws:

ClientException - if an error occurs while obtaining the Receiver remote desired capabilities.

address

public java.lang.String address()
                         throws ClientException

Description copied from interface: Receiver

Returns the address that the Receiver instance will be subscribed to.

• If the Receiver was created with the dynamic receiver methods then the method will return the dynamically created address once the remote has attached its end of the receiver link. Due to the need to await the remote peer to populate the dynamic address this method will block until the open of the receiver link has completed.
• If not a dynamic receiver then the address returned is the address passed to the original Session.openReceiver(String) or Session.openReceiver(String, ReceiverOptions) methods.

Specified by:

address in interface Receiver

Returns:

the address that this Receiver is sending to.

Throws:

ClientException - if an error occurs while obtaining the Receiver address.

source

public Source source()
              throws ClientException

Description copied from interface: Receiver

Returns an immutable view of the remote Source object assigned to this receiver link. If the attach has not completed yet this method will block to await the attach response which carries the remote Source.

Specified by:

source in interface Receiver

Returns:

the remote Source node configuration.

Throws:

ClientException - if an error occurs while obtaining the Receiver remote Source.

target

public Target target()
              throws ClientException

Description copied from interface: Receiver

Returns an immutable view of the remote Target object assigned to this receiver link. If the attach has not completed yet this method will block to await the attach response which carries the remote Source.

Specified by:

target in interface Receiver

Returns:

the remote Target node configuration.

Throws:

ClientException - if an error occurs while obtaining the Receiver remote Target.

queuedDeliveries

public long queuedDeliveries()
                      throws ClientException

Description copied from interface: Receiver

Returns the number of Deliveries that are currently held in the Receiver delivery queue. This number is likely to change immediately following the call as more deliveries arrive but can be used to determine if any pending Delivery work is ready.

Specified by:

queuedDeliveries in interface Receiver

Returns:

the number of deliveries that are currently buffered locally.

Throws:

ClientException - if an error occurs while attempting to fetch the queue count.